Agent 上线前必查清单:50 个容易翻车的问题与规避方案
摘要:Agent 系统的 Demo 跑通和"能上线"之间,隔着的是一整类在测试环境永远不会出现、只在真实流量与真实预算下才暴露的问题——模型被静默换版本、某个用户把配额吃光、重试把成本放大五倍、日志里躺着明文密钥、工具调用写了脏数据。本文把这些问题收敛成 50 项可勾选的检查项,按 Prompt 与模型 / 输入输出 / 工具与副作用 / 状态与持久化 / 并发与限流 / 成本与配额 / 可观测 / 安全与合规 八组组织,每项给出「检查项 / 翻车现象 / 怎么查 / 规避方案 / 优先级 / 对应篇号」。核心主张是:上线前不是"再测一遍功能",而是跑一遍有明确判据的门禁——功能正确只是三个门槛里最低的那个,另外两个是稳定性门槛和成本门槛。另外给出把清单固化成 CI 门禁的可运行脚本。
📌 版本声明:本文基于 Python 3.11+、pydantic v2、httpx 0.28 编写,撰写时间 2026 年 10 月。文中引用的第三方默认参数(如
httpx.Limits默认max_connections=100、max_keepalive_connections=20、keepalive_expiry=5.0)以 HTTPX 官方文档为准,不同版本可能调整。故障分级参考 PagerDuty 公开的 SEV 定义,SLO / SLI / 错误预算参考 Google SRE 的定义,各团队应替换成自己的口径。适用边界:适用于要接真实用户流量、真实预算、真实数据的 Agent 服务。如果你做的是内部单人脚本或一次性批处理,50 项里大概有 20 项不适用——按组跳过即可,不需要全做。另外本文是清单不是教程,每项的"为什么"在前序篇目里,这里只给判据和修复方向。
文章目录
一、为什么"跑通了"不等于"能上线"
1.1 三个只在上线后出现的翻车
翻车一:功能全绿,成本崩了。
某智能客服 Agent 在测试环境跑了两个月,所有用例通过,人工评测满意度 4.2/5。上线第一天账单是预算的 5 倍。原因不是流量超预期——流量只有预估的 60%。真正的原因是重试放大:上游偶发 429,客户端无上限地指数重试,一次用户提问最多触发了 7 次重试,每次重试都重新带上完整上下文。测试环境没有 429,所以这条路径从来没被走过。
翻车二:功能全绿,一个用户拖垮所有人。
平台对每个用户做了 5 并发限制。上线第三天,一个企业客户用脚本提交了 200 个批量任务。每个"请求"合规,但每个请求内部拆成上百次模型调用——会话锁把同一个会话串行了,却没有对用户级的 Token 速率做任何限制。其余 300 个普通用户的 P99 从 2 秒涨到 40 秒。这个问题在测试环境永远复现不了,因为它需要一个用户同时发足够多的长任务。
翻车三:功能全绿,第二天发现日志里有明文密钥。
为了让调试方便,某个中间件在 DEBUG 级别打印了完整的请求头。上线后日志级别被运维调成 DEBUG 排查另一个问题,两小时内 API Key 被写进了日志系统,而日志系统对全公司可读。这类问题不会导致功能失败,所以所有测试都是绿的。
💡 这三个翻车有个共同点:它们都不会让功能测试变红。 功能测试验证的是"输入 A 能否得到输出 B",而上面三个问题分别属于成本维度、隔离维度、安全维度——它们需要各自独立的判据。这就是为什么"再多测几轮功能"不能替代上线前检查。
1.2 上线的三个门槛
我把"能不能上线"拆成三个独立门槛,三个都过才算过:
| 门槛 | 回答的问题 | 验证手段 | 谁负责 | 没过的后果 |
|---|---|---|---|---|
| 功能门槛 | 能不能正确完成任务 | 评测集 + 人工抽检(第 36 篇) | 算法/产品 | 用户觉得不好用 |
| 稳定性门槛 | 在真实负载下会不会崩 | 压测 + 故障演练(第 35、38 篇) | 工程 | 事故、资损、口碑 |
| 成本门槛 | 钱烧得起吗 | 单请求成本上限 + 预算熔断 | 工程 + 财务 | 预算超支、项目被砍 |
功能门槛是团队天然会做的那一类,因为它有明确的对错。稳定性和成本门槛最容易被跳过,因为它们在测试环境"看起来没问题"——而它们恰恰是上线后出事故的主要来源。
⚠️ 一个残酷的规律:这三个门槛的修复成本随发现阶段指数上升。功能问题在需求阶段改是 1 倍成本,上线后改是 10 倍;稳定性问题在上线前改是 1 倍,上线后改是 30 倍以上(要加上事故响应、客户沟通、复盘的人力);成本问题在上线前改只是改几行配置,上线后改意味着已经烧掉的钱回不来。
1.3 SLI / SLO / 错误预算:稳定性门槛的度量语言
在讨论"稳定性够不够"之前,必须先有统一的度量语言。按 Google SRE 与 Google Cloud 的定义:
- SLI(Service Level Indicator,服务水平指标):对服务性能的一个量化测量,比如"延迟低于 300ms 的请求占比"。
- SLO(Service Level Objective,服务水平目标):SLI 在一段时间内的目标值,比如"30 天滚动窗口内 99% 的请求延迟低于 300ms"。
- 错误预算(Error Budget):
1 - SLO余下的部分,即在不违反 SLO 的前提下允许失败的比例。SLO 99.9% 对应 30 天约 43 分钟的不可用额度。
错误预算的实用价值在于它把"要不要发布"变成了客观判断:错误预算快耗尽时不应该发布有风险的新版本;预算充足时可以激进一些。Agent 服务建议至少定义三个 SLI——可用性(非 5xx 占比)、延迟(P95/P99)、以及 Agent 特有的"任务完成率"(第 36 篇)。
| SLI | 建议初值 | 为什么是它 |
|---|---|---|
| 可用性 | ≥ 99.5% | Agent 链路长,99.9% 通常不现实 |
| P95 延迟 | ≤ 8s(交互式) | 超过 8 秒用户会明显感到卡顿 |
| 任务完成率 | ≥ 95% | 这是 Agent 真正的质量指标 |
| 单请求成本 | ≤ 预算上限 | 成本控制必须可度量才能控制 |
💡 不要一上來就设 99.99%。 有用的 SLO 必须低于 100%,因为
100% - SLO就是你的错误预算——设成 100% 意味着你没有错误预算,也就失去了"什么时候可以冒险发布"的判断依据。先用一周的真实数据测出基线,再把 SLO 设在基线略微宽松的位置,然后逐季度收紧。
1.4 这份清单怎么用
50 项看起来多,实际用法是分优先级、分批次:
三条使用原则:
第一,P0 是门禁,不是建议。 P0 项没通过就不发布,没有"先上再修"的余地——因为 P0 项对应的翻车一旦发生,就是安全事故或资损,不是"体验差一点"。
第二,P1 可以豁免,但必须写清楚谁豁免的、为什么。 豁免记录的价值在于事后复盘时有据可查,也在于让"豁免"变成一个需要承担责任的动作,而不是默认选项。
第三,P2 不阻塞发布,但要进 backlog。 P2 项通常是"优化"而非"缺陷"——比如缓存复用、小模型路由。它们不该拦住上线,但也不该被忘掉。

图1:上线前的三个门槛——功能正确只是最低的那个门槛
二、核心概念:什么是"上线前"
2.1 "上线前"是一个有时间窗口的状态,不是一个瞬间
很多人把上线理解成"点一下部署按钮"。实际上从代码冻结到放量完成,是一个持续数小时到数天的状态,而这个状态里要做的检查比部署本身重要得多。
这张状态图里最该注意的是"灰度 5% → 观察窗口"这一段。 很多团队的流程是"灰度 5% 看一眼没问题就全量",观察窗口短到根本发现不了慢性问题——比如内存缓慢增长、成本缓慢爬升、某个长尾输入导致输出质量下降。我的经验值是:5% 观察 30 分钟、30% 观察 2 小时,少于这个时长等于没观察。
另一个要点是"打回修复 → 重新提交"这条回路。 它意味着门禁检查必须是可重复执行的——不能是"几个人坐在一起过一遍清单",而应该是一条命令能跑完的脚本。否则第二次检查的质量会显著低于第一次。
2.2 三类检查项的执行方式不同
50 项检查不是同一种东西,它们分属三类,执行成本和自动化程度差异很大:
| 类型 | 占比 | 自动化程度 | 执行时机 | 典型项 |
|---|---|---|---|---|
| 静态可查 | 约 60% | 完全自动(脚本/CI) | 每次提交 | 密钥扫描、模型版本锁定、超时配置 |
| 运行可测 | 约 30% | 自动(压测/演练) | 发布前 | 并发隔离、降级生效、预算熔断 |
| 人工判断 | 约 10% | 半自动(评测集) | 发布前评审 | 输出质量、合规审阅、工具权限合理性 |
静态可查的项应该全部进 CI,因为它们的边际成本几乎为零。运行可测的项应该做成可重复执行的脚本,每次发布前跑一次。人工判断的项要有明确的 checklist 和责任人,不能是"大家觉得没问题"。
⚠️ 最容易出错的是把"人工判断项"当成"静态可查项"来对待。 比如"输出质量是否达标"——有人会写一个断言说"输出长度 > 100 字",然后就以为检查过了。这类伪自动化比不检查更危险,因为它给了虚假的安全感。输出质量必须由评测集 + 人工抽检共同判定(第 36 篇),不能简化成一个正则。
2.3 修复成本随发现阶段的变化
为什么要在上线前检查?看这条曲线的形状就够了:
从"上线前门禁"到"生产事故",成本涨了 4 倍。 但这只是直接工程成本——生产事故还要加上事故响应(多人小时级)、客户沟通、复盘文档、以及最贵的:信任损失。所以真实的倍数远高于图上画的。
这条曲线也解释了为什么"先上线再修"是个坏主意:它不是把成本转移了,而是把成本放大了。唯一的例外是 P2 项——它们的成本曲线很平(本来就是优化项),所以可以放到上线后。
三、清单总览:八组五十项
| 组 | 主题 | 项数 | P0 | P1 | P2 | 主要对应篇号 |
|---|---|---|---|---|---|---|
| A | Prompt 与模型 | 7 | 3 | 2 | 2 | 36、38、28 |
| B | 输入输出 | 7 | 3 | 3 | 1 | 27、37、30、39 |
| C | 工具与副作用 | 7 | 4 | 3 | 0 | 31、37、39、24 |
| D | 状态与持久化 | 6 | 3 | 2 | 1 | 30、40、34 |
| E | 并发与限流 | 6 | 3 | 2 | 1 | 40、31、32 |
| F | 成本与配额 | 6 | 3 | 2 | 1 | 44、37、39、38 |
| G | 可观测 | 6 | 3 | 3 | 0 | 27、31、38、37 |
| H | 安全与合规 | 5 | 4 | 1 | 0 | 34、44、40、29、31 |
| 合计 | — | 50 | 26 | 18 | 6 | — |
优先级判据(这是我的口径,团队应替换成自己的):
| 优先级 | 判据 | 未通过时的处理 | 数量 |
|---|---|---|---|
| P0 | 翻车会导致安全事故、资损、服务不可用 | 禁止发布 | 26 |
| P1 | 翻车会导致体验明显下降或成本显著上升 | 可豁免,需记录责任人与原因 | 18 |
| P2 | 属于优化项,不影响可用性 | 进 backlog,不阻塞 | 6 |

图2:八组检查项速查——按上线前必过的顺序排列
四、A 组:Prompt 与模型(7 项)
这一组管的是"模型的行为会不会在意想不到的情况下变掉"。第 36 篇讲过评测,这里讲的是上线前必须锁死的东西。
| # | 检查项 | 翻车现象 | 怎么查 | 规避方案 | 优先级 | 篇号 |
|---|---|---|---|---|---|---|
| 1 | Prompt 有版本号与变更记录 | 改了 Prompt 无法回滚,线上行为变化无从追查 | 检查代码里 Prompt 是否为常量字符串散落各处 | Prompt 集中管理 + 版本号 + 变更 diff 记录 | P1 | 36 |
| 2 | 模型版本显式锁定 | 上游把别名指向新版本,输出风格突变、格式失配 | 打印实际返回的模型标识并与期望值比对 | 用带日期的具体版本号,不用 latest 一类别名 | P0 | 36、44 |
| 3 | 有离线评测集与通过阈值 | 只靠人工感觉判断"还行",上线后质量塌陷 | 跑评测集,看关键指标是否达到阈值 | 评测集 ≥ 100 例,含边界与对抗样本(第 36 篇) | P0 | 36 |
| 4 | 系统提示与用户输入分离 | 用户输入被拼进系统提示,可越权改写指令 | 检查调用构造,是否用 role 区分 | 系统提示走 system 角色,用户输入永不拼入 | P2 | 28 |
| 5 | 采样参数显式设置 | 依赖上游默认值,换供应商后输出差异巨大 | 检查是否显式传了 temperature / top_p | 显式传参并写入配置,不依赖默认 | P1 | 36 |
| 6 | 有 Prompt 注入防护 | 用户上传的文档里藏指令,Agent 执行了它 | 用含"忽略以上指令"的样本做对抗测试 | 输入隔离 + 输出后置校验 + 工具权限最小化 | P0 | 31 |
| 7 | 有小模型兜底路由 | 主模型不可用即整体不可用 | 演练:主模型返回 5xx,看是否自动降级 | 配置降级链,见第 38 篇降级矩阵 | P2 | 38 |
我的拍板建议:第 2 项(模型版本锁定)是这一组里最容易被忽略、代价又最大的一项。 上游用别名(比如 latest、带 -latest 后缀的名字)是为了让你自动享受更新,但对生产系统来说"自动变更"就是"不可控变更"。第 44 篇的第四个事故就是它——输出偶尔多出一段乱码或英文,排查了两天才发现是模型版本被静默切换。
下面这段脚本同时检查模型锁定与 Prompt 版本化,可以直接放进 CI:
# checks/prompt_model.py —— A 组静态检查,CI 可直接调用
from __future__ import annotations
import json
import re
from pathlib import Path
# 允许出现在生产配置里的模型标识:必须是带日期或版本号的精确版本
STRICT_MODEL_RE = re.compile(r"^[a-z0-9.\-]+-\d{4}-\d{2}-\d{2}$|^[a-z0-9.\-]+@v\d+$")
# 明确禁止在生产配置里出现的可变别名
FORBIDDEN_ALIASES = {"latest", "stable", "preview", "default"}
def check_model_pinned(cfg_path: str) -> list[str]:
"""检查模型版本是否被显式锁定。
判据:配置里的模型标识必须匹配严格版本格式,
且不能是 latest / stable 这类会被上游重新指向的别名。
"""
problems: list[str] = []
cfg = json.loads(Path(cfg_path).read_text(encoding="utf-8"))
for key, value in cfg.get("models", {}).items():
name = str(value)
tail = name.rsplit("-", 1)[-1].lower()
if tail in FORBIDDEN_ALIASES:
problems.append(f"[A2][P0] 模型 {key} 使用了可变别名: {name}")
elif not STRICT_MODEL_RE.match(name):
problems.append(f"[A2][P0] 模型 {key} 不是精确版本: {name}")
return problems
def check_prompt_versioned(prompt_dir: str) -> list[str]:
"""检查 Prompt 是否有版本号与内容指纹。
判据:每个 prompt 文件必须带 version 字段,
否则改动无法追溯、也无法与评测结果对应。
"""
problems: list[str] = []
for path in sorted(Path(prompt_dir).glob("*.txt")):
text = path.read_text(encoding="utf-8")
if not re.search(r"^#\s*version\s*:\s*\S+", text, flags=re.M):
problems.append(f"[A1][P1] Prompt 缺少版本号: {path.name}")
if "system" in path.name and "{{" in text:
problems.append(
f"[A4][P2] 系统提示里存在模板变量,确认用户输入不会被拼入: {path.name}"
)
return problems
def check_runtime_model_mismatch(expected: str, actual: str) -> list[str]:
"""运行期校验:上游实际返回的模型与期望是否一致。
这是 A2 的动态兜底——即使配置锁了,也要在运行期确认。
不一致必须告警而不是静默接受,因为输出格式可能已变。
"""
if expected != actual:
return [f"[A2][P0] 模型版本漂移: 期望 {expected} 实际 {actual}"]
return []
if __name__ == "__main__":
issues = check_model_pinned("config/models.json")
issues += check_prompt_versioned("prompts/")
print("\n".join(issues) if issues else "A 组检查通过")
⚠️
check_runtime_model_mismatch这一项不能省。 配置锁定只是"我请求的是这个版本",而上游返回的可能不是——尤其是走网关或代理的时候(第 31 篇)。正确做法是每次调用都比对响应里返回的模型标识,不一致就打告警标签并记录到指标里。这是第 44 篇事故④唯一的早期检测手段。
五、B 组:输入输出(7 项)
这一组管的是"数据的边界有没有兜住"。Agent 的输入来自用户(不可信),输出来自模型(不可控),两端都必须有硬边界。
| # | 检查项 | 翻车现象 | 怎么查 | 规避方案 | 优先级 | 篇号 |
|---|---|---|---|---|---|---|
| 8 | 输出有结构化校验 | 模型偶尔返回非约定格式,下游解析崩溃 | 用畸形输出样本跑解析路径 | pydantic 模型校验 + 失败修复重试(第 37 篇) | P0 | 27、37 |
| 9 | 解析失败有修复重试 | 一次解析失败就整体失败,成功率凭空掉 5% | 统计解析失败率与修复成功率 | 最多 2 次修复重试,把原始输出回传要求重格式化 | P1 | 37 |
| 10 | 输入长度有上限与截断策略 | 用户粘了一篇长文,Token 暴涨、成本失控、上下文溢出 | 构造超长输入看是否报错或爆炸计费 | 硬上限 + 中段截断 + 明确告知用户 | P0 | 30 |
| 11 | 输入与输出有敏感信息脱敏 | 用户手机号、身份证进了日志和上下文 | 用含手机号/邮箱的输入跑一遍,grep 日志 | 入站脱敏(可逆映射)+ 出站过滤 | P0 | 28 |
| 12 | 编码统一为 UTF-8 且无 BOM | 输出偶尔出现乱码或多出一段英文 | 检查读写链路的 encoding 参数 | 全链路显式 encoding="utf-8",禁用系统默认编码 | P1 | 44 |
| 13 | 输出长度有上限 | 模型进入重复循环,单次输出几十万 Token | 压测时观察输出 Token 分布的长尾 | 设 max_output_tokens + 重复片段检测提前中断 | P0 | 39 |
| 14 | 输出有后置事实/越权校验 | Agent 编造了不存在的订单号并调用了退款 | 用对抗样本测试越权输出 | 关键字段做存在性校验 + 高风险动作二次确认 | P2 | 36 |
我的拍板建议:第 13 项(输出长度上限)是成本与稳定性的双重保险,我见过太多团队漏掉它。 模型进入重复循环时不会报错,它会一直生成到你自己超时——而这期间 Token 一直在计费。设一个 max_output_tokens 只是配一个参数的事,但它是"单请求成本上限"的第一道闸门。
下面的代码把 B 组最关键的几项(schema 校验 + 修复重试 + 输出长度守卫 + 脱敏)合成一个可运行的守卫层:
# guards/io_guard.py —— B 组运行期守卫
from __future__ import annotations
import re
from typing import TypeVar
from pydantic import BaseModel, ValidationError
T = TypeVar("T", bound=BaseModel)
# 常见敏感信息的正则——入站脱敏与出站过滤共用
PII_PATTERNS = {
"phone": re.compile(r"1[3-9]\d{9}"),
"email": re.compile(r"[\w.+-]+@[\w-]+\.[\w.]+"),
"idcard": re.compile(r"\d{17}[\dXx]"),
"sk": re.compile(r"sk-[A-Za-z0-9]{16,}"),
}
MAX_INPUT_CHARS = 20_000
MAX_OUTPUT_TOKENS = 4_096
class OutputTooLong(RuntimeError):
pass
class OutputGuard:
"""输出守卫:长度上限 + 重复循环检测 + schema 校验 + 修复重试。
四项分别对应检查项 13 / 13 / 8 / 9。
重复检测为什么必须有:max_output_tokens 只在生成结束时截断,
而循环生成的中间过程已经在计费,提前中断能省下这笔钱。
"""
def __init__(self, max_tokens: int = MAX_OUTPUT_TOKENS,
repeat_window: int = 120, repeat_times: int = 3):
self.max_tokens = max_tokens
self.repeat_window = repeat_window
self.repeat_times = repeat_times
def check_chunk(self, acc: str) -> None:
"""流式场景下的增量检查——每收到一个 chunk 调一次。"""
if len(acc) // 3 > self.max_tokens: # 中文按 3 字符 ≈ 1 token 粗估
raise OutputTooLong(f"输出超过上限 {self.max_tokens} tokens")
tail = acc[-self.repeat_window * self.repeat_times:]
if len(tail) >= self.repeat_window * 2:
seg = tail[-self.repeat_window:]
if tail.count(seg) >= self.repeat_times:
raise OutputTooLong("检测到重复循环生成,提前中断")
def parse(self, raw: str, schema: type[T]) -> T:
"""一次性输出的结构化校验——失败时抛给上层做修复重试。"""
return schema.model_validate_json(raw)
async def parse_with_repair(raw: str, schema: type[T], call_llm,
max_repair: int = 2) -> T:
"""带修复重试的解析。
修复的做法是把原始输出和报错一起回传给模型,
要求它按 schema 重新格式化——这比重新生成整条回答便宜得多。
"""
guard = OutputGuard()
guard.check_chunk(raw)
try:
return guard.parse(raw, schema)
except ValidationError as exc:
for attempt in range(max_repair):
prompt = (
"下面是模型的原始输出,它不符合约定的 JSON 结构。\n"
f"结构要求:{schema.model_json_schema()}\n"
f"报错信息:{exc}\n原始输出:{raw}\n"
"请只输出修正后的 JSON,不要任何解释。"
)
raw = await call_llm(prompt)
guard.check_chunk(raw)
try:
return guard.parse(raw, schema)
except ValidationError as again:
exc = again
raise exc
def scrub(text: str, placeholder: bool = True) -> str:
"""入站脱敏:把敏感信息替换成占位符。
注意这里是替换不是删除——删除会破坏语义(模型不知道那里有个手机号),
替换成占位符既保护了数据,又保留了"这里有个手机号"这个结构信息。
"""
out = text
for name, pat in PII_PATTERNS.items():
out = pat.sub(f"<redacted:{name}>" if placeholder else "", out)
return out
💡
scrub用替换而不是删除,这一点值得强调。 如果直接删掉手机号,模型会认为用户压根没提供联系方式,行为会错;替换成<redacted:phone>后,模型知道"这里有个手机号但我看不到",可以正确回答"请提供您的手机号"这类问题。脱敏的目标是不泄露,不是让信息凭空消失。
六、C 组:工具与副作用(7 项)
这一组是最容易造成真实损害的一组——因为工具是 Agent 唯一能"改变外部世界"的通道(第 24 篇讲 Supervisor 时提到过工具循环,第 39 篇讲过幂等)。
| # | 检查项 | 翻车现象 | 怎么查 | 规避方案 | 优先级 | 篇号 |
|---|---|---|---|---|---|---|
| 15 | 工具有危险等级标注 | 删除类工具被当作只读工具随便调用 | 检查工具注册表里每个工具是否有风险标记 | 三级分类:只读 / 可写 / 危险,分级授权 | P0 | 31 |
| 16 | 写操作有二次确认或审批 | Agent 自作主张改了生产数据 | 演练:让 Agent 执行写操作,看是否被拦截 | 危险级工具必须人工确认或走审批队列 | P0 | 37 |
| 17 | 工具参数有校验 | 传入非法参数导致下游脏数据或报错 | 用越界/错类型参数调用工具 | 每个工具有参数 schema,非法参数直接拒绝 | P1 | 27 |
| 18 | 写操作有幂等键 | 超时重试导致同一笔操作执行两次 | 制造超时后重试,检查数据是否重复 | 幂等键 + 结果缓存(第 39 篇) | P0 | 39 |
| 19 | 工具有独立超时 | 一个慢工具拖死整个请求 | 让某工具 sleep 60s,看整体是否被拖到超时 | 每个工具独立超时,总和小于请求预算 | P1 | 39 |
| 20 | 工具失败有明确错误语义 | 工具返回自然语言错误,模型误判为成功 | 让工具抛异常,观察模型后续行为 | 结构化错误码 + 是否可重试标记 | P1 | 37 |
| 21 | 有工具调用次数上限 | Agent 陷入调用循环,一次请求调了几百次 | 压测统计单请求的工具调用次数分布 | 上限(如 20 次)+ 超限时转人工或降级 | P0 | 24 |
我的拍板建议:第 18 项(幂等键)是这一组的核心,也是第 44 篇第五个事故的直接原因。 超时重试是分布式系统的必然行为——你不可能保证"请求一定不重复",只能保证"重复执行无害"。幂等键的实用做法是:由调用方生成、随请求携带、服务端按 (tool_name, idempotency_key) 做唯一索引或结果缓存。
# guards/tool_guard.py —— C 组核心守卫
from __future__ import annotations
import hashlib
import json
import time
from dataclasses import dataclass, field
from enum import Enum
class Risk(str, Enum):
READ = "read" # 只读:可自由调用
WRITE = "write" # 可写:需要幂等键
DANGER = "danger" # 危险:需要人工确认
@dataclass
class ToolSpec:
name: str
risk: Risk
timeout_s: float = 10.0
max_calls_per_request: int = 3
@dataclass
class ToolGuard:
"""工具守卫:危险分级 + 幂等 + 调用次数上限。
三个机制分别对应检查项 15/16、18、21。
幂等结果缓存为什么要带 TTL:无限期保存会让内存无限增长,
而大多数重试发生在秒级到分钟级窗口内,TTL 覆盖这个范围就够。
"""
specs: dict[str, ToolSpec] = field(default_factory=dict)
idempotency_ttl_s: float = 600.0
global_call_budget: int = 20
_idem: dict[str, tuple[float, object]] = field(default_factory=dict)
_calls: dict[str, int] = field(default_factory=dict)
_total: int = 0
def register(self, spec: ToolSpec) -> None:
self.specs[spec.name] = spec
def make_idem_key(self, tool: str, args: dict, scope: str) -> str:
"""幂等键由 (工具名 + 参数规范化 + 业务作用域) 生成。
scope 通常是 user_id 或 session_id——
不加 scope 会让不同用户的相同参数互相命中缓存,这是错的。
"""
canon = json.dumps(args, sort_keys=True, ensure_ascii=False)
digest = hashlib.sha256(f"{tool}|{canon}|{scope}".encode()).hexdigest()[:32]
return digest
async def invoke(self, tool: str, args: dict, scope: str, executor,
approver=None):
spec = self.specs.get(tool)
if spec is None:
raise KeyError(f"未注册的工具: {tool}")
# 调用次数上限:先全局后单工具
self._total += 1
if self._total > self.global_call_budget:
raise RuntimeError(f"单请求工具调用超过预算 {self.global_call_budget}")
self._calls[tool] = self._calls.get(tool, 0) + 1
if self._calls[tool] > spec.max_calls_per_request:
raise RuntimeError(f"工具 {tool} 调用次数超限")
# 危险级工具必须走审批
if spec.risk is Risk.DANGER:
if approver is None:
raise PermissionError(f"危险工具 {tool} 未配置审批通道")
if not await approver(tool, args):
raise PermissionError(f"危险工具 {tool} 未获批准")
# 写操作必须走幂等
if spec.risk in (Risk.WRITE, Risk.DANGER):
key = self.make_idem_key(tool, args, scope)
now = time.monotonic()
hit = self._idem.get(key)
if hit and now - hit[0] < self.idempotency_ttl_s:
return hit[1] # 重复请求直接返回上次结果
result = await executor(tool, args, timeout=spec.timeout_s)
self._idem[key] = (now, result)
return result
return await executor(tool, args, timeout=spec.timeout_s)
⚠️ 幂等键里的
scope参数不能省。 只用(tool, args)生成键会出严重问题:用户 A 和用户 B 传相同参数时会互相命中缓存,B 拿到的是 A 的结果。第 40 篇讲租户隔离时强调过同一件事——任何缓存/状态的键都必须带上作用域,这是多租户系统的第一原则。

图3:工具危险分级与三道闸门——只读放行,可写要幂等,危险要审批
七、D 组:状态与持久化(6 项)
这一组对应第 30 篇,管的是"服务重启、实例漂移、会话变长之后,数据还对不对"。
| # | 检查项 | 翻车现象 | 怎么查 | 规避方案 | 优先级 | 篇号 |
|---|---|---|---|---|---|---|
| 22 | 会话状态可持久化与恢复 | 实例重启后用户会话全丢,对话断片 | 杀掉进程重启,看会话是否恢复 | 每次状态变更落盘,启动可从存储重建 | P0 | 30 |
| 23 | 状态写入有版本号/乐观锁 | 并发写导致后写覆盖先写,回复丢失 | 同会话并发发两条消息,检查是否丢内容 | 版本号 + CAS,或会话级串行(第 40 篇) | P0 | 30、40 |
| 24 | 会话有 TTL 与清理机制 | 会话表无限增长,三个月后查询变慢 | 查会话表行数与时间分布 | TTL + 定期归档清理 | P1 | 30 |
| 25 | 长会话有上下文压缩策略 | 对话 50 轮后 Token 暴涨、成本翻倍、超窗口报错 | 模拟 50 轮对话观察 Token 与成本曲线 | 摘要压缩 + 滑窗,见第 30 篇三层状态 | P2 | 30 |
| 26 | 多实例下状态共享或会话粘滞 | 用户第二次请求落到另一个实例,找不到上下文 | 多实例压测,看是否有上下文丢失 | 外部存储共享 或 会话粘滞路由(第 40 篇) | P1 | 40 |
| 27 | 状态中不含密钥与大对象 | 会话状态里存了 API Key,存储泄露即密钥泄露 | 扫状态存储里的敏感字段 | 只存引用(如凭据 ID),不存明文 | P0 | 34 |
我的拍板建议:第 23 项和第 28 项(E 组会话串行)是同一件事的两种解法,我建议两个都做。 版本号乐观锁是"数据层正确性",会话串行是"执行层正确性"——只做前者会在并发高时产生大量重试,只做后者会在跨实例部署时失效。
# guards/state_guard.py —— D 组核心检查
from __future__ import annotations
import json
import time
from dataclasses import dataclass, field
@dataclass
class StateRecord:
payload: dict
version: int = 0
updated_at: float = field(default_factory=time.time)
class VersionedStateStore:
"""带版本号的状态存储——D23 的实现。
为什么用 CAS 而不是直接写:并发写场景下"读-改-写"非原子,
后写者会覆盖先写者的结果(第 40 篇事故二的根因)。
版本号让覆盖变成可检测的冲突,而不是静默的数据丢失。
"""
def __init__(self, ttl_s: float = 86_400.0):
self._data: dict[str, StateRecord] = {}
self.ttl_s = ttl_s
def load(self, key: str) -> tuple[dict, int]:
rec = self._data.get(key)
if rec is None:
return {}, 0
if time.time() - rec.updated_at > self.ttl_s:
self._data.pop(key, None) # TTL 到期即清理(D24)
return {}, 0
return rec.payload, rec.version
def compare_and_set(self, key: str, payload: dict, expect: int) -> bool:
rec = self._data.get(key)
if rec is None:
if expect != 0:
return False
self._data[key] = StateRecord(payload=payload, version=1)
return True
if rec.version != expect:
return False # 版本冲突,交给上层重试
rec.payload = payload
rec.version += 1
rec.updated_at = time.time()
return True
def scan_sensitive(self, forbidden_keys: set[str]) -> list[str]:
"""扫状态里的敏感字段——D27。
这类扫描要定期跑而不只在上线前跑,
因为"往状态里塞个 key 方便调试"是很容易复发的行为。
"""
hits = []
for key, rec in self._data.items():
blob = json.dumps(rec.payload, ensure_ascii=False).lower()
for bad in forbidden_keys:
if bad.lower() in blob:
hits.append(f"会话 {key} 疑似包含敏感字段: {bad}")
return hits
⚠️
scan_sensitive要定期跑,不是只在上线前跑一次。 我见过的情况是:上线前检查通过,两周后有人为了调试方便往会话状态里塞了个api_key,然后忘了删。把这类扫描做成每日定时任务,比一次性检查有效得多——它是"持续合规"而不是"一次性合规"。
八、E 组:并发与限流(6 项)
这一组是第 40 篇的直接落地,管的是"在真实负载下会不会被拖垮"。
| # | 检查项 | 翻车现象 | 怎么查 | 规避方案 | 优先级 | 篇号 |
|---|---|---|---|---|---|---|
| 28 | 会话级串行 | 同一会话两请求并发,回复互相覆盖 | 同会话并发 10 次,检查最大并发是否为 1 | 会话锁(第 40 篇 4.2 节) | P0 | 40 |
| 29 | 有用户/租户级配额 | 一个客户吃光所有配额,其他人全超时 | 单租户打满流量,测其他租户 P99 | 租户令牌桶 + 预留 20%~30% 共享余量 | P1 | 40 |
| 30 | 有全局 Token 速率限制 | 请求数没超但 TPM 超了,上游 429 一片 | 压测统计上游 429 次数 | 令牌桶 + 事后校正(第 40 篇 4.3 节) | P0 | 40 |
| 31 | 队列有界且有溢出策略 | 无界队列导致"全都超时但没有一个被拒绝" | 过载压测,观察队列长度与拒绝率 | 有界队列 + reject/drop_oldest/降级 | P0 | 40 |
| 32 | 连接池大小匹配实际并发 | 并发设了 50 但连接池只有 20,出现"假并发" | 监控连接池等待队列长度是否长期 > 0 | 池大小 ≥ 实际并发 × 1.2(第 40 篇 2.4 节) | P1 | 40、44 |
| 33 | 长任务与交互式资源分离 | 一个 10 分钟批量任务饿死 50 个交互式请求 | 混合负载压测,对比交互式 P99 | 独立资源池,批量池故意设小 | P2 | 40 |
我的拍板建议:第 32 项(连接池)是这一组里最"隐形"的一项,也是第 44 篇第一个事故的直接原因。 httpx 客户端的默认连接池上限是 max_connections=100、max_keepalive_connections=20——如果你的实际并发调用数超过 100,超出的请求会在池里排队等连接,表现出来是"并发上不去、延迟莫名很高",而 CPU 和内存看起来都很健康。
下面的命令用于在压测时体检连接池与并发配置,建议在每次发布前的压测里跑一遍:
# E 组:并发与连接池体检(发布前压测时执行)
# 1) 观察连接池等待队列——长期大于 0 说明池是瓶颈,加大并发限制无效
# 在应用里暴露该指标后,用下面的查询看 5 分钟内的均值与峰值
curl -s "http://localhost:9090/metrics" \
| grep -E "http_client_pool_waiting|http_client_pool_active" \
| sort | uniq -c
# 2) 统计上游 429 次数——这是判断"瓶颈是否在配额"的决定性指标
# 扩容后 429 增加但吞吐不变 => 瓶颈在上游配额,扩容有害
curl -s "http://localhost:9090/metrics" | grep -c "upstream_status=\"429\""
# 3) 用 wrk 打混合负载,分别观察交互式与批量的 P99
# -c 表示并发连接数,-d 表示持续时长
wrk -t4 -c64 -d300s -s interactive.lua http://localhost:8000/v1/chat
wrk -t2 -c8 -d300s -s batch.lua http://localhost:8000/v1/tasks
# 4) 会话串行验证:同一会话并发 20 次,最大并发必须为 1
python - <<'PY'
import asyncio, sys
sys.path.insert(0, ".")
from concurrency.session import SessionLock
async def main():
lock = SessionLock()
cur = {"n": 0, "peak": 0}
async def op():
cur["n"] += 1
cur["peak"] = max(cur["peak"], cur["n"])
await asyncio.sleep(0.05)
cur["n"] -= 1
await asyncio.gather(*[lock.run("sess-1", op) for _ in range(20)])
print("同一会话最大并发:", cur["peak"], "->", "OK" if cur["peak"] == 1 else "❌ 未串行")
asyncio.run(main())
PY
💡 "扩容后 429 增加但吞吐不变"这句话要记牢,它是判断瓶颈的黄金判据。 如果你的瓶颈是上游 Token 配额,那么从 4 个实例扩到 40 个只会让 429 更多——更多的并发请求打向同一个配额。这时应该去申请更高配额或优化 Token 使用(缓存、小模型路由、Prompt 压缩),而不是继续扩容(第 40 篇 5.5 节)。
九、F 组:成本与配额(6 项)
这一组是最常被整体跳过的一组,也是第 44 篇第三个事故的直接来源。
| # | 检查项 | 翻车现象 | 怎么查 | 规避方案 | 优先级 | 篇号 |
|---|---|---|---|---|---|---|
| 34 | 单请求成本上限 | 一个失控请求烧掉几百元 | 统计单请求成本的 P99 与最大值 | 超过上限立即中断并降级 | P0 | 44 |
| 35 | 日/月预算上限与硬性熔断 | 一夜之间成本超预算 5 倍 | 看账单的最小告警粒度是小时还是天 | 小时级预算检查 + 触顶熔断(不只是告警) | P0 | 44 |
| 36 | 重试有次数上限且成本可感知 | 一次用户输入触发 7 次重试,每次带完整上下文 | 统计重试放大倍数 = 总调用数 / 用户请求数 | 重试次数 ≤ 3,重试计入同一预算 | P0 | 37、39 |
| 37 | 有缓存复用 | 相同问题重复付费 | 统计缓存命中率 | 精确缓存 + 语义缓存(第 32 篇) | P1 | 32 |
| 38 | 成本可按租户/用户归因 | 只知道总账单,不知道谁花的 | 看能否按用户导出成本明细 | 每次调用打上归属标签并记账 | P1 | 31 |
| 39 | 有小模型路由降本 | 简单问题也用最贵的模型 | 统计简单问题的模型分布 | 复杂度分级路由(第 38 篇) | P2 | 38 |
我的拍板建议:第 35 项里"告警"和"熔断"是两件完全不同的事,大多数团队只做了前者。 告警是"告诉你钱烧多了",熔断是"让钱不再烧"。凌晨三点收到一条成本告警没有意义——值班的人既看不懂也不会半夜起来改配置。必须做成自动熔断:预算触顶就停止调用或强制降级,第二天早上再人工恢复。
# guards/budget_guard.py —— F 组成本守护,可运行
from __future__ import annotations
import asyncio
import time
from dataclasses import dataclass, field
class BudgetExceeded(RuntimeError):
pass
@dataclass
class BudgetGuard:
"""成本守护:单请求上限 + 小时预算熔断 + 重试计入同一预算。
三个机制对应检查项 34、35、36。
为什么要小时级而不是天级:账单通常按天出,
等天级告警到达时钱已经烧完了,小时级是可止损的最粗粒度。
"""
hourly_budget: float # 每小时预算(元)
per_request_ceiling: float = 3.0 # 单请求成本上限(元)
price_per_1k_tokens: float = 0.02 # 单价,按实际模型填写
spent_this_hour: float = 0.0
hour_started: float = field(default_factory=time.monotonic)
total_spent: float = 0.0
_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
tripped: bool = False
def _roll_hour(self) -> None:
now = time.monotonic()
if now - self.hour_started >= 3600.0:
self.hour_started = now
self.spent_this_hour = 0.0
self.tripped = False # 新小时自动恢复,但需人工确认大故障
async def charge(self, tokens: int, *, label: str = "") -> float:
"""记账并校验预算——每次模型调用返回后调用。
注意:重试也走这里,这样重试成本天然计入同一预算,
不需要额外维护"重试专用预算"(检查项 36 的实现要点)。
"""
async with self._lock:
self._roll_hour()
cost = tokens / 1000.0 * self.price_per_1k_tokens
if cost > self.per_request_ceiling:
raise BudgetExceeded(
f"单次调用成本 {cost:.2f} 超过上限 {self.per_request_ceiling}"
)
if self.spent_this_hour + cost > self.hourly_budget:
self.tripped = True
raise BudgetExceeded(
f"小时预算 {self.hourly_budget} 已触顶,熔断中({label})"
)
self.spent_this_hour += cost
self.total_spent += cost
return cost
async def guard_call(self, fn, *, label: str = ""):
"""把一次模型调用包进预算守护——触顶时抛错由上层降级。"""
if self.tripped:
raise BudgetExceeded(f"预算已熔断,拒绝新调用({label})")
result, tokens = await fn()
await self.charge(tokens, label=label)
return result
@property
def usage_ratio(self) -> float:
return self.spent_this_hour / self.hourly_budget
⚠️ 熔断后的恢复策略要提前定好,不能临时拍脑袋。 我的做法是:新小时自动恢复,但连续熔断两次就要人工确认。原因是不少"熔断"其实是预算设得太低或单价填错,如果每次都自动恢复,真正的问题会被掩盖;而每次都要人工确认又会把值班同学拖垮。两次是个平衡点。
十、G 组:可观测(6 项)
这一组管的是"出问题时你能不能查得出来"。没有可观测性,前面七组的检查做得再好,事故来了也只能靠猜。
| # | 检查项 | 翻车现象 | 怎么查 | 规避方案 | 优先级 | 篇号 |
|---|---|---|---|---|---|---|
| 40 | 链路标识贯穿全链路 | 日志上万条但无法串成一次请求 | 拿一个请求 ID 查,看能否拉出完整链路 | trace_id + correlation_id 贯穿(第 27 篇) | P0 | 27 |
| 41 | 记录了 Token 与成本指标 | 只知道慢,不知道贵 | 看监控里有没有成本指标 | 每次调用记录 Token 与折算成本 | P1 | 31 |
| 42 | 有 P95/P99 与错误率看板 | 平均值正常但用户抱怨很慢 | 看有没有分位数指标 | 分位数 + 分租户维度 | P0 | 40 |
| 43 | 有降级触发次数指标 | 悄悄降级了三个月没人知道 | 查降级计数器 | 降级次数与降级率入监控并告警 | P1 | 38 |
| 44 | 日志有脱敏与分级 | 日志里出现明文密钥和手机号 | grep 日志里的 sk-、手机号 | 结构化日志 + 敏感字段过滤(第 28 篇) | P0 | 28、44 |
| 45 | 有关键告警与值班响应 | 出问题两小时后被用户告知 | 演练:手动触发故障,看多久告警 | 分级告警 + 值班表(参照 SEV 分级) | P1 | 37 |
我的拍板建议:第 44 项和第 H 组的第 47 项(日志无明文密钥)要一起做,而且要在日志框架层做,不是在业务代码里做。 靠"每个开发者记得不打印密钥"是不可靠的——正确做法是提供一个结构化日志工具,它默认就把敏感字段过滤掉(第 28 篇中间件的思路)。
# guards/logging_guard.py —— G 组日志脱敏,框架层强制
from __future__ import annotations
import json
import logging
import re
# 与 B 组共用同一套模式,保证入站脱敏与出站过滤口径一致
SENSITIVE_RE = re.compile(
r"(sk-[A-Za-z0-9]{16,}" # API Key
r"|1[3-9]\d{9}" # 手机号
r"|\d{17}[\dXx]" # 身份证
r"|[\w.+-]+@[\w-]+\.[\w.]+)" # 邮箱
)
class RedactingFormatter(logging.Formatter):
"""日志脱敏 Formatter——在框架层强制生效。
为什么放在 Formatter 而不是业务代码:业务代码里"记得不打印"不可靠,
而 Formatter 是每条日志的必经之路,绕不过去。
"""
def format(self, record: logging.LogRecord) -> str:
text = super().format(record)
return SENSITIVE_RE.sub("<redacted>", text)
def install(level: int = logging.INFO) -> None:
handler = logging.StreamHandler()
handler.setFormatter(
RedactingFormatter("%(asctime)s %(levelname)s %(name)s %(message)s")
)
root = logging.getLogger()
root.handlers = [handler]
root.setLevel(level)
def scan_log_file(path: str, chunk: int = 8192) -> list[int]:
"""离线扫描已有日志里是否残留明文敏感信息——G44 / H47 的验证手段。
上线前跑一次,之后每周跑一次(防止有人绕过 Formatter 直接写文件)。
"""
hits: list[int] = []
with open(path, encoding="utf-8", errors="replace") as fh:
lineno = 0
while True:
line = fh.readline()
if not line:
break
lineno += 1
if SENSITIVE_RE.search(line):
hits.append(lineno)
return hits
# G44 / H47:上线前与日常巡检的日志密钥扫描
# 1) 扫应用日志
python -c "from guards.logging_guard import scan_log_file; \
print('命中行号:', scan_log_file('logs/app.log')[:20])"
# 2) 兜底 grep(防止有代码绕过 Formatter 直接写文件)
grep -nE "sk-[A-Za-z0-9]{16,}|1[3-9][0-9]{9}" logs/*.log | head -20
# 3) 扫代码里是否把密钥写进了日志语句
grep -rnE "(logger|log)\.(debug|info|warning|error).*(api_key|secret|token|password)" \
--include="*.py" . | head -20
# 4) 扫配置文件是否误提交
grep -rnE "sk-[A-Za-z0-9]{16,}" --include="*.py" --include="*.yaml" \
--include="*.json" --include="*.env" . | head -20
"扫代码里是否把密钥写进日志语句"这一条最有用,因为它能在事故还没发生时发现问题——等日志里已经有明文了,你还要额外做密钥轮转(第 44 篇事故⑥的修复里最贵的那一步)。
十一、H 组:安全与合规(5 项)
| # | 检查项 | 翻车现象 | 怎么查 | 规避方案 | 优先级 | 篇号 |
|---|---|---|---|---|---|---|
| 46 | 密钥只在服务端且有轮转机制 | 密钥硬编码在前端或配置里,泄露后无法快速失效 | 扫代码库 + 检查密钥管理方案 | 环境变量/密钥服务注入 + 定期轮转(第 34 篇) | P0 | 34 |
| 47 | 日志与追踪中无明文密钥 | 日志系统可读范围大于密钥权限,等于密钥公开 | 跑第十节的两条扫描 | 框架层脱敏 Formatter | P0 | 44 |
| 48 | 租户数据隔离在数据访问层强制 | 一个租户查到另一个租户的数据 | 用租户 A 的凭据查租户 B 的 ID | 存储层强制注入租户条件(第 40 篇 2.3 节) | P0 | 40 |
| 49 | 关键操作有审计留痕 | 出事后无法还原谁在什么时候做了什么 | 抽查一次写操作的审计记录 | 事件化审计日志(第 29 篇) | P1 | 29 |
| 50 | 有内容安全与合规过滤 | Agent 生成违规内容并直接返回给用户 | 用对抗样本测试输入输出 | 入站 + 出站双重过滤(第 31 篇) | P0 | 31 |
我的拍板建议:第 48 项的判据是"在技术上不可能忘记",不是"大家记得加条件"。 第 40 篇 2.3 节给的做法是在数据访问层强制注入租户条件——业务代码拿不到"不带租户条件"的查询接口。在应用层加 WHERE tenant_id = ? 不算隔离,因为总会有人忘记。

图4:P0 项未通过的四类后果——安全事故、资损、雪崩、合规风险
十二、把清单固化成 CI:可执行的门禁
清单如果只存在于文档里,第二次发布时就会被跳过。必须做成一条命令能跑完的脚本。
12.1 检查项注册表
# checks/registry.py —— 50 项检查的注册表
from __future__ import annotations
from dataclasses import dataclass
from typing import Callable, Awaitable
P0, P1, P2 = "P0", "P1", "P2"
@dataclass(frozen=True)
class Check:
no: int # 编号 1..50
group: str # A..H
name: str
priority: str # P0 / P1 / P2
article: str # 对应前序篇号,便于回溯
runner: Callable[[], Awaitable[list[str]]]
REGISTRY: list[Check] = [
# 实际项目里这里放全部 50 项;下面给出代表性的 8 项作为骨架
Check(2, "A", "模型版本显式锁定", P0, "36/44", None),
Check(3, "A", "离线评测集达到阈值", P0, "36", None),
Check(6, "A", "Prompt 注入防护", P0, "31", None),
Check(8, "B", "输出结构化校验", P0, "27/37", None),
Check(18, "C", "写操作幂等键", P0, "39", None),
Check(28, "E", "会话级串行", P0, "40", None),
Check(35, "F", "小时预算熔断", P0, "44", None),
Check(47, "H", "日志无明文密钥", P0, "44", None),
]
def by_priority(priority: str) -> list[Check]:
return [c for c in REGISTRY if c.priority == priority]
12.2 门禁主脚本
# preflight.py —— 上线前门禁,CI 调用入口
from __future__ import annotations
import argparse
import asyncio
import sys
from collections import Counter
from checks.registry import REGISTRY, P0, P1, P2
async def run_checks(priorities: set[str]) -> dict[str, list[str]]:
results: dict[str, list[str]] = {}
for chk in REGISTRY:
if chk.priority not in priorities or chk.runner is None:
continue
try:
problems = await chk.runner()
except Exception as exc: # 检查脚本自身崩溃也必须算失败
problems = [f"检查脚本异常: {type(exc).__name__}: {exc}"]
results[f"{chk.no:02d} [{chk.priority}] {chk.name} (第{chk.article}篇)"] = problems
return results
async def main() -> int:
parser = argparse.ArgumentParser(description="Agent 上线前门禁")
parser.add_argument("--only", default="P0,P1,P2",
help="要执行的优先级,逗号分隔")
parser.add_argument("--strict", action="store_true",
help="P1 未通过也视为失败(默认允许豁免)")
args = parser.parse_args()
priorities = {p.strip() for p in args.only.split(",")}
results = await run_checks(priorities)
p0_fail = [k for k, v in results.items() if v and "[P0]" in k]
p1_fail = [k for k, v in results.items() if v and "[P1]" in k]
p2_fail = [k for k, v in results.items() if v and "[P2]" in k]
print("=" * 68)
print(f"已执行 {len(results)} 项检查,分布: {Counter(c.priority for c in REGISTRY)}")
print(f"P0 未通过 {len(p0_fail)} 项 | P1 未通过 {len(p1_fail)} 项 | P2 未通过 {len(p2_fail)} 项")
print("=" * 68)
for name, problems in results.items():
if problems:
print(f"\n❌ {name}")
for p in problems:
print(f" - {p}")
if p0_fail:
print("\n🚫 P0 项未通过,禁止发布。")
return 2
if p1_fail and args.strict:
print("\n🚫 P1 项未通过且开启了 --strict,禁止发布。")
return 1
if p1_fail:
print("\n⚠️ P1 项未通过,如需发布请在发布单写明豁免责任人与原因。")
print("\n✅ 门禁通过(P2 项未通过不阻塞,请记入 backlog)。")
return 0
if __name__ == "__main__":
sys.exit(asyncio.run(main()))
# 发布前执行:默认跑 P0 + P1 + P2
python preflight.py
# 只看 P0(快速门禁,适合每次提交)
python preflight.py --only P0
# 严格模式:P1 未通过也拦住(适合大版本发布)
python preflight.py --only P0,P1 --strict
💡
--strict这个开关值得保留。 日常小改动发布时用默认模式(P1 可豁免),大版本或架构变更时用--strict。原因是 P1 豁免机制的存在是为了不阻塞日常迭代,但它不该成为大版本发布时的妥协借口——大变更的风险面本身就更大。
12.3 门禁项与失败阈值
| 门禁项 | 命令 | 失败阈值 | 处理 |
|---|---|---|---|
| 模型版本锁定 | python preflight.py --only P0 | 存在可变别名 | 禁止发布 |
| 会话串行 | 同会话并发 20 次测试 | 最大并发 > 1 | 禁止发布 |
| 预算熔断 | 注入超预算调用 | 未抛 BudgetExceeded | 禁止发布 |
| 日志脱敏 | scan_log_file + grep | 命中行数 > 0 | 禁止发布 + 轮转密钥 |
| 评测集回归 | python -m eval.run | 关键指标下降 > 3% | 禁止发布 |
| 降级演练 | 注入上游故障 | 降级未生效 | 禁止发布 |
| 压测 P99 | wrk 混合负载 | P99 > 8s 或 429 > 0 | 禁止发布 |
十三、适用边界与风险提示 ⚠️
① 这份清单是针对"接真实流量的服务",单人脚本不适用。 如果你做的是内部一次性批处理,八组里大概有 D、E、H 三组基本不适用——按组跳过,不要为了凑数硬做。
② 优先级是我的口径,团队必须替换成自己的。 P0 的判据是"翻车会导致安全事故、资损或服务不可用",但"多大的资损算资损"取决于你的业务规模。一个日调用 100 次的内部工具和一个日调用 100 万次的对外服务,P0 集合显然不同。
③ 清单会过时。 模型能力、上游 API、合规要求都在变。建议每季度复核一次清单,把已经不成立的项删掉,把新出现的翻车加进去。一份两年没改过的检查清单,可信度低于没有清单——因为它给了虚假的安全感。
④ 门禁脚本本身也要被测试。 见过门禁脚本因为一处路径写错而"永远通过",团队用它跑了半年。做法是故意引入一个已知缺陷,确认门禁能拦住——这个测试应该每个季度做一次。
⑤ 不要把"通过门禁"当成"不会出事"。 门禁拦的是已知问题,它拦不住未知的失效模式。第 44 篇的六个事故里,有四个是清单覆盖到的(说明清单有用),有两个是清单没覆盖的(说明清单不万能)。正确的心态是:门禁降低事故概率,灰度缩短事故时长,可观测加快事故定位——三者都不能省。
十四、总结
核心只有一句:上线前不是"再测一遍功能",而是跑一遍有明确判据的门禁——功能正确只是三个门槛里最低的那个。
五个最该记住的结论:
第一,功能测试全绿不能证明能上线。 本文开头三个翻车分别属于成本、隔离、安全维度,它们都不会让功能测试变红。所以必须有各自的独立判据。
第二,三个门槛里,稳定性和成本最容易被跳过。 因为它们在测试环境"看起来没问题"——而真实流量、真实预算、真实并发才是它们的触发条件。
第三,P0 = 26 项是门禁不是建议。 未通过就没有"先上再修"的余地,因为 P0 对应的翻车是安全事故、资损、雪崩和合规风险,不是"体验差一点"。
第四,成本防护要做成熔断而不是告警。 凌晨三点的成本告警没有意义,预算触顶必须自动停止调用。另外重试必须计入同一预算,否则重试放大(第 44 篇事故③)会绕过所有单请求上限。
第五,清单必须固化成脚本。 存在于文档里的清单,第二次发布就会被跳过。做成一条命令能跑完的门禁,并定期用"故意引入缺陷"验证门禁真的能拦住。
最后一点:这份清单是起点不是终点。 它来自我和团队踩过的坑,但你的系统会踩到它没覆盖的坑。每次事故之后往清单里加一项,是让这套机制持续有效的唯一方式——一份会增长的清单,比一份完美的清单有用得多。
落地自检清单(Checklist)
- ✅ 明确定义了三个门槛(功能 / 稳定性 / 成本)与各自的判据
- ✅ 定义了 SLI / SLO / 错误预算,且 SLO 低于 100%
- ✅ 八组 50 项已按团队情况调整优先级
- ✅ P0 的 26 项已做成 CI 门禁,未通过禁止发布
- ✅ P1 有豁免记录(责任人 + 原因)
- ✅ P2 已进 backlog 且不阻塞发布
- ✅ 模型版本显式锁定,且运行期比对实际返回标识
- ✅ 有 ≥100 例的离线评测集与通过阈值
- ✅ 输出有 schema 校验 + 修复重试 + 长度上限
- ✅ 输入有 长度上限与脱敏(替换而非删除)
- ✅ 工具有危险分级,危险级有审批通道
- ✅ 写操作有幂等键,且键里带作用域
- ✅ 有单请求工具调用次数预算
- ✅ 状态写入有版本号 CAS,有 TTL 与清理
- ✅ 会话级串行已用并发测试验证(最大并发 = 1)
- ✅ 有全局 Token 速率限制与有界队列
- ✅ 连接池大小 ≥ 实际并发 × 1.2,压测时监控等待队列
- ✅ 有单请求成本上限 + 小时预算熔断
- ✅ 重试计入同一预算且次数 ≤ 3
- ✅ trace_id 贯穿全链路,有 P95/P99 分位数看板
- ✅ 日志在框架层脱敏,且定期离线扫描
- ✅ 密钥只在服务端且有轮转机制
- ✅ 租户隔离在数据访问层强制
- ✅ 有灰度观察窗口(5% 观察 30 分钟、30% 观察 2 小时)
- ✅ 门禁脚本每季度用"故意引入缺陷"验证一次
常见问题(FAQ)
Q1:50 项太多了,能不能只做 P0?
能,而且建议小团队就只做 P0。 26 项 P0 覆盖了所有"翻车即事故"的场景,P1/P2 是质量与成本优化。先跑通 P0,再按实际遇到的问题往里加 P1——这比一上来全做更容易坚持下去。
Q2:SLO 该设多少?
先测一周基线,再设在基线略微宽松的位置。 不要照抄别人的 99.9%:可用性 99.5%、P95 延迟 8 秒、任务完成率 95% 对大多数 Agent 服务是更现实的起点。关键是有数字并且持续看,而不是数字本身多漂亮。
Q3:预算熔断会不会误伤正常业务?
会,所以阈值要留余量并分两级。 我的做法是:80% 预算告警(提示)、100% 熔断(停止调用)、连续熔断两次需人工确认恢复。这样既不会在正常波动时误熔断,也不会让真问题被自动恢复掩盖。
Q4:幂等键的 TTL 设多久?
覆盖重试窗口即可,我常用 10 分钟。 大部分超时重试发生在秒级到分钟级;设得太长会让缓存无限增长,设得太短会让"用户隔一会儿重试"变成重复执行。如果你的业务有"隔天重试"的场景,TTL 就要改成按业务单据号做唯一索引,而不是靠时间窗口。
Q5:日志脱敏放在 Formatter 里会不会漏?
会漏,所以要三重防护:① Formatter 默认脱敏(覆盖绝大多数);② 定期离线扫描日志(发现绕过);③ 扫代码里的日志语句(事前预防)。单次防护不可靠,三重叠加才敢说"基本不会漏"。
Q6:灰度观察 5% 多久合适?
我的经验值是 5% 观察 30 分钟、30% 观察 2 小时。 短于这个时长,慢性问题(内存缓慢增长、成本缓慢爬升、长尾输入质量下降)根本暴露不出来。观察的指标是错误率、P95 延迟、单请求成本三项同时稳定,不是"没报错"。
Q7:团队很小,没有运维,这些还适用吗?
适用,但只做最关键的六项:模型版本锁定、输出 schema 校验、会话串行、单请求成本上限、预算熔断、日志脱敏。这六项的实现成本都在几十行以内,但它们覆盖了 80% 的严重事故。
Q8:清单多久复核一次?
每季度一次,另外每次事故之后必加项。 一份两年没改的检查清单可信度低于没有清单——因为它给了虚假的安全感,让人以为"过了一遍就没事了"。
参考资料
- Google SRE Workbook — Implementing SLOs(SLI / SLO / 错误预算定义与实操):https://sre.google/workbook/implementing-slos/
- Google Cloud Observability — Concepts in service monitoring(SLI、SLO、合规期与错误预算):https://cloud.google.com/stackdriver/docs/solutions/slo-monitoring
- PagerDuty Incident Response — Severity Levels(SEV-1 到 SEV-5 的公开分级定义):https://response.pagerduty.com/before/severity_levels/
- HTTPX 官方文档 — Resource Limits(连接池
max_connections/max_keepalive_connections默认值):https://www.python-httpx.org/advanced/resource-limits/ - OWASP — Top 10 for Large Language Model Applications(Prompt 注入、不安全输出处理等风险清单):https://owasp.org/www-project-top-10-for-large-language-model-applications/
- Python 官方文档 —
logging模块与自定义 Formatter:https://docs.python.org/3/library/logging.html - OpenTelemetry 官方文档 — Traces(trace_id 与 span 的贯穿模型):https://opentelemetry.io/docs/concepts/signals/traces/
- Google SRE Book — Handling Overload(有界队列、负载丢弃与背压策略):https://sre.google/sre-book/handling-overload/
- OpenAI 官方文档 — Rate limits(TPM / RPM 配额模型与 429 处理建议):https://platform.openai.com/docs/guides/rate-limits
更多推荐


所有评论(0)