docs: finalize redis activity pool delivery

deploy/compose_test.go

@@ -0,0 +1,91 @@
+package deploy
+
+import (
+	"os"
+	"testing"
+
+	"go.yaml.in/yaml/v4"
+)
+
+type composeDocument struct {
+	Services map[string]composeService `yaml:"services"`
+	Volumes  map[string]any            `yaml:"volumes"`
+}
+
+type composeService struct {
+	Command   []string `yaml:"command"`
+	Volumes   []string `yaml:"volumes"`
+	DependsOn any      `yaml:"depends_on"`
+}
+
+func TestLocalRedisIsExplicitlyEphemeral(t *testing.T) {
+	document := loadComposeDocument(t)
+	redis, ok := document.Services["redis"]
+	if !ok {
+		t.Fatal("docker-compose.yml has no redis service")
+	}
+	if value, ok := commandFlag(redis.Command, "--appendonly"); !ok || value != "no" {
+		t.Fatalf("redis --appendonly = %q, %t; want no", value, ok)
+	}
+	if value, ok := commandFlag(redis.Command, "--save"); !ok || value != "" {
+		t.Fatalf("redis --save = %q, %t; want empty schedule", value, ok)
+	}
+	if len(redis.Volumes) != 0 {
+		t.Fatalf("redis volumes = %v; want no persistent mount", redis.Volumes)
+	}
+	if _, exists := document.Volumes["redis-data"]; exists {
+		t.Fatal("docker-compose.yml still declares redis-data")
+	}
+}
+
+func TestLocalGatewaysDoNotDependOnControlPlaneStorage(t *testing.T) {
+	document := loadComposeDocument(t)
+	for _, name := range []string{"gateway-a", "gateway-b"} {
+		gateway, ok := document.Services[name]
+		if !ok {
+			t.Fatalf("docker-compose.yml has no %s service", name)
+		}
+		for _, storage := range []string{"postgres", "redis"} {
+			if composeDependsOn(gateway.DependsOn, storage) {
+				t.Errorf("%s depends on %s; gateway startup must be storage-independent", name, storage)
+			}
+		}
+	}
+}
+
+func loadComposeDocument(t *testing.T) composeDocument {
+	t.Helper()
+	payload, err := os.ReadFile("docker-compose.yml")
+	if err != nil {
+		t.Fatalf("read docker-compose.yml: %v", err)
+	}
+	var document composeDocument
+	if err := yaml.Unmarshal(payload, &document); err != nil {
+		t.Fatalf("parse docker-compose.yml: %v", err)
+	}
+	return document
+}
+
+func composeDependsOn(value any, service string) bool {
+	switch dependencies := value.(type) {
+	case map[string]any:
+		_, exists := dependencies[service]
+		return exists
+	case []any:
+		for _, dependency := range dependencies {
+			if dependency == service {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func commandFlag(command []string, name string) (string, bool) {
+	for index := 0; index+1 < len(command); index++ {
+		if command[index] == name {
+			return command[index+1], true
+		}
+	}
+	return "", false
+}

deploy/docker-compose.yml

@@ -17,11 +17,6 @@ x-app: &app
     PROVIDER_A_TOKEN: ${PROVIDER_A_TOKEN:?set PROVIDER_A_TOKEN}
     PROVIDER_B_TOKEN: ${PROVIDER_B_TOKEN:?set PROVIDER_B_TOKEN}
   stop_grace_period: 45s
-  depends_on:
-    postgres:
-      condition: service_healthy
-    redis:
-      condition: service_healthy
 
 services:
   gateway-a:
@@ -49,6 +44,11 @@ services:
   controller:
     <<: *app
     command: ["proxy-controller"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
     expose: ["8081", "8082", "9090"]
     ports:
       - "127.0.0.1:8081:8081"
@@ -63,6 +63,11 @@ services:
   checker:
     <<: *app
     command: ["proxy-checker"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
     expose: ["9090"]
     healthcheck:
       test: ["CMD", "curl", "--fail", "--silent", "http://127.0.0.1:9090/readyz"]
@@ -111,10 +116,8 @@ services:
   redis:
     image: redis:8.2-alpine
     restart: unless-stopped
-    command: ["redis-server", "--appendonly", "yes", "--save", "60", "1"]
+    command: ["redis-server", "--appendonly", "no", "--save", ""]
     networks: [backend]
-    volumes:
-      - redis-data:/data
     healthcheck:
       test: ["CMD", "redis-cli", "ping"]
       interval: 5s
@@ -160,6 +163,5 @@ networks:
 
 volumes:
   postgres-data: {}
-  redis-data: {}
   prometheus-data: {}
   grafana-data: {}

docs/adr/005-redis-activity-pool.md

@@ -2,7 +2,7 @@
 
 ## 状态
 
-接受，2026-07-29。
+接受并已实现，2026-07-29。
 
 ## 背景
 
@@ -15,14 +15,14 @@ Redis 只承载控制面中的可重建短效状态：Proxy 活动池、健康
 30 秒，因此数据结构必须支持高频刷新、有界清理和硬过期，不能把逐个 Proxy
 或逐次提取记录写入 PostgreSQL。
 
-当前 `activitypool.MemoryPool` 已定义 Provider Upsert、Distribution Extract 和
+`activitypool.MemoryPool` 定义 Provider Upsert、Distribution Extract 和 Worker
-Worker Ownership 的参考语义，但生产 Redis 实现还存在以下缺口：
+Ownership 的参考语义，生产 Redis Adapter 已按同一套公用契约实现：
 
-- `ownership.Repository` 缺少 `context.Context` 和存储错误返回值。
+- 所有远程存储端口接收 `context.Context` 并返回存储错误。
-- Provider 写入 `FETCHED` 后没有公用健康状态更新端口。
+- Provider Upsert、健康更新、提取、所有权和维护能力通过窄接口复用。
-- 本地 `FetchBudget` 不能作为多进程环境的最终库存权威。
+- 原子 Lua 在提交前完成记录解码和候选校验，提取结果不依赖提交后的凭据解析。
-- 提取结果需要真实代理凭据，不能在 Redis 已提交消费后再执行可能失败的解析。
+- 全局 ownership epoch 使用 Redis `INCR`，库存读取与过期清理均采用有界扫描。
-- 短 TTL 条目不能依赖无上限全池扫描或长期数据库记录完成清理。
+- 真实 Redis 8.2 fixture 覆盖并发提取、所有权竞争、幂等硬过期和键 TTL。
 
 ## 决策
 

docs/development/implementation-plan.md

@@ -127,7 +127,7 @@ test/{fixtures,integration,e2e,load}/
 - [x] Enforce minRemainingTTL, maxHealthCheckAge, maxCount, client limits, and
   reserveForGateway.
 - [x] Atomically remove selected AVAILABLE entries from the allocatable set and return
-  the result; the current memory Store models the production Redis atomic boundary.
+  the result; MemoryPool and the production Redis Adapter run the same shared contract.
 - [x] Implement partial and allOrNothing without Lease, release, or renewal concepts.
 - [x] Run 1,000 concurrent claim attempts and prove every Proxy ID appears at most once.
 
@@ -161,14 +161,18 @@ test/{fixtures,integration,e2e,load}/
 - [ ] Define PostgreSQL ports for ConfigVersion, Upstream/Routing management state,
   AdminAudit, Outbox, and optional aggregate metrics; never persist Proxy details or
   per-extraction records.
-- [ ] Implement the Redis TTL activity pool and one atomic extraction operation covering
+- [x] Implement the Redis TTL activity pool and one atomic extraction operation covering
   candidate eligibility, Gateway reserve, ownership, removal, and short-lived idempotency.
-- [ ] Implement Redis Provider leader, distributed rate, Client limit, and Worker
+- [x] Implement Redis Worker ownership, drain/ACK, expiry reclaim, inventory and bounded
-  heartbeat/ownership; rebuild short-lived Proxy inventory from Providers after loss.
+  sweep primitives with a monotonic global epoch.
-- [ ] Keep Provider output in Redis TTL activity state and node memory only; keep the
+- [ ] Implement Redis Provider leader, distributed rate, Client limit and Worker
+  heartbeat; wire automatic Provider inventory rebuild after Redis loss.
+- [x] Keep Provider output in Redis TTL activity state and node memory only; keep the
   Gateway request path on immutable local snapshots with no Redis/PostgreSQL calls.
-- [ ] Expose Distribution extraction/status and Admin status/enable/disable/switch/reload.
+- [x] Expose Distribution extraction/status and Admin status/enable/disable/switch/reload
-- [ ] Add integration tests using Compose-backed PostgreSQL/Redis.
+  HTTP handlers and contracts.
+- [x] Add Compose-backed Redis 8.2 integration and shared Adapter contract tests.
+- [ ] Add PostgreSQL management Adapter and Compose-backed integration tests.
 
 当前进度（2026-07-29）：已实现共享 `platform/httpapi`、Distribution
 extract/live/ready Handler 与 Admin status/enable/disable/switch/reload Handler；
@@ -177,14 +181,15 @@ extract/live/ready Handler 与 Admin status/enable/disable/switch/reload Handler
 Bearer/CIDR、可信代理、Client ID、本地准入和 API 401/Gateway 407 差异，并作为
 Admin/Distribution 必需依赖。共享 `platform/httpserver` 与
 `controller/runtime` 已完成 Distribution/Admin 独立监听器、首错联动关闭和
-有界优雅停机；端点正式勾选仍等待 Redis 活动池/原子提取 Adapter、PostgreSQL
+有界优雅停机。生产命令入口、PostgreSQL 管理面 Adapter 及其 Compose 集成测试
-管理面 Adapter、命令入口与 Compose 集成测试。
+仍待实现。
 
 已新增公用 `domain/activitypool` 契约及并发安全内存参考实现，Provider
 Reconciler 通过 `UpsertFetched` 写入带供应商 TTL 和分配安全余量的批次；已覆盖
 `usableUntil` 向 Worker Snapshot 的传播与 Gateway 本地截止过滤、
 重复刷新、过期淘汰、独占提取、短期幂等及 Worker ownership 互斥。生产 Redis
-Lua/Function Adapter 和多节点集成测试仍待实现。
+Adapter 已通过真实 Redis 8.2 运行同一套公用契约；原子 Lua 覆盖提取、所有权和
+有界清理。Redis Sentinel/故障转移验证与代表性多节点压测仍待实施。
 
 ## Task 11: Checker and Health Reducer
 

docs/operations/runbook.md

@@ -48,6 +48,12 @@ docker compose -f deploy/docker-compose.yml config
 kubectl kustomize deploy/kubernetes/base > rendered.yaml
 ```
 
+本地 Compose 的 Redis 只作为可重建短效状态 fixture，固定使用
+`--appendonly no --save ""`，且不挂载 `/data` 或命名卷。真实 Redis 8.2 契约可
+通过 `.\scripts\test-redis.ps1` 执行；脚本使用唯一命名空间并在结束时定向清理，
+不执行 `FLUSHDB`。生产环境的 Redis 高可用与持久化策略必须独立评审，不能照搬
+本地 fixture。
+
 目标拓扑入口：
 
 - Gateway：`127.0.0.1:8080`
@@ -243,7 +249,8 @@ Prometheus 标签禁止包含 Proxy IP、Client ID、Session、完整 URL、requ
 - PostgreSQL：每日全量、连续 WAL/PITR，保护配置版本、Upstream/Routing 管理
   状态、Admin 审计与 outbox；至少每季度做恢复演练。
 - Redis：保存可由 Provider 重建的 TTL 活动池、所有权/Leader 协调和短期幂等
-  结果；使用高可用与持久化降低窗口丢失风险，但不把它当长期业务档案。
+  结果；生产环境可使用高可用与受控持久化降低窗口丢失风险，但不把它当长期
+  业务档案或备份源。本地 Compose 刻意关闭持久化并且不挂载数据卷。
 - 配置：版本化保存校验通过的不可变 Revision 与校验和。
 - Secret：由密钥平台版本化，日志和备份中不得出现明文。
 

docs/requirements/traceability.md

@@ -11,7 +11,7 @@
 | ARCH-002 | 热路径只做认证、本地路由和网络转发 | 1-70, 380-430 | 依赖规则、测试、性能剖析 |
 | ARCH-003 | Gateway、Distribution、Admin、Metrics 独立入口 | 8904-8958 | 配置、监听装配、端口测试 |
 | ARCH-004 | Controller 集中 Provider 获取与切换 | 1403-1580 | Leader、singleflight、集成测试 |
-| ARCH-005 | 100k QPS 峰值使用多 Worker 集群 | 当前会话 | 容量公式、负载场景、部署清单 |
+| ARCH-005 | 100k QPS 峰值使用多 Worker 集群 | 当前会话 | 未验证设计目标；待代表性集群负载报告 |
 
 ## Routing 与 Upstream
 
@@ -49,7 +49,7 @@
 | CAP-002 | 补池依据 Available Slots，不只看 Proxy 数量 | 1203-1402, 8530-8597 | `Inventory.AvailableSlots` 与 Pool Reconciler 测试 |
 | CAP-003 | pool.maxSize 包括 FETCHED/CHECKING/AVAILABLE/SUSPECT/DRAINING 与 pending expected | 3001-3533, 6642-6680 | `FetchBudget` 100 并发额度预占测试 |
 | CAP-004 | TTL safety margin 内禁止新分配 | 173-220, 6728-6741 | 时钟测试 |
-| CAP-005 | 多 Worker 不在热路径访问 Redis 计数 | 1403-1467 | 依赖审计与压测 |
+| CAP-005 | 多 Worker 不在热路径访问 Redis 计数 | 1403-1467 | Gateway 包依赖审计、Snapshot/Dispatch 测试 |
 
 ## Gateway
 
@@ -66,9 +66,9 @@
 | ID | 最终需求 | 来源 | 验证证据 |
 |---|---|---|---|
 | DIST-001 | API 提取固定为一次性独占发放，不使用 Lease | 9083-9404 | Domain 状态机与 API 测试 |
-| DIST-002 | AVAILABLE -> EXTRACTED 必须原子完成后才能返回 | 9083-9189 | 共享 Repository 所有权/提取 100 轮竞态测试 |
+| DIST-002 | AVAILABLE -> EXTRACTED 必须原子完成后才能返回 | 9083-9189 | Memory/Redis 公用契约与真实 Redis 100 轮竞态测试 |
 | DIST-003 | 支持 partial 与 allOrNothing，默认 partial | 9190-9215 | API 契约测试 |
-| DIST-004 | 保存审计记录，不提供释放接口 | 9216-9252 | 原子审计、幂等测试与 OpenAPI |
+| DIST-004 | 不保存逐代理/逐次提取审计记录，不提供释放接口；仅保留短期幂等结果 | 9216-9252 | Redis 幂等 TTL 契约、OpenAPI 与 PostgreSQL 边界审计 |
 | DIST-005 | 返回 expiresAt 与 remainingTtlSeconds | 9334-9360 | `extraction/service_test.go` |
 | DIST-006 | 提取前校验 minRemainingTTL 与 maxHealthCheckAge | 9334-9369 | 过滤测试 |
 | DIST-007 | reserveForGateway 防止 Extract 清空共享池 | 9281-9333 | 共享池测试 |
@@ -86,4 +86,4 @@
 | OPS-001 | 配置校验后构建不可变快照并原子替换 | 8959-8999 | 100k 索引、版本/epoch 与并发 Apply/Acquire 测试 |
 | OPS-002 | 优雅停机停止新请求/Fetch，等待现有流量后超时关闭 | 8981-9000 | Provider Run 收敛与 `Handler.Shutdown` HTTP 排空、Hijacked CONNECT 超时关闭测试 |
 | OBS-001 | 指标禁止 Proxy IP、session、Client、完整 URL 高基数标签 | 9001-9029 | 指标描述符测试 |
-| TEST-001 | 覆盖对话中列出的 11 个关键并发与故障场景 | 9030-9082 | CI 测试清单 |
+| TEST-001 | 覆盖对话中列出的 11 个关键并发与故障场景 | 9030-9082 | 测试清单；Redis 活动池由 Memory/Redis 公用契约覆盖，跨进程故障场景仍按清单推进 |

docs/testing/strategy.md

@@ -1,10 +1,15 @@
 # 测试策略
 
+> 本文保留为早期领域与容量检查清单。存储边界和当前执行命令以
+> `test-strategy.md`、ADR-005 为准：Proxy 明细与逐次提取记录不写 PostgreSQL，
+> 独占提取只在 Redis TTL 活动池保留短期幂等结果。
+
 ## 1. 分层
 
 - **领域单测**：状态机、TTL、路由、容量、Fetch 分类和 Extraction 原子性。
 - **契约测试**：配置、OpenAPI、Protobuf 和 Provider Adapter fixture。
-- **集成测试**：PostgreSQL 事务、Redis Leader/限流、Outbox 与重建。
+- **集成测试**：Redis 活动池原子契约、PostgreSQL 管理事务、Leader/限流、
+  Outbox 与重建。
 - **端到端测试**：HTTP、CONNECT、Admin、Distribution 和优雅停机。
 - **负载测试**：Worker 调度微基准、50k 隧道 soak、集群 100k QPS 场景。
 
@@ -32,6 +37,15 @@ go test -race ./internal/...
 go build ./...
 ```
 
+真实 Redis 8.2 活动池契约使用独立 Compose fixture：
+
+```powershell
+.\scripts\test-redis.ps1
+```
+
+该 fixture 使用唯一命名空间，不执行 `FLUSHDB`，并关闭 AOF、RDB 与数据卷；
+测试结束后按命名空间清理活动池、所有权和幂等键。
+
 单条测试命令超时 60 秒。依赖真实等待的用例必须改为 fake clock；集成和
 soak 测试单独标记，不混入快速单测。
 

docs/testing/test-strategy.md

@@ -76,6 +76,18 @@ go vet ./...
 go build ./...
 ```
 
+Redis 活动池 Adapter 与内存参考实现共享同一套公用行为契约。真实 Redis 8.2
+fixture 的执行命令是：
+
+```powershell
+.\scripts\test-redis.ps1
+```
+
+契约覆盖 Upsert/去重/容量、健康更新、partial/allOrNothing 提取、Gateway 保留、
+零数量与非零数量幂等、幂等硬过期、Worker 所有权/Drain/ACK、库存、过期清理、
+100 轮并发提取和 100 轮所有权竞争。fixture 使用唯一命名空间，不执行
+`FLUSHDB`；本地 Redis 关闭 AOF、RDB 和数据卷，避免短效 Proxy 与凭据落盘。
+
 需要 PostgreSQL/Redis 的测试使用独立实例和短生命周期容器，不复用开发数据。
 测试结束后验证没有残留 Worker ownership、Leader 租约、活动池条目或幂等键，
 并检查 PostgreSQL 中不存在 Proxy 明细和逐次提取记录。

progress.md

@@ -10,12 +10,19 @@
   `LoadResolved` 回归测试。
 - 已新增公用 `activitypool` 契约和并发安全内存参考实现；Provider 按各供应商
   TTL 与安全余量写入，独占提取、短期幂等和 Worker 所有权在同一原子边界内。
+- 已实现生产 Redis Activity Adapter：Upsert、健康更新、原子提取、所有权、
+  Drain/ACK、库存读取与有界过期清理均封装为窄领域端口和 Lua 原子操作。
+- MemoryPool 与 Redis Adapter 运行同一套公用契约；真实 Redis 8.2 fixture 已覆盖
+  100 轮并发提取和 100 轮所有权竞争，本地 Compose 不持久化短效代理数据。
 - Proxy 明细不写 PostgreSQL；PostgreSQL 仅保存配置版本、管理状态、Admin
   审计、管理 outbox 和可选聚合指标。
 - `usableUntil` 已进入 Worker Snapshot 契约，Gateway 在供应商硬过期前按安全
   余量停止新分配。
-- 生产 Redis Adapter、PostgreSQL 管理面 Adapter、生产命令入口与代表性
+- PostgreSQL 管理面 Adapter、Provider Leader/分布式限流与心跳装配、生产命令
-  100,000 QPS 集群压测仍待实现。
+  入口、Redis 故障转移验证和代表性 100,000 QPS 集群压测仍待实现。
+- 本轮 `.\scripts\verify.ps1`、`.\scripts\test-redis.ps1`、Compose 静态展开和
+  Compose 非持久化策略测试通过；Windows `CGO_ENABLED=0`，race 继续由 Linux
+  CI 执行。
 
 ## 2026-07-28
 
@@ -36,8 +43,7 @@
 - Windows 当前 `CGO_ENABLED=0` 且无 C 编译器，race 测试由 Linux CI 承担。
 - 100,000 QPS 仍是未验证设计目标；运行进程、存储适配器、完整网络转发与
   代表性集群压测尚未实施，已在完成审计中明确列出。
-- 已生成 `proxy-pool-docs-v1.0.zip`，包含 50 个条目，SHA-256 为
+- 历史文档压缩包已由用户删除，当前交付以仓库内可追踪文档为准。
-  `A6882B71196210CE3594A10992C2A0A73EA3A1CF31D8A570709CA999133CE104`。
 - 已实现 random、roundRobin、weighted、leastConnections，并将 Sequential
   拆成共享 Upstream 空结果状态与每 Routing 版本化游标。
 - 已实现 Provider 合并通知、完整 attempt 超时、永久错误契约、指数退避、

task_plan.md

@@ -26,6 +26,8 @@
 8. [已完成] 按需求矩阵逐项审计并生成版本化文档包
 9. [已完成] 将 Proxy 明细、独占提取、短期幂等和 Worker 所有权统一到
    TTL 活动池契约；PostgreSQL 退出代理数据路径
+10. [已完成] 实现生产 Redis Activity Adapter、原子 Lua、公用行为契约和
+    Redis 8.2 集成 fixture；本地 Redis 禁止短效代理数据持久化
 
 ## 串并行关系
 
@@ -46,5 +48,5 @@
 
 - Docker Compose 配置与 Kubernetes Kustomize 已完成静态渲染验证；未启动
   目标运行拓扑。
-- `cmd/proxy-*`、生产 Redis 活动池 Adapter、PostgreSQL 管理面 Adapter 与
+- `cmd/proxy-*`、PostgreSQL 管理面 Adapter、Provider Leader/分布式限流、
-  Checker 运行时属于后续实施范围，见完成审计。
+  Checker 运行时、Redis 故障转移验证与代表性集群压测属于后续实施范围。