主题
实施路线与参考部署
一句话：落地不是一次性把所有组件装齐，而是按依赖顺序交付六个可独立验收的切片；每一片都要能单独回滚，否则一次失败会把整个平台拖回原点。
平台落地的通用取舍见 落地路线与关键取舍；本篇只讲这套开源组合的部署形态、启动顺序与运维动作。
为什么需要
“大爆炸”式上线通常死在四个地方：
- 组件全装好了，但身份没打通，所有请求都算到同一个默认租户；
- 先上了市场，却没有稳定供给，门户里只有两个演示产品；
- 直接按“生产高可用”部署，Helm 默认单副本、
Recreate更新，升级即中断； - 把预览版组件放进关键路径，出问题时没有降级路径。
正确的做法是把平台切成一个设计切片（S0）、六个交付切片（S1–S6）和两个验证/改进切片（S7–S8），每个切片有独立的验收标准与回滚方式；切片之间只通过已经冻结的接口连接。
核心机制
一、切片划分：S0–S8
| 切片 | 交付物 | 依赖 | 验收 | 回滚 |
|---|---|---|---|---|
| S0 架构设计 | 三平面归属、权限边界、影响半径、Release 六要素模板 | 业务场景 | 每个 Agent 能回答"长在哪、谁能改、失败谁恢复" | 回到上一版设计基线 |
| S1 身份与入口 | Higress 路由、消费者、配额；账号到主体的映射 | 账号体系、证书 | 伪造租户被拒，配额可生效 | 关路由，回退到旧入口 |
| S2 内核与状态 | 单 Agent、Redis 状态、对象存储快照 | Redis、S3 兼容存储 | 换节点会话能续，工具结果可追 | 切回无状态演示模式 |
| S3 控制面 | Service 目录、Session API、Endpoint | PostgreSQL | Dataplane 重启后会话继续 | 停用新端点，保留旧入口 |
| S4 任务 | Scheduler、Outbox、LiteTopic、Worker | RocketMQ 5.5、RocksDB | 重投只执行一次，断线能续 | 关闭异步通道，退回同步调用 |
| S5 供给与路由 | HiMarket、Nacos、HiRoute、Jev | Nacos、网关 | 订阅/发现/准入分别可验证 | 直接从 Nacos 手工配置端点 |
| S6 证据与治理 | OTel、事件日志、黄金集、门禁 | Collector、评测环境 | 任取一条回答能还原 span 树 | 保留原始日志，暂停自动门禁 |
| S7 仿真台 | 场景、Manifest、Run、证据包、用户/环境模拟器 | S2、S5 | SUT 边界不被替换；证据不足输出"不可判定" | 停用仿真入口，保留场景与记录 |
| S8 调优闭环 | Trajectory、Pipeline、Dataset、Evaluator、Experiment、Release 门禁 | S4、S6、S7 | 轨迹→题→实验→Release 可追；退化能发现 | 回退到上一 Release，暂停自动门禁 |
S7 与 S8 的定义、表结构与接缝见 25、26；全量对标见 24。
每个切片控制在两到四周，交付后至少稳定运行一周再开下一个。S4 之前的系统可以同步执行，S4 之后才真正需要队列；不要为了“架构完整”提前引入异步。
二、三种参考部署形态
| 形态 | 组成 | 适合 | 关键限制 |
|---|---|---|---|
| 单机 Compose | 网关、控制面、数据面、调度器、PostgreSQL 同机 | 演示、联调、单团队试点 | 无 HA，重启即中断 |
| 小规模 K8s | 控制面与数据面分 Deployment，PG 用托管或主从 | 单租户/少租户生产 | Helm 默认单副本，升级需维护窗口 |
| 多租户生产 | 网关多副本、控制面多副本、数据面 HPA、PG 主从、MQ 集群、Nacos 集群 | 多租户、按量计费 | 跨面契约与迁移必须自行验证 |
部署顺序是依赖顺序：对象存储与数据库 → Nacos → 控制面 → 数据面 → 调度与队列 → 网关 → 渠道。网关最后接，是因为它一上线就会有真实流量；渠道再最后，是因为它会把外部身份带进来。
三、容量估算：先算三类资源
| 资源 | 估算方式 | 常见误判 |
|---|---|---|
| 数据面并发 | 同时执行的 Turn 数 ≈ 会话活跃数 × 单轮时长 / 间隔 | 按总会话数配 Pod，峰谷差被抹平 |
| 状态存储 | 单会话状态通常几十 KB 到几 MB；按活跃会话 × 保留期 | 把历史会话全留在 Redis |
| 消息通道 | 活跃会话数决定 LiteTopic 数；单通道串行决定 Worker 槽位 | 按消息总量估并发，忽略单通道上限 |
| 对象存储 | 产物与快照按任务数 × 平均大小 × 保留期 | 忘记快照会被反复重写 |
| 数据库连接 | 控制面与数据面分别计连接池，预留运维连接 | 两面共用一个小连接池 |
| 观测存储（Langfuse 栈） | 官方最小足迹 ≈9C/21.5GiB（Web 2C/4Gi + Worker 2C/4Gi + Postgres 2C/4Gi + Redis 1C/1.5Gi + ClickHouse 2C/8Gi + S3 兼容存储）；单机起步 ≥4C/16GiB/100GiB；存量按 QPS×span 数×保留天数估（ClickHouse 单分片可到 TB 级 trace） | 漏算 ClickHouse 大盘与 S3 对象层；观测面故障不得阻塞业务主链路（投递异步/丢弃策略） |
LiteTopic 的容量要按“通道数”而不是“消息数”规划：百万级通道是它的设计目标，但单通道只有一个队列，吞吐上限由单会话串行决定。
四、发布与回滚
- 定义与运行分离：Agent 发布产生不可变版本，Session 创建时冻结；回滚切 Endpoint release，不改定义；
- 数据库迁移向前兼容：先加列后写、先双写后切读；迁移脚本与版本一起评审；
- 网关蓝绿：路由规则与 Wasm 插件分开发布，插件回滚不应要求重启数据面；
- 队列兼容：消息信封只增字段不删字段；消费者先升级，生产者后升级；
- 预览组件隔离：Hosted Runtime、Service 的预览能力放在非关键路径，准备手工降级流程。
回滚演练要覆盖三种：单组件回滚、整切片回滚、数据回滚（恢复到某个 revision 的会话状态）。只演练第一种，事故时仍然不会做后两种。
五、运维 Runbook：五种高频故障
| 故障 | 现象 | 判断 | 处置 |
|---|---|---|---|
| Dataplane 重启 | 会话卡在“执行中” | 位点是否已提交、租约是否过期 | 重连后从位点继续；未提交则按幂等键重投 |
| 通道积压 | 队列等待升高，单会话变慢 | 是单通道慢还是全局慢 | 单通道暂停/扩容 Worker；全局查模型与工具 |
| PostgreSQL 故障 | 控制面 5xx、会话无法创建 | 主库还是连接池 | 切主；只读模式下降级目录查询 |
| 模型网关 429 | 错误率与首 Token 延迟同时上升 | 租户配额还是上游限流 | 按候选回退；必要时降级模型档位 |
| Nacos 不可用 | 新实例发现失败，旧实例仍可调用 | 客户端是否命中本地快照 | 依赖本地快照继续服务，恢复后对账 |
| ClickHouse 故障 | 观测查询变慢/报错，trace 写入积压 | 磁盘水位还是副本分片 | 写侧先落 Redis/S3 兜底或异步丢弃；查询降级到 PG 短窗指标；恢复后回灌补写（40 篇 §6.8 纳入平台自身可观测） |
| Langfuse 故障 | trace 缺失、观测面 5xx | 业务主链路是否受影响（必须不受影响） | 投递侧异步/丢弃策略保业务；恢复后对账缺口，评估回填 |
| PG 迁移故障 | 迁移脚本执行中断、加列/双写中途失败 | 迁移事务已提交与否、新旧结构兼容性 | 先加列后写、先双写后切读；失败即回滚迁移版本，不手工乱改表结构；回滚演练覆盖数据回滚（revision 级会话恢复） |
| 预览组件异常 | Hosted 任务失败、恢复不可用 | 适配器能力还是服务端 | 切回 Managed 或手工执行，保留任务记录 |
Runbook 要写到“谁执行、执行什么命令、验证什么指标”，而不是“检查服务状态”。
最小上手
用四周做一个最小闭环，每周一个可演示的切片：
text
第 1 周：账号 → Higress 消费者 → 单 Agent 同步调用；验收租户归属与配额。
第 2 周：接 Redis 与对象存储；验收换节点续跑与产物可追。
第 3 周：接 Service 与 PostgreSQL；验收版本冻结与会话恢复。
第 4 周：接触发、Outbox、LiteTopic 与 OTel；验收重投幂等与 trace 串链。四周之后再评估是否需要市场、Nacos 与本地路由；没有多供给方时，市场只会增加审批环节。
生产动作
- 一份部署清单：端口、镜像 tag、配置项、依赖版本、证书有效期，全部版本化。
- 备份分开做：PostgreSQL 做 PITR，对象存储开版本化，Nacos 导出配置，Vault 单独备份；恢复要演练。
- 容量按月复算：会话数、Token、通道数、快照大小四条曲线一起看，避免只扩计算不扩存储。
- 变更窗口：控制面与网关分开变更；升级前先 drain Runtime Host，等在途任务结束。
- 降级开关：模型回退、异步转同步、Hosted 转手工、市场转直连，四个开关要能独立操作。
- 验收留证：每个切片的验收结果、trace 样例、回滚记录归档，作为下一阶段的基线。
边界
- 参考部署不是生产承诺：Helm 默认单副本、预览版接口都可能变化；HA 与 SLA 要自己验证。
- 切片不是团队边界：一个团队可以负责多个切片，但每个切片必须有唯一验收人。
- 不要提前上多租户：单租户跑稳再拆命名空间，否则隔离问题会和功能问题混在一起。
- 容量估算不是精确值：用它做数量级判断与扩容触发线，不要当账单预测。
- 回滚不是万能：涉及外部副作用的动作（已发出的消息、已执行的退款）无法回滚，只能补偿。
讲清楚
落地要按依赖切片：架构设计（S0）→ 身份与入口 → 内核与状态 → 控制面 → 任务 → 供给与路由 → 证据与治理 → 仿真（S7）→ 调优（S8）。每片独立验收、独立回滚，稳定一周再开下一片。
部署顺序是存储与数据库 → 注册中心 → 控制面 → 数据面 → 队列 → 网关 → 渠道；容量按活跃会话、通道数、快照与连接池四条线估算，不要按消息总量拍脑袋。
判断路线是否成立，看四条：每片能单独回滚、升级有维护窗口、备份能恢复、四个降级开关都能独立操作。
适用：2026 年开源 Agent 平台组件 / AgentScope Service 2.1.0-BETA1 | 初稿 2026-10