容器与云原生 / 知识点
Docker Compose 配置与运维速查手册
手册条目
跳过构建缓存以排除旧层或依赖未更新问题。
无缓存重新构建
当镜像仍包含旧依赖、旧构建产物或异常缓存层时,用 docker compose build --no-cache 重新执行 Dockerfile 的每个构建步骤;需要同时刷新基础镜像时再加 --pull。该操作只重建镜像,不会自动替换正在运行的容器。:contentReference[oaicite:0]{index=0}
命令定位
只处理 Compose 中带 build: 的服务。优先指定单个服务,避免整个项目无差别重建;镜像构建成功后,再用 docker compose up -d 让目标容器采用新镜像。
基本语法
docker compose build --no-cache [--pull] [SERVICE...]--no-cache 禁止本次构建复用 Dockerfile 层缓存;--pull 始终尝试拉取更新的基础镜像;SERVICE... 省略时会构建所有可构建服务。:contentReference[oaicite:1]{index=1}
高频用法
下面以 web 服务为例,先彻底重建镜像,再仅重建并启动该服务,避免无关依赖被重启。
# 跳过构建缓存,并检查基础镜像是否有更新
docker compose build --no-cache --pull web
# 使用新镜像替换 web 容器,不主动启动其依赖
docker compose up -d --no-deps web预期输出
[+] Building <TIME> (12/12) FINISHED
[+] Running 1/1
✔ Container <PROJECT>-web-1 <ACTION><TIME>、项目名和步骤数会变化;<ACTION> 常见为 Started 或 Recreated。出现 FINISHED 表示镜像构建完成,随后容器状态成功即表示新镜像已应用。
风险与边界
触发全量无缓存构建时,每一层都要重新执行,可能显著增加耗时、网络流量和仓库限流风险。安全做法是先限定服务,并仅在基础镜像也需刷新时使用 --pull。
--no-cache 不会删除现有构建缓存,也不会清理命名卷。若旧文件来自挂载卷,重建镜像仍不会改变卷内数据;不要直接执行 docker compose down -v,否则可能删除数据库等持久化数据,应先确认挂载来源并备份。
排障清单
- 代码仍未更新:确认 Compose 使用了正确的文件、项目目录和
build.context,并检查.dockerignore是否排除了目标文件。 - 基础镜像仍旧:确认已加
--pull;若 Dockerfile 固定了镜像摘要,版本不变化属于预期行为。 - 依赖仍旧:检查依赖是否被复制进镜像,还是来自 bind mount、命名卷或外部包缓存。
- 构建成功但服务未变化:执行
docker compose up -d --no-deps web,再通过服务日志或版本接口验证实际运行版本。
速查:无缓存构建解决的是镜像层复用问题,不等同于清卷、清宿主机文件或自动更新运行中容器。
从镜像仓库更新 Compose 服务依赖的镜像。
拉取服务镜像
发布前需要从镜像仓库更新 Compose 服务使用的镜像时,执行 docker compose pull。它只下载镜像,不会启动服务,也不会自动让现有容器切换到新镜像;拉取后需再执行 docker compose up -d。:contentReference[oaicite:2]{index=2}
命令定位
适用于 Compose 服务通过 image: 引用仓库镜像的场景。可以拉取全部服务,也可以只指定本次发布涉及的服务,生产环境通常优先采用后者以缩小变更范围。
基本语法
docker compose pull [OPTIONS] [SERVICE...]常用参数包括:--include-deps 同时拉取 depends_on 依赖服务,--policy always 强制检查远端镜像,--policy missing 仅在本地缺失时拉取,--ignore-buildable 跳过可本地构建的服务,--quiet 隐藏进度输出。:contentReference[oaicite:3]{index=3}
高频用法
下面只更新 web 和 worker,拉取全部成功后再重建对应容器。使用 && 可避免拉取失败时继续发布。
# 仅拉取本次发布涉及的服务
docker compose pull --policy always web worker &&
# 用已拉取的新镜像重建并后台启动容器
docker compose up -d web worker预期输出
[+] Pulling 2/2
✔ web Pulled
✔ worker Pulled
[+] Running 2/2
✔ Container <PROJECT>-web-1 <ACTION>
✔ Container <PROJECT>-worker-1 <ACTION><PROJECT> 和 <ACTION> 会随项目及容器原状态变化。看到服务为 Pulled 仅表示下载完成;后续容器成功 Started 或 Recreated,才表示运行实例已切换。
风险与边界
当标签是 latest、stable 等可变标签时,强制拉取可能得到未经验证的新镜像,导致兼容性或回滚困难。生产环境应优先使用不可变版本标签或镜像摘要,并在发布前记录当前摘要。
使用 --ignore-pull-failures 时,部分服务拉取失败仍会继续,可能形成新旧镜像混跑。除非明确接受部分更新,否则不要在生产发布链路中使用;更安全的做法是让命令失败并先处理认证、标签或网络问题。
docker compose pull 不会构建仅含 build: 且没有可拉取镜像的服务。此类服务应使用 docker compose build;混合项目可用 --ignore-buildable 跳过可构建服务,减少无意义警告。:contentReference[oaicite:4]{index=4}
排障清单
- 提示认证失败:先确认仓库地址与账号权限,再执行对应仓库的
docker login。 - 提示
manifest unknown:检查镜像名、标签及目标 CPU 架构是否存在。 - 提示服务不存在:用
docker compose config --services核对解析后的服务名。 - 拉取成功但版本未变:执行
docker compose up -d <SERVICE>,再用docker compose images或应用版本接口核对镜像摘要。 - 依赖镜像未更新:显式列出依赖服务,或使用
--include-deps。
速查:先拉取、再重建容器、最后验证镜像摘要或应用版本,三步缺一不可。
在启动项目前先构建或重新构建服务镜像。
构建后启动
在修改 Dockerfile、依赖清单或构建上下文后,用 docker compose up --build 先构建镜像,再创建或更新并启动服务。它适合本地开发、测试环境和单机部署;需要后台运行并等待服务就绪时,可组合 -d --wait。
命令定位
up 负责创建、重建并启动容器,--build 要求启动前处理带有 build: 配置的服务。已有容器在配置或镜像发生变化时会被替换,命名卷和绑定挂载继续复用;只声明 image:、没有 build: 的服务不会被本地构建。
基本形式是 docker compose up --build [选项] [服务...]。未写服务名时处理整个项目;写入 api 等服务名时只以该服务为目标,并默认带起它依赖的服务。
主示例
在包含 compose.yaml 的目录执行:
# 构建有 build 配置的服务,后台启动,并等待 running/healthy
docker compose up --build -d --wait
# 确认容器状态与端口映射
docker compose ps预期输出
[+] Building <TIME> (10/10) FINISHED
[+] Running 2/2
✔ Network demo_default Created
✔ Container demo-web-1 Started
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
demo-web-1 demo-web "<COMMAND>" web <TIME> ago Up <TIME> (healthy) 0.0.0.0:<PORT>->8080/tcp<TIME>、<PORT>、容器名和构建步骤会随项目变化。先看 Building ... FINISHED 是否成功,再看 STATUS;存在健康检查时应为 healthy,否则通常只显示 Up。
常用参数
| 参数 | 什么时候用 | 关键边界 |
|---|---|---|
--build |
启动前构建本地镜像 | 会使用构建缓存,不等于全量无缓存重建 |
-d |
让服务在后台持续运行 | 命令返回不代表应用已可接流量 |
--wait |
脚本或部署需要等待运行或健康 | 建议为关键服务配置 healthcheck |
--pull always |
构建或启动前希望检查远端镜像 | 会增加网络请求和启动时间 |
--force-recreate |
配置未变但必须替换容器 | 会造成服务中断,不适合无维护窗口强制执行 |
--remove-orphans |
清理同项目中已从 Compose 文件删除的服务 | 先确认项目名称,避免误删仍需保留的旧服务 |
高频组合可按目标增减参数:日常开发使用 --build -d;自动化验证增加 --wait;仅更新某个服务时在末尾指定服务名;需要刷新基础镜像时增加 --pull always。
风险与排障
--build 仍可能命中缓存。触发条件是 Dockerfile 指令和相关输入未变化,后果是依赖或基础镜像没有刷新;安全替代方案是先执行无缓存构建,再启动:docker compose build --pull --no-cache,确认成功后再运行 docker compose up -d --wait。
在运行中的环境使用 --force-recreate 会停止并替换容器,可能出现短暂不可用。应先确认维护窗口、健康检查和数据挂载;要求滚动升级时不要依赖单机 Compose,改用支持滚动发布的编排平台。
构建内容不符合预期时,依次检查 build.context、Dockerfile 路径、.dockerignore 和缓存命中;启动失败时查看端口占用、依赖服务状态及 docker compose logs。若当前 Compose 不识别 --wait,先用 docker compose version 确认版本,移除该参数后通过 docker compose ps 和应用探针验证就绪。
自定义项目名称以隔离容器、网络和数据卷命名空间。
设置项目名称
当同一主机需要并行运行开发、测试、分支或租户环境时,用 Compose 项目名称隔离默认生成的容器、网络和卷命名空间。最直接的方式是在每条命令的子命令前加 -p <项目名>,并在后续 ps、logs、down 等操作中保持同一个名称。
命令定位
全局参数 -p, --project-name 必须写在 compose 与子命令之间,例如 docker compose -p billing-dev up -d。项目名只允许小写字母、数字、短横线和下划线,并且必须以小写字母或数字开头。
Compose 解析项目名的优先级从高到低为:命令行 -p、环境变量 COMPOSE_PROJECT_NAME、Compose 文件顶层 name:、项目目录名、当前目录名。命令行显式值会覆盖其他来源。
主示例
在同一份 compose.yaml 上启动名为 billing-dev 的独立项目,并用相同名称查询:
# -p 是 Compose 全局参数,必须放在 up、ps、down 等子命令之前
docker compose -p billing-dev up -d
docker compose -p billing-dev ps
docker compose ls -a预期输出
[+] Running 2/2
✔ Network billing-dev_default Created
✔ Container billing-dev-web-1 Started
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
billing-dev-web-1 billing-web "<COMMAND>" web <TIME> ago Up <TIME> 0.0.0.0:<PORT>->8080/tcp
NAME STATUS CONFIG FILES
billing-dev running(1) <PATH>/compose.yaml看到资源名前缀 billing-dev,说明命令正在操作目标项目。<TIME>、<PORT> 和名称分隔符可能因版本、兼容模式及配置而不同,判断项目归属时应以 Compose 项目标签和 docker compose ls 为准。
设置方式
| 方式 | 适用场景 | 注意点 |
|---|---|---|
-p billing-dev |
临时运行、脚本显式传参、并行任务 | 优先级最高;每条生命周期命令都要保持一致 |
COMPOSE_PROJECT_NAME=billing-dev |
CI 或统一环境变量管理 | 避免多个作业复用同一个固定值 |
顶层 name: billing-dev |
项目仓库希望提供稳定默认名 | 仍可被环境变量和 -p 覆盖 |
| 目录名推导 | 单项目本地开发 | 复制目录或改名后,项目名可能随之变化 |
需要在仓库内固定默认名称时,可加入以下配置片段:
name: billing-dev
services:
web:
image: nginx:alpine该配置会让未传 -p、未设置 COMPOSE_PROJECT_NAME 的命令使用 billing-dev。验证方法是执行 docker compose up -d 后查看 docker compose ps 或 docker compose ls 中的项目名称。
风险与边界
修改项目名不会“重命名”已有资源,而是让 Compose 进入另一个命名空间。触发条件是此前用旧名称启动、随后改用新名称,可能造成两套容器并存、端口冲突或旧资源无人清理;安全做法是记录旧名称,并用旧名称执行 docker compose -p <旧名称> down,确认后再启动新项目。
显式 container_name、带 name: 的网络或卷,以及标记为 external: true 的资源不一定随项目名隔离。它们可能在并行项目之间发生名称冲突或共享数据;优先删除不必要的 container_name,让 Compose 自动命名,并为确需共享的外部资源明确约定所有权。
CI 中若多个任务共用固定项目名,会互相重建或删除资源。安全替代方案是使用经过字符清洗的分支名加流水线 ID 生成唯一名称,并确保清理阶段仍使用完全相同的值。发现“容器不见了”时,先检查本次命令的 -p、环境变量、顶层 name: 和工作目录是否与启动时一致,再用 docker compose ls -a 查找旧项目。
使用非默认路径或名称的 Compose 配置文件。
指定配置文件
当 Compose 配置不在当前目录,或文件名不是默认的 compose.yaml、docker-compose.yaml 时,用全局选项 -f 或 --file 明确指定文件。先执行 config 校验实际模型,再执行 up、down、logs 等操作,可避免误用当前目录中的其他配置。
基本语法
下面是命令模板;-f 放在 docker compose 与子命令之间,路径可以是相对路径或绝对路径。
docker compose -f <PATH> <COMMAND> [OPTIONS]
docker compose --file <PATH> <COMMAND> [OPTIONS]未提供 -f 时,Compose 会从当前目录及其父目录查找默认配置文件。-f - 表示从标准输入读取配置;此时配置中的相对路径以当前工作目录为基准。
主示例
以下示例创建一个非默认名称的配置文件,并只解析服务列表,不启动容器,也不拉取镜像。
workdir="$(mktemp -d)"
cat > "$workdir/compose.demo.yaml" <<'YAML'
services:
app:
image: alpine:3.20
command: ["sh", "-c", "echo ready"]
YAML
# 先确认 Compose 确实读取了指定文件
docker compose -f "$workdir/compose.demo.yaml" config --services预期输出:
app输出每行对应一个服务名;出现 app 表示文件路径正确且配置已成功解析。若只需检查是否合法且不打印完整模型,可改用 docker compose -f <PATH> config --quiet,成功时退出码为 0 且通常无输出。
高频用法
校验并查看规范化后的完整配置:docker compose -f ./deploy/compose.prod.yaml config。预期结果是输出变量替换、短语法展开后的有效 Compose 模型。
后台启动全部服务:docker compose -f ./deploy/compose.prod.yaml up -d。预期结果是按该文件创建或更新项目资源;容器名称和进度日志会随项目名及 Compose 版本变化。
只启动一个服务:docker compose -f ./deploy/compose.prod.yaml up -d api。预期结果是启动 api 及其必要依赖,不会自动启动无关服务。
脚本中重复使用同一文件时,可设置 COMPOSE_FILE=./deploy/compose.prod.yaml 后执行 docker compose config。命令行显式传入的 -f 优先于该环境变量。
风险与边界
配置路径写错或文件不可读时,命令会在创建容器前失败。安全做法是先运行 test -r <PATH>,再执行 docker compose -f <PATH> config --quiet。
配置中的 build、env_file、绑定挂载等相对路径会受项目目录影响。默认项目目录取首个指定 Compose 文件所在位置;需要固定基准时使用 --project-directory <DIR>,不要靠切换终端目录碰运气。
同一套配置若使用不同的项目名或项目目录执行,可能生成两组网络、容器和卷,看起来像“旧容器未更新”。生产脚本应固定 -p <PROJECT>,并让 up、ps、logs、down 使用完全相同的 -f 与 -p 参数。
排障清单
- 运行
docker compose version,确认调用的是 Compose CLI。 - 运行
docker compose -f <PATH> config --quiet,先排除 YAML、变量和模型一致性错误。 - 运行
docker compose -f <PATH> config --services,确认目标服务确实存在。 - 文件能解析但资源不对时,检查
-p、--project-directory和实际传入的文件路径。 - 从标准输入读取时,重点检查相对路径;它们以当前工作目录为基准。
本文以 docker compose 的 Compose CLI 用法为准;旧式 docker-compose 独立程序可能接受相似参数,但不应作为新脚本的兼容目标。
组合基础配置与开发、测试或生产环境覆盖配置。
合并多个配置文件
当基础配置需要叠加开发、测试或生产差异时,连续传入多个 -f。Compose 按命令行顺序构建最终模型:前面的文件提供基线,后面的文件新增字段、合并集合或覆盖冲突值,因此顺序本身就是配置的一部分。
基本语法
下面是命令模板。基础文件通常放在最前,环境覆盖文件放在后面。
docker compose -f <BASE_FILE> -f <OVERRIDE_FILE> <COMMAND> [OPTIONS]也可以继续追加更多 -f。显式使用 -f 后,只会合并列出的文件;不要假设目录中的 compose.override.yaml 仍会自动参与。
主示例
以下示例让生产覆盖文件替换 app 镜像,并新增 worker 服务。config --images 只打印最终模型引用的镜像,便于验证覆盖结果。
workdir="$(mktemp -d)"
cat > "$workdir/compose.yaml" <<'YAML'
services:
app:
image: alpine:3.19
YAML
cat > "$workdir/compose.prod.yaml" <<'YAML'
services:
app:
image: alpine:3.20
worker:
image: busybox:1.36
YAML
# 后一个文件覆盖 app.image,并保留新增的 worker
docker compose \
-f "$workdir/compose.yaml" \
-f "$workdir/compose.prod.yaml" \
config --images | sort预期输出:
alpine:3.20
busybox:1.36alpine:3.19 未出现,说明后置文件已覆盖同名字段;busybox:1.36 出现,说明新服务已并入最终模型。该命令只解析配置,不启动容器。
合并规则速查
- 映射对象按键合并;同名键通常以后置文件的值为准,例如
image、环境变量名和标签名。 command、entrypoint与healthcheck.test使用后置值替换,不会把两条命令拼接起来。- 普通序列通常追加,但
ports、volumes、secrets、configs按各自唯一键处理;相同容器挂载目标或相同端口定义可能被合并或替换。 - 需要删除基础文件中的值时,不能只写空的近似配置并期待自动消失;应使用受支持的
!reset,需要完全替换集合时再考虑!override,并先用config验证结果。
高频用法
开发环境:docker compose -f compose.yaml -f compose.dev.yaml up -d。预期结果是基础服务叠加源码挂载、调试端口或开发变量。
生产环境:docker compose -f compose.yaml -f compose.prod.yaml up -d。预期结果是采用生产镜像、资源限制和生产变量,不包含未列出的开发覆盖文件。
发布前审查:docker compose -f compose.yaml -f compose.prod.yaml config。预期结果是输出真正将要应用的合并模型;应把这一步放在 up 之前。
停止或查看同一项目时,必须重复相同文件顺序,例如 docker compose -f compose.yaml -f compose.prod.yaml down。顺序或文件集合改变后,解析出的项目模型也会改变。
风险与边界
把覆盖文件写在基础文件前面会反转优先级,可能让旧镜像、错误端口或调试变量进入生产。安全做法是固定“基础 → 环境 → 本机临时覆盖”的顺序,并在脚本中集中定义参数。
所有文件中的相对路径都以第一个 -f 文件为基准,而不是各自所在目录。覆盖文件分散在其他目录时,build、env_file 或绑定挂载可能指向错误位置;可使用 --project-directory <DIR> 固定基准,或在需要独立路径语义时改用 Compose 的 include 机制。
列表合并可能保留基础值并追加新值,导致端口重复、挂载来源不符合预期或同时暴露多个入口。不要直接部署猜测结果;先检查 docker compose ... config 的 ports、volumes、environment 和 command。
排障清单
- 执行
docker compose -f <BASE> -f <OVERRIDE> config --quiet,排除语法和模型错误。 - 执行同一命令但去掉
--quiet,核对最终image、command、端口、挂载和环境变量。 - 结果与预期相反时,首先检查
-f顺序;越靠后的文件优先级越高。 - 相对路径失效时,检查第一个配置文件的位置和
--project-directory。 up后找不到容器时,确认ps、logs、down使用了相同的-f顺序与-p项目名。
合并完成后以 docker compose ... config 输出为准,不要仅凭某个覆盖文件的局部内容判断最终部署。
通过变量插值复用端口、镜像版本和连接参数。
使用环境变量
当端口、镜像标签或连接地址随环境变化时,在 compose.yaml 中使用 ${...} 插值,并通过 environment 明确写入容器。先展开最终配置再启动,可提前发现变量缺失、空值替换和镜像标签拼接错误。
命令定位
Compose 在解析配置时对 YAML 的值执行插值;宿主机存在同名变量,并不代表该变量会自动进入容器。容器需要读取的值应在 environment 中声明,或由服务级 env_file 提供。用于插值时,宿主机 shell 的值优先于 --env-file,未指定 --env-file 时再读取项目目录的 .env。:contentReference[oaicite:0]{index=0}
基本语法
| 写法 | 行为 |
|---|---|
${VAR} |
直接替换;未定义时警告并替换为空字符串 |
${VAR:-default} |
未定义或为空时使用默认值 |
${VAR-default} |
仅未定义时使用默认值,空字符串仍保留 |
${VAR:?message} |
未定义或为空时立即报错并停止解析 |
$$VAR |
输出字面量 $VAR,把展开留给容器内 shell |
插值支持 $VAR 和 ${VAR},但推荐带花括号,避免变量名与后续字符连在一起。Compose 只插值 YAML 值,不插值映射键;需要动态标签键时应改用 KEY=VALUE 列表形式。:contentReference[oaicite:1]{index=1}
高频用法
下面的示例复用镜像标签和应用参数,并把数据库地址设为必填。命令只解析配置,不会创建容器;需要本机已安装 Docker Compose V2。
cat > compose.yaml <<'YAML'
services:
app:
image: alpine:${ALPINE_TAG:-3.20}
environment:
APP_PORT: "${APP_PORT:-8080}"
DB_HOST: "${DB_HOST:?DB_HOST is required}"
YAML
DB_HOST=db.internal APP_PORT=9090 docker compose config --environment \
| grep -E '^(APP_PORT|DB_HOST)=' | sort
DB_HOST=db.internal APP_PORT=9090 docker compose config --images预期输出:
APP_PORT=9090
DB_HOST=db.internal
alpine:3.20前两行是本次参与插值的输入值,最后一行证明 ALPINE_TAG 未设置时使用了默认标签。若删除 DB_HOST=db.internal,配置解析会失败,而不是带着空连接地址继续启动。
风险与边界
未设置的 ${VAR} 会被替换为空字符串,可能形成 image: repo:、空端口或空连接参数。关键变量使用 ${VAR:?说明},可选变量使用明确默认值,并在部署前检查展开后的配置。
密码、令牌和私钥写入环境变量后,可能被进程环境、调试日志或配置输出暴露。触发条件是把敏感值放进 .env、environment 或命令行;后果是凭据进入日志、历史记录或错误报告。安全替代方案是使用 Compose secrets,只向需要的服务挂载 /run/secrets/<name>。:contentReference[oaicite:2]{index=2}
需要让容器内 shell 展开变量时必须写 $$VAR。若误写 $VAR,Compose 会在宿主机提前替换,容器可能收到空值或错误值。Compose CLI 的 .env 插值能力也不适用于 docker stack deploy。:contentReference[oaicite:3]{index=3}
排障清单
先检查变量来源,再检查展开结果,最后检查容器环境。重点确认当前 shell 是否残留同名变量、.env 是否位于实际项目目录、必填表达式是否报错,以及 environment 是否真正声明了容器需要的变量。速查原则:插值决定 Compose 配置,environment 才决定容器环境。
从指定环境文件读取 Compose 插值变量或容器环境变量。
加载环境变量文件
需要按开发、测试或生产环境切换整组变量时,先区分两种入口:CLI 的 --env-file 给 Compose 插值使用,服务级 env_file 把变量写入容器。两者用途、路径基准和覆盖顺序不同,混用是最常见的配置失效原因。
命令定位
docker compose --env-file <文件> 用于解析 ${VAR}、镜像标签、端口和 Compose 预定义变量;未指定时,Compose 默认读取项目目录的 .env。服务配置中的 env_file: 则把文件内容传给容器,不会自动成为镜像标签等插值变量。:contentReference[oaicite:4]{index=4}
| 入口 | 主要作用 | 相对路径基准 |
|---|---|---|
--env-file ./config/dev.env |
Compose 配置插值 | 执行命令时的当前工作目录 |
服务级 env_file: ./config/app.env |
注入容器环境变量 | compose.yaml 所在目录 |
高频用法
下面同时使用两个文件:compose.dev.env 决定镜像标签和端口,app.env 提供应用运行参数。$$APP_PORT 等写法用于阻止 Compose 提前展开,让容器内 shell 读取最终环境。
mkdir -p config
cat > config/compose.dev.env <<'ENV'
IMAGE_TAG=3.20
APP_PORT=9090
ENV
cat > config/app.env <<'ENV'
LOG_LEVEL=info
API_BASE=https://api.internal
ENV
cat > compose.yaml <<'YAML'
services:
app:
image: alpine:${IMAGE_TAG:?IMAGE_TAG is required}
env_file:
- ./config/app.env
environment:
APP_PORT: "${APP_PORT:?APP_PORT is required}"
command:
- sh
- -c
- |
printf 'APP_PORT=%s\nLOG_LEVEL=%s\nAPI_BASE=%s\n' \
"$$APP_PORT" "$$LOG_LEVEL" "$$API_BASE"
YAML
docker compose --env-file ./config/compose.dev.env \
run --rm --no-deps app预期输出如下;首次运行可能先出现镜像拉取或网络创建日志,程序标准输出保持不变。
APP_PORT=9090
LOG_LEVEL=info
API_BASE=https://api.internalAPP_PORT 来自 CLI 插值文件,并通过 environment 注入容器;另外两个变量直接来自服务级 env_file。这能验证两个文件承担的是不同阶段的职责。
覆盖顺序
多个 CLI --env-file 按命令行顺序读取,后面的文件覆盖前面的同名变量。多个服务级 env_file 也从上到下处理,后面的同名值生效;服务里的 environment 优先级更高,即使其值为空,也会覆盖 env_file。:contentReference[oaicite:5]{index=5}
可选的本地覆盖文件可使用映射写法。以下是片段示例,需放在目标服务下;执行 docker compose config 可验证文件解析结果。
env_file:
- path: ./config/app.env
required: true
- path: ./config/local.override.env
required: falserequired: false 表示文件缺失时静默跳过,适合不提交仓库的个人覆盖文件;基础配置仍应保持 required: true,避免生产环境因文件遗漏而悄悄使用错误默认值。:contentReference[oaicite:6]{index=6}
风险与边界
CLI --env-file 路径相对当前工作目录,服务级 env_file 路径相对 Compose 文件目录。触发条件是在 CI、脚本或其他目录执行同一命令;可能后果是读取错文件或直接报找不到文件。安全替代方案是固定工作目录,或在脚本中显式传入经校验的路径。
环境文件不是秘密存储。把密码或令牌提交到仓库、复制进镜像构建上下文,或在诊断命令中输出完整配置,都可能泄露凭据。敏感值应改用 Compose secrets,环境文件只保存非敏感配置或秘密文件路径。:contentReference[oaicite:7]{index=7}
排障与兼容性
变量未生效时,先确认它应参与“Compose 插值”还是进入“容器环境”,再核对文件路径和覆盖顺序。required 属性要求 Docker Compose 2.24.0 及以上;env_file.format: raw 要求 2.30.0 及以上,旧版本应使用普通 KEY=VALUE 文件。:contentReference[oaicite:8]{index=8}
速查原则:改镜像、端口和 ${VAR} 用 .env 或 --env-file;给应用进程传变量用服务级 env_file,需要最终覆盖时再使用 environment。
使用 profiles 按场景选择性启用调试、监控或辅助服务。
启用服务配置组
使用 profiles 把调试、监控或一次性工具保留在同一份 compose.yaml 中,并只在指定场景启用。未配置 profiles 的核心服务始终进入应用模型;配置了 profile 的服务,只有 profile 被激活或服务被显式点名时才会运行。
基本配置
下面把 app 设为常驻服务,把调试容器和监控容器分别放入 debug、monitoring 配置组。profile 名称区分大小写,建议统一使用小写短名称。
services:
app:
image: nginx:alpine
debugger:
image: alpine:3.21
command: ["sh", "-c", "while true; do sleep 3600; done"]
profiles: ["debug"]
metrics:
image: prom/prometheus:latest
profiles: ["monitoring"]不带 profile 执行 docker compose up -d 时只启动 app。顶层的网络、卷、配置和密钥不会因为 profile 未启用而自动消失,但只有实际启用的服务会使用它们。
启用与验证
--profile 是 docker compose 的全局选项,应放在子命令之前。下面启用调试组,并检查当前运行的服务。
docker compose --profile debug up -d
docker compose --profile debug ps --services --status running预期输出如下;首次执行可能先出现镜像拉取信息,<PROJECT> 和启动耗时会因目录名与环境不同而变化。
[+] Running 2/2
✔ Container <PROJECT>-app-1 Started
✔ Container <PROJECT>-debugger-1 Started
app
debugger同时启用多个组时可重复传入选项,或通过环境变量传入逗号分隔值。
docker compose --profile debug --profile monitoring up -d
COMPOSE_PROFILES=debug,monitoring docker compose config --services预期结果中应包含三个服务:
app
debugger
metrics高频用法
查看文件中声明的所有 profile,可执行 docker compose config --profiles。临时运行某个带 profile 的工具时,可直接执行 docker compose run --rm debugger;Compose 会自动激活该目标服务及其 depends_on 依赖,但不会顺带启动同一 profile 下的其他兄弟服务。
需要停止之前启用的可选服务时,应带上相同 profile 执行 docker compose --profile debug down,或明确执行 docker compose stop debugger。之后仅运行不带 profile 的 up,不会可靠地替你清理此前已经启动的可选容器。
风险与边界
使用 --profile "*" 会激活所有配置组。触发条件是文件中同时存在调试、监控、管理后台等可选服务;后果可能是额外资源占用、端口冲突或把管理入口暴露到宿主机。生产环境应明确列出允许的 profile,并在启动前执行 docker compose --profile <NAME> config -q 校验。
不要把数据库、消息队列等核心依赖随意放入可选 profile。若常驻服务引用了未激活且不共享 profile 的依赖,Compose 可能报告模型无效。安全做法是让核心服务不配置 profiles,或确保依赖双方在相同场景下同时可用。
排障清单
profile 未生效时,先用 docker compose config --profiles 核对名称,再确认命令写成 docker compose --profile debug up。服务被显式点名却缺少依赖时,检查依赖是否被另一个未启用的 profile 隔离。切换场景后仍看到旧容器时,使用 docker compose ps -a 查明状态,并按原 profile 执行停止或清理。
兼容性
优先使用现代 docker compose 插件。旧版 docker-compose 若无法识别 profiles 或相关全局选项,应先用 docker compose version 确认版本并升级,而不是删除 profile 约束后直接启动全部辅助服务。
定义服务之间的启动顺序和依赖关系。
配置启动依赖
使用 depends_on 控制服务的创建、启动和移除顺序,并通过条件区分“容器已启动”“健康检查已通过”和“一次性任务已成功完成”。它能消除常见的启动竞态,但不能替代应用自身的重试、熔断和运行期故障恢复。
条件选择
短写法 depends_on: [db] 只保证依赖容器先启动,不等待数据库真正可接受请求。需要等待就绪状态时使用长写法:
service_started:依赖容器已启动,等价于短写法。service_healthy:依赖服务的healthcheck已通过。service_completed_successfully:一次性依赖以退出码0完成。restart: true:通过 Compose 显式更新或重启依赖时,同时重启当前服务。required: false:依赖不可用时只告警,适合确实允许降级的可选组件。
完整示例
下面的顺序是:数据库健康后执行建表任务;建表任务成功退出后再启动应用。健康检查中的 $$ 用于把变量留给容器内 Shell 展开,避免被 Compose 提前插值。
services:
db:
image: postgres:18-alpine
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: compose-example-only
POSTGRES_DB: appdb
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 5s
timeout: 3s
retries: 10
migrate:
image: postgres:18-alpine
environment:
PGPASSWORD: compose-example-only
command: ["sh", "-c", "psql -h db -U app -d appdb -c 'CREATE TABLE IF NOT EXISTS startup_probe(id integer);'"]
depends_on:
db:
condition: service_healthy
app:
image: alpine:3.21
command: ["sh", "-c", "echo 'app started'; sleep 3600"]
depends_on:
db:
condition: service_healthy
restart: true
migrate:
condition: service_completed_successfully
启动后用自定义格式同时查看运行中和已退出的一次性服务。
docker compose up -d
docker compose ps -a --format 'table {{.Service}}\t{{.State}}\t{{.Health}}\t{{.ExitCode}}'预期输出如下;列宽与顺序可能因 Compose 版本略有差异,关键结果是 db 为 healthy、migrate 退出码为 0、app 为 running。
SERVICE STATE HEALTH EXIT CODE
app running 0
db running healthy 0
migrate exited 0启动与关闭行为
Compose 按依赖顺序创建服务,因此 db 先于 migrate,migrate 成功后才创建并启动 app。执行 docker compose down 时顺序反向,应用先移除,数据库最后移除。restart: true 只响应 Compose 控制的显式操作,不包含容器运行时因崩溃和重启策略触发的自动重启。
风险与边界
只写短格式时,触发条件是依赖程序启动慢于容器进程;后果通常是应用首次连接收到 connection refused。安全替代方案是为依赖编写真实就绪检查,并使用 service_healthy,同时保留应用侧指数退避重试。
健康检查若只判断进程存在,可能过早返回成功,使依赖链形同虚设。检查命令应验证实际能力,例如数据库可登录、HTTP 就绪端点返回成功或队列能接受请求。循环依赖会让模型无法形成有效顺序,应拆分初始化任务或取消双向启动约束。
depends_on 不持续监控运行期依赖。数据库在应用启动后宕机时,Compose 不会自动停止应用;应由应用处理断线重连,并配合健康检查、重启策略和外部监控。
排障清单
应用一直未启动时,先执行 docker compose ps -a;若 db 为 unhealthy,查看 docker compose logs db 和健康检查命令。若 migrate 为非零退出,执行 docker compose logs migrate 修复脚本后重新 up。应用已启动却仍连接失败时,检查健康检查是否验证了真正的业务就绪状态,而不是仅验证端口或进程存在。
兼容性
depends_on.restart 需要 Docker Compose 2.17.0 或更高版本,required 需要 2.20.0 或更高版本。交付到不同环境前先执行 docker compose version 与 docker compose config -q;旧环境不支持长写法字段时应升级 Compose,而不是退回只保证进程启动的短格式。
为服务定义健康探测命令、周期、超时和重试次数。
配置健康检查
在服务启动慢、依赖需要等待就绪或容器偶发假活时,用 healthcheck 定义容器内探测。探测命令退出码为 0 表示健康,非零表示失败;连续失败达到阈值后,状态变为 unhealthy。
基本语法
下面为 Redis 定义轻量探测,并给出启动宽限期,避免初始化阶段被过早判定失败。
services:
cache:
image: redis:7-alpine
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 5
start_period: 10stest 的首项常用 CMD 或 CMD-SHELL。CMD 不经过 shell,参数边界明确;需要管道、重定向、变量展开或 || 时才用 CMD-SHELL。interval 是常规探测间隔,timeout 是单次最长执行时间,retries 是判为不健康前允许的连续失败次数,start_period 内的失败不计入重试阈值。
验证状态
先校验配置并启动服务,再读取 Docker 保存的健康状态。
set -e
docker compose config -q
# --wait 在服务未健康时返回非零,便于脚本阻断后续步骤
docker compose up --wait --wait-timeout 60 >/dev/null 2>&1
docker inspect --format '{{.State.Health.Status}}' "$(docker compose ps -q cache)"预期输出
healthy--wait 会等待服务进入运行或健康状态;若超过 60 秒,命令以非零状态退出。未使用 --wait 时,刚启动可能先得到 starting,至少一个成功探测周期后才会变为 healthy。查看最近探测记录可读取 docker inspect 输出中的 State.Health.Log,重点关注 ExitCode、Output、Start 和 End。
高频用法
依赖服务必须真正可用后才能启动时,在依赖方使用 depends_on 的 condition: service_healthy。镜像已经声明 Dockerfile HEALTHCHECK 时,Compose 中的配置会覆盖镜像值;需要关闭镜像探测可设置 healthcheck: { disable: true }。
探测应检查本服务的关键就绪条件,例如数据库接受连接、HTTP 就绪端点返回成功或队列能够响应。不要只检查进程是否存在,也不要在探测中写数据、执行迁移或调用昂贵的外部链路。
风险与边界
当 interval 太短、探测命令过重或 timeout 小于正常响应时间时,会增加 CPU、连接数和日志压力,并造成误判。安全做法是先测量正常与高负载延迟,再设置宽限期和连续失败阈值。
普通 Docker Compose 只会标记容器为 unhealthy,不会仅因健康失败自动重启。需要恢复动作时,应由应用自愈、外部监控或编排平台处理;不要把健康探测误当成重启策略。
排障清单
- 容器一直为
starting:确认探测命令存在、能在容器内运行,且start_period与真实初始化时间匹配。 - 很快变为
unhealthy:进入容器手工执行test对应命令,并检查退出码与标准错误。 - 本机执行成功但探测失败:健康命令运行在容器网络和文件系统内,地址通常应使用
127.0.0.1或容器内端口。 - 依赖方仍提前启动:确认使用长格式
depends_on,并设置condition: service_healthy,而不是默认的service_started。
将容器端口发布到主机并控制监听地址。
映射主机端口
需要让主机或外部客户端访问容器服务时,用 ports 把主机监听地址和端口发布到容器端口。生产环境应明确 host_ip,避免省略监听地址后意外暴露到所有网卡。
基本语法
短格式为 [主机地址:]主机端口:容器端口[/协议]。下面使用长格式把主机回环地址的 8080/tcp 映射到 Nginx 容器的 80/tcp,只有本机能够直接访问。
services:
web:
image: nginx:1.27-alpine
ports:
- target: 80
published: "8080"
host_ip: 127.0.0.1
protocol: tcptarget 是容器内监听端口,published 是主机端口,host_ip 控制绑定地址,protocol 常用 tcp 或 udp。端口值建议写成字符串,避免 YAML 解析差异。等价短格式为 "127.0.0.1:8080:80/tcp"。
验证映射
启动后同时检查 Compose 记录的映射和实际 HTTP 响应。
set -e
docker compose up -d >/dev/null 2>&1
docker compose port web 80
# 重试连接,避免容器已运行但 Nginx 尚未开始监听
curl --retry 10 --retry-connrefused --retry-delay 1 -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/预期输出
127.0.0.1:8080
200容器名、启动日志和耗时会随项目变化,但映射地址应为 127.0.0.1:8080,HTTP 状态码应为 200。若主机端口交给 Docker 自动分配,可省略 published,再用 docker compose port web 80 查询实际端口。
常用写法
- 仅本机访问:
"127.0.0.1:8080:80",适合数据库、调试端口和本地管理页。 - 对所有网卡开放:
"8080:80",适合确需被局域网或公网入口访问的服务,但必须同时配置主机防火墙和上游访问控制。 - 发布 UDP:
"127.0.0.1:5353:53/udp",协议必须与容器内服务一致。 - 只供 Compose 网络内服务访问:不配置
ports;其他服务直接使用服务名和容器端口,例如http://web:80。expose也不会把端口发布到主机。
风险与边界
省略 host_ip 时,Docker 通常会在主机所有可用地址上发布端口,可能使管理接口、数据库或调试服务被局域网甚至公网访问。安全替代方案是默认绑定 127.0.0.1,再通过反向代理、VPN、SSH 隧道或受控负载均衡器对外提供入口。
主机端口只能被一个监听者占用。已有容器或进程占用 8080 时,启动会失败并出现 port is already allocated 或 address already in use。不要直接停止未知进程;先确认归属,再改用空闲端口或按变更流程释放占用。
排障清单
先查是否已有 Docker 容器发布该端口;Linux 主机再查普通进程监听。动态值用占位符表示,实际名称、ID 和进程号会不同。
docker ps --filter publish=8080 --format '{{.ID}}\t{{.Names}}\t{{.Ports}}'
ss -ltnp | grep ':8080 '预期结果示例
<ID> <CONTAINER_NAME> 127.0.0.1:8080->80/tcp
LISTEN 0 4096 127.0.0.1:8080 0.0.0.0:* users:(("<PROCESS>",pid=<PID>,fd=<FD>))命令可能只返回其中一行,也可能无输出。映射存在但访问失败时,确认应用确实监听容器内的 target 端口;远程访问失败但本机正常时,检查 host_ip、主机防火墙、云安全组和路由,不要把容器端口误当成主机端口。
在 Linux 上可使用 ss;macOS 可改用 lsof -nP -iTCP:8080 -sTCP:LISTEN。Docker Desktop、Rootless Docker 或替代运行时的实际绑定行为可能受虚拟机网络和运行时能力影响,排障时以 docker compose port、主机监听结果和实际连通性为准。
创建自定义网络并控制服务间的网络连通关系。
配置服务网络
在需要隔离前端、应用和数据库,或让某个服务同时跨越多个网络时,在顶层声明自定义网络,再在各服务的 networks 中明确加入关系。只有共享至少一个网络的服务,才能通过服务名或网络别名直接解析并通信。
基本语法
下面把 proxy 与 api 放入前端网络,把 api 与 db 放入后端网络;proxy 不加入后端网络,因此不能直接解析 db。internal: true 让后端网络不提供默认外部连通,但 api 仍可通过它加入的其他网络访问外部资源。

services:
proxy:
image: busybox:1.36
command: ["sh", "-c", "sleep 1d"]
networks:
- front
api:
image: busybox:1.36
command: ["sh", "-c", "sleep 1d"]
networks:
- front
- back
db:
image: busybox:1.36
command: ["sh", "-c", "sleep 1d"]
networks:
- back
networks:
front:
driver: bridge
back:
driver: bridge
internal: true该配置创建两个项目级网络。网络实际名称通常带 Compose 项目前缀;需要固定名称时才设置 name,需要复用平台已存在的网络时使用 external: true。
连通性验证
在包含上述 compose.yaml 的目录执行。命令先校验配置,再启动容器并验证三条路径,最后清理本次资源。
docker compose config --quiet && echo "config OK"
docker compose up -d >/dev/null 2>&1
docker compose exec -T proxy sh -c 'ping -c 1 api >/dev/null && echo "proxy->api OK"'
docker compose exec -T api sh -c 'ping -c 1 db >/dev/null && echo "api->db OK"'
docker compose exec -T proxy sh -c 'if ping -c 1 -W 1 db >/dev/null 2>&1; then echo "proxy->db UNEXPECTED"; else echo "proxy->db BLOCKED"; fi'
docker compose down >/dev/null 2>&1 && echo "cleanup OK"预期输出
config OK
proxy->api OK
api->db OK
proxy->db BLOCKED
cleanup OK看到前两条 OK 且第三条为 BLOCKED,说明共享网络内可通信,未共享网络之间已隔离。实际容器 IP 和网络名称可能不同,不应把固定 IP 写入应用配置。
常用配置
driver: bridge:单机 Compose 最常见;同一 Docker 主机上的容器通过用户自定义桥接网络通信。internal: true:创建外部隔离网络,适合仅供应用层与数据层内部通信。name:指定不带项目名前缀的固定网络名,适合多个 Compose 项目明确共享同一网络。external: true:只引用已有网络,Compose 不负责创建和删除;该网络不存在时启动会失败。
风险与边界
固定 name 在并行环境中可能发生同名冲突,导致不同项目意外加入同一网络。生产环境应使用环境标识生成唯一名称,或保留 Compose 默认的项目级命名。
启用 internal 不等于完成全部访问控制。服务若同时加入其他网络、使用主机网络或经反向代理暴露,仍可能从其他路径被访问;安全替代方案是最小化网络加入关系,并同时控制端口发布、主机防火墙和应用鉴权。
使用 external: true 时,Compose 不管理网络生命周期。部署前应由基础设施流程创建并校验网络,删除应用时也不要假设该网络会被自动清理。
排障清单
- 配置校验失败:检查服务引用的网络名是否在顶层
networks中声明,YAML 缩进是否正确。 - 服务名无法解析:确认源服务与目标服务至少共享一个网络;仅发布端口不会建立容器间 DNS 关系。
- 启动提示外部网络不存在:核对外部网络名称与当前 Docker 环境,避免把开发机名称直接用于生产。
- 连通但请求失败:继续检查目标进程监听地址与端口;网络可达不代表应用已监听或健康。
为同一服务配置网络内可解析的附加主机名。
配置服务别名
当调用方需要使用兼容旧系统的主机名、稳定的业务名称,或同一服务在不同网络中使用不同名称时,在服务级 networks 长语法下配置 aliases。别名只在对应网络内生效,不会写入宿主机 DNS。
基本语法
下面为 api 在 app_net 网络中增加 backend 和 users-api 两个可解析名称。网络内其他容器既可以使用服务名 api,也可以使用任一别名访问同一个服务容器。
services:
api:
image: busybox:1.36
command: ["sh", "-c", "sleep 1d"]
networks:
app_net:
aliases:
- backend
- users-api
client:
image: busybox:1.36
command: ["sh", "-c", "sleep 1d"]
networks:
- app_net
networks:
app_net: {}aliases 必须写在具体服务加入某个网络的配置下,而不是顶层网络定义中。一个服务加入多个网络时,可以在每个网络分别配置不同别名。
验证解析
在包含上述 compose.yaml 的目录执行。验证命令分别使用服务名和两个别名进行 DNS 解析与连通测试,并在结束后清理资源。
docker compose config --quiet && echo "config OK"
docker compose up -d >/dev/null 2>&1
docker compose exec -T client sh -c 'for h in api backend users-api; do ping -c 1 "$h" >/dev/null && echo "$h OK"; done'
docker compose down >/dev/null 2>&1 && echo "cleanup OK"预期输出
config OK
api OK
backend OK
users-api OK
cleanup OK三种名称均返回 OK,说明它们在 app_net 内解析到 api 服务。实际 IP 可能随容器重建而变化,调用方应始终使用服务名或别名,不依赖解析出的固定地址。
高频用法
- 兼容迁移:旧应用继续访问
legacy-db,新服务实际名称保持为database。 - 业务命名:调用方使用
orders-api,避免依赖 Compose 文件中的内部服务名。 - 分网络命名:同一服务在业务网络使用
backend,在监控网络使用metrics-target。 - 蓝绿切换:把稳定别名指向当前版本,但切换前必须避免两个服务同时声明同一别名造成不确定解析。
风险与边界
别名具有网络作用域。调用方未加入同一网络时,即使别名拼写正确也无法解析;安全做法是只让确有通信需要的服务共享网络,而不是把所有服务接入一个大网络。
多个容器或多个服务可以共享同一别名,但名称最终解析到哪个容器不保证固定。不要把重复别名当作可控的主备切换机制;应使用反向代理、服务发现或编排平台提供的负载均衡。
别名只解决主机名解析,不转换端口,也不验证应用健康状态。调用地址仍需使用容器实际监听端口,例如 backend:8080,并配合健康检查和客户端超时重试。
排障清单
- 别名不生效:确认
aliases位于服务的目标网络映射下,且不是短列表语法的同级误缩进。 - 服务名可解析但别名不可解析:重新创建容器以应用网络配置变更,仅重启现有容器可能不足以更新网络端点。
- 名称解析成功但连接拒绝:检查目标进程是否监听
0.0.0.0和正确容器端口。 - 解析结果偶发变化:检查是否有多个服务或副本共享别名;需要确定路由时改用唯一别名或专用代理。
使用 Docker 管理的数据卷持久化数据库和应用数据。
挂载命名卷
命名卷适合保存数据库、队列和应用运行数据。数据由 Docker 管理,不依赖固定主机目录;容器删除或重建后,只要重新挂载同一个卷,数据仍可继续使用。
基本语法
服务内的 volumes 负责挂载,顶层 volumes 负责声明卷。短语法是 卷名:容器路径[:ro];生产配置更建议使用长语法,便于明确类型、读写模式和卷选项。
services:
db:
image: postgres:16-alpine
environment:
POSTGRES_PASSWORD: example-password
volumes:
- type: volume
source: pgdata
target: /var/lib/postgresql/data
volumes:
pgdata:
name: demo-pgdatasource 引用顶层逻辑名称 pgdata,target 必须是容器内绝对路径。name 指定 Docker 中的实际卷名;省略时,Compose 通常按项目名生成类似 <PROJECT>_pgdata 的名称。
高频用法
启动服务,在卷内写入探针文件,重建容器后再次读取,用于确认数据没有落入容器可写层。
docker compose up -d
docker compose exec db sh -c 'echo compose-volume > /var/lib/postgresql/data/probe.txt'
docker compose down
docker compose up -d
docker compose exec db cat /var/lib/postgresql/data/probe.txt
docker volume inspect demo-pgdata --format '{{.Name}} {{.Driver}} {{.Mountpoint}}'预期输出
compose-volume
demo-pgdata local <PATH>第一行证明容器删除并重新创建后文件仍存在;第二行显示实际卷名、驱动和主机存储位置,<PATH> 会随 Docker Engine 和操作系统变化。不要直接修改该目录,应通过容器或备份工具访问数据。
已有卷需要跨 Compose 项目复用时,先创建卷,再声明为外部资源。Compose 不负责创建或删除外部卷,名称不存在时会直接报错。
docker volume create shared-pgdata
docker volume inspect shared-pgdata --format '{{.Name}}'预期输出
shared-pgdata对应配置片段如下,验证方法是运行 docker compose config 后再执行 docker compose up -d。
volumes:
pgdata:
external: true
name: shared-pgdata常用参数
read_only: true:只读挂载,适合备份程序读取数据,不适合数据库主实例。volume.nocopy: true:首次创建空卷时,不把镜像目标目录中的已有内容复制进卷;仅在确认初始化逻辑不依赖这些文件时使用。volume.subpath:只挂载卷内子目录;子目录必须满足运行环境要求,使用前先验证 Compose 版本和目录是否存在。driver、driver_opts:接入本地驱动、NFS 或存储插件;参数由具体驱动决定,错误配置会导致部署失败。
风险与边界
执行 docker compose down -v、docker volume rm 或清理脚本删除卷时,数据库文件会被永久移除。安全替代方案是先做可恢复备份并验证,再只执行不带 -v 的 docker compose down。
修改项目名、顶层卷键或 name 后,Compose 可能挂载一个新的空卷,表现为“数据丢失”。先用 docker volume ls 和 docker volume inspect 核对旧卷,再修正映射,禁止立即初始化或删除疑似旧卷。
不要让两个独立数据库实例同时写同一数据目录。即使卷允许多容器挂载,数据库文件格式也通常不支持并发共享;需要高可用时应使用数据库自身的复制或集群机制。
排障清单
docker compose config:确认最终source、target、name和变量替换结果。docker compose ps -a:确认服务是否因权限、初始化或存储驱动错误退出。docker inspect <CONTAINER>:检查Mounts中Type=volume、目标路径和RW。docker volume inspect <VOLUME>:核对卷是否存在、驱动是否正确、当前是否被容器占用。
速查:持久业务数据优先命名卷;需要人工访问宿主机文件时再考虑绑定挂载。
将本地文件或目录绑定到容器用于开发和配置注入。
挂载主机目录
绑定挂载把主机文件或目录直接映射进容器,适合开发源码同步、配置注入和导出构建产物。主机内容会立即影响容器,因此应明确源路径、读写权限和目标目录。
基本语法
短语法是 主机路径:容器路径[:ro]。相对路径应以 ./ 或 ../ 开头,避免被识别为命名卷;长语法可以显式指定 type: bind,并阻止路径写错时自动创建空目录。
services:
app:
image: alpine:3.20
command: ['sh', '-c', 'cat /etc/demo/app.conf && while :; do sleep 3600; done']
volumes:
- type: bind
source: ./config
target: /etc/demo
read_only: true
bind:
create_host_path: falsesource 是 Docker daemon 所在主机的路径,相对路径按主 Compose 文件所在目录解析;target 必须是容器内绝对路径。配置注入通常设置 read_only: true,避免容器改写主机文件。
高频用法
先准备主机目录和配置文件,再启动服务。示例使用只读挂载,同时检查挂载类型、实际源路径和读写状态。
mkdir -p config
printf 'mode=development\n' > config/app.conf
docker compose up -d
docker compose exec app cat /etc/demo/app.conf
docker inspect "$(docker compose ps -q app)" --format '{{range .Mounts}}{{.Type}} {{.Source}} -> {{.Destination}} rw={{.RW}}{{println}}{{end}}'预期输出
mode=development
bind <PATH>/config -> /etc/demo rw=false<PATH> 是主机上的绝对路径,实际值可能不同;rw=false 证明容器只能读取。修改 config/app.conf 后再次执行 docker compose exec app cat /etc/demo/app.conf,应立即看到新内容,无需重建镜像。
只挂载单个配置文件时,主机文件必须预先存在。使用长语法和 create_host_path: false 可让路径拼写错误尽早失败,而不是意外创建同名目录。
services:
app:
image: alpine:3.20
command: ['sh', '-c', 'cat /etc/demo/app.conf && while :; do sleep 3600; done']
volumes:
- type: bind
source: ./config/app.conf
target: /etc/demo/app.conf
read_only: true
bind:
create_host_path: false验证方法
docker compose config
docker compose up -d
docker compose exec app cat /etc/demo/app.conf预期输出
mode=development常用参数
read_only: true或短语法:ro:阻止容器修改主机内容,配置、证书和只读源码应优先使用。bind.create_host_path: false:源路径不存在时直接失败,适合生产配置和单文件挂载。bind.selinux: z:允许多个容器共享重新标记后的内容;Z表示私有标记,仅用于启用 SELinux 的 Linux 主机。bind.propagation:控制子挂载传播,普通应用保持默认值;只有容器需要观察或创建主机挂载点时才调整。
风险与边界
绑定挂载默认可写时,容器进程能创建、修改或删除主机文件。挂载源码可以使用读写模式,配置和系统文件应改为只读,并避免把 /、/etc、/usr、用户主目录等宽范围路径交给不可信容器。
把主机目录挂到容器内已有内容的目录,会遮蔽镜像原有文件,可能导致程序、依赖或默认配置“消失”。安全替代方案是挂到专用空目录,或先用临时容器检查镜像目录内容,再决定目标路径。
短语法在源路径不存在时可能自动创建目录。若原本想挂载文件,应用会看到目录并报“不是文件”或“是一个目录”;生产环境优先使用长语法并设置 create_host_path: false。
绑定挂载作用于 Docker daemon 主机,不是发起命令的客户端。连接远程 daemon 时,本机 ./config 不会被上传;应把文件部署到远程主机、改用配置管理机制,或构建进镜像。
排障清单
pwd与ls -ld ./config ./config/app.conf:确认当前目录、路径类型和主机权限。docker compose config:检查相对路径解析、变量替换和最终只读设置。docker inspect <CONTAINER>:在Mounts中确认Type=bind、Source、Destination与RW。- 出现
permission denied时,核对容器运行用户的 UID/GID、主机目录权限以及 SELinux/AppArmor 策略。 - Docker Desktop 无法访问路径时,检查文件共享授权和路径是否位于可共享范围。
速查:开发源码可读写绑定;配置、证书和生产只读资产使用长语法加 read_only: true 与 create_host_path: false。
使用 configs 和 secrets 向容器提供配置文件或敏感内容。
注入配置与密钥
当服务需要读取配置文件、密码、令牌或证书,而又不希望把内容写进镜像或普通环境变量时,使用 configs 和 secrets。configs 适合非敏感配置,secrets 适合敏感内容;两者都按文件挂载,并且必须先在顶层声明,再授权给具体服务。
基本语法
下面的示例把应用配置挂载到 /etc/myapp/app.conf,把密码文件挂载到默认路径 /run/secrets/db_password。容器只打印配置和密钥长度,避免把密钥本身写入日志。
workdir="$(mktemp -d)"
cd "$workdir"
cat > app.conf <<'EOF'
log_level=info
EOF
# 演示环境使用固定内容;生产环境应从受控密钥系统或安全文件注入。
printf '%s' 'change-me-123' > db_password.txt
chmod 600 db_password.txt
cat > compose.yaml <<'YAML'
services:
app:
image: alpine:3.20
command:
- sh
- -c
- |
echo "CONFIG:"
cat /etc/myapp/app.conf
echo "SECRET_LENGTH:"
wc -c < /run/secrets/db_password
configs:
- source: app_config
target: /etc/myapp/app.conf
secrets:
- db_password
configs:
app_config:
file: ./app.conf
secrets:
db_password:
file: ./db_password.txt
YAML
docker compose run --rm app
docker compose down >/dev/null 2>&1预期核心输出如下;首次运行还可能出现镜像拉取、网络创建等日志。
CONFIG:
log_level=info
SECRET_LENGTH:
13读取方法:配置文件使用显式 target,应用直接读取该路径;短语法密钥默认位于 /run/secrets/<名称>。wc -c 返回字节数,用于确认密钥已挂载,但不会泄露内容。
常用写法
短语法只写名称,适合接受默认挂载位置;长语法使用 source 和 target,适合应用必须读取固定路径的场景。顶层 file 指向宿主机源文件,路径应与 Compose 文件的路径解析规则保持一致。
services:
app:
configs:
- source: app_config
target: /etc/myapp/app.conf
secrets:
- db_password
configs:
app_config:
file: ./app.conf
secrets:
db_password:
file: ./db_password.txt生效行为:启动服务后,两个文件以只读方式出现在容器内。修改源文件后不要假定应用会自动重载;应按应用能力执行重载或重建,并再次检查容器内文件和应用日志。
风险与边界
使用 file 型密钥时,源文件仍以明文存在于宿主机。触发条件是仓库误提交、目录权限过宽、备份外泄或运维脚本打印文件;后果是凭据直接暴露。安全替代方案是把文件排除出版本控制、限制为最小权限,并在生产环境接入专用密钥管理系统或编排平台原生密钥能力。
不要用 cat、echo 或调试日志输出密钥正文。即使容器随后删除,日志平台、终端历史和流水线记录仍可能长期保存。验证时优先检查文件是否存在、权限、字节数或应用是否认证成功。
挂载文件通常只读。若程序会重写配置,直接写入挂载路径会失败;安全做法是在启动脚本中复制到容器可写目录或命名卷,再让程序操作副本。
排障清单
先运行 docker compose config 检查结构和插值结果,再确认顶层名称与服务引用完全一致。若提示源文件不存在,检查相对路径、当前 Compose 文件组合及文件权限;若容器内没有文件,使用 docker compose exec app ls -l /etc/myapp /run/secrets 核对挂载位置。应用仍报认证失败时,检查密钥是否带有意外换行、编码或旧内容,但不要把正文打印到日志。
限制服务可使用的 CPU、内存和进程数量。
限制服务资源
当单个服务可能抢占宿主机 CPU、内存或创建过多进程时,在服务级设置 cpus、mem_limit、mem_reservation 和 pids_limit。这些限制由容器运行时执行,可防止一个异常服务拖垮同机其他容器,但数值过低也会导致超时、OOM 或进程创建失败。
基本语法
下面启动一个常驻容器,并用 docker inspect 验证最终传给 Docker Engine 的限制值。示例中的 128 MiB、64 MiB 和 0.5 CPU 会分别转换为字节数和 NanoCPU。
workdir="$(mktemp -d)"
cd "$workdir"
cat > compose.yaml <<'YAML'
services:
worker:
image: alpine:3.20
command: ["sh", "-c", "echo limits-ready; exec tail -f /dev/null"]
cpus: 0.50
mem_limit: 128m
mem_reservation: 64m
pids_limit: 64
YAML
docker compose up -d
cid="$(docker compose ps -q worker)"
# 直接读取运行时配置,避免只检查 YAML 而误判限制已经生效。
docker inspect "$cid" --format 'NanoCPUs={{.HostConfig.NanoCpus}} Memory={{.HostConfig.Memory}} MemoryReservation={{.HostConfig.MemoryReservation}} PidsLimit={{.HostConfig.PidsLimit}}'
docker compose down预期关键校验行如下;容器名、网络名和启动进度会因项目目录而不同。
NanoCPUs=500000000 Memory=134217728 MemoryReservation=67108864 PidsLimit=64读取方法:NanoCPUs=500000000 表示最多使用 0.5 个 CPU;Memory 是硬上限;MemoryReservation 是软保留值;PidsLimit=64 限制容器内可用的进程或线程任务数量。
常用参数
| 字段 | 作用 | 典型边界 |
|---|---|---|
cpus |
设置可用 CPU 时间上限,例如 0.50 |
超限时通常被节流,不会直接杀死容器 |
mem_limit |
设置内存硬上限,例如 128m |
超过后可能触发 OOM,进程常以 137 退出 |
mem_reservation |
设置内存软目标 | 宿主机有压力时更有意义,不能替代硬上限 |
pids_limit |
限制进程和线程任务数量 | 过低会导致 fork、线程池或运行时启动失败 |
生产值应以实际峰值和压测结果为依据。常见起点是先记录无约束运行时的峰值,再给稳定峰值预留余量,最后通过压测观察延迟、错误率、OOM 和节流情况。
高频用法
修改限制后执行 docker compose up -d --force-recreate worker,再用 docker inspect 验证,不能只相信配置文件。运行期间可用以下命令读取一次资源快照。
docker stats --no-stream "$(docker compose ps -q worker)"预期输出包含以下列,具体数值随负载变化。
CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS
<ID> <PROJECT>-worker-1 <N>% <USED> / 128MiB <N>% <RX> / <TX> <R> / <W> <N>重点看 MEM USAGE / LIMIT 是否显示 128 MiB、PIDS 是否持续逼近 64,以及 CPU 是否长期接近配额上限。若应用延迟升高但 CPU 接近上限,通常是被节流;若容器反复重启并出现 137,优先排查内存硬限制和应用峰值。
风险与边界
内存硬限制过低时,触发条件是瞬时峰值、缓存增长或并发增加;后果是内核终止进程、请求中断和重启循环。安全替代方案是先做压测并保留合理余量,同时设置健康检查和重启策略,但不要用无限重启掩盖持续 OOM。
pids_limit 过低时,Java、Node.js、数据库或高并发服务可能无法创建线程,即使进程数看起来不多。应把线程池、子进程和运行时后台线程都计入预算,并在压测时观察 PIDS。
Docker Desktop 中限制实际作用于其 Linux 虚拟机内的容器;宿主机总资源仍受 Desktop 配额约束。不同 Compose 版本和编排平台对 deploy.resources 的处理可能不同,本地 docker compose 优先使用上述服务级字段,并以 docker inspect 的运行时结果为准。
排障清单
限制未生效时,先确认使用的是 docker compose 而不是行为不同的旧工具,再执行 docker compose config 检查解析值。若 inspect 中仍为零,强制重建容器并检查 Docker Engine 是否支持相应 cgroup 控制器。若容器退出,查看 docker compose ps -a、docker compose logs worker 和 docker inspect <ID> 的退出码及 OOM 标志,区分应用错误、内存 OOM 与 PID 耗尽。
临时调整无固定容器名服务的运行副本数量。
扩缩服务副本
无状态服务需要临时扩容或恢复单实例时,使用 docker compose up --scale 调整副本数。命令会创建或删除该服务的 Compose 容器,并覆盖 Compose 文件中的 scale 设置。
命令定位
语法中的 SERVICE 和 NUM 是占位符:
docker compose up [OPTIONS] --scale SERVICE=NUM [SERVICE...]在包含 compose.yaml 的目录执行。项目使用自定义配置文件、环境文件或项目名时,必须继续携带原有的 -f、--env-file 和 -p 参数。常用选项包括后台运行的 -d、等待运行或健康状态的 --wait,以及设置停止等待秒数的 -t N。
高频用法
下面假设存在无固定容器名的 web 服务:
docker compose up -d --scale web=3 web
docker compose ps web预期输出中的项目名、镜像和时间会变化:
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
<PROJECT>-web-1 <IMAGE> <COMMAND> web <TIME> Up <TIME> <PORTS>
<PROJECT>-web-2 <IMAGE> <COMMAND> web <TIME> Up <TIME> <PORTS>
<PROJECT>-web-3 <IMAGE> <COMMAND> web <TIME> Up <TIME> <PORTS>确认 SERVICE 均为 web、共有 3 行且状态为 Up。将目标数改为 1 即可缩容;Compose 会停止并删除多余副本。有健康检查时,发布脚本宜加 --wait 后再接入流量。
风险与边界
- 配置
container_name且副本数大于 1 时,多个容器会争用同一名称并报错。安全替代是删除固定名称,让 Compose 自动命名。 - 发布固定宿主机端口,如
8080:80,第二个副本可能因端口冲突启动失败。安全替代是使用动态宿主机端口,或由反向代理统一接入。 - 多副本同时写同一文件卷、执行同一计划任务或依赖内存会话时,可能出现重复执行、锁冲突或数据损坏。安全替代是使用外部数据库、缓存或队列,并设计单写者或分布式锁。
- 缩容会删除容器,未持久化数据和处理中请求可能丢失。安全替代是先摘除流量、等待任务排空,并确认数据已写入命名卷或外部存储。
排障清单
先用 docker compose config --services 核对服务名,再用 docker compose config 检查 container_name 和固定端口。副本未全部运行时查看 docker compose ps -a web,随后读取 docker compose logs --tail=100 web,重点排查端口占用、健康检查失败、资源不足和进程退出。
当前插件使用 docker compose;旧版独立程序使用 docker-compose,参数和输出可能不同。自动化脚本应先记录 docker compose version。
实时观察 Compose 项目中的创建、启动、退出和健康事件。
查看容器事件
需要确认 Compose 容器何时创建、启动、退出或切换健康状态时,使用 docker compose events 订阅当前项目的实时事件。它适合观察发布和异常退出,不替代持久化日志或审计系统。
命令定位
服务名可省略;省略后监听项目内全部容器:
docker compose events [OPTIONS] [SERVICE...]命令默认持续阻塞,空闲时没有输出。自定义项目使用了 -f、--env-file 或 -p 时,监听命令必须携带相同参数。--json 输出逐行 JSON,--since <TIME> 回放指定时间后的事件,--until <TIME> 到指定时间自动停止。
高频用法
在终端 A 监听 web:
docker compose events --json web预期结果:命令保持运行,触发事件后逐行输出 JSON。终端 B 可制造重建、启动和退出事件:
docker compose up -d --force-recreate web
docker compose stop web预期结果:web 被重新创建、启动并停止;若配置了健康检查,还会产生健康状态变化事件。终端 A 的输出节选如下,时间、ID 和镜像会变化:
{"time":"<TIME>","type":"container","action":"create","id":"<ID>","service":"web","attributes":{"name":"<PROJECT>-web-1","image":"<IMAGE>"}}
{"time":"<TIME>","type":"container","action":"start","id":"<ID>","service":"web","attributes":{"name":"<PROJECT>-web-1","image":"<IMAGE>"}}
{"time":"<TIME>","type":"container","action":"health_status: healthy","id":"<ID>","service":"web","attributes":{"name":"<PROJECT>-web-1","image":"<IMAGE>"}}
{"time":"<TIME>","type":"container","action":"die","id":"<ID>","service":"web","attributes":{"name":"<PROJECT>-web-1","image":"<IMAGE>"}}健康事件只在定义了 healthcheck 且状态发生变化时出现。停止或重建时还可能看到 stop、kill、destroy,顺序取决于进程退出方式。
输出字段说明
| 字段 | 读取方法 |
|---|---|
time |
事件发生时间 |
action |
create、start、die、health_status: healthy 等动作 |
id |
容器 ID |
service |
Compose 服务名 |
attributes |
容器名称、镜像等附加属性 |
--json 输出的是 JSON Lines,不是一个 JSON 数组,脚本应逐行解析。排查退出时优先匹配 die,不要只搜索自然语言中的“退出”。
风险与边界
- 未设置结束条件时监听会长期阻塞。安全替代是使用
--until、外部超时控制或按Ctrl+C停止。 - 项目名、配置文件或 Docker 上下文不一致时,事件流可能为空或来自错误环境。安全替代是先核对
docker compose ls、docker context show和docker compose ps -a。 - 事件历史不是持久审计记录。需要长期追溯时,应把
--json输出发送到日志平台,并为采集进程设计重连和落盘。
排障清单
无事件时主动执行 docker compose restart <SERVICE> 产生动作。健康事件缺失时,用 docker inspect --format '{{json .State.Health}}' <CONTAINER> 检查探针。需要观察整台主机而非单个 Compose 项目时,改用 docker events 并增加过滤条件。
当前插件使用 docker compose events;旧版 docker-compose 的参数和字段可能不同。自动化判断应容忍额外动作和字段,不依赖固定顺序。