Docker 部署故障排查手册：打不开、502、登录失败与上传失败

动手前先知道

这篇文章对应的真实任务是：按故障现象整理 Docker 部署排查路径，覆盖首页打不开、接口报错、后台登录、图片上传、数据库连接和磁盘占满。

第一次阅读先弄清“为什么需要这一步、它改变了哪个运行对象、失败时去哪里检查”，再执行命令。命令可以查，运行模型和排障路径才是长期能力。

这一篇是 Docker 部署故障排查手册。真正上线时，最怕的是页面打不开却不知道从哪里查。这里按现象整理排查路径。

现象一：首页打不开

先看容器：

docker compose ps

如果 nginx、web、api 有容器退出，再看日志：

docker compose logs --tail=100 nginx
docker compose logs --tail=100 web
docker compose logs --tail=100 api

再看端口：

ss -lntp

常见原因：

• Nginx 没启动。
• 安全组没开放端口。
• Compose 服务名写错。
• 前端构建失败。
• API 地址配置错。

现象二：页面能打开，但接口报错

先访问健康检查：

curl http://127.0.0.1/api/v1/health

如果走 Nginx：

curl http://127.0.0.1/api/v1/health

如果容器内测试：

docker compose exec nginx wget -qO- http://api:8080/api/v1/health

常见原因：

• API 容器没启动。
• Nginx /api 转发写错。
• 后端连接数据库失败。
• 环境变量没加载。
• CORS 配置不包含当前域名。

现象三：后台登录失败

排查顺序：

1. 账号密码是否正确。
2. Cookie 是否被浏览器保存。
3. API 登录接口是否 200。
4. CORS 和 SameSite 配置是否正确。
5. 后端 session/JWT 密钥是否变化。
6. 数据库管理员账号是否存在。

如果每次重启后登录状态都丢失，要检查密钥是否每次随机生成。

现象四：图片上传失败

先看浏览器 Network：

• 请求状态码是多少？
• 报错来自前端、Nginx、后端，还是 COS？

再看后端日志：

docker compose logs --tail=100 api

常见原因：

• Nginx 上传大小限制太小。
• COS Secret 配置错。
• Bucket 地域写错。
• 图片格式不允许。
• 后端临时目录没有权限。

现象五：数据库连接失败

常见错误：

connection refused
access denied
unknown database
timeout

分别对应：

• 数据库没启动或地址错。
• 用户名密码错。
• 数据库不存在。
• 网络不通或安全组拦截。

如果数据库在 Compose 内部，后端 DSN 主机名通常应该是 mysql，不是 127.0.0.1。

现象六：新版本没生效

排查：

docker compose images
docker compose ps
docker compose logs --tail=50 web

常见原因：

• 镜像没有重新 build。
• Compose 仍然引用旧镜像。
• 浏览器缓存。
• Nginx 缓存。
• 前端静态资源没有更新。

可以尝试：

docker compose build web api
docker compose up -d

现象七：磁盘满了

查看磁盘：

df -h
docker system df

常见占用：

• Docker 镜像层。
• 容器日志。
• MySQL 数据。
• 备份文件。
• 构建缓存。

清理前先确认不要删数据库 volume。生产服务器清理命令一定要谨慎。

排障心法

不要一上来改配置。先定位是哪一层：

浏览器
  ↓
Nginx
  ↓
Web / API
  ↓
数据库 / COS / 外部 AI

每次只改变一个因素，改完立刻验证。这样问题会越来越小，不会越修越乱。