Docker Compose 最佳实践

一、总体设计原则（先记住这 6 条）

1️⃣ 一个 Compose = 一个应用

不要把无关服务塞进一个 compose
生命周期统一：起 -> 用 -> 停 -> 删

✅ 正确：

erp/
 ├─ api/
 ├─ web/
 └─ docker-compose.yml

❌ 错误：

all-in-one-compose.yml

2️⃣ Service 是“模板”，不是实例

不关心容器名
不依赖容器 IP
不写死 hostname

✅ 用 service 名通信

❌ 用 IP / container_name 通信

3️⃣ 容器必须无状态

代码无状态
会话无状态
数据全部外置（DB / volume）

4️⃣ 配置外置，镜像通用

镜像不含环境差异
使用 env / env_file / volume

5️⃣ 开发、测试、预发 Compose 可复用

通过 override / profile 控制差异

6️⃣ Compose 是“应用编排”，不是运维系统

不做 HA
不做自愈
不做调度

二、目录结构最佳实践

推荐结构

project/
├─ docker/
│  ├─ Dockerfile
│  ├─ nginx.conf
│  └─ entrypoint.sh
├─ docker-compose.yml
├─ docker-compose.override.yml
├─ .env
├─ api/
└─ web/

📌 Compose 文件在项目根目录

三、环境变量最佳实践（非常重要）

1️⃣ 使用 .env 文件（默认加载）

APP_ENV=dev
DB_HOST=db
DB_PORT=5432

services:
  api:
    env_file:
      - .env

2️⃣ 不在 YAML 里写敏感信息

❌

POSTGRES_PASSWORD: 123456

✅

POSTGRES_PASSWORD: ${DB_PASSWORD}

3️⃣ 变量只用于“配置”，不用于“逻辑”

Compose 不是模板引擎。

四、网络最佳实践

1️⃣ 永远用 service 名通信

api -> db:5432

❌ 不用 IP ❌ 不用 links（废弃）

2️⃣ 端口只在需要暴露时映射

ports:
  - "8080:80"

📌 容器间通信不需要 ports

3️⃣ 拆分前后端网络（中大型项目）

networks:
  frontend:
  backend:

五、存储最佳实践

1️⃣ 数据库一定用 volume

volumes:
  - pgdata:/var/lib/postgresql/data

2️⃣ 配置文件用只读 bind mount

volumes:
  - ./config:/etc/app:ro

3️⃣ 不往容器层写日志

日志走 stdout
Docker / ELK 收集

六、depends_on & healthcheck（高频坑）

❌ 错误理解

depends_on = 服务就绪

❌ 错

✅ 正确做法

db:
  healthcheck:
    test: ["CMD", "pg_isready"]
    interval: 5s
    retries: 5

api:
  depends_on:
    db:
      condition: service_healthy

七、资源限制（别忽视）

推荐写法（本地 / CI）

mem_limit: 512m
cpus: 1.0

📌 防止：

本地机器被拖死
CI OOM

八、日志最佳实践

1️⃣ 控制日志大小

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

2️⃣ 日志归宿

stdout / stderr
交给 Docker / Loki / ELK

九、构建镜像最佳实践

1️⃣ 不在 Compose 里写复杂 build

复杂逻辑放 Dockerfile。

2️⃣ 利用缓存

build:
  context: .

3️⃣ 镜像可复用

image: erp-api:${APP_VERSION}

十、Profiles（Compose v2 强烈推荐）

场景控制

services:
  admin:
    profiles: ["dev"]

docker compose --profile dev up

📌 极佳替代多个 compose 文件。

十一、override 文件最佳实践

docker-compose.override.yml

本地开发自动加载
不提交生产配置

services:
  api:
    volumes:
      - ./api:/app

十二、restart 策略

restart: unless-stopped

适合：

API
Web
Worker

十三、Compose 常见反模式（必避）

❌ 使用 container_name
❌ 使用 links
❌ 用 IP 通信
❌ 在容器里跑 cron / systemd
❌ 把 Compose 当 Kubernetes 用
❌ 在 Compose 里做复杂逻辑判断

十四、Compose -> Kubernetes 迁移建议

Compose	Kubernetes
service	Deployment
volume	PVC
network	Service
env	ConfigMap
secret	Secret

📌 Compose 写得好，迁移成本极低。

十五、一个“高质量 Compose 模板”

name: erp

services:
  api:
    image: erp-api:${APP_VERSION}
    build: .
    ports:
      - "8000:8000"
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    mem_limit: 512m
    cpus: 1.0

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 5s
      retries: 5

volumes:
  pgdata:

十六、总结

Compose 是单机级应用编排工具

Service 是模板，不是实例

Compose 管理的是“应用生命周期”