已合并
docs: 补充HTTP/SSE内部链路mTLS证书认证设计与接口文档 #533
Wal1et创建于 25 天前
docs: 补充HTTP/SSE内部链路mTLS证书认证设计与接口文档 #533
已合并
共 10 个文件变更+708-15
| @@ -0,0 +1,212 @@ | |||
| 1 | +# HTTP/SSE 内部链路 mTLS 设计 | ||
| 2 | + | ||
| 3 | +## 1. 目标与范围 | ||
| 4 | + | ||
| 5 | +本设计描述 JiuwenSwarm 内部 HTTP/SSE 链路的服务身份认证与实例绑定。覆盖以下组件： | ||
| 6 | + | ||
| 7 | +- Manager 向 Gateway、Agent Runtime 下发配置； | ||
| 8 | +- Gateway 向 Agent Runtime 请求路由，并与 AgentServer 建立 SSE 数据通道； | ||
| 9 | +- Agent Runtime 管理 AgentServer Pod，并对 AgentServer 执行健康探测； | ||
| 10 | +- Agent Runtime 创建 AgentServer 时注入其链路证书材料。 | ||
| 11 | + | ||
| 12 | +链路启用后同时使用 HTTPS、双向 TLS、角色证书指纹和绑定版本校验。用户登录、组织准入、Agent 授权等业务权限仍由原有认证与管理逻辑处理。 | ||
| 13 | + | ||
| 14 | +## 2. 组件与链路 | ||
| 15 | + | ||
| 16 | +```text | ||
| 17 | + 配置面 | ||
| 18 | + ┌──────────────────────────────────┐ | ||
| 19 | + │ │ | ||
| 20 | + Manager ── HTTPS/mTLS ──► Gateway │ | ||
| 21 | + │ │ | ||
| 22 | + └──── HTTPS/mTLS ──► Agent Runtime │ | ||
| 23 | + │ | ||
| 24 | + 创建、探活 │ | ||
| 25 | + ▼ | ||
| 26 | +Gateway ── HTTPS/mTLS ──► AgentServer ◄── HTTPS/mTLS ── Agent Runtime | ||
| 27 | + HTTP/SSE | ||
| 28 | +``` | ||
| 29 | + | ||
| 30 | +各连接承担的职责如下： | ||
| 31 | + | ||
| 32 | +| 调用方 | 服务端 | 主要用途 | | ||
| 33 | +|---|---|---| | ||
| 34 | +| Manager | Gateway | 模型、Agent、实例资源及其他管理配置下发 | | ||
| 35 | +| Manager | Agent Runtime | `config_sync` 等 Runtime 配置下发 | | ||
| 36 | +| Gateway | Agent Runtime | `route`、`touch`、`cleanup`、`config_refresh` | | ||
| 37 | +| Gateway | AgentServer | HTTP/SSE 业务请求 | | ||
| 38 | +| Agent Runtime | AgentServer | Pod 健康探测与资源管理 | | ||
| 39 | + | ||
| 40 | +## 3. 身份模型 | ||
| 41 | + | ||
| 42 | +### 3.1 服务角色 | ||
| 43 | + | ||
| 44 | +证书材料按四种角色隔离： | ||
| 45 | + | ||
| 46 | +| 角色 | 证书用途 | | ||
| 47 | +|---|---| | ||
| 48 | +| `manager` | 作为配置面客户端访问 Gateway、Agent Runtime | | ||
| 49 | +| `gateway` | 作为 HTTPS 服务端接收 Manager 请求；作为客户端访问 Agent Runtime、AgentServer | | ||
| 50 | +| `runtime` | 作为 HTTPS 服务端接收 Manager、Gateway 请求；作为客户端访问 AgentServer | | ||
| 51 | +| `agentserver` | 作为 HTTPS 服务端接收 Gateway、Agent Runtime 请求 | | ||
| 52 | + | ||
| 53 | +同一部署的四个角色由同一 CA 签发，但每个角色使用不同的私钥和叶证书。证书的扩展用途与角色一致：Manager 仅包含客户端用途，AgentServer 仅包含服务端用途，Gateway 和 Runtime 同时包含客户端与服务端用途。 | ||
| 54 | + | ||
| 55 | +### 3.2 标识分层 | ||
| 56 | + | ||
| 57 | +| 标识 | 含义 | 生命周期 | | ||
| 58 | +|---|---|---| | ||
| 59 | +| `jiuwenclaw_id` | Manager 业务实例主键，用于实例、资源、用户和组织等业务关联 | 随 Manager 实例记录 | | ||
| 60 | +| `GATEWAY_INSTANCE_ID` | Gateway 运行身份，用于选主及 Redis 键隔离 | 随 Gateway 部署配置 | | ||
| 61 | +| Runtime `instance_id` | 当前 Runtime 进程或副本身份 | 可随 Pod 或进程重建变化 | | ||
| 62 | +| `mtls_deployment_id` | 一套部署证书材料的内部标识 | 首次签发后随材料持久化 | | ||
| 63 | +| `mtls_binding_id` | 当前 mTLS 绑定的唯一标识 | 随绑定材料持久化 | | ||
| 64 | +| `mtls_binding_epoch` | 绑定版本号，单调递增 | 随绑定变更推进 | | ||
| 65 | + | ||
| 66 | +`jiuwenclaw_id` 用于 Manager 选择业务实例及其 `instance_link_binding` 记录。TLS 对端身份由实际客户端证书、角色指纹、`mtls_binding_id` 和 `mtls_binding_epoch` 共同确定。 | ||
| 67 | + | ||
| 68 | +多副本 Gateway 和 Runtime 共享同一套部署绑定材料；每个 Runtime 副本仍保留独立的进程 `instance_id`，因此证书身份不会替代现有的副本选主、日志和运行态标识。 | ||
| 69 | + | ||
| 70 | +## 4. 认证模型 | ||
| 71 | + | ||
| 72 | +### 4.1 TLS 层 | ||
| 73 | + | ||
| 74 | +服务端使用 TLS 1.2 或更高版本，并要求客户端提供证书。客户端完成以下校验： | ||
| 75 | + | ||
| 76 | +1. 服务端证书由部署信任 CA 签发； | ||
| 77 | +2. 访问主机名与证书 SAN 匹配； | ||
| 78 | +3. 服务端叶证书指纹属于目标角色； | ||
| 79 | +4. Manager 多实例请求还要求叶证书指纹与当前 `jiuwenclaw_id` 的绑定记录一致。 | ||
| 80 | + | ||
| 81 | +服务端从 TLS 连接中取得对端 DER 证书并计算 SHA-256 指纹。证书指纹决定调用方角色，请求 Header 不参与角色判定。 | ||
| 82 | + | ||
| 83 | +### 4.2 绑定层 | ||
| 84 | + | ||
| 85 | +非健康检查请求携带以下 Header： | ||
| 86 | + | ||
| 87 | +```text | ||
| 88 | +X-Jiuwenswarm-Mtls-Binding-Id: <mtls_binding_id> | ||
| 89 | +X-Jiuwenswarm-Mtls-Binding-Epoch: <mtls_binding_epoch> | ||
| 90 | +``` | ||
| 91 | + | ||
| 92 | +服务端将 Header 与本地已加载 profile 中的绑定标识和版本进行比较。只有 TLS 角色校验和绑定 Header 校验同时通过，请求才进入业务处理。 | ||
| 93 | + | ||
| 94 | +健康检查路径 `/healthz`、`/api/health`、`/api/v1/health`、`/api/v1/ready` 仍要求合法客户端证书，但不要求绑定 Header，便于组件在配置写入前完成可信探活。 | ||
| 95 | + | ||
| 96 | +### 4.3 角色权限 | ||
| 97 | + | ||
| 98 | +| 服务端 | 路径 | 允许的客户端角色 | | ||
| 99 | +|---|---|---| | ||
| 100 | +| Gateway | 健康检查 | `manager`、`gateway`、`runtime` | | ||
| 101 | +| Gateway | 其他内部接口 | `manager` | | ||
| 102 | +| Agent Runtime | 健康检查 | `manager`、`gateway`、`runtime` | | ||
| 103 | +| Agent Runtime | `route`、`touch`、`cleanup`、`config_refresh` | `gateway` | | ||
| 104 | +| Agent Runtime | 其他内部接口，包括 `config_sync` | `manager` | | ||
| 105 | +| AgentServer | 健康检查 | `manager`、`gateway`、`runtime` | | ||
| 106 | +| AgentServer | 业务接口 | `gateway` | | ||
| 107 | + | ||
| 108 | +认证失败统一返回 HTTP 403 和 `LINK_BINDING_MISMATCH`，并在服务端记录拒绝原因。 | ||
| 109 | + | ||
| 110 | +## 5. 证书与 profile | ||
| 111 | + | ||
| 112 | +### 5.1 签发结果 | ||
| 113 | + | ||
| 114 | +首次初始化生成一套十年有效期的材料： | ||
| 115 | + | ||
| 116 | +```text | ||
| 117 | +CA | ||
| 118 | +├── manager/ca.crt, tls.crt, tls.key, profile.json | ||
| 119 | +├── gateway/ca.crt, tls.crt, tls.key, profile.json | ||
| 120 | +├── runtime/ca.crt, tls.crt, tls.key, profile.json | ||
| 121 | +└── agentserver/ca.crt, tls.crt, tls.key, profile.json | ||
| 122 | +``` | ||
| 123 | + | ||
| 124 | +CA 私钥仅在签发过程中使用；持久化材料包含 CA 证书、四个角色的叶证书、角色私钥和 profile。 | ||
| 125 | + | ||
| 126 | +### 5.2 profile 内容 | ||
| 127 | + | ||
| 128 | +每个角色的 `profile.json` 包含： | ||
| 129 | + | ||
| 130 | +- `version`、`status` 和 `persistence`； | ||
| 131 | +- `mtls_deployment_id`、`mtls_binding_id`、`mtls_binding_epoch`； | ||
| 132 | +- 当前 `role`； | ||
| 133 | +- CA、证书和私钥的相对路径； | ||
| 134 | +- 四种角色的证书指纹集合； | ||
| 135 | +- Gateway、Runtime 等受管端点。 | ||
| 136 | + | ||
| 137 | +加载 profile 时会校验结构、角色、证书有效期、私钥与证书匹配关系、证书摘要及本地角色指纹。服务运行期间，每个请求都会重新检查 profile 状态、绑定版本、文件引用和材料摘要；检测到变更时要求进程使用新身份重新启动。 | ||
| 138 | + | ||
| 139 | +### 5.3 地址与 SAN | ||
| 140 | + | ||
| 141 | +Gateway 和 Runtime 证书包含 Service 名称、命名空间内 DNS、完整集群 DNS 和回环地址。AgentServer 证书包含 headless Service 下的通配 Pod DNS： | ||
| 142 | + | ||
| 143 | +```text | ||
| 144 | +*.<agentserver-headless-service>.<namespace>.svc.<cluster-domain> | ||
| 145 | +``` | ||
| 146 | + | ||
| 147 | +因此 Agent Runtime 可按以下稳定名称访问动态创建的 AgentServer Pod： | ||
| 148 | + | ||
| 149 | +```text | ||
| 150 | +https://<pod-id>.<headless-service>.<namespace>.svc.<cluster-domain>:<port> | ||
| 151 | +``` | ||
| 152 | + | ||
| 153 | +受管端点与 profile 中声明的 authority 匹配时，`enforce` 模式将其解析为 HTTPS，并保留路径和查询参数。外部地址在 `enforce` 模式下使用显式 `https://`。 | ||
| 154 | + | ||
| 155 | +## 6. 材料持久化与运行时注入 | ||
| 156 | + | ||
| 157 | +### 6.1 `link_binding_state` | ||
| 158 | + | ||
| 159 | +Gateway 数据库中的 `link_binding_state` 保存 Gateway 公开绑定状态及可恢复的完整四角色材料。部署初始化采用数据库中的唯一 Gateway 记录作为权威状态；重复部署读取并校验该记录，然后复用同一套材料。 | ||
| 160 | + | ||
| 161 | +Agent Runtime 数据库中的同名表只保存 Runtime 的公开绑定状态和 AgentServer Secret 引用。Runtime 启动时核对数据库状态、当前 profile 和 Runtime 证书指纹是否一致。 | ||
| 162 | + | ||
| 163 | +### 6.2 Kubernetes Secret | ||
| 164 | + | ||
| 165 | +部署集成把四个角色分别写入专属 Secret： | ||
| 166 | + | ||
| 167 | +```text | ||
| 168 | +jiuwenswarm-link-manager | ||
| 169 | +jiuwenswarm-link-gateway | ||
| 170 | +jiuwenswarm-link-runtime | ||
| 171 | +jiuwenswarm-link-agentserver | ||
| 172 | +``` | ||
| 173 | + | ||
| 174 | +Manager、Gateway 和 Agent Runtime 挂载各自的 Secret。Agent Runtime 创建 AgentServer Pod 时，仅向主容器注入 AgentServer Secret 和相关环境变量；普通 sidecar 不接收链路证书材料。 | ||
| 175 | + | ||
| 176 | +当 AgentServer 主容器以非 root 用户运行或设置 `fsGroup` 时，Runtime 使用内存卷及受限 helper 容器复制私有材料，并保持主容器读取路径不变。helper 删除全部 Linux capabilities，禁止提权，只挂载源 Secret 和目标内存卷。 | ||
| 177 | + | ||
| 178 | +## 7. Manager 多实例绑定 | ||
| 179 | + | ||
| 180 | +Manager 使用 `instance_info.jiuwenclaw_id` 选择业务实例，再从 `instance_link_binding` 取得该实例对应的： | ||
| 181 | + | ||
| 182 | +- `mtls_binding_id` 和 `mtls_binding_epoch`； | ||
| 183 | +- Gateway、Runtime 精确端点； | ||
| 184 | +- Manager、Gateway、Runtime、AgentServer 证书指纹； | ||
| 185 | +- 信任包引用和绑定状态。 | ||
| 186 | + | ||
| 187 | +同一 Gateway 或 Runtime authority 在 `bound` 状态下只能属于一个业务实例，数据库唯一索引在并发情况下保持该约束。相同绑定请求幂等返回当前记录；重新绑定要求使用更高的 `mtls_binding_epoch`。 | ||
| 188 | + | ||
| 189 | +共同部署的 Manager 可在 `instance_info` 中的 Gateway、Runtime 地址与本地 profile 声明完全一致时登记部署绑定。后续配置请求按 `jiuwenclaw_id` 读取绑定记录，并把目标地址、信任包、目标证书指纹和绑定 Header 作为同一个请求目标使用。 | ||
| 190 | + | ||
| 191 | +## 8. 模式 | ||
| 192 | + | ||
| 193 | +| 模式 | 行为 | | ||
| 194 | +|---|---| | ||
| 195 | +| `off` | 保持既有 HTTP 行为，不加载链路身份 | | ||
| 196 | +| `observe` | 校验本地材料并记录预检结果，业务传输保持 HTTP | | ||
| 197 | +| `enforce` | 启用 HTTPS、双向证书、角色指纹、绑定 Header 和 AgentServer Secret 注入 | | ||
| 198 | + | ||
| 199 | +模式由 `JIUWENSWARM_LINK_MTLS_MODE` 控制，默认值为 `off`。 | ||
| 200 | + | ||
| 201 | +## 9. 代码边界 | ||
| 202 | + | ||
| 203 | +| 代码位置 | 职责 | | ||
| 204 | +|---|---| | ||
| 205 | +| `foundation/openjiuwen_runtime/foundation/security/` | 证书签发、profile、TLS transport、材料持久化与部署准备 | | ||
| 206 | +| `applications/agent_runtime/src/agent_runtime/link_mtls.py` | Runtime 模式、端点、TLS 客户端/服务端参数和路由元数据 | | ||
| 207 | +| `applications/agent_runtime/src/agent_runtime/link_binding_state.py` | Runtime 公开绑定状态同步 | | ||
| 208 | +| `applications/agent_runtime/src/agent_runtime/resource_manager/k8s.py` | AgentServer DNS、Secret 与 helper 注入 | | ||
| 209 | +| `applications/manager/manager_server/src/manager_server/` | 多实例绑定模型、接口及 Manager mTLS 客户端 | | ||
| 210 | +| JiuwenSwarm Gateway、AgentServer 与部署脚本 | 对端守卫、HTTP/SSE 数据面及 Kubernetes Secret 安装 | | ||
| 211 | + | ||
| 212 | +接口级约束见 [`../api/link-mtls-contract.md`](../api/link-mtls-contract.md)，实现规格见 [`../spec/link-mtls.md`](../spec/link-mtls.md)。 | ||
| @@ -10,13 +10,16 @@ | |||
| 10 | |---|---|---| | 10 | |---|---|---| |
| 11 | | 本文件 | 架构一页纸 + 键前缀总览 + 测试/部署入口 | 先读 | | 11 | | 本文件 | 架构一页纸 + 键前缀总览 + 测试/部署入口 | 先读 | |
| 12 | | [service-core.md](service-core.md) | 组装(main)/CLI/配置(`AGENT_RUNTIME_*`)/错误码契约/字段分类/工具/部署 | 改装配、配置、错误契约、部署时 | | 12 | | [service-core.md](service-core.md) | 组装(main)/CLI/配置(`AGENT_RUNTIME_*`)/错误码契约/字段分类/工具/部署 | 改装配、配置、错误契约、部署时 | |
| 13 | +| [link-mtls.md](link-mtls.md) | HTTP/SSE 链路 mTLS：模式、profile、请求守卫、数据库与 AgentServer Pod 注入 | 改内部链路认证、证书材料或部署集成时 | | ||
| 13 | | [session-manager.md](session-manager.md) | SM:route/touch/config_sync/config_refresh/cleanup 编排、6 个 Lua、SM 键表 | 改会话编排/配置层时 | | 14 | | [session-manager.md](session-manager.md) | SM:route/touch/config_sync/config_refresh/cleanup 编排、6 个 Lua、SM 键表 | 改会话编排/配置层时 | |
| 14 | | [resource-manager.md](resource-manager.md) | RM:acquire/后台任务/K8s 适配、6 个 Lua、RM 键表 | 改 Pod 池/扩缩容/清理时 | | 15 | | [resource-manager.md](resource-manager.md) | RM:acquire/后台任务/K8s 适配、6 个 Lua、RM 键表 | 改 Pod 池/扩缩容/清理时 | |
| 15 | | [evaluation.md](evaluation.md) | 自评估:采样/评估两 job、`{agent_runtime:eval}` 键表、规则清单、LLM 降级矩阵 | 改自评估/趋势/报告时 | | 16 | | [evaluation.md](evaluation.md) | 自评估:采样/评估两 job、`{agent_runtime:eval}` 键表、规则清单、LLM 降级矩阵 | 改自评估/趋势/报告时 | |
| 16 | | [e2e-test-cases.md](e2e-test-cases.md) | 全部 e2e 用例的场景/输入/预期输出 | 写或跑 e2e 时 | | 17 | | [e2e-test-cases.md](e2e-test-cases.md) | 全部 e2e 用例的场景/输入/预期输出 | 写或跑 e2e 时 | |
| 17 | | [load-test.md](load-test.md) | 压测/浸泡工具 `scripts/load_test.py`:6 场景矩阵、判定层(客户端/可视化/ERROR 日志/巡检)、使用指南与已知容量语义 | 跑压测/浸泡、给工具加场景或判定时 | | 18 | | [load-test.md](load-test.md) | 压测/浸泡工具 `scripts/load_test.py`:6 场景矩阵、判定层(客户端/可视化/ERROR 日志/巡检)、使用指南与已知容量语义 | 跑压测/浸泡、给工具加场景或判定时 | |
| 18 | | `../api/config-plane-api.md` | 配置面对外接口文档(config_sync/config_refresh/visualization:字段表+curl+真实返回示例) | 给调用方(Claw Manager/运维/可视化前端)交付接口契约时 | | 19 | | `../api/config-plane-api.md` | 配置面对外接口文档(config_sync/config_refresh/visualization:字段表+curl+真实返回示例) | 给调用方(Claw Manager/运维/可视化前端)交付接口契约时 | |
| 20 | +| `../api/link-mtls-contract.md` | HTTPS/mTLS、证书角色、绑定 Header、Manager 绑定接口契约 | 对接 Gateway、Manager 或 AgentServer 时 | | ||
| 19 | | `../design/Agent-Runtime-HLD.md` | 架构总览/接口契约/场景 A–N/Redis 键表(语义权威) | 语义不确定时 | | 21 | | `../design/Agent-Runtime-HLD.md` | 架构总览/接口契约/场景 A–N/Redis 键表(语义权威) | 语义不确定时 | |
| 22 | +| `../design/http-sse-link-mtls-design.md` | 内部链路 mTLS 的身份、信任、持久化和多实例设计 | 理解安全边界和跨组件关系时 | | ||
| 20 | | `../design/session-manager-design.md` | SM 详细设计(6 个 Lua 全文) | 深挖 SM 设计动机 | | 23 | | `../design/session-manager-design.md` | SM 详细设计(6 个 Lua 全文) | 深挖 SM 设计动机 | |
| 21 | | `../design/resource-manager-design.md` | RM 详细设计(6 个 Lua 全文) | 深挖 RM 设计动机 | | 24 | | `../design/resource-manager-design.md` | RM 详细设计(6 个 Lua 全文) | 深挖 RM 设计动机 | |
| 22 | 25 | ||
| @@ -6,3 +6,4 @@ | |||
| 6 | - [3. Agent部署](3.%20Agent部署.md) | 6 | - [3. Agent部署](3.%20Agent部署.md) |
| 7 | - [4. Agent接入](4.%20Agent接入.md) | 7 | - [4. Agent接入](4.%20Agent接入.md) |
| 8 | - [5. 安全模块](5.%20安全模块.md) | 8 | - [5. 安全模块](5.%20安全模块.md) |
| 9 | +- [内部链路 mTLS 接入](内部链路mTLS接入.md) | ||
| @@ -17,7 +17,7 @@ JIUWENSWARM_LINK_MTLS_MODE=enforce | |||
| 17 | 17 | ||
| 18 | `observe` 只预检本地材料，不切换协议、不代表已经开启认证；不能用 `true`、`false` 或 `on` 代替枚举值。 | 18 | `observe` 只预检本地材料，不切换协议、不代表已经开启认证；不能用 `true`、`false` 或 `on` 代替枚举值。 |
| 19 | 19 | ||
| 20 | -由部署工具为各组件生成并注入角色材料，无须另填 CA/CERT/KEY 路径、绑定 ID、epoch 或手写 profile。详细安装步骤、客户管理服务示例、数据结构与运维限制见配套 JiuwenSwarm 仓库的 `docs/zh/HTTP-SSE链路mTLS部署配置.md`。 | 20 | +由部署工具为各组件生成并注入角色材料，无须另填 CA/CERT/KEY 路径、绑定 ID、epoch 或手写 profile。详细安装步骤、客户管理服务示例和数据结构见配套 JiuwenSwarm 仓库的 `docs/zh/HTTP-SSE链路mTLS部署配置.md`。 |
| 21 | 21 | ||
| 22 | 无内置 Manager 交付采用 `APPLY_PATCH=true` 和 `up gateway web runtime`；部署工具使用 manager 角色证书下发初始配置。客户自己的管理服务也是 manager 角色，不要求部署 Manager Server、Manager Web 或 Identity Center。 | 22 | 无内置 Manager 交付采用 `APPLY_PATCH=true` 和 `up gateway web runtime`；部署工具使用 manager 角色证书下发初始配置。客户自己的管理服务也是 manager 角色，不要求部署 Manager Server、Manager Web 或 Identity Center。 |
| 23 | 23 | ||
| @@ -27,23 +27,21 @@ Manager 的服务证书不绑定某一个 `instance_info.jiuwenclaw_id`。Manage | |||
| 27 | 27 | ||
| 28 | 自动登记和显式绑定均只接受无凭据、无路径、无查询参数的精确 Gateway/Runtime 地址，并要求地址与该 `instance_info` 记录一致，避免把相似 URL 或其他实例的地址误认成当前部署。多实例请求先按业务 `jiuwenclaw_id` 选择绑定记录，再把该记录的 mTLS 绑定 Header、目标地址、目标 CA 和目标叶证书指纹作为同一个目标对象使用；不能把一个实例的 Header 与另一个实例的 TLS 目标混用。业务 ID 不放入 mTLS Header。 | 28 | 自动登记和显式绑定均只接受无凭据、无路径、无查询参数的精确 Gateway/Runtime 地址，并要求地址与该 `instance_info` 记录一致，避免把相似 URL 或其他实例的地址误认成当前部署。多实例请求先按业务 `jiuwenclaw_id` 选择绑定记录，再把该记录的 mTLS 绑定 Header、目标地址、目标 CA 和目标叶证书指纹作为同一个目标对象使用；不能把一个实例的 Header 与另一个实例的 TLS 目标混用。业务 ID 不放入 mTLS Header。 |
| 29 | 29 | ||
| 30 | -既有 ID 和 mTLS ID 不混用：`jiuwenclaw_id` 仍是 Manager 业务实例主键，`GATEWAY_INSTANCE_ID` 仍服务于 Gateway 主备/Redis，Runtime `instance_id` 仍是进程或副本身份。新机制只新增内部 `mtls_deployment_id`、`mtls_binding_id` 和 `mtls_binding_epoch`。`mtls_deployment_id` 由部署工具首次随机生成并持久化，不作为客户配置或请求 Header。 | 30 | +`jiuwenclaw_id` 是 Manager 业务实例主键，`GATEWAY_INSTANCE_ID` 服务于 Gateway 主备和 Redis，Runtime `instance_id` 表示进程或副本。mTLS 使用内部的 `mtls_deployment_id`、`mtls_binding_id` 和 `mtls_binding_epoch`；`mtls_deployment_id` 由部署工具首次随机生成并持久化。 |
| 31 | 31 | ||
| 32 | ## 运行与数据原理 | 32 | ## 运行与数据原理 |
| 33 | 33 | ||
| 34 | - Runtime 的内部 API 在 enforce 下要求 HTTPS/mTLS；会话 route、touch、cleanup、config_refresh 接受绑定的 gateway 角色，管理配置接口接受 manager 角色。 | 34 | - Runtime 的内部 API 在 enforce 下要求 HTTPS/mTLS；会话 route、touch、cleanup、config_refresh 接受绑定的 gateway 角色，管理配置接口接受 manager 角色。 |
| 35 | -- 除 TLS CA/SAN 验证外，还核验对端角色指纹、`mtls_binding_id` 和 `mtls_binding_epoch`。Manager 的 `jiuwenclaw_id` 保留在原有业务 API 中，不作为证书身份；请求头不能替代实际 TLS 对端证书。 | 35 | +- 除 TLS CA/SAN 验证外，还核验实际 TLS 对端证书的角色指纹、`mtls_binding_id` 和 `mtls_binding_epoch`。Manager 的 `jiuwenclaw_id` 保留在原有业务 API 中，用于选择当前实例绑定。 |
| 36 | - Runtime 创建 AgentServer 时，向其主容器注入 AgentServer 专用 Secret，使用 headless Service 下的 Pod DNS；不向 JiuwenBox 注入证书。不要求为动态 Pod IP 逐个签发证书。 | 36 | - Runtime 创建 AgentServer 时，向其主容器注入 AgentServer 专用 Secret，使用 headless Service 下的 Pod DNS；不向 JiuwenBox 注入证书。不要求为动态 Pod IP 逐个签发证书。 |
| 37 | -- 同一绑定的 AgentServer 可共享 AgentServer 角色证书，不代表每个 Pod 具有独立证书身份。Gateway、Runtime、manager 使用各自独立的私钥。 | 37 | +- 同一绑定的 AgentServer 使用 AgentServer 角色证书；Gateway、Runtime、manager 使用各自独立的私钥。 |
| 38 | - Gateway 数据库的 `link_binding_state` 保存可恢复的完整角色材料，Runtime 同名表只保存公开状态及 AgentServer Secret 引用。实际运行依赖角色专属的 Secret/文件，不是直接把整套数据库材料交给每个服务。 | 38 | - Gateway 数据库的 `link_binding_state` 保存可恢复的完整角色材料，Runtime 同名表只保存公开状态及 AgentServer Secret 引用。实际运行依赖角色专属的 Secret/文件，不是直接把整套数据库材料交给每个服务。 |
| 39 | -- 首次随机签发十年证书，普通重部署复用已入库材料，不重签、不延长有效期；不一致、已撤销、过期或材料残缺时停止，不回退明文。 | 39 | +- 首次随机签发十年证书并写入数据库；部署时校验数据库、Secret 和 profile 的材料及绑定版本一致性。 |
| 40 | 40 | ||
| 41 | -## 交付与安全约束 | 41 | +## 部署与运行要求 |
| 42 | 42 | ||
| 43 | 1. Gateway、Runtime、AgentServer、部署工具及 Runtime foundation 需要使用配套版本。镜像构建应包含 `foundation[link-mtls]` 所声明的 HTTP/TLS 依赖；不能仅给旧镜像增加环境变量即视为功能可用。 | 43 | 1. Gateway、Runtime、AgentServer、部署工具及 Runtime foundation 需要使用配套版本。镜像构建应包含 `foundation[link-mtls]` 所声明的 HTTP/TLS 依赖；不能仅给旧镜像增加环境变量即视为功能可用。 |
| 44 | -2. 不新增独立证书管理 Pod、在线 CA 或 Runtime 续期任务；非 root/权限适配场景可在现有 Pod 中使用仅复制材料的初始化/同步辅助容器。 | 44 | +2. 数据库保存部署证书材料，Kubernetes Secret 保存各工作负载的角色材料；需按私钥数据保护数据库账号、备份、部署权限和 Secret RBAC。 |
| 45 | -3. 私钥材料可从 Gateway 数据库恢复，需保护数据库账号、备份、部署权限和 Secret RBAC；应用未额外加密材料列，Secret Base64 也不是加密。 | 45 | +3. 受管地址在 `enforce` 下解析为 HTTPS；外部地址使用显式 HTTPS 并通过 CA、SAN 和目标指纹验证。 |
| 46 | -4. 没有自动续期、跨组件一键换证/撤销/重绑定或旧材料自动导入。修改本地 profile、单个 Secret、某一数据库字段不构成完整集群维护流程。 | 46 | +4. 多实例 Manager 发起配置请求时，按 `jiuwenclaw_id` 同时选择绑定 Header、信任包、目标地址和目标叶证书指纹。 |
| 47 | -5. 受管地址在 enforce 下解析为 HTTPS；外部地址须显式 HTTPS 且通过验证。此机制不会改写模型 API、用户登录或外部 A2A 的协议。 | 47 | +5. 服务在启动时读取 mTLS 模式和 profile；部署配置更新通过对应工作负载的重新部署生效。 |
| 48 | -6. 从已启用的部署回退到 off 需协调全部相关组件及存量 AgentServer；仅修改 `.env` 不会立即改变运行中的服务。 | ||
| 49 | -7. 多实例 Manager 发起配置写请求时必须按 `jiuwenclaw_id` 同时选择绑定 Header、信任包和目标叶证书指纹；只信任全局 CA、却不核对该实例登记的目标指纹，不属于完整绑定校验。 | ||