架构图排障证据的保留

架构图排障证据的保留

本文讨论“用精美架构图讲清复杂技术原理的方法：日志、指标、Trace 的可观测性落地”。这里的场景只用于说明方法，不对应某次真实线上事故；任何效果判断都应以项目自己的数据、配置和负载为准。

先定义问题和边界

“用精美架构图讲清复杂技术原理的方法”不是一个可以直接优化的指标。开始前应明确目标对象、受影响请求、输入边界、依赖服务和验收标准。涉及质量时，应准备带有判定规则的样本，而不是只凭主观印象。

留下可核验的证据

明确输入输出契约、状态归属、失败语义、超时预算和幂等要求，并把不支持的能力写在边界里。 记录还应包含时间范围及代码、模型或配置版本，避免把环境变化误判为方案效果。 先覆盖高风险路径，避免用主流程代替完整验证。

按小步变更验证

把超时、重试、限额、降级和错误返回放在明确位置，先用开关或隔离范围验证一个假设。出现异常时，应能回退到已知状态。 先覆盖高风险路径，避免用主流程代替完整验证。

验证清单

结论应限于已有记录，并把风险与下一步验证项写清。 先覆盖高风险路径，避免用主流程代替完整验证。

证据要足够复现，也要控制暴露范围

有效的排障材料能回答时间、版本、输入类别、异常阶段和当时采取的动作。日志片段、指标快照、追踪记录和配置差异最好由同一个关联标识串起来；只截一张告警图，往往看不到问题发生前后的上下文。采集时先保存原始时间线，再做解释，避免事后只留下符合某个猜测的片段。

留证不等于保留所有数据。请求正文、访问令牌、用户标识、堆转储和完整环境变量可能包含敏感信息，应按定位所需最小化采集，放在有访问控制与保留期限的位置。对外分享时优先提供脱敏摘要。验证修复要尽量复用相同输入和环境，一次只调整一个因素，并把能够稳定触发问题的条件加入回归测试。证据无法支持因果关系时，就写清仍有哪些可能，而不是用肯定语气补齐故事。

回到大模型检索应用的实际约束

讨论“架构图排障证据的保留”时，容易混在一起的是检索、重排、生成、缓存和异步任务。可以先画出一条真实操作的状态变化，标出每一步由哪段代码或哪个团队负责，再检查失败会停在哪里。把引用、版本和降级结果留在同一条记录里。示例里的参数只能说明写法，接入项目后仍要依据当前依赖、设备或数据重新测量。

验证时保留一份最小输入，并准备与它对应的失败输入。正常路径确认结果能被下一环节消费，失败路径确认提示、日志和恢复动作一致。若现有材料不足以支持某个性能或效果结论，就保留限制条件，等有可复现记录后再判断。这样写出的方案不会显得花哨，却能让接手的人知道从哪里开始、在哪里停下，以及怎样确认修改没有越过原来的边界。