主题
Gateway / Runtime 多副本部署方案
1. 方案摘要
本方案将入口接收与 Agent 执行分成 Gateway、Runtime 两类角色，并通过稳定路由键、内部派发和共享事实源支持横向扩展。组合角色保留作为单进程交付形态，角色拆分用于生产容量、故障隔离和独立扩缩容。
2. 设计目标与非目标
设计目标
- 让 IM、OpenAPI、Schedule 与 Web/SSE 获得适合自身的路由路径。
- 保证同一 Chat 的路由稳定和 ownership 可验证。
- 明确哪些状态必须外置，哪些状态只能是副本本地运行态。
非目标
- 不把 Gateway 变成 Agent 执行节点。
- 不依赖 sticky session 代替 ownership fence。
- 不在本方案中承诺完整 K8s 清单和容量数值。
3. 架构范围与视图
生产角色如何拆分，入口、内部通信、共享状态和组合部署如何对应？
本图描述当前角色拆分和内部协议；K8s manifests 与完整演练仍属于规划交付项。
图中绿色实线表示当前能力，紫色虚线表示规划或待完善能力。图片用于建立空间关系，本文正文定义方案语义、边界和落地规则。
4. 组件与责任边界
| 组件 | 责任 |
|---|---|
| Ingress | 按 X-Route-Chat-Id 对 Runtime 请求做稳定路由。 |
| Gateway | 承载 IM Connector、OpenAPI、Scheduler、RuntimeClient、事件回调和副本监控。 |
| Runtime | 承载 Web / SSE、内部 dispatch、Agent、Session、Memory、File 与 Plugin。 |
| 内部派发 | Gateway 通过带内部鉴权的 HTTP 调用 Runtime。 |
| 事件回调 | Runtime 将 IM / OpenAPI 过程事件回调到 Gateway。 |
| 共享存储 | MySQL 负责业务状态和 owner，Redis 负责缓存 / 广播 / 租约，对象存储负责文件与归档。 |
| 组合角色 | 单个进程可以同时承载 Gateway 与 Runtime 能力。 |
组件之间只通过明确的输入、输出和生命周期契约协作。上层可以编排下层能力，但不能绕过下层的权限、租户和状态边界直接读写内部对象。
5. 核心设计决策
- Web/SSE 直达 Runtime，避免流式连接经过 Gateway 二次转发。
- Gateway 通过内部鉴权 HTTP 派发非 Web 任务并接收过程事件。
- MySQL、Redis 和对象存储分别承载业务事实、通知/租约和文件归档。
这些决策共同保证：入口可以替换、执行可以迁移、状态可以恢复，而不会改变用户可见的任务和会话语义。
6. 关键流程与时序
主流程
- Web 请求由 Ingress 路由到 Runtime 并保持本地 SSE
- IM / OpenAPI / Schedule 进入 Gateway
- Gateway 选择稳定路由键并内部派发
- Runtime claim ownership 后执行
- Runtime 事件回调 Gateway
- 共享状态写入外部基础设施
流程解释
流程中的每一步都应产生可追踪的上下文：租户、Agent、Chat、Task、运行副本和结果引用。过程事件用于向用户反馈进度，终态写入和结果归档必须在事实源更新后再对外确认。
7. 数据、一致性与状态管理
- X-Route-Chat-Id 只提供稳定路由提示，最终写入仍由 ownership guard 保护。
- 副本心跳、任务数和维护状态写入共享副本记录。
- 本地 Engine Map、EventBus 和文件目录不能作为跨副本事实源。
当前专题的关键约束
- Web Chat 不经 Gateway 转发 SSE。
- 同一 chatId 的路由键必须稳定。
- 跨副本不能依赖 Engine Map、EventBus 或本地文件作为事实源。
8. 异常、恢复与安全边界
- Gateway 派发失败时保留可重试任务，不在 Gateway 伪造 Runtime 终态。
- Runtime 失联由 monitor 完成 fencing 和 Chat 收口，再进入恢复派发。
- Ingress 路由变化不能绕过 owner CAS。
异常处理遵循“先阻止错误扩散，再保留可恢复状态，最后由明确的补偿动作完成收口”。任何重试都必须具备幂等条件，任何恢复都必须重新校验租户、权限、版本和 ownership。
9. 部署与扩展边界
- 本地或小规模环境使用组合部署。
- 生产环境按 Gateway、Runtime、数据库、Redis、对象存储分别扩缩容。
- K8s readiness 必须包含副本身份和心跳有效性。
部署形态可以变化，但不能把本地内存、临时文件或单副本事件队列当作跨副本事实源。需要横向扩展的能力应先明确共享状态、路由键、健康状态和故障补偿方式。
10. 当前能力与演进计划
当前已落地
- 组合 / Gateway / Runtime 三种运行角色
- 内部派发、事件回调、ownership、heartbeat 与 replica monitor
规划或待完善
- K8s manifests
- 多 Runtime 故障演练与完整运维流程
- 跨副本实时事件适配
演进方向
- 补齐 manifests、容量基线、故障演练和跨副本实时事件适配。
- 按入口类型和租户负载拆分独立扩缩容策略。
11. 方案验收要点
- Web SSE 全程保持在 Runtime，不经 Gateway 回调。
- Gateway 重启不丢失已持久化任务。
- Runtime 副本失联后旧 owner 不能继续覆盖新状态。
验收时应同时检查正常链路、重复操作、空态或拒绝态、依赖不可用和副本切换，不能只验证图中最短路径。