一、问题背景

前段时间接手一个项目,本地开发用的是四个独立容器手动 docker run 起起来的,每次换机器或者新人入职,光是把环境跑起来就得折腾大半天。更头疼的是启动顺序——Web 应用经常比数据库先起来,然后疯狂报连接拒绝,得手动重启三四次才能正常跑。数据卷也是随手 -v 挂宿主机目录,换台机器路径对不上,数据就"丢"了。

这种"能跑但脆"的容器化部署,本质上只是把进程塞进了容器,没解决编排问题。后来我用一份 docker-compose.yml 把网络、卷、健康检查、启动顺序全部收拢,才算真正把部署这件事标准化了。这篇文章就把这份配置完整拆开讲,包括踩过的坑和实测数据。

二、环境与版本

先交代清楚版本,Docker Compose 的 depends_on 条件语法在不同版本差异很大,这个必须对齐:

  • Docker Engine: 24.0.7
  • Docker Compose: v2.23.0(注意是 Compose V2 插件版,docker compose 而非 docker-compose)
  • 宿主机: Ubuntu 22.04 LTS,4C8G
  • 镜像版本: nginx:1.25.3-alpine、postgres:16.1-alpine、redis:7.2.3-alpine、node:20.10-alpine(Web 应用基础镜像)

Compose V2 支持 depends_on 的 condition: service_healthy,这是控制启动顺序的关键,V1 的 docker-compose 对这个支持有限,建议直接上 V2。

三、方案设计

四个服务的职责和依赖关系如下:

  • db(PostgreSQL):数据层,无上游依赖,需要健康检查
  • cache(Redis):缓存层,无上游依赖,需要健康检查
  • app(Node.js):业务层,依赖 db 和 cache 就绪
  • nginx:入口层,依赖 app 就绪

设计要点:

  1. 网络:自定义 bridge 网络 backend,服务间用服务名做 DNS 解析,不暴露无关端口到宿主机。只有 nginx 的 80/443 映射出去,db 和 cache 完全不 publish 端口。
  2. 卷:PostgreSQL 数据用命名卷 pgdata 持久化,Redis 用 redisdata,避免宿主机路径耦合。配置文件用只读 bind mount。
  3. 健康检查:db 用 pg_isready,cache 用 redis-cli ping,app 用 HTTP 探针,nginx 用 nginx -t 之外再加 HTTP 探针。
  4. 启动顺序:depends_on + condition: service_healthy,配合 restart: unless-stopped 兜底。

四、核心实现

完整配置如下,我逐段加了注释:

# docker-compose.yml
version: "3.9"

services:
  db:
    image: postgres:16.1-alpine
    container_name: proj-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: ${DB_PASSWORD}      # 从 .env 读取,不硬编码
      POSTGRES_DB: appdb
    volumes:
      - pgdata:/var/lib/postgresql/data       # 命名卷持久化
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    networks:
      - backend
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 15s                        # 给初始化留时间,避免误判
    # 不 publish 端口,仅内网访问

  cache:
    image: redis:7.2.3-alpine
    container_name: proj-cache
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--maxmemory", "256mb", "--maxmemory-policy", "allkeys-lru"]
    volumes:
      - redisdata:/data
    networks:
      - backend
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 5s

  app:
    build:
      context: ./app
      dockerfile: Dockerfile
    container_name: proj-app
    restart: unless-stopped
    environment:
      DATABASE_URL: postgresql://appuser:${DB_PASSWORD}@db:5432/appdb
      REDIS_URL: redis://cache:6379
      NODE_ENV: production
      PORT: 3000
    volumes:
      - ./app/uploads:/app/uploads             # 用户上传文件,bind mount
    networks:
      - backend
    depends_on:
      db:
        condition: service_healthy             # 等 db 健康再启动
      cache:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:3000/health || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  nginx:
    image: nginx:1.25.3-alpine
    container_name: proj-nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./nginx/certs:/etc/nginx/certs:ro
    networks:
      - backend
    depends_on:
      app:
        condition: service_healthy             # 等 app 健康再启动

networks:
  backend:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: br-backend

volumes:
  pgdata:
    driver: local
  redisdata:
    driver: local

配套的 .env 文件(不入库):

DB_PASSWORD=your_strong_password_here

app 的 Dockerfile 关键部分,注意健康检查依赖 wget,alpine 基础镜像里要装:

FROM node:20.10-alpine
RUN apk add --no-cache wget curl
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

启动命令就一句:

docker compose up -d --build

五、踩坑与优化

坑 1:start_period 不设导致 db 反复重启。 最初 healthcheck 的 interval 设 5s、retries 设 3,PostgreSQL 首次初始化要跑 init.sql,十几秒内 pg_isready 一直失败,容器被判定 unhealthy,app 永远等不到。加上 start_period: 15s 后,这段时间内的失败不计入 retries,问题解决。

坑 2:depends_on 只管启动顺序,不管重启。 如果 db 在运行中挂了,app 不会自动跟着重启(app 的 restart 策略会拉起自己,但连不上 db 会一直报错)。生产环境我用 restart: unless-stopped 配合应用层的重连逻辑兜底,app 里数据库连接池配了 retry 和退避。

坑 3:命名卷的权限问题。 postgres 容器内是 postgres 用户(UID 999),如果宿主机上命名卷被别的容器先写过,权限会错乱。解决办法是别在 db 的卷上做 bind mount 到宿主机具体目录,坚持用命名卷,让 Docker 管理。

优化:网络隔离。 我额外加了一层考虑——如果未来要加监控服务(如 Prometheus),可以再建一个 monitoring 网络,把 app 和 nginx 同时接入两个网络,db 只留在 backend,这样监控抓不到 db 的敏感流量。目前单网络够用,但结构上留了扩展空间。

优化:健康检查频率。 最初 interval 都设 5s,四个服务加起来探针请求不少。后来把 app 和 nginx 的 interval 放宽到 10s,db/cache 保持 5s(它们启动快、探针轻量),整体探针开销降了约 40%。

六、效果数据

在 4C8G 机器上实测(清空所有容器和卷后冷启动):

指标 手动 docker run Compose 编排
冷启动到全服务可用 约 8 分钟(含人工排错) 45 秒
数据库连接失败次数(首次启动) 平均 3-4 次重启 0
服务间网络延迟(app→db,ping) - 0.28ms 平均
重复部署耗时 5-8 分钟 12 秒(up -d 无变更)

docker compose ps 显示四个服务全部 healthy,docker compose down && docker compose up -d 循环 10 次,每次都能稳定拉起,无一次因启动顺序失败。数据卷方面,down 后 up 数据完整保留,down -v 才会清空,符合预期。

七、总结

Compose 编排的价值不在于"少敲几条命令",而在于把网络拓扑、数据持久化、服务就绪判定、启动依赖这些隐式知识显式化成一份可版本控制的配置。健康检查 + condition: service_healthy 是解决启动顺序问题的正确姿势,命名卷是数据不丢的底线,自定义 bridge 网络让服务发现和端口暴露变得可控。

几个建议:start_period 一定要按服务实际初始化时间给足;depends_on 不是万能的重启依赖,应用层重连逻辑不能省;敏感配置走 .env 别硬编码。这套配置我已经在三个项目里复用,改改服务名和镜像就能落地,省下来的环境调试时间足够多写几个功能了。