一、问题背景

去年底我把一个内部工具从"手动docker run"迁移到Docker Compose。项目结构不复杂:一个Nginx托管的前端静态站、一个Node.js API、一个PostgreSQL 16、一个Redis 7。四个服务,听起来用Compose一把梭就完事了。

结果上线第一周就出问题。API容器启动时PostgreSQL还没完成初始化,Node进程连不上数据库直接exit(1),restart策略把它拉起来,再崩,再拉。日志里刷了几十条ECONNREFUSED 5432。更烦的是Redis偶尔也慢半拍,导致API的session模块初始化失败。

我一开始用depends_on写了顺序,以为能解决——后来才发现默认的depends_on只保证容器启动顺序,不保证服务就绪。容器起来了,但Postgres还在跑initdb,端口根本没监听。

这篇文章就把我最终的配置方案完整写出来,包括网络规划、卷挂载策略、健康检查探针设计、启动顺序控制,以及几个踩过的坑。环境是Ubuntu 22.04 + Docker Engine 25.0.3 + Docker Compose v2.24.5。

二、环境与版本

先固定版本,避免"我这里能跑"的扯皮:

组件 版本
宿主机 Ubuntu 22.04.3 LTS
Docker Engine 25.0.3
Docker Compose v2.24.5 (Compose Spec)
Node.js 镜像 node:20.11-alpine
PostgreSQL postgres:16.2-alpine
Redis redis:7.2-alpine
Nginx nginx:1.25-alpine

Compose文件用name:顶层字段指定项目名(v2.20+支持),不再依赖目录名。这点很重要,因为CI里checkout的目录名经常变。

三、方案设计

整体思路四句话:

  1. 网络分层:前端和后端放一个自定义bridge网络app-net,数据库和Redis单独放data-net,API同时接入两个网络。这样Nginx碰不到数据库,减少攻击面。
  2. 卷挂载:数据库和Redis用命名卷(named volume)持久化,前端静态文件和Nginx配置用bind mount方便改。
  3. 健康检查:Postgres用pg_isready,Redis用redis-cli ping,API自己暴露/healthz端点,Nginx用wget探本地。
  4. 启动顺序:depends_on配合condition: service_healthy,让API等Postgres和Redis健康后再启动,Nginx等API健康后再启动。

这里有个细节:service_healthy条件在Compose v2里是原生支持的,不需要version: "3.8"那套老写法。我直接把version字段删了,用最新Compose Spec。

四、核心实现

完整docker-compose.yml如下,我加了注释说明每个参数为什么这么配:

name: internal-tool

services:
  postgres:
    image: postgres:16.2-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD:?err}
      POSTGRES_DB: appdb
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - pg-data:/var/lib/postgresql/data
      - ./initdb:/docker-entrypoint-initdb.d:ro
    networks:
      - data-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 15s
    deploy:
      resources:
        limits:
          memory: 512M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  redis:
    image: redis:7.2-alpine
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--maxmemory", "256mb", "--maxmemory-policy", "allkeys-lru"]
    volumes:
      - redis-data:/data
    networks:
      - data-net
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 2s
      retries: 5
      start_period: 5s
    deploy:
      resources:
        limits:
          memory: 320M

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    image: internal-tool/api:1.4.2
    restart: unless-stopped
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://app:${DB_PASSWORD}@postgres:5432/appdb
      REDIS_URL: redis://redis:6379
      PORT: "3000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app-net
      - data-net
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/healthz"]
      interval: 10s
      timeout: 3s
      retries: 6
      start_period: 20s
    deploy:
      resources:
        limits:
          memory: 256M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  web:
    image: nginx:1.25-alpine
    restart: unless-stopped
    ports:
      - "80:80"
    volumes:
      - ./web/dist:/usr/share/nginx/html:ro
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      api:
        condition: service_healthy
    networks:
      - app-net
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1/"]
      interval: 15s
      timeout: 3s
      retries: 3

networks:
  app-net:
    driver: bridge
  data-net:
    driver: bridge
    internal: true

volumes:
  pg-data:
  redis-data:

几个关键点说明:

internal: true 加在data-net上,这个网络里的容器无法访问外网,只能内部互通。数据库和Redis本来就不该出网,这条配置直接堵死数据外泄的一个通道。API同时挂两个网络,所以它既能连数据库,又能被Nginx访问。

start_period 是很多人忽略的参数。Postgres首次启动要跑initdb,15秒内pg_isready失败不算数,不会计入retries。没有这个参数,健康检查会在初始化阶段就把容器标记为unhealthy。

${DB_PASSWORD:?err} 是Compose的变量语法,没设这个环境变量就直接报错退出,避免用默认密码裸奔。

API的Dockerfile里健康检查端点很简单:

// api/src/health.js
const db = require('./db');
const redis = require('./redis');

module.exports = async function healthz(req, res) {
  const checks = { db: false, redis: false };
  try {
    await db.query('SELECT 1');
    checks.db = true;
  } catch (e) { /* 记录但不抛 */ }
  try {
    checks.redis = (await redis.ping()) === 'PONG';
  } catch (e) { /* 同上 */ }

  const ok = checks.db && checks.redis;
  res.status(ok ? 200 : 503).json({ status: ok ? 'ok' : 'degraded', checks });
};

健康检查探的是依赖项,不是简单的return 200。这样如果运行中数据库挂了,API会被标记unhealthy,配合外部监控能触发告警。

五、踩坑与优化

坑1:depends_on不解决重启场景。 service_healthy只在首次启动生效。如果Postgres中途重启,API不会自动跟着重启,它的连接池会进入重连循环。我的处理是在API里加了连接池重试(pg-pool的connectionTimeoutMillis: 5000配合指数退避),并且用Compose的restart: unless-stopped兜底。彻底方案要上编排平台,Compose层面做到这步够了。

坑2:命名卷和bind mount混用踩权限。 一开始我把./pg-data目录bind mount进去,宿主机uid和容器内postgres用户的uid(999)对不上,启动报could not change permissions。换成命名卷pg-data后问题消失——命名卷由Docker管理,权限自动对齐。教训:数据库数据目录永远用命名卷,别用bind mount。

坑3:日志把磁盘写满。 没配logging.options之前,一个API容器跑两周写了40GB json日志。加上max-size: "10m"和max-file: "3"后,单容器日志上限30MB。

坑4:internal: true网络里DNS解析。 刚开始API连不上postgres主机名,查了半天发现是API只挂了app-net。加上data-net后正常。Compose的网络别名机制要求容器加入对应网络才能解析该网络内的服务名。

优化项:给每个服务加了deploy.resources.limits.memory。Compose本地模式(非Swarm)下deploy字段部分生效,内存限制实测有效(Docker 25 + Compose v2.24)。Postgres给512M,Redis 320M(含maxmemory 256mb余量),API 256M,总内存占用控制在1.2G以内,跑在2C4G的机器上很稳。

六、效果数据

改完配置后跑了两周,数据对比:

指标 改造前 改造后
冷启动失败率 12%(约每8次启动失败1次) 0%
冷启动耗时(up -d到全健康) 不稳定,常卡在API重试 稳定18秒左右
因启动顺序导致的重启次数 日均3次 0
单容器日志磁盘占用(两周) 峰值40GB ≤30MB
数据库数据丢失事件 1次(bind mount权限问题重建) 0

docker compose up -d之后docker compose ps能看到所有服务healthy状态,depends_on的条件启动链路按预期执行:postgres/redis并行启动 → 健康后api启动 → api健康后web启动。

七、总结

Docker Compose做多服务编排,核心就三件事:网络隔离划清楚、卷挂载选对类型、健康检查配好start_period和condition。depends_on的service_healthy条件是启动顺序控制的正解,但别指望它处理运行时的依赖故障,那需要应用层重试兜底。

配置文件里那些看起来啰嗦的参数——start_period、internal: true、max-size——都是踩过坑之后加的。建议直接抄这份结构,把镜像版本和密码换掉就能用。Compose v2已经不需要version字段了,看到还在写version: "3.8"的教程可以直接跳过。