一、问题背景:7 条 docker run 和一堆 sleep

我们做的是一个内部工单系统,服务不多但该有的都有:

  • api:Node.js 20 写的后端,端口 3000
  • postgres:PostgreSQL 16,主数据库
  • redis:Redis 7.2,做会话缓存和限流计数
  • nginx:反向代理 + 静态资源,对外暴露 80

最早的部署方式是写在 deploy.sh 里的一串 docker run:

docker network create ticket-net
docker run -d --name pg --network ticket-net -e POSTGRES_PASSWORD=xxx -v pgdata:/var/lib/postgresql/data postgres:16
sleep 10
docker run -d --name redis --network ticket-net redis:7.2
docker run -d --name api --network ticket-net -e DATABASE_URL=... -p 3000:3000 ticket-api:1.4.2
sleep 5
docker run -d --name nginx --network ticket-net -p 80:80 -v ./nginx.conf:/etc/nginx/nginx.conf:ro nginx:1.25

痛点非常具体:

  1. 启动顺序靠 sleep。sleep 10 在开发机上够用,到了 CI 的冷机器上 PostgreSQL 初始化要 20 多秒,API 一连库就 ECONNREFUSED 退出,然后整个流水线红掉。
  2. 网络配置重复。每条 docker run 都要带 --network,漏一条就连不上。
  3. 环境变量散落。数据库密码在脚本里硬编码,改一次要动三处。
  4. 无法一键清理。docker rm -f 要写五个容器名,卷还得单独 docker volume rm。

这篇文章就是把我们迁移到 Docker Compose 的完整配置和踩坑过程写出来,重点在网络、卷挂载、健康检查和启动顺序这四件事上。

二、环境与版本

先交代版本,Compose 的 depends_on.condition 在不同版本行为差异很大,这个必须说清楚:

组件 版本
Docker Engine 25.0.3
Docker Compose v2.24.6(插件形式,docker compose 而非 docker-compose)
Compose Spec 对应 version 字段已废弃,不再写
Node.js 镜像 node:20.11-alpine
PostgreSQL postgres:16.2-alpine
Redis redis:7.2-alpine
Nginx nginx:1.25-alpine

两个关键提醒:

  • 不要再写 version: "3.8"。Compose V2 已经忽略这个字段,写了只会看到 the attribute 'version' is obsolete 的警告。
  • condition: service_healthy 需要 Compose V2。老的单机 docker-compose 1.x 在 v3 格式下不支持这个条件,只有 service_started,这正是很多人误以为"Compose 不能控制启动顺序"的原因。

三、方案设计

整体设计思路四条:

  1. 一个自定义 bridge 网络 ticket-net,所有服务接入,靠服务名做 DNS 解析。Nginx 里 proxy_pass http://api:3000 直接可用,不用管容器 IP。
  2. 三类卷:pgdata 命名卷存数据库、redisdata 命名卷存 AOF 持久化文件、./nginx/conf.d 和 ./static 用 bind mount 方便改配置热重载。
  3. 健康检查全覆盖。PostgreSQL 用 pg_isready,Redis 用 redis-cli ping,API 用容器内 wget 打自己的 /healthz,Nginx 依赖 API 健康。
  4. 启动顺序用 depends_on + condition:api 等 postgres 和 redis 都 healthy 再启动,nginx 等 api healthy 再启动。

另外加两个工程化细节:restart: unless-stopped 保证崩溃自愈,logging 限制日志大小防止磁盘被撑爆。

四、核心实现

4.1 目录结构

ticket-system/
├── docker-compose.yml
├── .env
├── api/
│   └── Dockerfile
├── nginx/
│   └── conf.d/
│       └── default.conf
└── static/

.env 放敏感配置,Compose 会自动读取:

POSTGRES_USER=ticket
POSTGRES_PASSWORD=Ch4ngeMeInProd
POSTGRES_DB=ticket
API_IMAGE=ticket-api:1.4.2

4.2 docker-compose.yml 完整配置

name: ticket-system

services:
  postgres:
    image: postgres:16.2-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - ticket-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 15s
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  redis:
    image: redis:7.2-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redisdata:/data
    networks:
      - ticket-net
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

  api:
    image: ${API_IMAGE}
    build:
      context: ./api
      dockerfile: Dockerfile
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://redis:6379
      PORT: "3000"
    expose:
      - "3000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/healthz"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 20s
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  nginx:
    image: nginx:1.25-alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./static:/usr/share/nginx/html:ro
    depends_on:
      api:
        condition: service_healthy
    networks:
      - ticket-net
    restart: unless-stopped

volumes:
  pgdata:
  redisdata:

networks:
  ticket-net:
    driver: bridge

几个值得单独说的参数:

  • start_period:容器启动后这段时间内的健康检查失败不计入 retries。PostgreSQL 首次初始化要跑 initdb,我们的 CI 机器上大约 12 秒,所以给 15 秒余量。没有这个参数,retries: 10 × interval 5s 很容易被初始化阶段消耗掉。
  • api 用 expose 而非 ports:API 不需要对宿主机暴露,只让 Nginx 通过 ticket-net 访问,减少攻击面。调试时临时用 docker compose exec api sh 进去。
  • pg_isready 用 CMD-SHELL:因为要展开 ${POSTGRES_USER} 环境变量,数组形式不会经过 shell 展开。
  • name: ticket-system:顶层项目名,决定容器名前缀(ticket-system-api-1)和默认网络名,避免和其他项目撞名。

4.3 Nginx 配置里的服务名解析

# nginx/conf.d/default.conf
upstream api_backend {
    server api:3000;
    keepalive 32;
}

server {
    listen 80;
    server_name _;

    location /api/ {
        proxy_pass http://api_backend/;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 30s;
    }

    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}

server api:3000 能生效的前提就是两个容器都在 ticket-net 上,Docker 内置 DNS 会把 api 解析到容器 IP。这里有个坑后面细说:Nginx 启动时解析 upstream 域名,如果 api 容器此时不存在,Nginx 会直接启动失败——这正是我们给 nginx 加 depends_on: api: service_healthy 的原因之一。

4.4 API 的 Dockerfile 与健康检查端点

FROM node:20.11-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

FROM node:20.11-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY . .
USER node
EXPOSE 3000
CMD ["node", "src/server.js"]

健康检查端点要轻量,不要在里面查数据库,否则数据库抖动会让 API 被误判不健康进而触发重启风暴:

// src/server.js 片段
app.get('/healthz', (req, res) => res.status(200).send('ok'));

五、踩坑与优化

坑 1:健康检查通过 ≠ 服务可用

最早 pg_isready 一通过我们就让 API 启动,结果 API 迁移脚本偶尔报 database "ticket" does not exist。原因是 PostgreSQL 官方镜像的初始化流程:先起一个临时实例执行 initdb 和 docker-entrypoint-initdb.d 里的脚本,完成后关闭再重启正式实例。pg_isready 在临时实例阶段就可能返回成功。

解决办法是把 start_period 从 5s 提到 15s,并且把迁移逻辑改成 API 启动时带重试(我们用的是 node-pg-migrate 加 3 次指数退避)。健康检查只是第一道闸,应用侧的重试不能省。

坑 2:depends_on 不会等待,只有 condition 才会

团队里有人写了:

depends_on:
  - postgres

这等价于 condition: service_started,只保证容器被创建并启动,不保证进程能接受连接。必须写成 map 形式带 condition: service_healthy。

坑 3:bind mount 的权限

./static 挂到 Nginx 的 /usr/share/nginx/html,宿主机文件属主是开发者的 UID 1000,Nginx worker 以 nginx 用户跑,读没问题。但如果哪天改成挂载需要写的目录,就会 permission denied。命名卷没这个问题,因为 Docker 会用镜像里目录的属主初始化卷。

坑 4:docker compose down -v 会删数据

这个不用多解释,但值得在 README 里加粗。我们现在的约定是:日常 docker compose down(保留卷),只有需要重置环境时才 down -v。

优化:日志与资源限制

生产环境加了 logging 限制后,单容器日志目录从最高见过 4.2GB 降到稳定在 30MB 以内(max-size 10m × max-file 3)。资源限制我们没在 Compose 里写 deploy.resources(那是 Swarm 语法,Compose 下部分字段被忽略),而是用 mem_limit 这种 V2 支持的写法,给 api 限了 512m,实测 P99 内存占用 310MB 左右,够用。

六、效果数据

迁移前后对比(同一台 4C8G 的 CI runner,冷缓存):

指标 迁移前(docker run 脚本) 迁移后(Compose)
冷启动到全部服务可用 约 95s(含固定 sleep 25s) 38s
部署脚本行数 60 行 8 行
因启动顺序导致的失败率 约 15%(近 20 次流水线挂 3 次) 0(近 50 次无相关失败)
环境变量维护点 3 处 1 处(.env)
一键清理 手动 6 条命令 docker compose down

日常开发里最直观的变化是 docker compose up -d 之后可以直接打开浏览器,不用再盯着 docker logs 看数据库起来没有。另外 docker compose config 能校验并展开最终配置,改 yml 时先在 CI 里跑一遍这个命令,语法错误在合并前就能拦住。

七、总结

Docker Compose 编排这件事,配置本身不难,难的是几个容易想当然的点:depends_on 默认不等健康、start_period 要给足初始化时间、Nginx 的 upstream 在启动时就解析域名、命名卷和 bind mount 的权限行为不同。把这四件事处理对,一个四服务的项目用一份 100 行左右的 docker-compose.yml 就能稳稳跑起来。

最后给两条实践建议:一是健康检查端点务必轻量,别把依赖服务的可用性绑进去;二是 .env 永远不要提交到仓库,用 .env.example 加 CI 注入的方式管理。Compose 的定位是单机编排,服务再往上长到需要多节点调度的时候,就该考虑 Kubernetes 了,但在那之前,它足够好用。