日志查看与故障排查

cheat-sheet：4 条命令看日志、1 个决策树定位、4 种常见报错照表处理。

8.1 关键命令

在 docker-compose.yml 所在目录，记住这 4 条就够。

# 实时跟随 agent 日志
docker compose logs -f agent

# 最近 200 行 / 过去 1 小时
docker compose logs --tail=200 agent
docker compose logs --since=1h agent

# 过滤报错
docker compose logs --since=1h agent | grep -i error

小贴士： 排查顺序：nginx error.log → agent 容器日志 → postgres 日志。绝大多数问题在前两步定位。

8.2 决策树 · 服务起不来

容器状态 Exit 或反复 Restarting，按报错关键字对号入座。

跑 docker compose logs --tail=100 agent 看最后几行
按下表关键字处理，处理完 docker compose up -d 重试

关键字	原因 / 处理
`connection refused` / `could not connect to postgres`	postgres 没起来，`docker compose logs postgres` 看它的报错
`permission denied` / `read-only file system`	数据卷权限，检查 `./data` / `./uploads` 属主（参考首次部署）
`port already in use`	3001 端口被占，用 `ss -tlnp` 过滤 `:3001` 看是谁，停掉或改端口映射
`missing env` / `required setting`	`.env` 缺关键变量，对照docker-compose 配置详解补齐

8.3 决策树 · 起来了但报错

容器 healthy，但用户操作失败。复现一次 + 盯 agent 日志即可。

开一个窗口 docker compose logs -f agent，让用户复现
看新冒出来的报错关键字，对应下表
截图 + 时间戳 + 复现步骤，丢给研发

关键字	处理
登录失败 / 授权错误	同账号能否直登 JECloud 业务平台？不能 → 平台账号问题；能 → 看 agent 日志「业务平台地址」或「token 校验」
订阅过期 / 授权相关	小匠侧授权过期，找采购续费，证书续上自动恢复
`Traceback` + Python 堆栈	截最后 10 行堆栈 + 复现步骤发研发
`upstream timeout` / `504`	业务平台或 LLM 接口慢，看 nginx `error.log` 哪段慢

注意： 带时间戳和复现步骤：「14:23 用户 A 点 X 按钮报 500」比光秃秃的截图快 10 倍定位。

8.4 4 个常见报错

出现频率最高，照表处理。

现象	关键字	处理
数据库锁	`database is locked` / `deadlock detected`	多在备份/迁移时，`SELECT * FROM pg_stat_activity` 看长事务，必要时 `pg_cancel_backend(pid)`
连接池满	`too many connections` / `pool exhausted`	`docker compose restart agent` 临时缓解 + `.env` 调 `DB_POOL_SIZE`
磁盘满	`no space left on device`	`df -h` 看分区，`docker system prune` + 清老备份 + 配日志轮转（8.5）
性能卡顿	用户喊「卡」	`docker stats` 看谁吃 CPU/内存，三项都不高去看性能调优

8.5 防爆盘 · 日志轮转

装完小匠就该配上，几个月不管能吃掉几十 GB。

编辑 /etc/docker/daemon.json（没有就新建），写入下面配置
夜间维护窗口 systemctl restart docker（会重启所有容器）
docker info | grep -i logging 确认生效

{
  "log-driver": "json-file",
  "log-opts": { "max-size": "50m", "max-file": "5" }
}

注意： 重启 docker = 断所有服务。提前告知用户，挑维护窗口做。

8.6 搞不定就求助

排查 30 分钟没定位 → 别硬磕，按下面格式找研发。

抓材料：docker compose logs --since=1h agent > agent.log + docker compose ps 截图 + 报错截图（带时间）+ 复现步骤
定级：全员登不上=P0；部分报错=P1；偶发=P2
临时止血：docker compose restart agent → down && up -d → 从备份回滚（数据备份与恢复）

注意： 不要在生产库盲跑 SQL。DELETE / UPDATE / DROP 前先备份并让研发 review。线上误删都是从「我先快速 fix 一下」开始的。