一、问题背景:手动docker run的噩梦

去年接手一个项目,技术栈是Node.js API + PostgreSQL + Redis。开发环境用docker run逐个启动容器,每次新同事搭环境都要折腾半天。问题是多方面的:

  • 三个容器要手动创建网络才能互相通信,命令记不住就得翻文档
  • PostgreSQL的数据卷挂载路径凭记忆敲,错了就得删容器重来
  • API容器启动比数据库快,连不上数据库直接退出,得手动重启
  • Redis没设密码,有次测试环境容器端口映射到公网被扫到,虽然没造成损失但惊出一身冷汗

后来迁移到docker-compose,一个docker compose up -d解决所有问题。下面分享这套配置的完整设计思路和实现细节。

二、环境与版本

先交代版本,Docker Compose不同版本行为有差异:

  • Docker Engine: 24.0.7
  • Docker Compose: v2.23.0(注意是插件版docker compose,不是老的docker-compose)
  • 宿主机: Ubuntu 22.04 LTS,4核8G
  • 应用镜像: node:18.19-alpine3.19
  • 数据库: postgres:16.1-alpine
  • 缓存: redis:7.2.3-alpine

Compose文件格式用version: "3.8",虽然新版本Compose已经弱化version字段,但保留它兼容性更好。

三、方案设计

核心设计目标四条:

  1. 网络隔离:自定义bridge网络,服务间用服务名做DNS解析,不暴露不必要的端口到宿主机
  2. 数据持久化:数据库和Redis用命名卷,API代码用bind mount方便开发热更新
  3. 健康检查:每个服务定义healthcheck,用真实业务探针而非端口探测
  4. 启动顺序:用depends_on的condition: service_healthy保证依赖就绪后再启动

目录结构:

project/
├── docker-compose.yml
├── .env
├── api/
│   ├── Dockerfile
│   └── src/
└── initdb/
    └── 01-init.sql

四、核心实现

先看完整的docker-compose.yml:

version: "3.8"

services:
  postgres:
    image: postgres:16.1-alpine
    container_name: app-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./initdb:/docker-entrypoint-initdb.d:ro
    networks:
      - backend
    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.3-alpine
    container_name: app-redis
    restart: unless-stopped
    command: >
      redis-server
      --requirepass ${REDIS_PASSWORD}
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
      --appendonly yes
    volumes:
      - redisdata:/data
    networks:
      - backend
    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}@postgres:5432/${DB_NAME}
      REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379/0
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - ./api/src:/app/src:ro
    networks:
      - backend
      - frontend
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 20s

networks:
  backend:
    driver: bridge
    internal: false
  frontend:
    driver: bridge

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

配套的.env文件(不提交到Git):

DB_USER=appuser
DB_PASSWORD=Ch4ng3M3_Str0ng
DB_NAME=appdb
REDIS_PASSWORD=R3dis_P@ss_2024

API的Dockerfile:

FROM node:18.19-alpine3.19

WORKDIR /app

COPY package*.json ./
RUN npm ci --omit=dev

COPY . .

# 非root用户运行
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

EXPOSE 3000
CMD ["node", "src/index.js"]

健康检查端点实现(Express示例):

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 });
  }
});

这里的关键设计点:

网络分层。backend网络承载数据库、缓存和API的内部通信,frontend网络给API对外暴露。数据库和Redis只挂在backend上,即使误操作映射端口也不会直接暴露。API同时挂两个网络做网关。

健康检查用业务探针。PostgreSQL用pg_isready,Redis用redis-cli ping,API用HTTP健康端点且端点内真实查询数据库和Redis。端口探测(比如nc -z)只能说明进程活着,不能说明服务可用——数据库进程启动后还要经历恢复、初始化,这期间端口已监听但查询会失败。

start_period的作用。PostgreSQL首次启动要初始化数据目录,我实测在4核机器上约8-12秒,慢速磁盘可能超过20秒。设30秒start_period,期间健康检查失败不计入retries,避免被误判为不健康。

depends_on条件启动。condition: service_healthy让API等到两个依赖都健康才启动,解决了之前"API启动太快连不上数据库"的问题。注意这只控制启动顺序,不控制关闭顺序,也不保证依赖一直健康。

五、踩坑与优化

坑一:PGDATA路径的权限问题。最初没设PGDATA环境变量,PostgreSQL 16默认用/var/lib/postgresql/data,但alpine镜像里这个目录的属主处理有变化,挂载命名卷后容器启动报chmod: changing permissions of '/var/lib/postgresql/data': Operation not permitted。显式指定PGDATA=/var/lib/postgresql/data/pgdata,让PostgreSQL在子目录初始化,绕开父目录权限问题。这是官方镜像的推荐做法。

坑二:healthcheck里的变量不展开。test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]这种写法,变量在Compose解析阶段展开,能正常工作。但如果写成test: ["CMD", "pg_isready", "-U", "${DB_USER}"],CMD形式不经过shell,变量不会展开,会拿字面量${DB_USER}去连接然后失败。要么用CMD-SHELL,要么写死值。我一开始用CMD踩了这个坑,健康检查一直failed,排查了半小时。

坑三:Redis密码在healthcheck里泄露到进程列表。redis-cli -a password会让密码出现在容器内进程列表。生产环境更安全的做法是用REDISCLI_AUTH环境变量:

healthcheck:
  test: ["CMD-SHELL", "REDISCLI_AUTH=$$REDIS_PASSWORD redis-cli ping"]

注意这里用$$转义,让变量在容器内展开而非Compose解析阶段。

优化:日志驱动限制。默认json-file日志驱动不限制大小,跑几个月磁盘就满了。加配置:

logging:
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

优化:资源限制。给每个服务加deploy.resources.limits(Compose v2在非swarm模式下也支持):

deploy:
  resources:
    limits:
      memory: 512M
    reservations:
      memory: 256M

六、效果数据

在4核8G的Ubuntu 22.04上实测(docker compose up -d到所有服务healthy):

指标 手动docker run Compose编排
冷启动到全部就绪 48秒(含手动等待+重启) 22秒
新环境搭建耗时 约15分钟 约2分钟
因启动顺序导致的失败率 约35%(10次有3-4次API先于DB就绪退出) 0
配置文件行数 分散在多个脚本 单文件约90行

docker compose ps输出确认三个服务均为healthy状态,API健康端点P99响应时间稳定在8ms以内(健康检查本身开销可忽略)。

七、总结

这套配置的核心就三件事:网络分层做隔离、健康检查用业务探针、depends_on用service_healthy控制顺序。三个坑里,PGDATA权限和healthcheck变量展开是最容易卡住的,建议直接抄配置。另外提醒一点,depends_on的条件启动只解决启动时序,如果数据库运行中挂了,API不会自动重连——那需要在应用层做连接池重试,或者用restart策略兜底,两者不冲突。

配置文件已按生产标准调过,直接改.env里的密码就能用。有疑问欢迎评论区交流。