1. 引言

适合需要数据库、缓存和 Web 服务一起跑的后端项目。

新同事拉下项目后，最耗时间的往往不是写代码，而是装数据库、建用户、改端口、启动缓存。Docker Compose 可以把这些依赖写进一个文件，让本地环境更接近团队约定。

这里以一个 Node API 服务为例，同时启动应用、Postgres 和 Redis，并给数据库加健康检查。

2. 把服务拆清楚

本地开发环境至少要区分三类服务：业务应用、持久化数据库、缓存或队列。应用可以频繁重建，数据库数据需要挂载 volume，缓存通常可以重启后重新生成。

服务关系
api
  depends_on postgres
  depends_on redis
postgres
  volume: pg_data
redis
  memory cache

目录里建议保留 .env.example，把数据库地址、用户名、密码、端口写成示例。真实 .env 不提交到仓库。

3. 编写 compose.yaml

Compose 文件里，api 服务负责构建当前项目，postgres 暴露 5432，redis 暴露 6379。开发环境可以直接映射端口，生产环境不要照搬这个配置。

compose.yaml 示例
services:
  api:
    build: .
    ports:
      - "3000:3000"
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app123
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 10
  redis:
    image: redis:7
    ports:
      - "6379:6379"
volumes:
  pg_data:

4. 启动并检查容器状态

第一次启动时，镜像下载和构建会慢一些。启动后先看容器状态，再看应用日志。数据库显示 healthy 后，应用连接失败的概率会低很多。

启动命令
docker compose up -d
docker compose ps
docker compose logs -f api

如果 API 日志提示数据库连接失败，优先核对 .env 里的 host。容器内部访问数据库应该使用服务名 postgres，不是 localhost。

开发环境的密码可以简单，但不要把同一份 compose 配置直接带到线上。端口暴露、密码、网络和 volume 策略都要重新设计。

5. 重置数据要单独确认

调试数据库结构时，可能需要清空 volume。这个动作会删除本地数据，应单独执行，不要写进普通启动脚本。

清理本地数据
docker compose down
docker volume rm project_pg_data
docker compose up -d

团队协作时，建议把初始化 SQL 或迁移命令写进 README。这样每个人启动环境后，都能用同一套数据结构联调。