一、问题背景:手动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字段,但保留它兼容性更好。
三、方案设计
核心设计目标四条:
- 网络隔离:自定义bridge网络,服务间用服务名做DNS解析,不暴露不必要的端口到宿主机
- 数据持久化:数据库和Redis用命名卷,API代码用bind mount方便开发热更新
- 健康检查:每个服务定义healthcheck,用真实业务探针而非端口探测
- 启动顺序:用
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里的密码就能用。有疑问欢迎评论区交流。