Docker Compose 全字段讲解与编写实战笔记

Docker Compose 全字段讲解与编写实战笔记

核心目标:看到一套应用的启动要求,能自己写出 compose.yaml,解释为什么这样写,并能验证和排错。

核对日期:2026-11-06。本文中的“docker-comp”按 Docker Compose 理解。以现代 docker compose 插件及 Compose Specification 为主;旧命令 docker-compose 仅在历史说明中出现。

阅读方式:先完成第 1~5 章,再学网络、存储、环境变量和健康检查,最后查完整字段字典。不要把所有字段同时塞进一个文件。

范围说明:“全字段”包含当前官方服务参考的字段、主要长语法子字段、Build / Deploy / Develop 及顶层资源。规范主分支可能领先已发布客户端,附录单独记录这类新字段。驱动私有的 driver_opts、日志插件选项、供应商 options 本身是开放字典,不能用一份固定清单穷尽。

目录

  1. Compose 的作用与边界
  2. 先把 YAML 写对
  3. 从需求推导配置的八个问题
  4. 第一个可运行案例
  5. 从 docker run 转成 Compose
  6. 顶层字段与项目命名
  7. 服务启动与镜像
  8. 环境变量与插值
  9. 端口与网络
  10. 数据卷与挂载
  11. 启动依赖与健康检查
  12. 生命周期与日志
  13. 资源、安全与设备
  14. services 全字段字典
  15. build 构建字段
  16. deploy 部署字段
  17. develop 开发字段
  18. configs、secrets、models
  19. 复用、合并、拆分和 profiles
  20. 完整练习:Python Web + PostgreSQL + Redis
  21. 运维命令与排错顺序
  22. 编写检查清单与练习
  23. 新规范字段及机器校验字段索引
  24. 官方参考与验证说明

1. Compose 的作用与边界

Dockerfile 描述如何制作镜像;镜像提供程序和运行依赖;容器是运行实例;Compose 描述应用由哪些服务组成,以及它们如何连接、存储和启动。

应用需求
  ├─ Web:镜像、命令、8080 入口
  ├─ 数据库:凭据、持久化、健康检查
  └─ 缓存:内部网络、数据保留策略
          ↓
      compose.yaml
          ↓ docker compose up -d
   容器 + 网络 + 卷 + 配置挂载

一个 service 是一类运行任务的配置,不等于固定只能有一个容器。服务可以扩容;但固定宿主机端口、固定 container_name、单机数据库数据目录都会限制扩容方式。

常规 docker compose up 面向一个 Docker Engine。它不会因为写了 deploy.placement 就变成 Kubernetes 调度器,也不会自动实现跨主机高可用。Swarm 的 docker stack deploy 与普通 Compose 的文件支持和执行行为有差别。

优先使用文件名 compose.yaml。compose.yml、docker-compose.yaml、docker-compose.yml 也有兼容支持。新文件通常不必写 version: "3.8";version 已过时,也不是 CLI 版本选择开关。

2. 先把 YAML 写对

2.1 层级、映射与列表

name: learn-compose          # 顶层键,字符串值
services:                    # 顶层映射
  web:                       # 服务名,由你命名
    image: nginx:stable-alpine
    ports:                   # 列表
      - "127.0.0.1:8080:80"  # 一个列表元素
    environment:             # 映射
      TZ: Asia/Shanghai
      FEATURE_ON: "true"
  • 用空格缩进,建议每层两个空格,不使用 Tab。
  • services、image 是规范关键字;web、db_data 是自己起的名字。
  • 端口映射、布尔形态的环境变量、数字形态的业务配置建议加引号。
  • 同一个映射不要重复写同名键,例如写两次 environment。
  • [] 是空列表,{} 是空映射,null 是空值;它们不一定语义相同。
  • # 后面通常是注释,含特殊字符的值应正确引用。

2.2 同一字段可能有短语法和长语法

# 短语法:紧凑
ports:
  - "127.0.0.1:8080:80"

# 长语法:含义明确,选项更多
ports:
  - target: 80
    published: "8080"
    host_ip: 127.0.0.1
    protocol: tcp

这两段是互相替代的写法,不应在同一服务中重复声明同一个 ports 键。

2.3 多行命令

command:
  - /bin/sh
  - -c
  - |
    echo "prepare"
    exec python app.py

| 保留换行;> 折叠大部分换行。需要变量、管道、重定向时显式调用 shell。最后的 exec 让应用接替 shell,便于收到停止信号。镜像中必须真的存在 /bin/sh 和目标程序。

3. 从需求推导配置的八个问题

写 YAML 前先填这张表:

问题 应写的字段 示例思路
跑什么程序? image 或 build 用已有镜像,还是构建自己的代码
怎么启动? command、必要时 entrypoint 默认启动命令是否符合要求
配置从哪里来? environment、env_file、configs、secrets 地址、业务配置、密码分开考虑
谁需要访问它? ports、networks 对外入口才发布端口,内部使用服务名
哪些数据不能丢? volumes 找到镜像真实数据目录
什么时候算就绪? healthcheck、depends_on 进程启动不等于能处理请求
如何退出和恢复? restart、stop_grace_period、init 前台运行、优雅停止、异常退出恢复
最多占多少资源? cpus、mem_limit、pids_limit 等 根据容量和负载设置,而非照抄

建议按以下顺序迭代:

image → 启动验证 → 配置 → 网络 → 持久化
      → 健康检查与依赖 → 资源与日志 → 复用和环境覆盖

每增加一个部分就运行 docker compose config -q,避免一次写完几十个字段再找错。

4. 第一个可运行案例

以下练习需要本机已安装 Docker Engine / Docker Desktop 与 Compose 插件,并能获取镜像。

创建独立练习目录,在其中保存 compose.yaml:

name: compose-first
services:
  web:
    image: nginx:stable-alpine
    ports:
      - "127.0.0.1:8080:80"
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

执行:

docker compose version
docker compose config -q
docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8080
docker compose logs --tail=50 web
docker compose down

逐行理解:name 给项目命名;web 是服务名;image 指定镜像;ports 把宿主机回环地址的 8080 转发到容器 80;restart 定义退出恢复策略;logging 限制单个日志文件大小与数量。

stable-alpine 是便于学习的可变标签。正式发布应记录实际版本并考虑固定 digest。127.0.0.1 仅供本机访问;改成 0.0.0.0 会改变暴露范围,应结合实际入口、防火墙与认证设计。

5. 从 docker run 转成 Compose

原命令:

docker run -d --name demo-web \
  -p 127.0.0.1:8080:80 \
  -e TZ=Asia/Shanghai \
  -v "$PWD/html:/usr/share/nginx/html:ro" \
  --restart unless-stopped \
  nginx:stable-alpine

对应配置:

services:
  web:
    image: nginx:stable-alpine
    ports:
      - "127.0.0.1:8080:80"
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped

需要提前创建 html 目录和页面文件。这里不强制指定 container_name,让 Compose 管理命名。

docker run 参数 Compose 对应项
-d 运行命令 docker compose up -d,没有对应的后台运行字段
--name container_name,通常可省略
-p ports
--expose expose
-e / --env-file 服务 environment / env_file
-v / --mount 服务 volumes
--network networks,具体模式也可能用 network_mode
--entrypoint entrypoint
镜像后的参数 command
-u / -w user / working_dir
--cpus / --memory cpus / mem_limit
--restart restart
--privileged privileged
-it stdin_open: true 与 tty: true,普通后台服务通常不需要

6. 顶层字段与项目命名

name: shop
services: {}
networks: {}
volumes: {}
configs: {}
secrets: {}
# include: ...   # 需要组合独立子项目时使用
# models: ...    # 需要模型运行集成时使用

上面只是结构图;空 services 不是可启动应用。

字段 作用 何时使用
name 项目名,影响默认容器、网络和卷的名称 避免依赖目录名
services 定义服务配置 编写普通应用的核心
networks 声明可复用网络 网络隔离、共享网络、IPAM
volumes 声明命名卷 数据持久化
configs 声明普通配置对象 配置文件注入
secrets 声明敏感配置来源 密码、令牌文件注入
include 引入其他 Compose 应用模型 拆分独立模块
models 声明模型运行需求 支持该能力的模型运行环境
version 兼容历史写法,现已过时 新文件通常不写
x-* 自定义扩展块,Compose 不作为普通运行字段解释 保存 YAML 复用片段

项目名常见优先级:-p > COMPOSE_PROJECT_NAME > 顶层 name > 项目目录名(特殊目录解析场景见官方文档)。在固定部署脚本中明确指定项目名,避免换目录后意外创建另一套资源。

docker compose -p shop-test up -d
docker compose -p shop-test ps

同样的命令操作后续资源时应使用相同项目名和相同文件组合。

7. 服务启动与镜像

7.1 image、build 和 pull_policy

services:
  api:
    image: example.invalid/team/api:1.0.0
    build:
      context: ./api
      dockerfile: Dockerfile
    pull_policy: build

这是结构示例,example.invalid 是占位域名。image 指定运行镜像和构建结果名称;build 说明如何构建;二者同时存在时要理解 pull_policy。缺省行为不能简单概括成“永远优先本地构建”。

常见策略:always 每次拉取;never 只用本地,缺失则失败;missing 缺失时拉取(latest 有特殊行为,仍会拉取);build 构建。较新客户端还支持 daily、weekly、every_12h 等定期检查方式。离线环境要先准备镜像,不是仅把策略改成 never 就完成了部署。

7.2 command 与 entrypoint

字段 意义 常见误区
entrypoint 覆盖镜像 ENTRYPOINT 数据库镜像入口可能负责初始化,不能随意覆盖
command 替换镜像默认 CMD,并与入口组合 不保证自动通过 shell 执行
working_dir 设置容器内工作目录 不会把宿主机代码自动复制进去
user 设置运行用户,例如 1000:1000 挂载目录权限必须匹配
init 添加轻量 init 处理信号转发和僵尸进程 不等同于运行 systemd

command: null 保留镜像默认命令;command: [] 或空字符串清空默认命令。entrypoint 为非 null 时会覆盖镜像入口,并使镜像默认 CMD 不再自动沿用;需要的命令要明确给出。

command: ["python", "app.py"]

若要 shell 展开:

command: ["/bin/sh", "-c", "echo $$APP_MODE; exec python app.py"]

$$ 让 $ 留到容器阶段,见下一章。容器主进程应在前台运行,不要靠 tail -f /dev/null 掩盖业务退出,也不要在启动命令里把主应用放到后台。

8. 环境变量与插值:必须分清两条链路

8.1 Compose 替换文件中的变量

.env:

APP_TAG=1.0.0
HTTP_PORT=8080

compose.yaml:

services:
  api:
    image: "my-api:${APP_TAG:-dev}"
    ports:
      - "127.0.0.1:${HTTP_PORT:-8080}:8000"

这里变量被 Compose 用来生成最终配置,.env 中的值不会因此全部自动进入容器。Shell 环境通常优先于用于插值的 .env / --env-file 值;工作目录、项目目录与多文件场景会影响默认 .env 的查找,部署脚本建议明确使用 --env-file。

docker compose --env-file .env.test config -q
docker compose --env-file .env.test up -d

8.2 传给容器进程的环境

services:
  api:
    image: my-api:1.0.0
    env_file:
      - ./app.env
    environment:
      APP_MODE: production
      LOG_LEVEL: "${LOG_LEVEL:-info}"

服务级 env_file 是给容器注入变量;CLI 的 --env-file 主要给 Compose 插值提供变量来源。两个名字相似,作用层次不同。

同一服务里,显式 environment 覆盖 env_file 中的同名值;env_file 多文件按顺序读取,后者覆盖前者;镜像内 ENV 通常是更低层的默认值。docker compose run -e KEY=value 可以为该次临时容器覆盖变量,不能把它与已存在的 up 容器混为一谈。

environment: {KEY: ""} 表示空字符串;KEY: 或列表形式 - KEY 会尝试从运行 Compose 的环境解析,无法解析时可能取消该变量。教学和部署模板里优先明确写值或必填表达式。

8.3 插值表达式

写法 含义
${VAR} 取值,未设置可能警告并替换为空
${VAR:-default} 未设置或为空时取默认值
${VAR-default} 仅未设置时取默认值
${VAR:?message} 未设置或为空就报错
${VAR?message} 仅未设置时报错
${VAR:+value} 设置且非空时使用 value,否则为空
${VAR+value} 设置时使用 value,否则为空
$$VAR 保留字面 $VAR,供后续 shell 使用
environment:
  DB_HOST: db
  DB_PASSWORD: "${DB_PASSWORD:?请设置数据库密码}"

密码更适合用应用支持的文件方式注入。config 与 config --environment 可能展示敏感值,排错时避免直接把完整输出贴到公共聊天或日志。

8.4 env_file 长语法

env_file:
  - path: ./defaults.env
    required: true
  - path: ./local.env
    required: false
    format: raw

required 控制文件是否必需;format: raw 保留值中的 $ 和引号等内容,需较新 Compose 支持。required 自 2.24.0 起支持,raw 自 2.30.0 起支持。环境变量里的 URL、JSON、密码都要认真处理引用,不要把 .env 直接当任意 shell 脚本执行。

9. 端口与网络

9.1 ports:谁访问谁

ports:
  - "127.0.0.1:18080:8080/tcp"

从左到右:宿主机绑定地址、宿主机端口、容器端口、协议。客户端访问 127.0.0.1:18080,服务在容器内监听 8080。应用通常必须监听容器的 0.0.0.0:8080,仅监听容器 127.0.0.1 会导致转发无法访问。

长语法字段:

字段 含义
target 容器端口
published 发布到宿主机的端口,建议写字符串,也可按支持范围使用区间
host_ip 宿主机绑定地址,平台需支持
protocol tcp 或 udp
app_protocol 应用协议提示,例如 http,不是自动添加 TLS
mode host / ingress 发布方式,主要有 Swarm 语义
name 端口说明名称,需客户端支持

expose: ["5432"] 表达容器端口信息,不发布到宿主机,也不是同网络服务互访的必需条件,更不是防火墙白名单。

9.2 默认网络与服务名

services:
  api:
    image: my-api:1.0.0
    environment:
      DB_HOST: db
      DB_PORT: "5432"
  db:
    image: postgres:17-alpine

示例仅演示寻址,数据库仍需初始化参数。两者默认加入项目的 default 网络,API 用 db:5432 访问数据库;不要用宿主机映射端口,也不要用 localhost 指代另一个容器。

9.3 网络分层

services:
  proxy:
    image: nginx:stable-alpine
    networks: [front]
  api:
    image: my-api:1.0.0
    networks: [front, back]
  db:
    image: postgres:17-alpine
    networks: [back]
networks:
  front: {}
  back:
    internal: true

internal 用于创建对外连接受限的网络,但不代替应用鉴权。多网络服务的默认网关和出口需要结合实际验证。

9.4 服务 networks 长语法

services:
  api:
    image: my-api:1.0.0
    networks:
      app_net:
        aliases: [backend]
        ipv4_address: 172.28.10.10
networks:
  app_net:
    ipam:
      config:
        - subnet: 172.28.10.0/24

固定 IP 仅在确实需要时使用,先排除与现有网络冲突;普通应用优先依赖服务名。

服务网络子字段 解释
aliases 当前网络上的别名;多个容器共享别名时,解析目标不保证唯一
ipv4_address、ipv6_address 固定地址,顶层 IPAM 必须覆盖所需网段
link_local_ips 链路本地地址,依赖平台
mac_address 为该网络连接指定 MAC
driver_opts 为连接传驱动选项,依赖驱动和版本
priority 连接处理优先级,不决定默认网关,也不保证网卡名
gw_priority 较高值的网络作为默认网关,需较新版本
interface_name 指定容器内接口名,需较新版本

9.5 顶层 networks 全字段

字段 解释
name 真实网络名,不自动添加项目名前缀
driver 网络驱动,例如单机常见 bridge;overlay 有集群环境要求
driver_opts 驱动私有参数,不能跨平台盲抄
external 引用已存在网络,不由本项目创建或删除
internal 外部连接隔离属性
attachable 允许独立容器连接,具体效果依赖驱动
enable_ipv4、enable_ipv6 控制地址族,依赖版本与引擎配置
labels 网络元数据
ipam.driver 地址管理驱动
ipam.config[].subnet 子网 CIDR
ipam.config[].ip_range 地址分配池
ipam.config[].gateway 网关
ipam.config[].aux_addresses 辅助保留地址映射
ipam.options IPAM 驱动参数

引用共享网络:

networks:
  shared:
    external: true
    name: shared-backend

服务仍需显式加入 shared。external: true 时通常仅保留 name,不要同时要求 Compose 设置驱动、IPAM 等创建参数。

network_mode: host 使用宿主机网络命名空间,不应再写 ports,也不能同时写服务 networks。host 模式的平台可用性不同;network_mode: none 禁用网络;service:其他服务 / container:容器 共享对应网络命名空间。

10. 数据卷与挂载

10.1 三种常用存储

类型 例子 用途与边界
命名卷 db_data:/var/lib/postgresql/data Docker 管理的持久化数据
bind 挂载 ./nginx.conf:/etc/nginx/nginx.conf:ro 使用宿主机上的具体文件或目录
tmpfs /tmp 临时内存文件系统,停止或移除后不持久化

容器可写层不应承担长期数据存储。重建容器与重启容器是两回事;要能重建而不丢业务数据。

10.2 顶层声明与服务挂载必须配合

services:
  db:
    image: postgres:17-alpine
    volumes:
      - db_data:/var/lib/postgresql/data
volumes:
  db_data: {}

顶层声明“有什么卷”;服务内声明“谁用它、挂到哪里”。数据库目录以所选镜像版本文档为准,不同大版本可能调整路径;不要只凭产品名照抄目录。

10.3 挂载长语法

volumes:
  - type: bind
    source: ./nginx.conf
    target: /etc/nginx/nginx.conf
    read_only: true
    bind:
      create_host_path: false
  - type: volume
    source: app_data
    target: /data
    volume:
      nocopy: true

create_host_path: false 能避免配置文件拼错时静默创建目录。nocopy: true 禁止首次创建卷时从镜像目标目录复制初始内容;它不负责备份。

子字段 作用
type volume / bind / tmpfs,另有平台相关 npipe、cluster 与较新 image
source 宿主机路径、命名卷,或对应类型的源;tmpfs 不填
target 容器内挂载点
read_only 该挂载只读
consistency 平台相关一致性提示
bind.propagation 挂载传播,例如 rprivate / rshared,需要相应宿主机设置
bind.create_host_path 是否自动创建不存在的源目录
bind.selinux z 共享标记、Z 私有标记;仅在适用平台使用
volume.nocopy 禁止初始内容复制
volume.subpath 仅挂载卷内子目录,需支持且子目录满足引擎要求
tmpfs.size、tmpfs.mode 内存挂载大小、权限位
image.subpath 较新 image 挂载的镜像内部子路径

10.4 顶层 volumes 全字段

name 指定真实卷名;driver 选择驱动;driver_opts 传驱动参数;labels 写元数据;external: true 引用已存在卷。外部卷通常只与 name 搭配。

volumes:
  db_data:
    external: true
    name: production-db-data

命名卷不是备份。把数据库文件同时挂到多个数据库实例,也不会自动形成数据库集群。数据库备份应采用产品支持的一致性备份方案,并验证恢复。

docker compose down 默认保留命名卷;docker compose down -v 会删除该项目管理的命名卷及关联匿名卷,可能永久丢失数据。外部卷不由 Compose 删除。不要把 -v 放到常规停止脚本里。

11. 启动依赖与健康检查

11.1 depends_on 不只是排列顺序

services:
  api:
    image: my-api:1.0.0
    depends_on:
      db:
        condition: service_healthy
        restart: true
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: "${DB_PASSWORD:?请设置密码}"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 30s

短语法 depends_on: [db] 只要求依赖服务先启动,不保证数据库已完成初始化。

长语法子字段 含义
condition: service_started 依赖容器已启动
condition: service_healthy 等待依赖健康检查通过
condition: service_completed_successfully 等待一次性服务成功退出,例如迁移任务
restart: true Compose 显式更新或重启依赖时联动重启当前服务;不是依赖崩溃后的无限自动级联
required: false 依赖不可用时可警告继续,需新版支持

即使启动时等待健康,运行中的数据库也可能断开。应用仍需连接重试、超时、断线重连;depends_on 不能替代这些能力。

11.2 healthcheck 全字段

字段 解释
test 检测命令:["CMD", ...] 直接执行;["CMD-SHELL", "..."] 通过 shell;字符串使用 shell 语义;["NONE"] 禁用
interval 检测间隔
timeout 单次检测超时
retries 连续失败达到次数后标为 unhealthy
start_period 启动宽限期,期间失败不按普通方式累计;成功可提前进入正常判定
start_interval 启动阶段的检测间隔,需客户端和引擎支持
disable true 禁用检查,包括镜像中定义的检查

检测命令在容器内部执行。宿主机有 curl 不代表容器里有;检查 HTTP 时应确认镜像带 curl / wget,或用程序运行时实现检测。

健康检查失败会改变健康状态,普通 Docker 的 restart 策略一般不会仅因 unhealthy 自动重启容器。要区分“进程退出”和“进程仍在但健康失败”。

12. 生命周期与日志

12.1 restart 策略

值 解释
"no" 不自动重启,建议加引号
on-failure 非零退出才重启,可写 on-failure:5 限次
always 退出后恢复;手动停止会抑制当次自动重启,Docker daemon 重启后的行为需结合策略理解
unless-stopped 类似 always,但主动停止的容器在 daemon 重启后仍保持停止

restart 不会修正错误配置,也不能保障零停机。一次性初始化任务通常用 restart: "no"。

12.2 优雅停止

init: true
stop_signal: SIGTERM
stop_grace_period: 30s

先发送停止信号,在宽限时间内等待退出,超时后可能被强制终止。应用要正确接收信号并关闭连接,数据库需要足够的刷盘时间。不要把容器停止等待与健康检查超时混为一谈。

12.3 日志

logging:
  driver: json-file
  options:
    max-size: "20m"
    max-file: "5"

driver 是日志驱动;options 是该驱动支持的字符串参数。应用应优先写 stdout/stderr,让引擎采集。若写入容器内文件,则要另外规划目录、轮转与采集。某些远程日志驱动影响 docker compose logs 可用性,取决于驱动和缓存配置。

12.4 生命周期钩子

post_start、pre_stop 是命令列表项,每项可配置 command、user、privileged、working_dir、environment。需要较新 Compose;post_start 相对主进程的精确执行时序不保证,不适合作为严格数据库迁移屏障;pre_stop 在异常崩溃或强杀等场景可能不会执行。

新规范的 pre_start 是独立临时初始化容器序列,与上述“在运行容器内执行命令”的钩子不同,见第 23 章,不能假设旧客户端支持。

13. 资源、安全与设备

13.1 单机常用资源设置

cpus: 1.5
mem_limit: 768m
mem_reservation: 256m
pids_limit: 256
shm_size: 128m
ulimits:
  nofile:
    soft: 65536
    hard: 65536

CPU 1.5 是计算配额,不是固定绑定某两个 CPU;cpuset: "0-1" 才是允许运行的 CPU 集合。cpu_shares 是争抢时的相对权重,不能当硬上限。mem_reservation 是软约束,不是预分配独占内存。

mem_limit 约束容器内的全部相关内存,JVM heap、Python 对象、native、线程栈等都需留余量。memswap_limit 表示内存与 swap 的总上限,实际效果取决于宿主机 swap/cgroup;不能把它直接解释成“额外 swap 大小”。

13.2 逐步收紧权限

user: "1000:1000"
read_only: true
cap_drop: [ALL]
security_opt:
  - no-new-privileges:true
tmpfs:
  - /tmp:size=64m,mode=1777

这是适用于兼容应用的组合示例,不能直接套在所有数据库和系统组件上。先识别应用写目录、低端口绑定和文件权限需求,再给最小必要权限。read_only 限制根文件系统,单独挂载的可写卷仍可以写。

privileged: true 扩大权限范围;需要某项设备时优先明确 devices、驱动和 capability。把 Docker API socket 挂入容器或启用 use_api_socket 会赋予强大的引擎访问能力,应仅用于明确需要管理引擎的工具。

13.3 GPU 两种常见表达

services:
  gpu-app:
    image: your-gpu-image:tag
    gpus: all

或在支持实现中使用设备预留:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: 1
          capabilities: [gpu]

这两段是占位示例。Compose 配置不会安装驱动或 NVIDIA Container Toolkit,也不能将只支持 CUDA 的镜像自动变成 NPU 镜像。count 与 device_ids 不应同时指定;capabilities 是设备请求的必要信息。GPU 整合先验证宿主机与容器运行时,再写应用配置。

14. services 全字段字典

以下按用途覆盖官方服务参考字段。示例值是表达方式,不是所有应用的推荐值。子结构见前后各章。

14.1 镜像、进程与身份

字段 作用 / 编写提示
image 镜像引用 仓库/名称:标签 或 @sha256:...
build 构建定义,详见第 15 章
pull_policy 镜像获取或构建策略,见第 7 章
platform 目标平台,如 linux/amd64;跨架构可能需模拟且有性能差异
command 覆盖 CMD,优先用列表明确参数
entrypoint 覆盖入口,谨慎处理镜像初始化逻辑
working_dir 容器内工作目录
user 用户名或 UID[:GID]
group_add 附加组列表,用于共享目录或设备访问
init 轻量 init 进程
container_name 固定容器名;妨碍服务扩容且容易跨项目冲突
hostname 容器自身主机名,通常不代替服务名发现
domainname 容器域名部分
stdin_open 保持标准输入打开,相当于 -i
tty 分配伪终端,相当于 -t
attach 是否默认附加服务日志输出;不是后台启动开关
restart 容器退出后的重启策略
scale 服务实例数量;与 deploy.replicas 同时设置时需一致
stop_signal 停止信号
stop_grace_period 优雅停止宽限时间
post_start、pre_stop 生命周期钩子,见第 12 章
pre_start 新规范初始化容器序列,先检查实际版本支持

14.2 配置、依赖与组织

字段 作用 / 编写提示
environment 容器环境变量,映射或 KEY=value 列表
env_file 容器变量文件,支持列表与新版长语法
configs 授权并挂载顶层配置对象
secrets 授权并挂载顶层敏感配置
depends_on 依赖关系、健康条件与完成条件
healthcheck 容器健康检测
profiles 控制按场景启用哪些服务
extends 从其他服务继承配置,资源声明仍需检查
labels 容器元数据,例如监控或反向代理发现规则
label_file 从文件加载标签;直接 labels 优先,较新功能
annotations 容器注释元数据,实际消费依赖平台
deploy 部署声明,支持范围取决于实现
develop 本地开发监听与同步
provider 让外部提供者管理服务,type 指定提供者、options 传其参数;非普通镜像服务模式
models 为服务授权/注入模型访问配置,依赖模型集成环境

14.3 网络与服务发现

字段 作用 / 编写提示
ports 发布端口到宿主机
expose 描述容器端口,不等于发布端口或访问控制
networks 加入哪些网络及每个连接的参数
network_mode host、none 或共享其他容器网络命名空间
dns 自定义 DNS 服务器列表
dns_search DNS 搜索域列表
dns_opt DNS resolver 选项,例如 ndots:1
extra_hosts 额外 hosts 记录,如 host.docker.internal:host-gateway,需引擎支持
mac_address 容器级 MAC;部分引擎限制使用,优先考虑网络级配置
links 旧式连接/别名机制,现代用户网络通常无需使用
external_links 连接外部已有容器的旧式功能,受网络条件限制

driver_opts 通常位于 services.<服务>.networks.<网络>,不要误写成通用的服务根字段。

14.4 存储、日志与命名空间

字段 作用 / 编写提示
volumes 挂载卷、宿主机文件、tmpfs 等
volumes_from 继承其他服务/容器的挂载,耦合较强,优先显式挂载
tmpfs 简写临时内存挂载,字符串或列表
read_only 根文件系统只读
storage_opt 容器存储驱动参数,依赖驱动/后端文件系统
logging driver 与该驱动的 options
shm_size /dev/shm 大小,数据库和多进程任务可能需要调整
ipc IPC 命名空间,如 shareable 或 service:xxx;host 等模式依赖平台
pid PID 命名空间模式,例如 host,影响隔离
uts UTS 命名空间模式,例如 host,依赖平台
cgroup host / private,控制 cgroup 命名空间
cgroup_parent 放入指定父 cgroup,依赖宿主管理方式
userns_mode 用户命名空间模式,例如 host,需结合 daemon 设置
isolation 容器隔离方式,常见于 Windows process / hyperv
runtime 选择已安装、已配置的运行时

14.5 资源字段

字段 作用 / 编写提示
cpus CPU 配额数量
cpuset 可使用的 CPU 集合,如 0-3,6
cpu_shares CPU 争抢相对权重
cpu_period CPU 调度计费周期,通常为微秒
cpu_quota 每个周期允许使用的 CPU 时间,与 period 配合
cpu_count CPU 数量控制,平台相关,常用于 Windows
cpu_percent CPU 百分比控制,平台相关
cpu_rt_period 实时调度周期,需要内核/daemon 支持
cpu_rt_runtime 实时调度时间预算,需要特殊支持与权限
mem_limit 内存硬上限
mem_reservation 内存软限制
memswap_limit 内存与 swap 总量上限
mem_swappiness 匿名页换出倾向,0~100,依赖平台/cgroup
pids_limit 进程数限制,防止进程数量失控
oom_kill_disable 请求禁用 OOM kill,风险和支持范围需评估,不能代替内存容量规划
oom_score_adj 调整 OOM 选择倾向,Linux 范围 -1000~1000
ulimits 进程资源限制,数字或 soft / hard 映射
blkio_config 块设备 I/O 权重与限速,依赖内核、cgroup 和实际设备

blkio_config 的完整常用子结构:

blkio_config:
  weight: 500
  weight_device:
    - path: /dev/sdb
      weight: 300
  device_read_bps:
    - path: /dev/sdb
      rate: "20mb"
  device_write_bps:
    - path: /dev/sdb
      rate: "10mb"
  device_read_iops:
    - path: /dev/sdb
      rate: 1000
  device_write_iops:
    - path: /dev/sdb
      rate: 500

这是设备示意,不要直接对不存在或不对应数据盘的设备套用。weight 为 10~1000;BPS 是字节速率,IOPS 是操作次数速率。

14.6 权限与设备字段

字段 作用 / 编写提示
privileged 高权限模式,不建议作为通用排错开关
cap_add 添加 Linux capability,如 NET_ADMIN
cap_drop 移除 capability,如 ALL
security_opt 安全配置,例如 no-new-privileges、seccomp、SELinux 选项
devices 设备映射 宿主机:容器:权限,新版可支持 CDI 设备选择字符串
device_cgroup_rules 设备 cgroup 访问规则,如字符设备主次号;不会自动创建设备节点
gpus GPU 请求,支持 all 或设备请求列表,需较新 Compose 和运行时
sysctls 容器命名空间允许修改的内核参数;不代表可修改任意宿主机参数
credential_spec Windows gMSA 凭据规范,支持 file / registry / config 等平台相关来源
use_api_socket 引擎 API socket 委托访问,权限范围需明确

15. build:如何把源码变成镜像

services:
  api:
    image: local/compose-api:dev
    build:
      context: ./app
      dockerfile: Dockerfile
      args:
        APP_VERSION: "1.0.0"
      target: runtime
    pull_policy: build

context 是可供构建访问的文件上下文;dockerfile 相对构建上下文解析;Dockerfile 中的 COPY 来源受上下文约束,不是任意宿主机路径。

字段 作用
context 本地目录、Git URL 等构建上下文
dockerfile Dockerfile 路径,相对 context
dockerfile_inline 内联 Dockerfile,不能与 dockerfile 同时使用
args Dockerfile ARG 值,不能当安全的密码传递方式
target 多阶段构建的目标阶段,Dockerfile 必须真的存在对应阶段
additional_contexts 命名附加上下文,可引用其他服务构建结果等,依赖 builder
cache_from 导入构建缓存位置
cache_to 导出构建缓存位置
no_cache 不使用构建层缓存,不等于一定重新拉取基础镜像
pull 构建时尝试更新基础镜像
network 构建 RUN 阶段网络模式,不是运行容器网络
extra_hosts 构建阶段 hosts 记录
platforms 构建目标平台列表,依赖 builder 和镜像存储能力
tags 附加镜像标签
labels 构建结果镜像的标签,不同于容器 labels
secrets 构建机密授权,Dockerfile 使用 secret mount
ssh 构建时转发 SSH agent / 密钥引用,用于受控私有仓库访问
shm_size 构建阶段共享内存大小
ulimits 构建阶段资源限制
isolation 构建容器隔离方式,平台相关
privileged 特权构建,平台相关且需明确需求
entitlements 特殊构建授权,如 network.host,需 builder 允许
provenance 构建来源证明开关或配置,依赖版本
sbom 软件物料清单证明生成,依赖版本

15.1 构建机密与运行机密不是一回事

services:
  api:
    build:
      context: ./app
      secrets:
        - source: package_token
          target: package_token
secrets:
  package_token:
    file: ./secrets/package_token.txt

Dockerfile 对应写法:

# syntax=docker/dockerfile:1
RUN --mount=type=secret,id=package_token \
    some-package-manager --token-file /run/secrets/package_token

最后一行是伪命令,要换成真实工具。build.secrets 长语法还支持 uid、gid、mode,按 builder 支持执行。运行时需要的 secret 要另写服务级 secrets。不要用 ARG PASSWORD=... 把凭据固化在构建记录或镜像层中。

16. deploy:部署字段与单机支持边界

不能一概说“deploy 全部无效”,也不能一概说“写了都生效”。现代 Docker Compose 支持其中部分配置,例如某些资源约束、设备请求与副本设置;Swarm 的调度、路由和滚动更新等语义不能直接套给单机 up。

字段路径 含义
mode replicated / global,集群任务模式还可有 replicated-job / global-job
replicas 期望副本数;单机多副本仍共享同一宿主机故障域
endpoint_mode vip / dnsrr,服务发现模式,主要是集群语义
labels 平台服务对象标签,区别于容器级 labels
placement.constraints 调度约束,例如节点标签
placement.preferences[].spread 分散放置偏好
placement.max_replicas_per_node 每个节点最多副本数
resources.limits.cpus CPU 上限
resources.limits.memory 内存上限
resources.limits.pids PID 数上限
resources.reservations.cpus CPU 预留,具体保障依赖平台
resources.reservations.memory 内存预留
resources.reservations.devices 设备请求,见下表
resources.reservations.generic_resources 泛型离散资源预留,平台相关
restart_policy 平台任务重启策略,不等同于简单 restart
update_config 平台滚动更新参数
rollback_config 平台回滚参数

设备请求子字段:capabilities 为能力列表;driver 为驱动;count 为数量或 all;device_ids 为具体设备列表;options 为驱动参数。不要同时指定 count 和 device_ids。

重启策略子字段:condition 为 none / on-failure / any;delay 为重试延迟;max_attempts 为重试上限;window 为评估窗口。

update_config 与 rollback_config 共有:parallelism 并行数、delay 批次间隔、monitor 观察时间、max_failure_ratio 失败比例、order(stop-first / start-first);update_config.failure_action 可为 pause / continue / rollback,回滚自身的 failure_action 通常为 pause / continue。

如在 service 同时设置 cpus 和 deploy.resources.limits.cpus,或 mem_limit 与 deploy 内存上限,值应一致。单机练习可以先使用直接资源字段,再通过引擎 inspect 验证结果。

17. develop:本地开发自动同步

services:
  api:
    build: ./app
    develop:
      watch:
        - action: sync
          path: ./app
          target: /app
          ignore:
            - __pycache__/
            - requirements.txt
        - action: rebuild
          path: ./app/requirements.txt
docker compose up --watch

sync 只同步文件,应用需要自己的热重载机制;rebuild 重新构建并重建容器。项目也可使用独立 docker compose watch 命令,具体行为查看本机帮助。

watch 子字段 作用
path 宿主机监听路径
action sync / rebuild,新版有 restart / sync+restart / sync+exec
target 容器同步目标路径,同步动作需使用
ignore 排除规则
include 仅包含匹配内容,较新功能
initial_sync 监听开始时进行初始同步,较新功能
exec sync+exec 后执行的命令对象,含 command、user、privileged、working_dir、environment

Develop 起始于 Compose 2.22.0,但不同 action 和子字段有更高版本要求。监听功能用于开发,不等于生产代码发布方案。

18. configs、secrets、models

18.1 configs:把配置作为文件提供

services:
  web:
    image: nginx:stable-alpine
    configs:
      - source: nginx_config
        target: /etc/nginx/nginx.conf
configs:
  nginx_config:
    file: ./nginx.conf

顶层 configs 常用字段:file 文件来源、content 内联内容、environment 从宿主机变量取内容、external 引用已有对象、name 实际对象名。文件/内联/环境变量来源按场景择一;内联内容也会涉及插值。

服务长语法:source 为顶层逻辑名;target 为容器文件路径;uid、gid、mode 表示所有权与权限请求。在本地文件 bind 实现中,不能假设 uid/gid/mode 都能按声明重新映射,需核验实际权限。

18.2 secrets:显式授权敏感文件

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password
secrets:
  db_password:
    file: ./secrets/db_password.txt

顶层主要字段:file、environment、external、name。服务长语法支持 source、target、uid、gid、mode。Linux 默认挂到 /run/secrets/<名称>;长语法可自定义目标。

POSTGRES_PASSWORD_FILE 是该镜像支持的约定,不是 Compose 自动识别的统一参数。其他应用必须自行支持读取文件。

本地 Compose 的 file secret 通常基于文件挂载,不等同于 Swarm 加密 secret 存储。仍需保护宿主机源文件、限制版本库提交并核验权限。external 的平台对象支持与普通本地 Compose 文件来源也有差别。

规范 schema 还包含资源的 labels、secret 的 driver / driver_opts / template_driver、config 的 template_driver 等平台相关字段。不要因为 JSON schema 接受就认为本地 Compose 后端会创建对应资源。

18.3 models:模型运行集成

models:
  assistant:
    model: ai/your-model:tag
    context_size: 8192
services:
  api:
    image: your-api:tag
    models:
      assistant:
        endpoint_var: MODEL_URL
        model_var: MODEL_NAME

这是结构示例,不保证占位模型可用。顶层模型字段包括 model(模型引用)、context_size(上下文大小)、runtime_flags(运行参数),schema 还定义 name。服务可短写模型名列表,或用长语法明确 endpoint_var / model_var 的环境变量名。需要支持该集成的 Compose 与模型运行后端,普通 Docker Engine 不会仅凭文件自动具备全部模型服务能力。

19. 复用、合并、拆分与 profiles

19.1 x-* 与 YAML anchor

x-common: &common
  restart: unless-stopped
  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "3"
services:
  web:
    <<: *common
    image: nginx:stable-alpine
  cache:
    <<: *common
    image: redis:7-alpine

&common 定义锚点,*common 引用,<< 合并映射。这是 YAML 层复用,不是跨文件模板语言;不能随意把列表当映射合并。复写一个嵌套映射时要留意它并非自动深度合并所有子键。

19.2 多文件覆盖

docker compose -f compose.yaml -f compose.prod.yaml config
docker compose -f compose.yaml -f compose.prod.yaml up -d

后面的文件覆盖或合并前面的配置。映射通常递归合并;列表常涉及追加;command、entrypoint、healthcheck.test 有替换规则;ports、volumes、secrets、configs 有唯一键合并规则。尤其端口列表可能保留旧入口,不能假设后一文件完整替换。

较新 Compose 可用 !reset 清空或 !override 整体替换,例如:

services:
  web:
    ports: !override
      - "127.0.0.1:9090:80"

这不是普通 YAML 通用功能,需 Compose 支持相应标签。多文件相对路径通常以第一个 Compose 文件的基础路径解析;不要按各覆盖文件所在目录想当然地推算。

19.3 extends 与 include

services:
  api:
    extends:
      file: ./common.yaml
      service: base-api
    environment:
      APP_MODE: production

extends.file 指定来源文件,extends.service 指定服务;继承服务配置不意味着关联网络、卷等顶层资源都会自动完整导入,最终模型必须检查。

include 导入另一个应用模型,短语法为路径列表;长语法含 path(单个或多个 Compose 文件)、project_directory(其相对路径基准)、env_file(其插值环境默认文件)。它适合独立模块组合,不等于 -f 覆盖;资源重名可能产生冲突。

19.4 profiles:可选组件

services:
  cache:
    image: redis:7-alpine
  debug-cache:
    image: redis:7-alpine
    profiles: [debug]
    command: ["redis-cli", "-h", "cache", "ping"]
    depends_on: [cache]
docker compose up -d
docker compose --profile debug up debug-cache

无 profiles 的服务默认启用;指定 profile 时再加入对应服务。显式点名一个带 profile 的服务时可以自动激活该目标及所需依赖,但不代表同 profile 所有服务都跟着启动。注意不要让必需服务依赖一个当前被过滤掉的可选服务。

20. 完整练习:Python Web + PostgreSQL + Redis

20.1 目标与目录

这套练习展示:构建应用、内部服务发现、数据库与缓存就绪、命名卷、secret 文件、资源限制、日志轮转以及 HTTP 检查。

compose-lab/
├── compose.yaml
├── .env
├── .gitignore
├── secrets/
│   └── db_password.txt
└── app/
    ├── Dockerfile
    ├── .dockerignore
    ├── requirements.txt
    └── app.py

本文旁的 compose-lab 文件夹提供了完整配套文件;所有运行命令都应在该目录执行。示例用于学习,不包含生产认证、TLS、备份调度和真实业务模型。

20.2 compose.yaml

name: compose-lab
services:
  app:
    image: local/compose-lab-app:dev
    build:
      context: ./app
    pull_policy: build
    init: true
    ports:
      - "127.0.0.1:${HTTP_PORT:-8080}:8000"
    environment:
      DB_HOST: db
      DB_NAME: demo
      DB_USER: demo
      DB_PASSWORD_FILE: /run/secrets/db_password
      REDIS_HOST: cache
    secrets: [db_password]
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      test:
        - CMD
        - python
        - -c
        - "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=2)"
      interval: 10s
      timeout: 10s
      retries: 3
      start_period: 15s
    restart: unless-stopped
    cpus: 1.0
    mem_limit: 256m
    pids_limit: 128
    read_only: true
    tmpfs:
      - /tmp:size=32m,mode=1777
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: demo
      POSTGRES_USER: demo
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U demo -d demo"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 20s
    restart: unless-stopped
    mem_limit: 512m
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
  cache:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped
    mem_limit: 256m
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
volumes:
  db_data: {}
  redis_data: {}
secrets:
  db_password:
    file: ./secrets/db_password.txt

这里刻意使用默认网络:服务名已能解决内部连接需求,不需要为了“完整”而增加固定 IP。数据库和 Redis 不发布宿主机端口。Redis 未设置认证,仅供这个本机隔离练习;真实部署要结合网络边界、ACL 和业务权限设计。

Redis 容器内存限制不是 Redis 的 maxmemory;有正式缓存容量要求时还要配置 maxmemory 和淘汰策略,并为进程其他内存留空间。

20.3 其他文件

.env:

HTTP_PORT=8080

app/requirements.txt:

Flask>=3.1,<4
psycopg[binary]>=3.2,<4
redis>=5,<7

这是学习用依赖范围;正式交付应生成并验证锁定版本。

app/Dockerfile:

FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt \
    && groupadd -g 10001 app \
    && useradd -u 10001 -g app -M -s /usr/sbin/nologin app
COPY --chown=app:app app.py .
USER app
EXPOSE 8000
CMD ["python", "app.py"]

app/app.py:

import os
from pathlib import Path

import psycopg
import redis
from flask import Flask, jsonify

app = Flask(__name__)


def check_dependencies():
    password = Path(os.environ["DB_PASSWORD_FILE"]).read_text().strip()
    with psycopg.connect(
        host=os.environ["DB_HOST"],
        dbname=os.environ["DB_NAME"],
        user=os.environ["DB_USER"],
        password=password,
        connect_timeout=2,
        options="-c statement_timeout=2000",
    ) as conn:
        conn.execute("SELECT 1").fetchone()
    client = redis.Redis(
        host=os.environ["REDIS_HOST"],
        socket_connect_timeout=2,
        socket_timeout=2,
    )
    try:
        client.ping()
    finally:
        client.close()


@app.get("/health")
def health():
    try:
        check_dependencies()
    except Exception:
        app.logger.exception("Dependency check failed")
        return jsonify(status="unavailable"), 503
    return jsonify(status="ok")


@app.get("/")
def index():
    return jsonify(message="Hello Docker Compose", health="/health")


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

为便于理解,示例使用 Flask 开发服务器。实际发布应使用适合生产的 WSGI 服务,并按线程/进程数规划连接池和内存。本示例健康接口访问真实依赖,因此比仅判断端口存在更严格;实际业务也可以区分存活检查与就绪检查,避免把依赖波动无限放大。

app/.dockerignore:

__pycache__/
*.pyc
.venv/
.env

.gitignore:

.env
secrets/
__pycache__/

20.4 启动、验证、停止

先生成本地练习密码:

mkdir -p secrets
python3 -c 'import secrets; from pathlib import Path; Path("secrets/db_password.txt").write_text(secrets.token_urlsafe(32) + "\n")'
chmod 700 secrets
chmod 644 secrets/db_password.txt
docker compose config -q
docker compose up -d --build
docker compose ps
curl -f http://127.0.0.1:8080/
curl -f http://127.0.0.1:8080/health
docker compose logs --tail=100 app db cache

权限解释:父目录 700 限制其他宿主机普通用户遍历;示例文件 644 是为了让 bind secret 在容器内 UID 10001 下可读。容器只挂入该文件,不能靠宿主机父目录权限阻止它读取。更严格的生产做法是明确协调容器 UID/GID、源文件组权限或使用专用 secret 管理后端;不能简单 chmod 600 后假设非 root 应用仍读得了。

生成密码只在首次初始化时执行。数据库命名卷已有数据后,修改密码文件不会自动修改数据库中的角色密码;重复生成会导致应用认证失败,应通过数据库密码变更流程同步。

健康检查串行访问数据库与 Redis,示例整体 healthcheck timeout 为 10 秒,为连接、查询与缓存检查预留时间;正式场景仍需按实际耗时、网络与期望恢复时间调整。

停止并保留数据:

docker compose down

再次 up 后会复用同名命名卷。只有明确要清空练习数据时才手动使用 down -v。

21. 运维命令与排错顺序

21.1 日常命令

命令 目的
docker compose version 查看插件版本
docker compose config -q 校验并解析配置,成功通常不输出
docker compose config 查看合并和插值后的配置,注意凭据
docker compose config --services 列出服务名
docker compose config --images 列出镜像
docker compose pull 拉取所需镜像,构建服务注意其策略
docker compose build app 构建 app
docker compose up -d 创建/更新并启动项目
docker compose up -d --build 构建后启动
docker compose up -d --wait 支持版本中等待 running/healthy,是否代表业务就绪取决于健康检查
docker compose ps -a 查看包括退出容器在内的状态
docker compose logs -f --tail=100 app 跟踪 app 最近日志
docker compose exec app sh 进入已运行容器;镜像不一定有 shell
docker compose run --rm app python -V 新建临时容器运行命令,默认不发布服务端口
docker compose restart app 重启已有容器,不应用 Compose 配置变更
docker compose stop 停止,保留容器
docker compose start 启动已有容器,不重新构建或创建
docker compose down 移除项目容器与项目网络,默认保留命名卷
docker compose top 查看容器进程
docker compose stats 支持版本中查看服务资源使用
docker compose port app 8000 查看容器端口的宿主机映射

修改 environment、ports、挂载或镜像等配置后用 up -d 让 Compose 协调重建;仅 restart 不会更新配置。

21.2 按层排错

第一层:配置能否解析?

docker compose config -q
docker compose config --services

检查缩进、错误字段、必填变量、未声明资源、客户端版本。错误如 Additional property ... is not allowed,先查字段层级和功能版本,不要先删除整段业务配置。

第二层:镜像能否获取或构建?

docker compose pull
docker compose build app

分别检查仓库连通性、认证、标签、架构与 Dockerfile 上下文。no matching manifest 常与平台不匹配有关;COPY 找不到文件常与 context 或 .dockerignore 有关。

第三层:容器为什么退出?

docker compose ps -a
docker compose logs --tail=100 app

看实际报错、退出码、入口命令、配置文件权限和依赖连接。OOMKilled 与普通非零退出要分开检查。

可用以下脚本查看容器实际状态及限制;将 app 替换成目标服务:

cid=$(docker compose ps -a -q app)
if [ -n "$cid" ]; then
  docker inspect --format '{{json .State}}' "$cid"
  docker inspect --format '{{json .HostConfig}}' "$cid"
fi

这段适用于单副本服务;多副本时应逐个处理容器 ID。HostConfig 也可能包含敏感信息或挂载路径,分享前检查。

第四层:网络通不通?

确认应用监听 0.0.0.0,端口左右顺序正确,调用方使用服务名和容器端口,两服务确实共享网络。不要只在宿主机测试成功就认定容器间一定成功。

配套练习可以执行:

docker compose exec app python -c 'import socket; print(socket.getaddrinfo("db", 5432)); socket.create_connection(("db", 5432), 2).close()'

这只证明 DNS 和 TCP,不证明数据库账号、SQL 权限或业务查询正确。

第五层:挂载和权限对不对?

检查源路径是文件还是目录、是否覆盖了镜像原有文件、UID/GID 是否匹配、SELinux 是否阻止、数据库路径是否适合当前镜像版本。路径存在不代表内容正确。

第六层:依赖是未启动、未健康,还是启动后断开?

看 healthcheck 命令是否存在,用户名/数据库名是否真实,检查预算是否合理。不要通过关闭健康检查来掩盖数据库故障。

21.3 常见现象速查

现象 优先查什么
host port already allocated 宿主机端口占用;是否错误扩容固定端口服务
容器 Running,HTTP 不通 监听地址、容器端口、ports、应用路由
DB 连接 localhost 失败 另一个服务应使用 db:5432
配置文件被识别为目录 bind 源不存在且被自动建目录
变量值为空 插值来源、必填表达式、environment 与 env_file 区别
unhealthy 但不重启 健康状态不等于主进程退出
改密码后 DB 仍拒绝 初始化环境只对空数据目录生效,角色密码未同步修改
重启后配置没变化 restart 不应用新配置,使用 up 协调
删除容器后数据丢失 数据写到可写层、匿名卷或错误路径
写了 placement 但没跨节点 普通 Compose 不是多节点调度器
内存限制写了仍异常 看实际 HostConfig、进程总内存、cgroup 与实现支持

22. 编写检查清单与练习

22.1 每次新写配置都检查

  • 服务名简洁,内部连接使用服务名和容器端口。
  • 镜像版本、架构与真实数据目录已确认。
  • 不随意覆盖数据库等镜像的 entrypoint。
  • 应用前台运行,能正确接收停止信号。
  • 仅对必要入口配置 ports,绑定范围符合访问需求。
  • 持久化目录已挂载,备份与恢复独立规划。
  • .env 插值与容器环境变量用途已分清。
  • 密码不提交到版本库,文件权限允许目标 UID 读取。
  • 依赖等待使用合适条件,应用仍有重试机制。
  • healthcheck 命令在镜像内存在,超时预算合理。
  • 配置内存、CPU、PID 与日志轮转,数值来自实际容量。
  • 所有新版、平台和驱动字段已检查本机支持。
  • config -q 通过,启动后检查实际状态和业务访问。
  • 不把 down -v 当普通停止操作。

22.2 五个练习与检查标准

  1. 单独运行 Nginx:将宿主机端口改为 18080,绑定回环地址;浏览器能访问。
  2. 挂载静态页面:使用长语法 bind,禁用自动创建源路径;故意拼错路径时应明确失败。
  3. 给练习项目换入口:只改 .env 中 HTTP_PORT,使用 up 更新;数据库无需映射宿主机端口。
  4. 验证依赖故障:停止 cache,等待 app 健康状态变化;观察 app 主进程未退出时 restart 策略不会仅因 unhealthy 自动恢复依赖。再启动 cache 并验证健康恢复。
  5. 验证持久化:给练习数据库建一个测试表并插入记录,执行 down 后再 up,记录仍在;先备份再做任何数据删除练习。

完成标准不是能默写几十个关键字,而是能回答:这个字段解决了什么需求,删掉后会怎样,它在当前平台是否真的生效,如何用可观察结果验证。

23. 新规范字段与机器校验字段索引

23.1 不把主分支 schema 当已安装客户端的支持承诺

本次读取的 compose-spec 主分支已包含以下演进项。它们与稳定参考页、发行版之间可能存在时间差,首次使用前应看实际发行说明并运行本机 docker compose config -q。

字段 规范含义 / 注意事项
顶层 jobs 一次性或定时任务模型,不等同于普通 service;不要假设旧客户端识别
jobs.<任务>.triggers.manual 是否允许手动触发
jobs.<任务>.triggers.schedule 调度列表:cron 必填,timezone 时区;concurrency 为 forbid/queue,missed_fires 为 one/skip;实现需核验
pre_start 按顺序执行独立临时初始化容器,全部成功才启动服务;每步可使用容器配置,另有 per_replica
pull_refresh_after schema 描述为与 pull_policy: refresh 配合的刷新时间;此策略尚需核验客户端实现,不能套用到旧版本
umask 进程初始文件创建掩码;null/省略沿用运行时行为,显式 0 不屏蔽权限位;不会修复已有文件权限
网络连接 use_service_name_alias 控制服务名别名行为的新规范字段,先核验实现

更兼容的一次性迁移写法,仍然是在 services 定义迁移服务,搭配 condition: service_completed_successfully,而不是盲目改用 jobs。

23.2 字段索引的用途

配套 Compose_schema字段路径索引.md 从此次下载的官方 JSON schema 自动生成,列出可枚举对象属性路径、类型和引用。它用于检查“是否漏看某个子字段”,不用于取代中文教学,也不说明所有后端都支持字段。开放字典的任意键值、扩展 x-* 不可能全部枚举。

24. 官方参考与验证说明

本文按官方规范与代码仓库整理,字段解释为中文归纳,案例为教学组合。重要事实应结合实际安装版本核验。

验证范围:配套 Python 文件做语法检查;40 个 YAML 示例块做了解析检查,完整配套项目通过官方 schema 静态校验。写作环境未安装 Docker,因此没有实际拉取镜像、构建应用或启动容器;不将静态校验描述成部署成功。片段中包含占位镜像、设备路径或依赖外部文件的部分,需按实际环境补齐。

©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成,浏览时请结合常识与多方信息审慎甄别。
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

友情链接更多精彩内容