From 885efa86a2c92e3a209507d0554ed772187b1f02 Mon Sep 17 00:00:00 2001 From: youfak Date: Fri, 31 Jul 2026 22:19:17 +0800 Subject: [PATCH] docs: align checker runtime status --- README.md | 23 +++++++++++-------- docs/api/control-plane.md | 11 +++++---- docs/development/implementation-plan.md | 14 ++++++----- docs/operations/runbook.md | 5 ++-- docs/requirements/completion-audit.md | 13 +++++++---- docs/requirements/traceability.md | 6 ++--- .../redisactivity/scripts/health_tasks.lua | 1 - 7 files changed, 42 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 57779df..6fb5306 100644 --- a/README.md +++ b/README.md @@ -80,17 +80,19 @@ flowchart LR ## 当前完成度 -截至 **2026-07-31**，实施计划检查项为 **56 / 74（75.7%）**。详情见 +截至 **2026-07-31**，实施计划中可直接勾选的检查项为 **53 / 74（71.6%）**。详情见 [实施计划](docs/development/implementation-plan.md)和 [交付完成度审计](docs/requirements/completion-audit.md)。 - **已完成**：严格配置、Provider 获取与协调、Redis 活动池、Distribution 原子 提取与限流、Controller 的 Admin/Distribution/Metrics 监听，以及 PostgreSQL 管理状态；WorkerControlPlane 的 Register、Snapshot ACK、Runtime 心跳接收和 - Redis 会话栅栏，以及 Gateway Outcome 上报的有界队列、序列确认与重试。 -- **部分完成**：Checker 的任务协议、租约契约和健康状态归并；Redis 共享调度、 - 实际探测器、Docker Compose/Kubernetes 运行时 mTLS Overlay。 -- **待完成**：Checker 调度与健康状态链，以及 loadgen 和代表性集群压测。 + Redis 会话栅栏，以及 Gateway Outcome 上报的有界队列、序列确认与重试； + Controller 的 Redis 共享 BASIC 检查任务、按上游的有界调度、Checker 探测和 + Observation 状态归并。 +- **部分完成**：EGRESS 与 TARGET 的任务编排和配置建模、SOCKS5 探测，Docker + Compose/Kubernetes 运行时 mTLS Overlay。 +- **待完成**：loadgen、故障演练和代表性集群压测。 检查项数量不等于生产就绪度。静态部署清单与 protobuf descriptor 验证也不代表 端到端拓扑已经完成；`100,000 QPS` 仍只是待验证的集群设计目标。 @@ -164,9 +166,9 @@ go run ./cmd/proxy-checker -config CONFIG_FILE ` Checker 的参数也可通过 `PROXY_POOL_CONTROL_PLANE_ADDRESS`、 `PROXY_POOL_CHECKER_ID`、`PROXY_POOL_CHECKER_INSTANCE_ID` 与 -`PROXY_POOL_CHECKER_MAX_IN_FLIGHT` 提供。它不会访问 Redis/PostgreSQL；当前生产 -Controller 尚未装配 Redis 共享任务 broker，任务流会返回 `Unavailable`，直到后续 -调度阶段接入。loadgen 命令尚未实现。 +`PROXY_POOL_CHECKER_MAX_IN_FLIGHT` 提供。它不会访问 Redis/PostgreSQL；生产 +Controller 在启用控制面时装配 Redis 共享任务 broker，并按启用的 Upstream 调度 +HTTP/HTTPS BASIC 检查。EGRESS 与 TARGET 尚未进入生产调度，loadgen 命令也尚未实现。 ## 关键配置与入口 @@ -197,8 +199,9 @@ Controller 尚未装配 Redis 共享任务 broker，任务流会返回 `Unavaila - **P0 - Worker 控制面闭环**：Worker session、Snapshot ledger、ACK、运行态接收、 ownership 索引，以及 Gateway 快照客户端。 -- **P0 - Checker 健康链**：Checker 调度、实际探测、Observation reducer，以及 - `FETCHED -> AVAILABLE / SUSPECT / UNHEALTHY` 状态链。 +- **P0 - Checker 健康链**：BASIC 的共享调度、实际探测、Observation reducer 和 + `FETCHED -> AVAILABLE / SUSPECT / UNHEALTHY` 状态链已完成；继续补齐 EGRESS、 + TARGET 和 SOCKS5。 - **P1 - Gateway 与 Routing**：Gateway 进程、快照凭据分发、五种 Routing 策略与 `onUnavailable` 已接入；动态容量调整和 Drain 闭环待完成。 - **P1 - 可观测与部署**：低基数业务指标、完整 Compose/Kubernetes 进程拓扑， diff --git a/docs/api/control-plane.md b/docs/api/control-plane.md index 7f8da76..d11bc0a 100644 --- a/docs/api/control-plane.md +++ b/docs/api/control-plane.md @@ -42,8 +42,9 @@ View 的其余候选中回退。`wait_timeout` 随 `on_unavailable=WAIT` 下发 Redis 只保留每个当前会话的一条序列和摘要；原始 Outcome、代理明细与逐请求记录均不写入 Redis 或 PostgreSQL。Gateway 只将结果写入本地有界队列，队列满时丢弃样本，不等待控制面 或存储。Checker 的有界任务领取、任务租约归属校验和 Observation 上报已经由 -gRPC 契约测试覆盖；Redis 共享 due-index、生产任务 broker 与独立 Checker 探测进程 -尚未接入启动拓扑。`100,000 QPS` 仍是未验证的设计目标。 +gRPC 契约测试覆盖；Controller 已装配 Redis 共享 due-index、生产任务 broker 与独立 +Checker 的 HTTP/HTTPS BASIC 探测进程。EGRESS 和 TARGET 尚未进入生产调度。 +`100,000 QPS` 仍是未验证的设计目标。 `WatchSnapshots` 建立时校验当前 session；每次签发快照引用时也把 `session_id` 交给 Redis 原子校验。重复 Register 会同时清除旧 Runtime 和已签发引用，因此迟到的 @@ -169,8 +170,10 @@ Routing 决定 AVAILABLE、SUSPECT 或 UNHEALTHY，并更新 Redis 活动池， 被领取时通过认证的 mTLS 流携带 endpoint、`secret_ref`、版本和任务期凭据；Checker 不访问 Redis 或 PostgreSQL。`ReportObservations` 在调用 Reducer 前校验 task、Proxy、 检查层级、目标 Profile 与领取者一致，Reducer 成功后才确认任务；相同领取者对已确认 -任务的同一事实可重放，由活动池摘要幂等处理。当前生产配置尚未装配 Redis 共享 broker， -因此无共享 broker 的服务会以 `Unavailable` 拒绝任务流，而不下发无租约任务。 +任务的同一事实可重放，由活动池摘要幂等处理。生产 Controller 装配 Redis 共享 +broker，按启用 Upstream 的有效检查策略调度 BASIC 任务；未装配 broker 的 fixture +服务仍会以 `Unavailable` 拒绝任务流，而不下发无租约任务。EGRESS 和 TARGET 的 +任务索引及调度策略尚未实现。 每次 Claim 还会签发新的不可预测 `lease_token`；Observation 必须回传该值。任务被重新 领取后，旧 token 即使拥有相同 `task_id` 和 `checker_id` 也会被拒绝，避免过期实例的 迟到事实覆盖新租约结果。 diff --git a/docs/development/implementation-plan.md b/docs/development/implementation-plan.md index e365702..c6e578f 100644 --- a/docs/development/implementation-plan.md +++ b/docs/development/implementation-plan.md @@ -261,8 +261,8 @@ Controller 多副本共享同一计数。Client 身份只以 SHA-256 摘要进 Gateway 请求热路径仍只使用本地准入，不增加 Redis/PostgreSQL 调用。 WorkerControlPlane gRPC 接收端、session 签发/心跳、Snapshot ACK 账本、基础 Snapshot 流、Gateway 会话客户端与快照凭据分发已完成；权威 Proxy/Routing 发布、 -Outcome 上报已完成为有界队列、批次序列/摘要栅栏和确认重试；健康执行链仍待完成， -因此 Task 10 尚未全部完成。 +Outcome 上报已完成为有界队列、批次序列/摘要栅栏和确认重试；健康 BASIC 执行链已 +完成，EGRESS/TARGET 编排和 REMOVE 生命周期仍待完成，因此 Task 10 尚未全部完成。 ## Task 11: Checker and Health Reducer @@ -281,10 +281,12 @@ Lua 同一原子边界归并，覆盖首次 CHECKING 失败进入 UNHEALTHY、AV Checker Observation 上报 RPC 已复用既有控制面监听接入 Controller：SPIFFE `checker` 身份、 每批上限、配置阈值解析、代理归属查询与 Reducer 均已闭环。`StreamCheckTasks` 现已实现为 有界 pull，并通过通用任务 broker 契约完成能力协商、同 Checker 并发窗口、租约到期回收、 -领取者加不可预测 lease token 的栅栏和完成后重放；任务凭据仅由认证流在执行期下发。Redis 共享 due-index/租约持久化、 -生产 broker 已有契约但 Redis 实现尚未完成；`proxy-checker` 独立进程、固定大小 worker-pool、 -任务期重试/微批上报和 HTTP/HTTPS BASIC/TARGET 探测器已完成并有测试。SOCKS5、EGRESS -专用出口探测、Redis due-index/跨副本租约和部署运行态仍未实现，因此本任务保持未完成。 +领取者加不可预测 lease token 的栅栏和完成后重放；任务凭据仅由认证流在执行期下发。 +Redis 共享 due-index/租约持久化、每 Upstream 的跨副本 in-flight 限制和生产 broker 已完成； +`proxy-checker` 独立进程、固定大小 worker-pool、任务期重试/微批上报和 HTTP/HTTPS +BASIC 探测器已完成并有测试。TARGET 探测器具备任务执行能力，但尚无生产任务调度； +SOCKS5、EGRESS 专用出口探测、EGRESS/TARGET 多维任务索引及部署运行态仍未实现， +因此本任务保持未完成。 ## Task 12: Machine-readable Contracts diff --git a/docs/operations/runbook.md b/docs/operations/runbook.md index 47a92d0..26636f3 100644 --- a/docs/operations/runbook.md +++ b/docs/operations/runbook.md @@ -23,8 +23,9 @@ `cmd/proxy-controller` 已完成配置单次加载、PostgreSQL 迁移、Redis 活动池、 Distribution/Admin/Metrics 独立监听和有界停机装配。Provider 自动补池、分布式 -配额、动态重载和 Admin 低基数统计已装配；Checker/Loadgen 与完整 mTLS 环境 Overlay -仍属于 `implementation-plan.md` 后续任务。 +配额、动态重载和 Admin 低基数统计已装配；Controller 已装配 Redis BASIC 任务 broker， +`proxy-checker` 可执行 HTTP/HTTPS BASIC 探测。EGRESS/TARGET 调度、loadgen 与完整 +mTLS 环境 Overlay 仍属于 `implementation-plan.md` 后续任务。 因此 Compose/Kubernetes 资产当前仍用于评审网络、资源、探针和依赖关系，不能 视为完整可运行拓扑。 diff --git a/docs/requirements/completion-audit.md b/docs/requirements/completion-audit.md index 50c1611..c130400 100644 --- a/docs/requirements/completion-audit.md +++ b/docs/requirements/completion-audit.md @@ -61,8 +61,9 @@ Outcome 已实现为 Gateway 本地有界队列、微批确认重试和 Controll 与 Memory/Redis 原子状态提交基础；TARGET Profile 以独立、随代理 TTL 过期的 Redis 记录归并，不改写 Proxy 全局状态。Controller 公用 Reducer 已作为 Observation 的唯一状态 归并边界，Checker Observation RPC 已在同一控制面监听以独立 SPIFFE 身份接入；有界任务领取、 -租约归属与任务期凭据传输已有通用契约和 gRPC 往返测试，Redis 共享任务运行态与独立执行进程 -尚未闭环。Snapshot 签发在 Redis 中原子匹配当前 +租约归属与任务期凭据传输已由通用契约和 gRPC 往返测试覆盖。Redis 共享 due-index、 +任务/租约持久化、按上游的 in-flight 限制以及独立 Checker 的 HTTP/HTTPS BASIC 执行 +进程已经闭环；EGRESS、TARGET 的多维任务索引与生产调度尚未实现。Snapshot 签发在 Redis 中原子匹配当前 `session_id`，重注册会清除旧引用，迟到旧 Stream 不会覆盖新 session。Controller 在最近成功下发的 Snapshot `valid_until` 到达时关闭流；Gateway 的公用 `SessionSupervisor` 已实现可恢复错误的有界退避重连。Gateway 会校验并执行 Snapshot @@ -98,7 +99,8 @@ Controller/Gateway 入口，完整 mTLS 运行时拓扑仍只有静态验证。 以下已有设计、接口或部署位置，但尚无端到端生产实现： -1. `cmd/proxy-checker/loadgen` 进程装配；`proxy-controller` 已完成 +1. `proxy-loadgen` 进程装配；`proxy-checker` 的 BASIC 任务进程已经完成， + `proxy-controller` 已完成 Admin/Distribution/Metrics 与 PostgreSQL/Redis 启动装配，`proxy-gateway` 已完成 HTTP/Metrics 与控制面 Session 装配，但 Provider 和业务指标链未闭环。 2. Gateway 的生产连接池调优与代表性流量压测。 @@ -112,8 +114,9 @@ Controller/Gateway 入口，完整 mTLS 运行时拓扑仍只有静态验证。 6. Worker 基础网络快照流、Proxy/Gateway Routing/凭据 Snapshot payload、Gateway Snapshot 客户端和进程装配、同版本 Routing 编译/动态匹配、五种策略上游选择与 reject/wait/direct 已完成； Outcome 上报已完成基础观测链；Redis ownership drain/ACK/过期回收及按 Worker 的可下发索引已完成。 -7. Checker 调度与探测器；全局与 TARGET Profile 的 Memory/Redis 原子归并、Controller - Reducer 和 Observation 上报 RPC 已完成。 +7. BASIC Checker 调度与 HTTP/HTTPS 探测器、全局与 TARGET Profile 的 Memory/Redis + 原子归并、Controller Reducer 和 Observation 上报 RPC 已完成；EGRESS、TARGET + 生产任务调度、SOCKS5 探测与 REMOVE 编排仍待实现。 8. Admin/Distribution 细粒度授权和审计查询；Distribution 分布式限流已完成。 9. 真实 Compose/Kubernetes 集成、故障演练和代表性集群负载测试。 10. 将 reject/wait/direct 接入 Distribution 运行链，补齐 Sequential 持久化恢复、跨实例 CAS diff --git a/docs/requirements/traceability.md b/docs/requirements/traceability.md index 31a9c14..50a6556 100644 --- a/docs/requirements/traceability.md +++ b/docs/requirements/traceability.md @@ -7,7 +7,7 @@ | ID | 最终需求 | 来源 | 验证证据 | |---|---|---|---| -| ARCH-001 | 数据面 Worker 与控制面 Controller 分离 | 1-70 | 包、协议和部署拓扑已分离；Controller 已运行 Worker Register/Watch/ACK/Runtime/Outcome 与 Checker Observation gRPC，并发布 Proxy/Gateway Routing/按引用去重凭据完整快照；Checker 任务流已具备有界领取、租约栅栏和任务期凭据契约。Gateway 已将快照编译为同版本动态 View，并由独立进程维护控制面会话。Checker/Loadgen 构建产物与 Redis 共享任务运行态待实现 | +| ARCH-001 | 数据面 Worker 与控制面 Controller 分离 | 1-70 | 包、协议和部署拓扑已分离；Controller 已运行 Worker Register/Watch/ACK/Runtime/Outcome 与 Checker Observation gRPC，并发布 Proxy/Gateway Routing/按引用去重凭据完整快照；Checker 任务流已具备有界领取、租约栅栏和任务期凭据契约。Gateway 已将快照编译为同版本动态 View，并由独立进程维护控制面会话。`proxy-checker` 与 Redis BASIC 共享任务运行态已实现；loadgen、EGRESS/TARGET 生产编排待实现 | | ARCH-002 | 热路径只做认证、本地路由和网络转发 | 1-70, 380-430 | Gateway bootstrap 集成测试验证启动期控制面会话与快照就绪，HTTP 请求只走本地 Snapshot/Dispatch；Outcome 仅写入有界非阻塞本地队列，代表性性能剖析待完成 | | ARCH-003 | Gateway、Distribution、Admin、Metrics 独立入口 | 8904-8958 | Controller 命令已装配 Distribution/Admin/Metrics 三个独立监听及联动停机；Gateway 命令已装配代理与 Metrics 监听，运行时 mTLS 部署 Overlay 待完成 | | ARCH-004 | Controller 集中 Provider 获取与切换 | 1403-1580 | Redis Leader、动态 Provider Supervisor 与 Bootstrap 生产装配已完成；Admin disable/reload 驱动取消替换，多副本按权威 HMAC 指纹和 revision 栅栏收敛并拒绝旧配置换主；Routing 切换到 Drain 的编排待完成 | @@ -80,8 +80,8 @@ | ID | 最终需求 | 来源 | 验证证据 | |---|---|---|---| | HEALTH-001 | 全局健康与 Routing/目标健康分离 | 221-270, 8679-8708 | `domain/health` 已将 BASIC/EGRESS 全局 Reducer 与 TARGET Profile Reducer 分离；TARGET 在 Memory 和 Redis 独立、随代理 TTL 归并，不改写 Proxy 全局状态；Routing 消费待实现 | -| HEALTH-002 | 健康调度有 jitter、maxInFlight 和分级频率 | 8679-8736 | 配置有效合并、URL 校验、稳定抖动/优先级 Planner、有界 Scheduler tick，以及 Checker 任务的能力协商和租约窗口测试已完成；Redis due-index、跨副本 in-flight 原子限制和生产执行器待实现 | -| HEALTH-003 | 失败分级 SUSPECT -> UNHEALTHY -> REMOVE | 8679-8736 | Controller 公用 Reducer 已通过 Memory/Redis 活动池原子提交全局连续失败、精确重放和成功恢复；任务调度与 REMOVE 编排待实现 | +| HEALTH-002 | 健康调度有 jitter、maxInFlight 和分级频率 | 8679-8736 | 配置有效合并、URL 校验、稳定抖动/优先级 Planner、有界 Scheduler tick、Redis due-index、跨副本 in-flight 原子限制，以及 HTTP/HTTPS BASIC 生产执行器已完成；EGRESS/TARGET 多维任务索引与调度待实现 | +| HEALTH-003 | 失败分级 SUSPECT -> UNHEALTHY -> REMOVE | 8679-8736 | Controller 公用 Reducer 已通过 Memory/Redis 活动池原子提交全局连续失败、精确重放和成功恢复；BASIC 任务调度已完成，REMOVE 编排待实现 | | SEC-001 | API 认证与 Proxy 认证分离，Secret 统一脱敏 | 7528-8111, 8904-8945 | Config 脱敏、Provider Store -> SecretRef -> Gateway Resolver 跨包测试与格式化泄漏回归测试 | | SEC-002 | 非回环监听无保护时严格模式启动失败 | 8112-8441 | 配置校验测试 | | OPS-001 | 配置校验后构建不可变快照并原子替换 | 8959-8999 | 100k 索引、版本/epoch 与并发 Apply/Acquire 测试 | diff --git a/internal/adapters/redisactivity/scripts/health_tasks.lua b/internal/adapters/redisactivity/scripts/health_tasks.lua index d5b7626..8412cfa 100644 --- a/internal/adapters/redisactivity/scripts/health_tasks.lua +++ b/internal/adapters/redisactivity/scripts/health_tasks.lua @@ -189,7 +189,6 @@ if operation == 'upstream_inflight' then if type(payload.upstreamTasksKey) ~= 'string' or payload.upstreamTasksKey == '' then return finish({status = 'invalid'}) end - redis.call('ZREMRANGEBYSCORE', payload.upstreamTasksKey, '-inf', now_ms) return finish({status = 'ok', count = redis.call('ZCARD', payload.upstreamTasksKey)}) end