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本身是开放字典,不能用一份固定清单穷尽。
目录
- Compose 的作用与边界
- 先把 YAML 写对
- 从需求推导配置的八个问题
- 第一个可运行案例
- 从 docker run 转成 Compose
- 顶层字段与项目命名
- 服务启动与镜像
- 环境变量与插值
- 端口与网络
- 数据卷与挂载
- 启动依赖与健康检查
- 生命周期与日志
- 资源、安全与设备
- services 全字段字典
- build 构建字段
- deploy 部署字段
- develop 开发字段
- configs、secrets、models
- 复用、合并、拆分和 profiles
- 完整练习:Python Web + PostgreSQL + Redis
- 运维命令与排错顺序
- 编写检查清单与练习
- 新规范字段及机器校验字段索引
- 官方参考与验证说明
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 五个练习与检查标准
- 单独运行 Nginx:将宿主机端口改为 18080,绑定回环地址;浏览器能访问。
- 挂载静态页面:使用长语法 bind,禁用自动创建源路径;故意拼错路径时应明确失败。
-
给练习项目换入口:只改
.env中 HTTP_PORT,使用 up 更新;数据库无需映射宿主机端口。 - 验证依赖故障:停止 cache,等待 app 健康状态变化;观察 app 主进程未退出时 restart 策略不会仅因 unhealthy 自动恢复依赖。再启动 cache 并验证健康恢复。
- 验证持久化:给练习数据库建一个测试表并插入记录,执行 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. 官方参考与验证说明
本文按官方规范与代码仓库整理,字段解释为中文归纳,案例为教学组合。重要事实应结合实际安装版本核验。
- Compose Specification 官方仓库:完整规范
- 官方 JSON schema
- Docker Compose 文件参考入口
- Services 字段参考
- Build 字段参考
- Deploy 字段参考
- Develop 字段参考
- Networks 字段参考
- Volumes 字段参考
- Configs 字段参考
- Secrets 字段参考
- 变量插值规则
- 多文件合并规则
验证范围:配套 Python 文件做语法检查;40 个 YAML 示例块做了解析检查,完整配套项目通过官方 schema 静态校验。写作环境未安装 Docker,因此没有实际拉取镜像、构建应用或启动容器;不将静态校验描述成部署成功。片段中包含占位镜像、设备路径或依赖外部文件的部分,需按实际环境补齐。