生产问题调查故障排查

可用性：available

从最窄边界开始排查。不要仅为获得更多信息就启用请求 debug 日志或暴露凭据。

API 未 ready

先检查 /livez，再检查 /readyz。API 启动需要可访问的 PostgreSQL、Redis 与有效 MENDRY_ENCRYPTION_KEY。启动依赖新 schema 的 binary 前需显式执行迁移，API 不会修复 migration history。

无法登录

确认 bootstrap-admin 命令已在同一数据库中创建登录账号。密码长度为 12 到 72 字节。API Session 需要 Redis，但 bootstrap 命令本身不使用 Redis。staging/production 必须使用 HTTPS，因为 Session Cookie 带 Secure。单用户数据库不能再初始化第二个用户名。

配置始终不完整

读取 /configuration/draft。完整配置端点要求 environment、repository、source 与 trigger 都已保存，每个组件独立保存。可选 LLM row 不会补全缺失的必需 row。

Webhook 返回 not found

确认 trigger 已保存、enabled 且 kind 为 signed_webhook，并确认发送端在轮换后使用最新 token。未知、禁用、不完整和已轮换 token 会故意返回相同的 404 webhook_not_found。

Webhook 返回 202 但没有事故

202 早于后台处理完成。使用项目/来源 scope 和 request correlation 搜索结构化日志中的 webhook.ingest.failed，不要搜索原始 token。检查 provider shape、模型连接、PostgreSQL 写入和事故配置。模型失败应使用确定性 fallback；持久化或证据失败仍需操作员处理。

SSH 日志探针安装失败或停留在 starting

确认已保存的采集源使用 SSH、host deployment 和 tail mode，且 trigger 已保存并启用。检查 SSH 凭据、日志文件绝对路径及读取权限，以及目标主机的 Python 3.6 或更新版本、运行中的 systemd 和无交互 sudo -n。主机还需能够通过 HTTPS 访问 MENDRY_PUBLIC_URL。

安装返回 starting 只表示远端命令已完成，还需等待本次探针上报新的 monitoring 状态。重新安装前先查看状态及错误提示。编辑 trigger 或轮换 token 后，使用 Install or update 替换远端的旧配置。

SSH 日志探针正在监控，但没有事故

探针首次启动只处理新增行。确认应用正在写入所选文件，并在 windowSeconds 内产生足够多的匹配行以达到 threshold。检查 excludePattern 和 cooldownSeconds，再查看投递错误以及到 Mendry 的连通性。当前探针不支持 Docker stdout、journald、多行堆栈聚合和“长时间无日志”规则。详见 SSH 日志监控。

修复停止或报告证据不足

这是策略结果，不是绕过门禁的理由。检查不可用来源、精确 Git 基线、工具 budget、已存证据 provenance，以及必需的腾讯 CLS direct detail。只有修复缺失 capability 或 evidence 后才重试。

未收到通知或投递失败

打开 Configuration → Notifications 检查最近投递。没有记录可能是事件发生时渠道未启用，或当前代次已经发送过首次 AI 结果。测试消息没有业务投递记录，人工恢复或关闭事故也不会发送通知。

投递失败时，检查凭据与到平台的出站 HTTPS 连通性，修复原因后再手动重试；对应渠道必须仍存在且已启用。已取消投递不能重试。迁移要求、消息顺序、凭据轮换和重试限制见项目通知。

安全诊断

使用 JSON 日志获取完整 trace/request ID。不要把 .env、Session Cookie、Webhook URL、凭据、原始 prompt、provider callback 或原始客户证据粘贴到 issue 中。

核验依据

• backend/README.md
• backend/.env.example