故障排查

约 541 字大约 2 分钟

遇到问题时先缩小范围：是浏览器访问、Gateway 路由、业务服务、数据库/对象存储，还是 AI 上游渠道。不要一开始就重启全部服务或修改数据库。

诊断路径

现象	检查顺序	常见原因
页面不可访问	DNS/TLS → Nginx → 前端容器 → Gateway	域名未解析、证书路径错误、容器未运行。
登录失败	用户端请求 → Gateway → user-service → MySQL	密钥不一致、服务未就绪、用户状态异常。
上传失败	浏览器 → Gateway/media-service → 对象存储	Bucket/域名配置缺失、对象存储权限或文件限制。
任务失败	任务 ID → generation-service → AI 控制/渠道 → 上游	模型映射、渠道凭证、输入参数或上游限流。
结果未回填	generation/media 日志 → 对象存储 → 回调地址	结果下载/保存失败、回调地址不可达。
后台数据异常	后台请求 → 目标服务 → 数据库	服务路由、权限或迁移版本不一致。

命令与证据

docker compose --env-file .env ps
docker compose --env-file .env logs --tail=300 gateway generation-service media-service
docker compose --env-file .env logs --tail=300 user-service ai-control-service billing-service
docker compose --env-file .env run --rm db-migrate -command version

排查记录应包含发生时间、用户/项目范围、请求或任务 ID、错误信息、关联服务日志和已执行动作。不要把密钥、授权头、支付私钥或完整个人信息写入工单。

常见修复动作

服务未运行：确认配置后，只重启受影响服务。
迁移未完成：检查 db-migrate 日志和版本，修正迁移问题后重新执行，不手工改表。
渠道异常：先停用有问题的渠道或降低权重，保持已验证渠道可用。
对象存储异常：检查启用状态、Bucket、访问域名、凭证和公网可访问性。
上游超时：检查上游状态、任务并发、轮询间隔和处理超时，避免无限重试。