容器与云原生 / 系统课时
Compose 文件基本结构
Compose 文件基本结构
Compose 文件的关键不是记住大量字段,而是先看懂层级:services 描述要运行的容器服务,networks 描述通信边界,volumes 描述可持久化的数据。掌握这三个顶层区域和 YAML 的缩进规则,就能写出大多数开发环境所需的基础编排文件。
学习目标
- 读懂
services、networks、volumes三个常用顶层配置的职责 - 正确使用 YAML 的映射、列表和缩进表达 Compose 配置
- 使用
docker compose config在启动前验证文件结构
从一个最小可运行文件开始
下面的 compose.yaml 定义两个服务:Nginx 提供 Web 端口,Redis 保存数据。两个服务加入同一个自定义网络,Redis 的 /data 目录挂载到命名卷,因此容器重建后数据卷仍可继续使用。
services:
web:
image: nginx:1.27
ports:
- "8080:80"
networks:
- app-net
cache:
image: redis:7.4
volumes:
- cache-data:/data
networks:
- app-net
networks:
app-net:
volumes:
cache-data:保存文件后,在同一目录先做结构验证:
docker compose config --quiet
echo $?
docker compose config --services预期输出
0
web
cache退出码 0 表示 Compose 成功解析并校验配置;--services 输出解析后的服务名。这个检查能发现 YAML 语法、未知字段和部分变量插值问题,但不能证明镜像一定可拉取,也不能证明应用启动后一定健康。
services 是 Compose 的核心
services 下的每个键都是一个服务名,例如 web 和 cache。服务通常由 image 或 build 指定来源,再通过 ports、environment、volumes、networks、command 等字段描述运行方式。
默认情况下,docker compose up 会为每个服务创建一个容器实例。服务名同时也是 Compose 网络中的稳定 DNS 名,因此处于同一网络的其他服务可以使用 cache 访问 Redis,而不需要依赖会变化的容器 IP。
networks 和 volumes 分离通信与数据
顶层 networks 用于声明项目需要的网络,服务再通过自己的 networks 列表选择加入哪些网络。这样可以把“谁能直接通信”写进配置,而不是依赖手工执行 docker network connect。
顶层 volumes 声明命名卷,服务内部的 volumes 再把卷挂载到容器路径。命名卷由 Docker 管理,docker compose down 默认不会删除它,因此适合保存数据库、缓存持久化文件等需要跨容器重建保留的数据。
如果完全省略顶层 networks,Compose 仍会为项目创建一个默认网络,并把未显式指定网络的服务接入其中。只有需要更清晰的通信隔离时,才应主动声明多个网络。
YAML 规则会直接影响配置含义
YAML 通过缩进表示层级,必须使用空格而不是 Tab。key: value 表示映射,前导 - 表示列表;同一层级的键必须保持相同缩进,否则字段可能被解释到错误的位置。
端口映射建议写成 "8080:80" 这样的字符串,环境变量中必须保持字符串语义的值也建议显式加引号。现代 Docker Compose 遵循 Compose Specification,通常不需要再写顶层 version 字段;重点应放在实际使用的配置项上。
启动前先解析,修改后再验证
docker compose config 会把多个 Compose 文件、环境变量插值和默认值解析为最终配置,因此它比只检查 YAML 是否能解析更接近真实执行结果。修改服务名、卷名、环境变量或覆盖文件后,都应先运行一次该命令。
配置通过后,再执行 docker compose up -d 启动项目,并用 docker compose ps 检查容器状态。把“先解析配置,再运行容器”作为固定习惯,可以在真正创建资源之前拦截大量缩进、字段和变量错误。