主题
多租户配置与跨副本广播方案
1. 方案摘要
本方案把配置解析、快照、事务更新和跨副本传播拆成四个阶段。公共配置库或文件是事实源，ConfigStore 管理当前 resolved 快照，广播只携带租户和版本提示，接收副本重新读取并 reconcile，从而避免把 Redis 消息内容当成完整配置。
2. 设计目标与非目标
设计目标
- 统一文件配置和多租户公共配置的解析语义。
- 支持 Agent、Model、Channel 等热域安全更新。
- 保证多副本最终收敛且不影响进行中的任务。
非目标
- 不把所有配置都承诺为热更新。
- 不通过广播消息直接传输密钥和完整配置。
- 不让单个副本修改其它副本的本地运行态。
3. 架构范围与视图
配置从哪里读取、如何形成租户快照、热更新怎样传播到其它副本？
本图聚焦配置事实源与传播，不展开扩展文件同步和数据库迁移流程。
图中绿色实线表示当前能力，紫色虚线表示规划或待完善能力。图片用于建立空间关系，本文正文定义方案语义、边界和落地规则。
4. 组件与责任边界
| 组件 | 责任 |
|---|---|
| 配置来源 | 文件模式读取 config.json；数据库多租户模式读取公共配置库。 |
| 环境变量引用 | 连接串和密钥通过 ${VAR} 在解析阶段注入。 |
| ConfigStore | 保存当前 resolved 快照，transact 完成校验、构建 shadow、swap 和 cleanup。 |
| bootCfg | 启动时冻结的冷配置快照。 |
| Reconciler | Agent、Model、Channel 等热域按事务应用。 |
| BroadcastBus | 数据库多租户模式下通过 Redis 或公共库事件表通知其它副本重新读取。 |
| Tenant Runtime | 每个租户维护独立配置、路径与领域服务。 |
组件之间只通过明确的输入、输出和生命周期契约协作。上层可以编排下层能力，但不能绕过下层的权限、租户和状态边界直接读写内部对象。
5. 核心设计决策
- 配置解析先合并基础值、租户覆盖和环境变量引用，再生成 resolved snapshot。
- transact 采用校验、shadow 构建、原子 swap、清理和广播。
- 广播携带 tenantCode + version，接收方按版本重新读取事实源。
这些决策共同保证：入口可以替换、执行可以迁移、状态可以恢复，而不会改变用户可见的任务和会话语义。
6. 关键流程与时序
主流程
- 读取文件或公共配置库
- 合并租户覆盖和环境变量
- 冻结 bootCfg 并建立 ConfigStore
- 管理 API 发起 transact
- 本副本验证并原子 swap
- 广播 tenantCode + version
- 其它副本重新读取并 reconcile
流程解释
流程中的每一步都应产生可追踪的上下文：租户、Agent、Chat、Task、运行副本和结果引用。过程事件用于向用户反馈进度，终态写入和结果归档必须在事实源更新后再对外确认。
7. 数据、一致性与状态管理
- Redis pub/sub 是低延迟通知，公共库事件表是兜底通知，配置库是最终事实源。
- 冷配置变更通过重启或滚动替换生效。
- 进行中任务继续使用开始时的 Agent/Model/Tool 快照。
当前专题的关键约束
- Redis 不是配置事实源。
- 身份认证、数据库连接、租户布局和运行角色属于冷配置。
- 进行中任务继续使用入口时固化的快照。
8. 异常、恢复与安全边界
- 解析、Schema 或业务校验失败时不替换当前快照。
- 广播丢失时由事件表或下一次 reconcile 补偿。
- 副本应用失败保留旧快照并记录版本差异，不能报告已完成。
异常处理遵循“先阻止错误扩散，再保留可恢复状态，最后由明确的补偿动作完成收口”。任何重试都必须具备幂等条件，任何恢复都必须重新校验租户、权限、版本和 ownership。
9. 部署与扩展边界
- 单副本可使用文件配置和 SQLite。
- 多租户多副本使用公共配置库、Redis 和副本本地 ConfigStore。
部署形态可以变化，但不能把本地内存、临时文件或单副本事件队列当作跨副本事实源。需要横向扩展的能力应先明确共享状态、路由键、健康状态和故障补偿方式。
10. 当前能力与演进计划
当前已落地
- ConfigStore 事务与 Agent / Model / Channel 热配置
- Redis pub/sub 与公共库广播兜底
规划或待完善
- 本专题暂未列出独立规划项。
演进方向
- 增加配置版本审计、灰度租户、回滚和变更影响预览。
- 为冷配置滚动重启建立自动编排和 readiness 协同。
11. 方案验收要点
- 任意副本最终能通过版本重新读取到相同 resolved 配置。
- 广播消息缺失不会导致永久不一致。
- 密钥不出现在广播载荷和文档化配置快照中。
验收时应同时检查正常链路、重复操作、空态或拒绝态、依赖不可用和副本切换，不能只验证图中最短路径。