专栏第 11 篇

目标：把“能跑”的 Agent 系统，变成“可控上线、可回滚、可持续运营”的生产系统。

---

一、问题描述：为什么很多 Agent 项目都倒在上线前后 2 周？

在开发阶段，系统通常能稳定跑 demo；但一到真实流量就暴露问题：

• 配置漂移：测试环境可用，生产环境失效；
• 突发流量：接口超时、重试风暴、服务雪崩；
• 安全缺口：工具调用越权、日志泄露敏感信息；
• 成本失控：token 与外部服务费用迅速上升；
• 缺少回滚：一旦发布异常，无法快速止损。

结论：上线不是“部署一次”，而是“通过一套门禁系统”。

---

二、先给结论：上线必须通过 6 大门禁域

上线前请按这 6 个维度逐项打勾：

1. 配置治理（Configuration）
2. 弹性与限流（Resilience & Rate Limit）
3. 安全与权限（Security & Access）
4. 成本与配额（Cost & Quota）
5. 可观测与告警（Observability & Alerting）
6. 发布与回滚（Release & Rollback）

任一核心门禁未通过：No-Go。

---

三、门禁域 #1：配置治理（防“环境正确性”事故）

3.1 必做项

• 配置分层：dev / staging / prod 明确隔离；
• 敏感信息（API Key/Token）统一走 Secret 管理；
• 配置版本化：每次改动可追溯；
• 启动前配置自检：缺项即拒绝启动。

3.2 建议实践

• 使用 .env.example + 配置 schema 校验；
• 在 CI 增加配置完整性检查；
• 禁止在代码中硬编码密钥与 endpoint。

---

四、门禁域 #2：弹性与限流（防流量冲击）

4.1 最小要求

• 接口限流：按用户 / IP / API Key 多维限流；
• 全链路超时预算：请求级 + 步骤级；
• 重试策略：只对可恢复错误重试，最多 2 次；
• 熔断机制：下游异常时快速失败并降级。

4.2 推荐阈值（可按业务调）

• 用户级 QPS：2~5
• IP 级突发桶：20~50
• 请求总超时：8~15s
• 熔断打开：失败率 > 50% 且样本 >= 20

---

五、门禁域 #3：安全与权限（防越权与泄露）

5.1 工具安全边界

• 工具白名单：仅注册工具可调用；
• 参数白名单：输入字段严格校验；
• 风险工具二次确认（写入、删除、外发类操作）。

5.2 数据安全

• 日志脱敏：token、手机号、邮箱、证件号统一掩码；
• 最小权限原则：服务账号仅授予必要权限；
• 审计留痕：关键操作必须记录 who/when/what。

---

六、门禁域 #4：成本与配额（防“可用但亏损”）

6.1 成本控制策略

• 模型分级：普通请求默认低成本模型；
• token 预算：单请求上限 + 日预算上限；
• 缓存优先：高频问答结果缓存；
• 检索裁剪：限制注入 chunk 数量与长度。

6.2 必监控指标

• cost_per_request
• daily_cost_total
• avg_input_tokens / avg_output_tokens
• cache_hit_ratio

---

七、门禁域 #5：可观测与告警（防“出事后看不见”）

7.1 全链路可观测最小集

• 日志：结构化 JSON，统一 request_id/trace_id；
• 指标：成功率、延迟、降级率、超时率、熔断次数；
• Trace：关键步骤 span（规划、工具、生成、返回）。

7.2 告警建议

至少配置以下 4 类告警：

1. 成功率告警（如 5 分钟窗口 < 97%）
2. 延迟告警（p95 超阈值）
3. 成本告警（日成本异常上涨）
4. 降级告警（degrade_rate 持续上升）

---

八、门禁域 #6：发布与回滚（防“发布即事故”）

8.1 灰度策略

• 5% → 20% → 50% → 100% 逐级放量；
• 每一档至少观察 30~60 分钟核心指标；
• 任一核心指标异常，停止放量并回滚。

8.2 回滚要求

• 一键切回上一个稳定版本；
• 回滚脚本与手册提前演练；
• 回滚后自动触发验证流程（健康检查 + 核心接口回归）。

---

九、上线 Go/No-Go 清单（可直接复用）

Go（全部满足）

• 配置校验通过，敏感信息合规管理
• 限流/超时/重试/熔断已实测
• 风险工具权限边界清晰
• 成本预算与监控就绪
• 关键日志、指标、告警齐全
• 灰度与回滚流程可执行

No-Go（任一命中）

• 无法在 5 分钟内完成回滚
• 无 request_id 无法定位单请求
• 成本无上限控制
• 关键路径无压测数据

---

十、典型事故复盘模板（建议团队固定使用）

[现象]
- 用户影响范围
- 指标异常时间线

[根因]
- 直接原因
- 系统性原因

[修复]
- 即时止损动作
- 长期治理动作

[验证]
- 修复后指标对比
- 回归测试结果

固化复盘模板，能让团队从“救火”走向“系统进化”。

---

十一、本篇总结

上线不是终点，而是系统进入真实约束环境的起点。

一句话总结：先守住稳定性、安全性、成本和回滚能力，再追求功能扩展。