Docker Compose 字段讲解

内容：顶层字段 -> service 字段 -> 网络/存储 -> 进阶字段 -> 已废弃字段

一、顶层字段（Top-level keys）

version: "3.9"   # 已可省略（v2 规范）
name: myapp
services:
networks:
volumes:
configs:
secrets:

1️⃣ version（已不推荐）

Compose v2 可以不写
官方推荐删除

# version: "3.9"  # 可省略

2️⃣ name

指定 Project 名（优先级高于目录名）

name: myapp

等价于：

docker compose -p myapp up

3️⃣ services（核心）

定义所有服务（= 容器模板）

services:
  web:
  api:
  db:

4️⃣ networks

定义网络（默认会自动创建 <project>_default）

5️⃣ volumes

定义命名数据卷

6️⃣ configs / secrets

configs：配置文件（偏 Swarm / K8S）
secrets：敏感信息

二、services 字段详解（重中之重）

1️⃣ 构建与镜像

image：指定镜像

image: nginx:1.27-alpine

build：构建镜像

build: .

完整写法：

build:
  context: .
  dockerfile: Dockerfile
  target: prod
  args:
    NODE_ENV: production

pull_policy：镜像拉取策略

pull_policy: if_not_present

可选：

always
missing
never

2️⃣ 容器运行行为

container_name：指定容器名（⚠️ 不推荐在 scale 时使用）

container_name: my-nginx

command：覆盖镜像 CMD

command: ["nginx", "-g", "daemon off;"]

entrypoint：覆盖 ENTRYPOINT

entrypoint: ["/app/start.sh"]

working_dir：设置工作目录

working_dir: /app

user：指定运行用户（安全）

user: "1000:1000"

3️⃣ 端口与网络

ports：端口映射（宿主机访问）

ports:
  - "8080:80"

expose：仅容器间可见（不映射宿主机）

expose:
  - "8080"

networks：指定服务加入的网络

networks:
  - backend

hostname：容器主机名

hostname: web01

extra_hosts：修改 /etc/hosts

extra_hosts:
  - "db.local:10.0.0.10"

4️⃣ 环境变量与配置

environment

environment:
  - ENV=production
  - DEBUG=false

或：

environment:
  ENV: production
  DEBUG: "false"

env_file：从文件加载环境变量

env_file:
  - .env

5️⃣ 存储相关

volumes：挂载数据

volumes:
  - db_data:/var/lib/postgresql/data
  - ./config:/etc/app:ro

tmpfs：内存文件系统

tmpfs:
  - /run
  - /tmp

6️⃣ 依赖与启动顺序

depends_on：控制启动顺序（⚠️ 不保证服务可用）

depends_on:
  - db

带 healthcheck：

depends_on:
  db:
    condition: service_healthy

healthcheck：健康检查（非常重要）

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost/health"]
  interval: 10s
  timeout: 2s
  retries: 3

7️⃣ 资源限制（重要）

deploy（⚠️ 在非 Swarm 下部分字段无效）

deploy:
  resources:
    limits:
      cpus: "1.0"
      memory: 512M

等价的非 deploy 写法（推荐本地用）：

mem_limit: 512m
cpus: 1.0

8️⃣ 重启策略

restart

restart: unless-stopped

可选：

no
always
on-failure
unless-stopped

9️⃣ 日志

logging

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

🔟 安全相关

privileged：是否特权模式（⚠️ 谨慎）

privileged: true

cap_add / cap_drop

cap_drop:
  - ALL
cap_add:
  - NET_BIND_SERVICE

security_opt

security_opt:
  - no-new-privileges:true

三、networks 字段详解

networks:
  backend:
    driver: bridge

高级用法：

networks:
  backend:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

四、volumes 字段详解

volumes:
  db_data:
    driver: local

五、configs / secrets（了解即可）

configs:
  app_config:
    file: ./config.yml

secrets:
  db_password:
    file: ./db_password.txt

六、已废弃 / 不推荐字段

字段	说明
links	已废弃，用 network
volumes_from	不推荐
extends	不推荐
cpu_shares	已废弃
version	可省略

七、一个完整示例（生产风格）

name: erp

services:
  api:
    build: .
    image: erp-api:1.0.0
    ports:
      - "8000:8000"
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

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

volumes:
  pgdata:

八、总结

service 是容器模板，不是容器

depends_on 不等于服务就绪

Compose 是单机编排，不是生产调度