一、为什么单容器部署撑不住了?

项目初期,我用几个docker run命令就能把服务跑起来。但服务数量增加到四个——Nginx前端、Node.js API、PostgreSQL 15、Redis 7——之后,问题开始集中爆发:

  • 启动顺序靠猜:API容器启动时数据库还没ready,直接crash,得手动重启。
  • 网络配置重复劳动:每次docker run都要带--network和端口映射参数,改一次端口要改三处脚本。
  • 数据丢失风险:有一次误删容器,数据库数据跟着没了,因为没用命名卷。
  • 环境不一致:开发机和服务器上的容器参数靠口口相传,CI环境又不一样。

这些问题本质上不是Docker的缺陷,而是缺少一层声明式的编排描述。Docker Compose正是解决这个问题的工具——用一个YAML文件定义所有服务、网络、卷和依赖关系,一条docker compose up -d搞定全部。

本文分享的配置经过三个月生产环境验证,目前稳定支撑日均20万请求的项目。

二、环境与版本说明

先交代清楚版本,避免读者因版本差异踩坑:

组件 版本 说明
Docker Engine 24.0.7 支持Compose V2
Docker Compose v2.23.0 使用docker compose(非docker-compose)
Compose文件格式 3.9 兼容性最好,支持depends_on条件
PostgreSQL 15.4-alpine 轻量镜像
Redis 7.2-alpine 带健康检查命令
Node.js API 20.9-slim 基于官方镜像构建
Nginx 1.25-alpine 反向代理前端

注意:Compose文件格式3.9中depends_on的condition字段在V2 CLI下才完整支持service_healthy,V1的docker-compose对某些条件支持不完整,建议统一用V2。

三、整体方案设计

项目结构如下:

project/
├── docker-compose.yml
├── api/
│   ├── Dockerfile
│   └── src/
├── frontend/
│   ├── Dockerfile
│   └── dist/
└── .env

服务拓扑设计:

  • frontend(Nginx):对外暴露80端口,反向代理到api:3000。
  • api(Node.js):不对外暴露端口,仅在内部网络中被frontend访问。
  • db(PostgreSQL):仅在内部网络,数据挂载到命名卷pgdata。
  • redis(Redis):仅在内部网络,用于API的会话缓存。

网络设计:创建一个自定义桥接网络app-net,所有服务加入同一网络,通过服务名DNS互相解析。不暴露db和redis的端口到宿主机,减少攻击面。

卷设计:pgdata命名卷持久化数据库,redis-data持久化Redis的AOF文件。

启动顺序:db和redis先启动并通过健康检查 → api启动并健康检查 → frontend最后启动。

四、核心实现:docker-compose.yml逐段拆解

完整配置文件如下,关键参数我都加了注释:

version: "3.9"

services:
  db:
    image: postgres:15.4-alpine
    container_name: app-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    networks:
      - app-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER} -d ${DB_NAME}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  redis:
    image: redis:7.2-alpine
    container_name: app-redis
    restart: unless-stopped
    command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis-data:/data
    networks:
      - app-net
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 10s

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    container_name: app-api
    restart: unless-stopped
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@db:5432/${DB_NAME}
      REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app-net
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000/health"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 40s

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    container_name: app-frontend
    restart: unless-stopped
    ports:
      - "80:80"
    depends_on:
      api:
        condition: service_healthy
    networks:
      - app-net

networks:
  app-net:
    driver: bridge

volumes:
  pgdata:
    driver: local
  redis-data:
    driver: local

几个关键点说明:

健康检查的start_period不能省。 PostgreSQL首次初始化需要执行init.sql,冷启动大概要20-30秒。start_period: 30s表示这30秒内的失败不计入retries,否则容器会在初始化完成前就被判定为unhealthy,导致api永远等不到依赖就绪。这个参数是我踩了两次坑才加上的。

depends_on的condition: service_healthy是启动顺序的核心。 不加condition的depends_on只保证容器启动顺序,不保证就绪顺序——db容器进程起来了但数据库还没接受连接,api照样连不上。加上service_healthy后,Compose会等健康检查通过才启动下游服务。

命名卷 vs 绑定挂载。 数据库数据用命名卷pgdata,由Docker管理存储位置,性能好且不会因宿主机目录权限问题翻车。init.sql用只读绑定挂载(:ro),仅在数据库首次初始化时执行。

环境变量抽离到.env。 密码等敏感信息不硬编码在YAML里,通过.env文件注入。.env加入.gitignore,CI环境通过secrets注入。

API的Dockerfile和健康检查端点也贴一下,保证可运行:

# api/Dockerfile
FROM node:20.9-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY src ./src
EXPOSE 3000
CMD ["node", "src/index.js"]
// api/src/index.js 中的健康检查端点
app.get('/health', async (req, res) => {
  try {
    await pool.query('SELECT 1');
    await redisClient.ping();
    res.status(200).json({ status: 'ok' });
  } catch (err) {
    res.status(503).json({ status: 'unhealthy', error: err.message });
  }
});

注意api的健康检查不只是返回200,而是实际探测了数据库和Redis连接。这样frontend等到的"健康"是真正可用的状态。

启动命令:

docker compose up -d --build

五、踩坑记录与优化

坑1:pg_isready返回成功但数据库还在recovery。 早期只用了pg_isready做健康检查,偶尔api启动后报"database is starting up"。后来在api的启动逻辑里加了3次重试(间隔2秒),双保险。更彻底的做法是健康检查里加一条实际查询:pg_isready -U user -d db && psql -U user -d db -c 'SELECT 1',但会增加检查开销,按需选择。

坑2:Redis密码含特殊字符导致健康检查失败。 redis-cli -a对含$、!的密码解析有问题。解决方案是把密码放在环境变量里用REDISCLI_AUTH传入,或者用--no-auth-warning配合转义。最终我选了简单方案:密码只用字母数字,长度32位,够安全也省事。

坑3:docker compose down误删卷。 有同事执行了docker compose down -v,-v会删除命名卷,数据库直接清空。团队约定:生产环境只用docker compose down,禁止带-v;备份通过pg_dump定时任务做,不依赖卷快照。

优化1:资源限制。 加了deploy.resources.limits(Compose V2支持)限制api内存512M、db 1G,防止单个服务吃满宿主机内存。

优化2:日志驱动。 默认json-file日志会无限增长,配置了logging.options.max-size: "10m"和max-file: "3",单服务日志最多占30M。

优化3:镜像构建缓存。 api的Dockerfile把COPY package*.json放在COPY src之前,依赖不变时复用npm ci层,构建时间从90秒降到15秒。

六、效果数据

部署前后对比(基于同一台4核8G云服务器,项目四服务):

指标 手动docker run Compose编排后
首次部署耗时 ~15分钟(含调试顺序) 约40秒(镜像已构建)
冷启动成功率 ~70%(需手动重启) 连续30次测试100%
配置文件数量 4个shell脚本 1个YAML + 1个.env
服务间网络配置 手动指定,易错 声明式,一次定义
数据持久化 无(易丢) 命名卷,重启不丢

健康检查间隔10-15秒,最坏情况下api等待db就绪的额外延迟不超过30秒,实际观测平均冷启动到全服务healthy约55秒(db初始化占大头)。

七、总结

Docker Compose的价值不在于"少敲几条命令",而在于把服务拓扑、依赖关系、健康状态变成可版本控制的声明式配置。这个项目里最关键的三个配置点是:depends_on的service_healthy条件、健康检查的start_period缓冲、以及命名卷替代绑定挂载。少了任何一个,部署稳定性都会打折扣。

如果你的项目服务数超过两个、且存在启动依赖,别犹豫,直接上Compose。配置文件写一次,后面所有环境(开发、CI、生产)复用同一份,改端口改密码只动.env,这才是容器化部署该有的样子。