摘要: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 项
26 项 · 硬性门禁

P0 全绿?

打回修复
不允许进入下一步

第二遍:跑 P1 项
18 项 · 有豁免机制

P1 有未通过?

记录豁免原因 + 责任人
写入发布单

第三遍:灰度 5% 流量
观察 30 分钟

核心指标是否劣化?

自动回滚
见第 38 篇

放量到 100%
P2 项进下个迭代

三条使用原则:

第一,P0 是门禁,不是建议。 P0 项没通过就不发布,没有"先上再修"的余地——因为 P0 项对应的翻车一旦发生,就是安全事故或资损,不是"体验差一点"。

第二,P1 可以豁免,但必须写清楚谁豁免的、为什么。 豁免记录的价值在于事后复盘时有据可查,也在于让"豁免"变成一个需要承担责任的动作,而不是默认选项。

第三,P2 不阻塞发布,但要进 backlog。 P2 项通常是"优化"而非"缺陷"——比如缓存复用、小模型路由。它们不该拦住上线,但也不该被忘掉。

在这里插入图片描述

图1:上线前的三个门槛——功能正确只是最低的那个门槛


二、核心概念:什么是"上线前"

2.1 "上线前"是一个有时间窗口的状态,不是一个瞬间

很多人把上线理解成"点一下部署按钮"。实际上从代码冻结到放量完成,是一个持续数小时到数天的状态,而这个状态里要做的检查比部署本身重要得多。

跑 P0 与 P1 清单

全部通过

P0 未通过

重新提交

输出回归失败

核心指标无劣化

错误率或成本超阈值

三十分钟稳定

指标劣化

两小时稳定

指标劣化

代码冻结

门禁检查

预发验证

打回修复

灰度五

影子流量对比通过

观察窗口

自动回滚

放量百分之三十

全量

观察的不是有没有报错
而是 P95 成本与完成率
三项是否同时稳定

这张状态图里最该注意的是"灰度 5% → 观察窗口"这一段。 很多团队的流程是"灰度 5% 看一眼没问题就全量",观察窗口短到根本发现不了慢性问题——比如内存缓慢增长、成本缓慢爬升、某个长尾输入导致输出质量下降。我的经验值是:5% 观察 30 分钟、30% 观察 2 小时,少于这个时长等于没观察。

另一个要点是"打回修复 → 重新提交"这条回路。 它意味着门禁检查必须是可重复执行的——不能是"几个人坐在一起过一遍清单",而应该是一条命令能跑完的脚本。否则第二次检查的质量会显著低于第一次。

2.2 三类检查项的执行方式不同

50 项检查不是同一种东西,它们分属三类,执行成本和自动化程度差异很大:

类型占比自动化程度执行时机典型项
静态可查约 60%完全自动(脚本/CI)每次提交密钥扫描、模型版本锁定、超时配置
运行可测约 30%自动(压测/演练)发布前并发隔离、降级生效、预算熔断
人工判断约 10%半自动(评测集)发布前评审输出质量、合规审阅、工具权限合理性

静态可查的项应该全部进 CI,因为它们的边际成本几乎为零。运行可测的项应该做成可重复执行的脚本,每次发布前跑一次。人工判断的项要有明确的 checklist 和责任人,不能是"大家觉得没问题"。

⚠️ 最容易出错的是把"人工判断项"当成"静态可查项"来对待。 比如"输出质量是否达标"——有人会写一个断言说"输出长度 > 100 字",然后就以为检查过了。这类伪自动化比不检查更危险,因为它给了虚假的安全感。输出质量必须由评测集 + 人工抽检共同判定(第 36 篇),不能简化成一个正则。

2.3 修复成本随发现阶段的变化

为什么要在上线前检查?看这条曲线的形状就够了:

缺陷修复成本随发现阶段的倍数变化(以需求阶段为 1) 需求阶段 开发阶段 测试阶段 上线前门禁 灰度阶段 生产事故 60 55 50 45 40 35 30 25 20 15 10 5 相对修复成本倍数

从"上线前门禁"到"生产事故",成本涨了 4 倍。 但这只是直接工程成本——生产事故还要加上事故响应(多人小时级)、客户沟通、复盘文档、以及最贵的:信任损失。所以真实的倍数远高于图上画的。

这条曲线也解释了为什么"先上线再修"是个坏主意:它不是把成本转移了,而是把成本放大了。唯一的例外是 P2 项——它们的成本曲线很平(本来就是优化项),所以可以放到上线后。


三、清单总览:八组五十项

组主题项数P0P1P2主要对应篇号
APrompt 与模型732236、38、28
B输入输出733127、37、30、39
C工具与副作用743031、37、39、24
D状态与持久化632130、40、34
E并发与限流632140、31、32
F成本与配额632144、37、39、38
G可观测633027、31、38、37
H安全与合规541034、44、40、29、31
合计—5026186—

优先级判据(这是我的口径,团队应替换成自己的):

优先级判据未通过时的处理数量
P0翻车会导致安全事故、资损、服务不可用禁止发布26
P1翻车会导致体验明显下降或成本显著上升可豁免,需记录责任人与原因18
P2属于优化项,不影响可用性进 backlog,不阻塞6
52% 36% 12% "50 项检查的优先级分布" P0 必查 [26] P1 建议 [18] P2 可选 [6]

在这里插入图片描述

图2:八组检查项速查——按上线前必过的顺序排列


四、A 组:Prompt 与模型(7 项)

这一组管的是"模型的行为会不会在意想不到的情况下变掉"。第 36 篇讲过评测,这里讲的是上线前必须锁死的东西。

#检查项翻车现象怎么查规避方案优先级篇号
1Prompt 有版本号与变更记录改了 Prompt 无法回滚,线上行为变化无从追查检查代码里 Prompt 是否为常量字符串散落各处Prompt 集中管理 + 版本号 + 变更 diff 记录P136
2模型版本显式锁定上游把别名指向新版本,输出风格突变、格式失配打印实际返回的模型标识并与期望值比对用带日期的具体版本号,不用 latest 一类别名P036、44
3有离线评测集与通过阈值只靠人工感觉判断"还行",上线后质量塌陷跑评测集,看关键指标是否达到阈值评测集 ≥ 100 例,含边界与对抗样本(第 36 篇)P036
4系统提示与用户输入分离用户输入被拼进系统提示,可越权改写指令检查调用构造,是否用 role 区分系统提示走 system 角色,用户输入永不拼入P228
5采样参数显式设置依赖上游默认值,换供应商后输出差异巨大检查是否显式传了 temperature / top_p显式传参并写入配置,不依赖默认P136
6有 Prompt 注入防护用户上传的文档里藏指令,Agent 执行了它用含"忽略以上指令"的样本做对抗测试输入隔离 + 输出后置校验 + 工具权限最小化P031
7有小模型兜底路由主模型不可用即整体不可用演练:主模型返回 5xx,看是否自动降级配置降级链,见第 38 篇降级矩阵P238

我的拍板建议:第 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 篇)P027、37
9解析失败有修复重试一次解析失败就整体失败,成功率凭空掉 5%统计解析失败率与修复成功率最多 2 次修复重试,把原始输出回传要求重格式化P137
10输入长度有上限与截断策略用户粘了一篇长文,Token 暴涨、成本失控、上下文溢出构造超长输入看是否报错或爆炸计费硬上限 + 中段截断 + 明确告知用户P030
11输入与输出有敏感信息脱敏用户手机号、身份证进了日志和上下文用含手机号/邮箱的输入跑一遍,grep 日志入站脱敏(可逆映射)+ 出站过滤P028
12编码统一为 UTF-8 且无 BOM输出偶尔出现乱码或多出一段英文检查读写链路的 encoding 参数全链路显式 encoding="utf-8",禁用系统默认编码P144
13输出长度有上限模型进入重复循环,单次输出几十万 Token压测时观察输出 Token 分布的长尾设 max_output_tokens + 重复片段检测提前中断P039
14输出有后置事实/越权校验Agent 编造了不存在的订单号并调用了退款用对抗样本测试越权输出关键字段做存在性校验 + 高风险动作二次确认P236

我的拍板建议:第 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工具有危险等级标注删除类工具被当作只读工具随便调用检查工具注册表里每个工具是否有风险标记三级分类:只读 / 可写 / 危险,分级授权P031
16写操作有二次确认或审批Agent 自作主张改了生产数据演练:让 Agent 执行写操作,看是否被拦截危险级工具必须人工确认或走审批队列P037
17工具参数有校验传入非法参数导致下游脏数据或报错用越界/错类型参数调用工具每个工具有参数 schema,非法参数直接拒绝P127
18写操作有幂等键超时重试导致同一笔操作执行两次制造超时后重试,检查数据是否重复幂等键 + 结果缓存(第 39 篇)P039
19工具有独立超时一个慢工具拖死整个请求让某工具 sleep 60s,看整体是否被拖到超时每个工具独立超时,总和小于请求预算P139
20工具失败有明确错误语义工具返回自然语言错误,模型误判为成功让工具抛异常,观察模型后续行为结构化错误码 + 是否可重试标记P137
21有工具调用次数上限Agent 陷入调用循环,一次请求调了几百次压测统计单请求的工具调用次数分布上限(如 20 次)+ 超限时转人工或降级P024

我的拍板建议:第 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会话状态可持久化与恢复实例重启后用户会话全丢,对话断片杀掉进程重启,看会话是否恢复每次状态变更落盘,启动可从存储重建P030
23状态写入有版本号/乐观锁并发写导致后写覆盖先写,回复丢失同会话并发发两条消息,检查是否丢内容版本号 + CAS,或会话级串行(第 40 篇)P030、40
24会话有 TTL 与清理机制会话表无限增长,三个月后查询变慢查会话表行数与时间分布TTL + 定期归档清理P130
25长会话有上下文压缩策略对话 50 轮后 Token 暴涨、成本翻倍、超窗口报错模拟 50 轮对话观察 Token 与成本曲线摘要压缩 + 滑窗,见第 30 篇三层状态P230
26多实例下状态共享或会话粘滞用户第二次请求落到另一个实例,找不到上下文多实例压测,看是否有上下文丢失外部存储共享 或 会话粘滞路由(第 40 篇)P140
27状态中不含密钥与大对象会话状态里存了 API Key,存储泄露即密钥泄露扫状态存储里的敏感字段只存引用(如凭据 ID),不存明文P034

我的拍板建议:第 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 节)P040
29有用户/租户级配额一个客户吃光所有配额,其他人全超时单租户打满流量,测其他租户 P99租户令牌桶 + 预留 20%~30% 共享余量P140
30有全局 Token 速率限制请求数没超但 TPM 超了,上游 429 一片压测统计上游 429 次数令牌桶 + 事后校正(第 40 篇 4.3 节)P040
31队列有界且有溢出策略无界队列导致"全都超时但没有一个被拒绝"过载压测,观察队列长度与拒绝率有界队列 + reject/drop_oldest/降级P040
32连接池大小匹配实际并发并发设了 50 但连接池只有 20,出现"假并发"监控连接池等待队列长度是否长期 > 0池大小 ≥ 实际并发 × 1.2(第 40 篇 2.4 节)P140、44
33长任务与交互式资源分离一个 10 分钟批量任务饿死 50 个交互式请求混合负载压测,对比交互式 P99独立资源池,批量池故意设小P240

我的拍板建议:第 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 与最大值超过上限立即中断并降级P044
35日/月预算上限与硬性熔断一夜之间成本超预算 5 倍看账单的最小告警粒度是小时还是天小时级预算检查 + 触顶熔断(不只是告警)P044
36重试有次数上限且成本可感知一次用户输入触发 7 次重试,每次带完整上下文统计重试放大倍数 = 总调用数 / 用户请求数重试次数 ≤ 3,重试计入同一预算P037、39
37有缓存复用相同问题重复付费统计缓存命中率精确缓存 + 语义缓存(第 32 篇)P132
38成本可按租户/用户归因只知道总账单,不知道谁花的看能否按用户导出成本明细每次调用打上归属标签并记账P131
39有小模型路由降本简单问题也用最贵的模型统计简单问题的模型分布复杂度分级路由(第 38 篇)P238

我的拍板建议:第 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 篇)P027
41记录了 Token 与成本指标只知道慢,不知道贵看监控里有没有成本指标每次调用记录 Token 与折算成本P131
42有 P95/P99 与错误率看板平均值正常但用户抱怨很慢看有没有分位数指标分位数 + 分租户维度P040
43有降级触发次数指标悄悄降级了三个月没人知道查降级计数器降级次数与降级率入监控并告警P138
44日志有脱敏与分级日志里出现明文密钥和手机号grep 日志里的 sk-、手机号结构化日志 + 敏感字段过滤(第 28 篇)P028、44
45有关键告警与值班响应出问题两小时后被用户告知演练:手动触发故障,看多久告警分级告警 + 值班表(参照 SEV 分级)P137

我的拍板建议:第 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 篇)P034
47日志与追踪中无明文密钥日志系统可读范围大于密钥权限,等于密钥公开跑第十节的两条扫描框架层脱敏 FormatterP044
48租户数据隔离在数据访问层强制一个租户查到另一个租户的数据用租户 A 的凭据查租户 B 的 ID存储层强制注入租户条件(第 40 篇 2.3 节)P040
49关键操作有审计留痕出事后无法还原谁在什么时候做了什么抽查一次写操作的审计记录事件化审计日志(第 29 篇)P129
50有内容安全与合规过滤Agent 生成违规内容并直接返回给用户用对抗样本测试输入输出入站 + 出站双重过滤(第 31 篇)P031

我的拍板建议:第 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%禁止发布
降级演练注入上游故障降级未生效禁止发布
压测 P99wrk 混合负载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:清单多久复核一次?

每季度一次,另外每次事故之后必加项。 一份两年没改的检查清单可信度低于没有清单——因为它给了虚假的安全感,让人以为"过了一遍就没事了"。


参考资料

  1. Google SRE Workbook — Implementing SLOs(SLI / SLO / 错误预算定义与实操):https://sre.google/workbook/implementing-slos/
  2. Google Cloud Observability — Concepts in service monitoring(SLI、SLO、合规期与错误预算):https://cloud.google.com/stackdriver/docs/solutions/slo-monitoring
  3. PagerDuty Incident Response — Severity Levels(SEV-1 到 SEV-5 的公开分级定义):https://response.pagerduty.com/before/severity_levels/
  4. HTTPX 官方文档 — Resource Limits(连接池 max_connections / max_keepalive_connections 默认值):https://www.python-httpx.org/advanced/resource-limits/
  5. OWASP — Top 10 for Large Language Model Applications(Prompt 注入、不安全输出处理等风险清单):https://owasp.org/www-project-top-10-for-large-language-model-applications/
  6. Python 官方文档 — logging 模块与自定义 Formatter:https://docs.python.org/3/library/logging.html
  7. OpenTelemetry 官方文档 — Traces(trace_id 与 span 的贯穿模型):https://opentelemetry.io/docs/concepts/signals/traces/
  8. Google SRE Book — Handling Overload(有界队列、负载丢弃与背压策略):https://sre.google/sre-book/handling-overload/
  9. OpenAI 官方文档 — Rate limits(TPM / RPM 配额模型与 429 处理建议):https://platform.openai.com/docs/guides/rate-limits
Logo

更多推荐