排查路径
- 1. API 症状
- 2. SSH / 运行时证据
- 3. 数据库状态
- 4. 根因
- 5. 验证修复
第 1 步 — 复现 API 错误
复现可以把模糊报告转化为可重复检查。对于 POST /orders，请从预期环境发送请求，并保留足够信息，把该失败请求与附近流量区分开。
- 方法：确认请求确实是 POST，而不是相近的 GET、PUT 或重试端点。
- URL：记录解析后的主机、路径和相关查询参数。
- 环境：发送前确认 dev、test 或 prod，以及当前变量值。
- 请求数据：保留数据结构和标识符，但不要在共享示例中放入秘密。
- 状态与响应：记录 HTTP 状态、响应体和相关响应头。
- 耗时：记录请求发生时间和持续时间，便于匹配服务器证据。
第 2 步 — 检查服务器证据
使用 SSH 检查处理该请求的服务证据。Unfour 提供终端、历史、文件、诊断和保存的任务；它不假设某种日志格式，也没有虚构的通用日志解析器。
应用日志
在相关时间窗口内搜索请求标识符、路由、错误消息或堆栈，避免把无关日志全部倒入排查。
进程与运行时状态
检查预期进程是否运行、重启、资源受限，或是否连接了正确依赖。
配置证据
比较部署环境、服务配置和相关远程文件是否符合请求预期。
第 3 步 — 检查数据库状态
把当前假设转化为最小的有效查询。对于订单失败，这可能是检查关联客户、库存记录、幂等键、约束或部分创建的订单，而不是浏览所有数据表。
- 先从只读开始，尤其是生产环境或难以恢复状态的环境。
- 使用前面步骤中的请求标识符和时间戳，让查询保持聚焦。
- 确认数据库连接和 API、服务器检查指向同一环境。
- 如果确实需要修改，请在执行前复核生成或建议的 SQL、目标数据行、事务行为和回滚方案。
第 4 步 — 关联证据
根因判断应同时解释三层证据，并正视相互矛盾的发现。对于 POST /orders，一条有效证据链可能是：API 在 14:03 失败，服务针对订单 ID 812 记录外键错误，而同一测试数据库中缺少关联客户记录。
时间
API 请求时间是否与服务器错误以及数据库事件或记录状态一致？
标识
请求 ID、实体 ID、用户 ID 和 trace 值是否指向同一操作？
环境
API 主机、SSH 连接和数据库连接是否都指向同一目标？
因果关系
建议的原因是否解释了该请求为何失败，还是仅仅发现了附近的异常？
第 5 步 — 验证修复
-
应用经过复核的修改
只修改证据所支持的代码、配置或数据，并遵循该环境正常的评审与部署流程。
-
重复最初请求
使用相同的相关数据和环境再次发送 POST /orders，而不是改用更容易成功的替代请求。
-
检查预期结果
确认响应状态和响应体，再检查能定义成功的服务器或数据库副作用。
-
检查回归线索
如果修复可能影响原请求之外的范围，请查看附近错误日志或意外的数据变化。
常见错误
- 只读取 API 响应就猜测服务端原因。
- 尚未理解错误状态如何产生，就直接修改数据库数据。
- 从不同环境检查 API、SSH 或数据库证据。
- 把代码修改或部署成功当作原始失败已经修复的证据。
- 在多个无关工具之间复制不完整上下文，导致时间戳、标识符和环境信息逐渐漂移。
MCP 在哪里有帮助
MCP 可以辅助这套流程，但不必成为整篇排查的主题。兼容 Agent 可以查询已授权的 Unfour 工具、关联同一工作区中选定的证据，并在建议修复后重复检查。
- 查询已授权的保存请求、脱敏历史、SSH 诊断、数据库结构或只读结果。
- 比较时间戳、标识符、环境和结果，无需手动反复粘贴片段。
- 修改后重新执行相同的范围明确检查，让验证沿用原证据路径。
- 让受保护和高风险动作继续受工作区策略和内容绑定确认约束。