一、为什么单容器部署撑不住了?
项目初期,我用几个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,这才是容器化部署该有的样子。