Docker Compose 部署项目

Docker Compose 部署项目常见错误排查实战

使用 Docker Compose 部署项目确实能省去很多手动配置的麻烦，但初学者在第一次运行时往往会被各种报错卡住。
这篇文章从实际运维经验出发，把最常见的错误和解决思路整理出来，方便你遇到问题时能直接照做。

一、部署前先检查这两个地方

不少报错其实在写 docker-compose.yml 这一步就可以避免。

端口是否被占用：项目里映射的端口（比如 "8080:80"）如果已经被本机其他进程占用，Compose 会直接退出。
可以先运行 lsof -i :8080（Linux/macOS）或 netstat -ano | findstr :8080（Windows）看端口是否空闲。
建议在 docker-compose.yml 中把宿主机端口尽量改成 8081、9090 这类不常用的。

目录挂载路径是否存在：比如配置了 ./data:/var/lib/mysql，但本地 data 目录没创建，MySQL 容器会因权限问题闪退。
稳妥做法是先用 mkdir -p ./data 创建好，并赋权 chmod 777 ./data。

二、容器启动失败？先看日志

服务起不来是最常见的报错。
别慌，直接看日志比猜原因快得多。

docker-compose logs --tail=50   # 查看所有服务的最后50行日志
docker-compose logs web -f      # 只看 web 服务的实时日志

常见故障分两类：

• 数据库容器先于应用启动：应用启动时数据库端口还没就绪，报 Connection refused。解决办法是在 depends_on 之后加 condition: service_healthy（健康检查），或者用 wait-for-it 脚本等待。示例片段：

services:
  web:
    depends_on:
      db:
        condition: service_healthy
  db:
    image: mysql:8
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]

• 环境变量缺失：比如应用需要 DB_HOST，但 docker-compose.yml 中没定义。检查 environment 块是否完整，或者 .env 文件是否存在。

三、容器网络不通怎么办

多容器项目经常出现 A 容器连不上 B 容器，比如前端打不开后端接口。

原因一：没有自定义网络。
默认 Composer 会给项目创建名为 项目名_default 的网络，但如果你在 docker-compose.yml 中显式指定了 networks，就必须保证所有服务都在同一个网络下。

services:
  backend:
    networks:
      - app-net
  frontend:
    networks:
      - app-net
networks:
  app-net:
    driver: bridge

原因二：容器间通信用服务名而不是 localhost。
比如后端访问数据库时，连接地址要写 db（服务名）而不是 127.0.0.1。

验证方法：进入一个容器 docker exec -it <容器名> sh，然后 ping db 看是否通。

四、数据卷权限与文件丢失

挂载本地目录后，容器内写的文件在宿主机上找不到，或者容器内进程无权限写入。

避免方法：

• 挂载目录时，宿主机目录的 UID/GID 与容器内进程的 UID 一致。比如 Nginx 默认用 www-data 用户（UID 33），可以 chown -R 33:33 ./html。
• 对数据库容器，建议使用 volumes 而不是 bind mounts，让 Docker 管理目录，减少权限踩坑。

volumes:
  mysql_data:
services:
  db:
    volumes:
      - mysql_data:/var/lib/mysql

五、避坑总结与最终验证

最后汇总几条最实用的经验：

• 每次修改 docker-compose.yml 后，必须重新 docker-compose up -d 才会生效，只重启某服务不会读取新配置。
• 如果项目使用 .env 文件，确保它与 docker-compose.yml 同级，并且变量名正确。
• 调试阶段不要用 -d 参数，直接 docker-compose up 可以实时看滚动日志，错误一目了然。

验证项目是否正常运行：访问配置的端口（比如 http://服务器IP:8080），如果能正常打开页面或者 API 返回数据，说明部署成功。
如果还是报错，优先检查第一步提到的端口是否真的映射正确：docker-compose ps 查看端口映射列。
如果端口显示 0.0.0.0:8080->80/tcp，说明正常。

如果你正在处理 Docker Compose 部署项目，常见错误排查，建议先按本文步骤完整执行，再根据自己的环境做微调；
遇到异常时优先回看避坑和高频问题部分，多半能直接找到答案。