容器与云原生 / 知识点
Docker Compose 配置与运维速查手册
手册条目
删除配置中已移除但仍属于当前项目的旧服务容器。
清理孤立容器
当 compose.yaml 删除或重命名服务后,旧容器可能仍带着当前 Compose 项目标识继续运行。使用 --remove-orphans 可按项目范围清理这些旧服务容器,同时避免使用全局清理命令误删其他项目资源。
命令定位
孤立容器是“仍属于当前 Compose 项目,但其服务名已不在当前生效配置中”的容器。它通常出现在服务改名、删除 Profile、切换 Compose 文件组合或回滚配置后。
先对比当前配置的服务清单与项目容器。docker compose ps --all 默认包含已停止容器和孤立服务,输出中的 SERVICE 不在 config --services 结果里时,应重点核实。
docker compose config --services
printf '\n'
docker compose ps --all预期输出:
web
db
NAME IMAGE SERVICE CREATED STATUS
demo-web-1 nginx:alpine web <TIME> Up <TIME>
demo-db-1 postgres:16 db <TIME> Up <TIME>
demo-worker-1 demo-worker worker <TIME> Exited (0)这里 worker 未出现在配置服务清单中,因此 demo-worker-1 是待确认的孤立容器。名称、时间和表格列宽会随项目与 Compose 版本不同。
高频用法
项目仍需继续运行时,重新对齐当前配置并删除孤立容器:
docker compose up -d --remove-orphans预期输出:
[+] Running 3/3
✔ Container demo-worker-1 Removed
✔ Container demo-db-1 Running
✔ Container demo-web-1 Running若本次同时要完整停止项目,可在停机窗口执行:
docker compose down --remove-orphans预期输出:
[+] Running 4/4
✔ Container demo-worker-1 Removed
✔ Container demo-web-1 Removed
✔ Container demo-db-1 Removed
✔ Network demo_default Removedup 会保留并启动当前配置中的服务;down 会停止并删除当前服务容器及项目网络。两者的 --remove-orphans 都只额外处理当前项目的孤立服务容器。
项目范围
Compose 依赖项目名识别资源。生产脚本应显式复用部署时的项目名和配置文件,避免因工作目录变化而选错项目。
PROJECT=demo
COMPOSE_FILE=/srv/demo/compose.yaml
docker compose -p "$PROJECT" -f "$COMPOSE_FILE" up -d --remove-orphans预期输出:
[+] Running <COUNT>/<COUNT>
✔ Container demo-<OLD_SERVICE>-1 Removed
✔ Container demo-<SERVICE>-1 Running-p 指定项目名,-f 指定本次生效配置;两者必须与原部署一致。使用多个 -f 文件时,也必须保持文件及顺序一致。
风险与边界
触发条件是项目中存在配置已移除的服务容器。若 -p、COMPOSE_PROJECT_NAME 或 -f 指向错误,可能清理另一个同名环境的容器并造成服务中断。安全做法是先运行同参数的 config --services 和 ps --all,确认项目名、服务名与容器名后再执行。
docker compose up -d --remove-orphans 还会按当前配置协调现有服务;当镜像、环境变量或挂载已变化时,当前容器可能被重建。只允许在既定发布流程中执行;不希望重建时,可先使用 docker compose up -d --no-recreate --remove-orphans,并确认启动已停止服务是否符合预期。
该选项不负责删除孤立容器曾使用的命名卷,也不会删除 bind mount 的宿主机目录。不要用 docker system prune 或无项目过滤的批量删除代替,它们的影响范围更大。
排障清单
- 未发现旧容器:确认执行时使用了原项目名、原 Compose 文件及相同 Profile。
- 容器仍存在:用
docker inspect <CONTAINER>检查com.docker.compose.project与com.docker.compose.service标签。 - 每次执行都出现孤立告警:检查是否交替使用了不同的
-f文件组合或服务重命名后仍有旧部署脚本。 - 删除后端口仍被占用:运行
docker ps --filter publish=<PORT>,确认占用者是否属于其他项目。
速查:继续运行项目用 up -d --remove-orphans;完整停机清理用 down --remove-orphans;执行前始终核对项目范围。
在确认数据可丢弃后移除项目容器及关联命名卷。
删除项目数据卷
当测试环境需要彻底重置,或项目确认下线且数据已经备份时,使用 docker compose down --volumes 删除项目容器、网络及 Compose 管理的数据卷。该操作不可逆,数据库、上传文件和队列持久化数据都可能永久丢失。
删除范围
--volumes 可简写为 -v。它会删除 Compose 文件顶层 volumes 中声明的命名卷,以及项目容器附加的匿名卷;同时 down 会停止并删除当前服务容器与项目网络。
声明为 external: true 的卷不会被删除,bind mount 对应的宿主机目录也不会被删除。镜像默认保留,除非另外使用 --rmi。
操作前确认
先列出配置声明的卷名和当前项目实际存在的卷。第一组是 Compose 模型中的逻辑名,第二组是 Docker Engine 中的实际资源名。
docker compose config --volumes
printf '\n'
docker compose volumes -q预期输出:
db-data
uploads
demo_db-data
demo_uploads若卷中保存数据库数据,应优先执行数据库自身的一致性备份,例如 pg_dump 或 mysqldump,并验证备份可恢复。仅复制运行中数据库卷的文件可能得到不一致备份;安全替代方案是先停止写入或使用数据库提供的在线备份机制。
高频用法
确认当前项目全部持久化数据可丢弃后执行:
docker compose down --volumes预期输出:
[+] Running 5/5
✔ Container demo-web-1 Removed
✔ Container demo-db-1 Removed
✔ Volume demo_db-data Removed
✔ Volume demo_uploads Removed
✔ Network demo_default Removed名称和数量会随项目变化。输出出现 Volume <NAME> Removed 才表示对应卷已删除;外部卷和 bind mount 不会出现在删除列表中。
自动化或非当前目录执行时,应显式指定部署时使用的项目名和 Compose 文件:
PROJECT=demo
COMPOSE_FILE=/srv/demo/compose.yaml
docker compose -p "$PROJECT" -f "$COMPOSE_FILE" down --volumes --remove-orphans预期输出:
[+] Running <COUNT>/<COUNT>
✔ Container demo-<SERVICE>-1 Removed
✔ Container demo-<OLD_SERVICE>-1 Removed
✔ Volume demo_<VOLUME> Removed
✔ Network demo_default Removed追加 --remove-orphans 会同时删除当前项目中配置已移除的旧服务容器;它不会扩大到其他项目。
删除后验证
使用 Compose 项目标签检查是否仍有其管理的卷。把 demo 改为实际项目名。
PROJECT=demo
docker volume ls --filter "label=com.docker.compose.project=$PROJECT"预期输出:
DRIVER VOLUME NAME只有表头表示未找到带该项目标签的剩余卷。若仍有记录,先用 docker volume inspect <VOLUME> 核对标签、挂载状态和是否为预期保留资源,不要直接批量删除。
风险与边界
触发条件是执行 down 时带有 -v 或 --volumes。后果是命名卷与匿名卷中的数据无法通过再次 up 恢复;后续启动会创建空卷,应用可能表现为数据库初始化、账号消失或文件缺失。安全替代方案是仅运行 docker compose down,它会保留卷。
若项目名或 Compose 文件选错,可能删除同名环境的数据卷。执行前应使用完全相同的 -p、-f、环境文件和 Profile,并核对 docker compose volumes -q 输出。共享宿主机上禁止用 docker volume prune 代替,因为它按“未被容器引用”清理,范围不限于当前项目。
自定义 name: 的卷仍可能由 Compose 管理;external: true 的卷始终由项目外部管理。不要仅凭名称前缀判断删除范围,应以 Compose 配置和卷标签为准。
排障清单
- 卷未删除:检查是否为
external: true、仍被其他容器占用,或命令使用了错误项目名。 - 再次启动仍有旧数据:检查服务是否使用 bind mount、外部卷,或应用数据实际写在远程数据库。
- 删除时报
volume is in use:先用docker ps --filter volume=<VOLUME>找出占用容器,再确认是否允许停止。 - 只想重建容器:不要加
-v,使用docker compose down && docker compose up -d。
速查:保留数据用 down;彻底清空项目卷用 down --volumes;生产环境执行前必须完成可恢复备份与范围核对。
定位因主机端口冲突导致的服务启动失败。
排查 Docker Compose 端口占用
当 docker compose up 出现 port is already allocated、address already in use 或端口绑定失败时,先确认冲突的主机端口,再区分占用者是另一个容器还是宿主机进程。最终应停止明确的旧实例,或修改当前项目的主机端口,而不是盲目结束进程。
快速定位
先从报错中记下主机端口。映射 8080:80 中,8080 是宿主机端口,80 是容器端口;冲突发生在前者。下面同时检查 Docker 容器和 Linux 主机的 TCP 监听者。
PORT=8080
docker ps --filter "publish=${PORT}" \
--format 'table {{.ID}}\t{{.Names}}\t{{.Ports}}'
sudo ss -ltnp "sport = :${PORT}"预期输出
CONTAINER ID NAMES PORTS
<ID> old-web 0.0.0.0:8080->80/tcp
State Recv-Q Send-Q Local Address:Port Peer Address:Port Process
LISTEN 0 4096 0.0.0.0:8080 0.0.0.0:* users:(("docker-proxy",pid=<PID>,fd=<FD>))第一段能定位发布该端口的运行中容器;第二段确认宿主机监听者。若 Docker 列表为空但 ss 有结果,通常是宿主机服务占用。UDP 冲突改查 sudo ss -lunp "sport = :${PORT}"。
处理冲突
若占用者是已经废弃的 Compose 项目,应进入那个项目的目录执行 docker compose down。若旧容器仍承担业务,优先修改当前项目的主机端口;不要改容器端口,除非应用本身也同步改为监听新端口。
services:
web:
ports:
- "127.0.0.1:8081:80"该配置把宿主机 127.0.0.1:8081 转发到容器 80/tcp。先检查合并后的配置,再重建服务并读取实际发布地址。
docker compose config --quiet
docker compose up -d web
docker compose port web 80预期输出
[+] Running 1/1
✔ Container <PROJECT>-web-1 Started
127.0.0.1:8081若服务必须被其他主机访问,可使用 "8081:80",并同时检查主机防火墙;仅本机使用时保留 127.0.0.1 更安全。
风险与边界
直接执行 kill -9 <PID>、docker stop $(docker ps -q) 或批量删除容器,可能中断无关业务并造成数据未正常落盘。安全替代是先用端口过滤结果确认名称、所属 Compose 项目和业务状态,再执行项目级 docker compose down 或单容器 docker stop <CONTAINER>。
把绑定地址从 127.0.0.1 改为 0.0.0.0 会让端口监听所有主机接口;若防火墙或云安全组同时放行,服务可能暴露到外网。需要远程访问时应限制来源地址,并优先通过反向代理或受控入口发布。
排障清单
- 用
docker compose config确认变量替换和多文件合并后的ports,避免实际端口与编辑文件不同。 - 用
docker compose ls检查是否有同目录、同项目名或旧目录启动的另一套 Compose 项目。 - 改端口后同步更新反向代理、健康检查、客户端地址和自动化脚本,否则容器虽已启动,调用方仍会访问旧端口。
- macOS 可用
sudo lsof -nP -iTCP:8080 -sTCP:LISTEN;Windows PowerShell 可用Get-NetTCPConnection -LocalPort 8080 -State Listen。Docker Desktop 场景仍先查docker ps --filter publish=8080,避免只看到 Docker 后端进程而找不到具体容器。
检查容器状态、监听地址、端口映射和应用绑定配置。
排查 Docker Compose 服务无法访问
服务已通过 Compose 启动但浏览器、接口客户端或其他容器无法连接时,应沿“客户端 → 主机发布端口 → Docker 转发 → 容器端口 → 应用监听”逐层验证。先判断请求在哪一层中断,再修改端口映射、监听地址、网络调用方式或防火墙规则。
访问链路

先从主机本机测试,再测试远程客户端。主机本机也失败,重点检查容器、映射和应用监听;主机成功而远程失败,重点检查发布地址、防火墙、安全组、反向代理和路由。
快速定位
把服务名和应用实际监听的容器端口写入变量。命令会确认容器是否存在、当前状态、健康状态以及该容器端口对应的主机发布地址。
SERVICE=web
CONTAINER_PORT=8080
CID=$(docker compose ps --all -q "$SERVICE" | head -n 1)
test -n "$CID" || {
echo "service container not found: $SERVICE"
exit 1
}
docker compose ps --all "$SERVICE"
docker compose port "$SERVICE" "$CONTAINER_PORT"
docker inspect --format 'status={{.State.Status}} health={{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$CID"预期输出
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
<PROJECT>-web-1 <IMAGE> "<COMMAND>" web <TIME> ago Up <TIME> (healthy) 0.0.0.0:8080->8080/tcp
0.0.0.0:8080
status=running health=healthyPORTS 为空表示没有发布到主机;status=exited、restarting 或 health=unhealthy 时,先执行 docker compose logs --tail=100 web 查应用启动错误。docker compose port 报无映射时,检查 Compose 文件中的 ports,不要把仅供容器网络使用的 expose 当成主机端口发布。
主机侧验证
在 Docker 主机上请求实际发布端口。下面只验证 HTTP 链路是否到达应用;路径可替换为项目已知的健康检查地址。
HOST_PORT=8080
curl --connect-timeout 3 --max-time 10 \
--silent --show-error \
--output /dev/null \
--write-out 'HTTP %{http_code}\n' \
"http://127.0.0.1:${HOST_PORT}/"预期输出
HTTP 200返回 200、3xx 或 4xx 都说明 TCP 转发已到达 HTTP 服务,后续应检查路由、认证或反向代理;curl: (7) Failed to connect 通常表示没有监听或转发目标错误;超时则继续检查防火墙、主机网络和应用是否阻塞。
修正端口与监听
短语法 HOST_PORT:CONTAINER_PORT 左侧是客户端访问的主机端口,右侧必须等于应用在容器内真实监听的端口。例如应用监听 8080,映射应写为:
services:
web:
ports:
- "8080:8080"配置生效后,docker compose port web 8080 应返回主机地址。若应用日志显示只监听 127.0.0.1:8080,Docker 转发通常无法从容器网络接口连接它;应使用应用自身的配置把监听地址改为 0.0.0.0,然后执行 docker compose up -d --force-recreate web 并重新验证。
容器间访问
同一 Compose 网络中的其他服务应使用服务名和容器端口,例如 http://web:8080。不要使用 localhost:8080,因为容器内的 localhost 指向调用方容器自身;也不要默认使用主机发布端口,容器间通信通常不需要经过宿主机端口。
若服务跨多个 Compose 项目,必须确认双方加入同一个显式外部网络,并使用该网络内可解析的服务名或别名。仅给两个服务配置相同的网络名称字符串,并不保证它们实际连接到同一个已存在网络。
风险与边界
把端口绑定到 0.0.0.0 并放行防火墙,会扩大可访问范围;对数据库、管理后台和调试端口尤其危险。安全替代是仅绑定 127.0.0.1,或通过受认证的反向代理、VPN、SSH 隧道和来源地址限制提供访问。
不要为“先通再说”给所有服务添加 ports。触发条件是服务只需容器间通信却被发布到主机,后果是增加攻击面和端口冲突;安全替代是保留内部网络访问,只对真正的入口服务发布端口。
排障清单
- 容器必须处于
running;存在健康检查时同时确认不是unhealthy。 docker compose port <SERVICE> <CONTAINER_PORT>必须返回预期主机地址,且右侧容器端口与应用实际监听端口一致。- 应用应监听
0.0.0.0或容器网卡地址,而不是只监听容器内的127.0.0.1。 - 主机本机访问成功、远程访问失败时,检查绑定地址、系统防火墙、云安全组、反向代理监听地址和上游目标。
- 容器访问容器时使用服务名与容器端口;主机访问容器时使用发布端口,二者不要混用。
- 修改 Compose 文件后执行
docker compose config确认最终配置,并重建服务;单纯docker compose restart不会应用端口映射等容器创建参数的变更。
检查服务网络归属、DNS 名称和容器间访问地址。
排查服务名解析失败
用于处理容器内访问 db、api 等服务名时报 Name or service not known、NXDOMAIN 或无法建立连接的问题。先确认两个服务是否属于同一个 Compose 网络,再从发起请求的容器内验证 DNS;不要直接改成容器 IP。
快速定位
Compose 默认会把服务接入项目的用户定义网络,并以服务名注册内部 DNS。容器间地址应写成 服务名:容器端口,例如 db:5432;localhost:宿主机映射端口 只适用于从宿主机访问。
下面假定请求方为 web、目标为 db。先将变量替换成 docker compose config --services 列出的真实服务名。
SRC=web
DST=db
docker compose config --services
for svc in "$SRC" "$DST"; do
cid=$(docker compose ps -q "$svc")
printf '%s: ' "$svc"
docker inspect -f '{{range $name, $_ := .NetworkSettings.Networks}}{{$name}} {{end}}' "$cid"
echo
done
docker compose exec "$SRC" sh -lc "getent hosts '$DST' 2>/dev/null || nslookup '$DST'"预期输出
web
db
web: demo_default
db: demo_default
172.20.0.3 db项目名、网络名和 IP 会不同。两个服务至少应有一个相同网络;最后一段能返回目标地址,说明服务名解析正常。若镜像同时缺少 getent 和 nslookup,应使用带网络工具的临时调试容器,而不是在生产镜像中长期安装排障包。
结果判断
出现 NXDOMAIN 或 bad address,优先检查服务名是否拼错、目标服务是否启用对应 profile、是否使用了另一套 -f、-p 或 --project-directory 参数。服务存在但网络列表没有交集时,应在 compose.yaml 中把双方接入同一个网络。
能够解析 IP,但连接报 Connection refused,说明 DNS 已正常,下一步检查应用监听地址和容器端口。容器间应访问目标进程实际监听的容器端口,不要使用 ports 左侧的宿主机端口;超时则继续检查网络策略、应用阻塞或目标服务健康状态。
高频修复
自定义网络场景下,确保请求方和目标方共享网络;跨 Compose 项目通信时,可让双方加入同一个预先创建的外部网络,并设置明确的网络别名。修改后执行 docker compose up -d 让 Compose 重建网络连接。
容器重建后 IP 会变化,客户端必须按服务名重新解析并重连。应用若长期缓存旧 IP,应调整连接池、DNS 缓存或重试策略,而不是把当前 IP 写入配置。
风险与边界
触发条件是使用 network_mode: host、network_mode: none 或直接接入 Docker 默认 bridge。这些模式可能使 Compose 服务名 DNS 不可用;安全替代方案是优先使用 Compose 创建的用户定义网络,仅在确有主机网络需求时使用 host。
把目标写进 extra_hosts 或硬编码 IP,短期可能绕过报错,但容器重建后地址会失效并造成隐蔽故障。稳定方案是服务名或网络别名。依赖 container_name 还会限制扩容并增加项目间冲突,通常应保留服务名发现。
排障清单
依次确认服务名存在、容器正在运行、双方网络有交集、容器内能解析服务名、访问的是容器端口、目标进程监听 0.0.0.0 或容器接口。最后再检查跨项目外部网络、profile、项目名和应用 DNS 缓存。
核对变量来源、插值阶段、优先级和最终容器环境。
排查环境变量未生效
用于处理修改 .env、env_file 或 environment 后,应用仍读取旧值、空值或另一套配置的问题。依次核对插值来源、最终服务模型和运行容器环境,配置变化后必须重建目标容器。
先分清两个阶段
.env、Shell 环境和 --env-file 主要参与 Compose 文件中的 ${VAR} 插值,不会因为文件存在就自动进入容器。运行时变量需要通过 environment、服务级 env_file、镜像 ENV 或命令行覆盖明确注入。
同名插值通常按当前 Shell、--env-file、默认 .env 的顺序取值。容器变量则要检查 docker compose run -e、environment、env_file 和镜像 ENV;最终以渲染模型和容器内实测为准。
主检查
示例假定服务名为 web,关注 APP_ENV 和 API_URL。替换为项目真实值;第一段没有输出,只表示变量未参与插值,不代表容器内一定不存在。
SERVICE=web
docker compose config --environment \
| grep -E '^(APP_ENV|API_URL)=' \
| sort
docker compose config "$SERVICE" \
| sed -n '/environment:/,/^[^ ]/p'
docker compose up -d --force-recreate "$SERVICE" >/dev/null
docker compose exec "$SERVICE" sh -lc \
'env | grep -E "^(APP_ENV|API_URL)=" | sort'预期输出
API_URL=http://api:8080
APP_ENV=production
environment:
API_URL: http://api:8080
APP_ENV: production
API_URL=http://api:8080
APP_ENV=production第一组是插值值,中间是将要应用的服务配置,最后一组才是容器实值。实际字段顺序和缩进可能不同;若中间正确但最后仍旧,通常是容器未重建,或检查命令使用了不同的项目名、Compose 文件或工作目录。
常见原因
docker compose restart 只重启现有容器,不会注入新的环境配置。应执行 docker compose up -d --force-recreate web;生产环境需预估短暂中断,并准备维护窗口、可用副本或回滚方案。
build.args 和 Dockerfile 的 ARG 只在构建阶段生效。修改它们需要重新构建镜像,但应用启动时所需变量仍应通过 environment、env_file 或 secret 注入。
${VAR-default} 只在变量未设置时采用默认值;${VAR:-default} 在未设置或空字符串时都会采用默认值。关键变量可写成 ${VAR:?missing VAR},让 Compose 在创建容器前直接报错。
优先级与路径
服务同时声明 environment 和 env_file 时,同名值以 environment 为准。docker compose run -e NAME=value 只覆盖新建的一次性容器,不会修改正在运行的服务,不能用其结果判断长期服务已经更新。
默认 .env 的选择受 --project-directory、首个 -f 文件和当前目录影响,服务级 env_file 又是另一类输入。多目录部署时,检查命令必须复用启动时相同的 -f、--env-file、-p 和工作目录。
风险与边界
直接打印密码或令牌会把敏感值留在终端历史、CI 日志或工单中。安全替代方案是 Compose secrets,或只验证变量是否存在并输出脱敏摘要。
强制重建会替换容器进程和可写层,可能短暂中断服务;命名卷中的数据通常保留,未持久化状态会丢失。执行前确认数据已挂载到卷,并保留旧镜像标签和配置用于回滚。
速查顺序:config --environment 看插值,config <service> 看最终模型,up -d --force-recreate 应用变更,exec env 看容器实值,最后检查应用自身配置文件、缓存和启动参数。
定位绑定挂载中的用户权限、文件模式和安全策略问题。
排查挂载权限错误
当绑定挂载目录出现 Permission denied、只能读不能写或应用无法创建文件时,按“挂载目标是否正确、容器实际用户、宿主机数字 UID/GID、文件模式、安全策略”依次检查。不要先用 chmod 777 或改成 root 运行,这会掩盖真正的所有权问题。
快速定位
下面的命令同时查看挂载映射、容器配置用户、宿主机目录权限,以及容器进程对目标路径的实际读写能力。先把三个变量改成当前服务和路径。
SERVICE=app
CONTAINER_PATH=/data
HOST_PATH=./data
CID="$(docker compose ps -q "$SERVICE")"
test -n "$CID" || { echo "service container not found"; exit 1; }
echo "== mount =="
docker inspect "$CID" --format '{{range .Mounts}}{{println .Type .Source "->" .Destination "rw=" .RW}}{{end}}'
echo "== configured user =="
docker inspect "$CID" --format '{{if .Config.User}}{{.Config.User}}{{else}}<image-default>{{end}}'
echo "== host path =="
stat -c 'path=%n uid=%u gid=%g mode=%a' "$HOST_PATH"
echo "== container path =="
docker compose exec -T "$SERVICE" sh -c '
id
stat -c "path=%n uid=%u gid=%g mode=%a" "$1"
[ -r "$1" ] && echo readable=yes || echo readable=no
[ -w "$1" ] && echo writable=yes || echo writable=no
' sh "$CONTAINER_PATH"预期输出示例:
== mount ==
bind /srv/myapp/data -> /data rw= true
== configured user ==
10001:10001
== host path ==
path=./data uid=0 gid=0 mode=755
== container path ==
uid=10001 gid=10001 groups=10001
path=/data uid=0 gid=0 mode=755
readable=yes
writable=no这里容器以 10001:10001 运行,而目录属于 0:0 且只有所有者可写,因此问题落在宿主机权限,而不是 Compose 没有挂载成功。若 rw=false,应先检查 read_only: true 或卷后缀 :ro。
判定路径
挂载列表中没有目标目录,通常是服务名、Compose 文件、相对路径或项目目录选错。相对宿主机路径以 Compose 文件所在项目为基准,先用 docker compose config 查看展开后的最终配置。
容器内外看到的数字 UID/GID 一致,但应用仍失败时,应继续检查具体文件而不是只看目录。创建文件需要父目录写权限和执行权限;覆盖文件还需要目标文件权限,删除文件主要取决于父目录权限。
容器内显示可写但应用仍报错,常见原因是应用实际写入了另一个路径、挂载被子挂载覆盖、根文件系统只读,或进程启动后又降权。应在报错日志中确认完整路径,并用同一运行用户测试该路径。
安全修复
优先让宿主机目录的所有权与容器运行用户一致。新建专用数据目录时,可直接设置目标 UID/GID 和最小权限,避免递归修改未知文件。
HOST_PATH=./data
sudo install -d -m 0750 -o 10001 -g 10001 "$HOST_PATH"
stat -c 'path=%n uid=%u gid=%g mode=%a' "$HOST_PATH"预期输出:
path=./data uid=10001 gid=10001 mode=750若目录已有数据,先确认 realpath "$HOST_PATH" 指向预期位置,再只对该专用目录执行 chown。镜像本身支持非 root 用户时,也可在 Compose 中显式固定运行身份,避免不同主机上的默认用户变化。
services:
app:
user: "10001:10001"
volumes:
- type: bind
source: ./data
target: /data
read_only: false该配置不会自动修改宿主机所有权;保存后用 docker compose up -d --force-recreate app 重建,再重复快速定位命令验证 writable=yes。
安全策略与平台差异
在启用 SELinux 的 Linux 主机上,传统权限正确仍可能被标签阻止。仅供单个服务私有使用的目录可用 :Z,多个容器共享同一目录时用 :z,例如 ./data:/data:Z。不要通过关闭 SELinux 规避问题;这会扩大整台主机的攻击面。
AppArmor、只读根文件系统和用户命名空间也可能产生类似报错。macOS 与 Windows Desktop 通过虚拟机共享文件,宿主机 UID/GID 不一定直接对应容器;此时还要检查 Docker Desktop 的文件共享范围,以及宿主目录是否被系统隐私策略阻止。
风险与排障清单
chmod -R 777 会让任意本地用户或容器进程修改数据;安全替代是对专用目录设置匹配的 UID/GID,并仅开放所需的组写权限。chown -R 在路径变量为空或指向错误目录时可能破坏系统文件,执行前必须检查 realpath。
速查顺序:确认最终挂载源和目标;确认 rw 状态;比较容器用户与目录数字 UID/GID;分别测试目录和具体文件;检查 SELinux/AppArmor;重建容器后再次验证。
结合退出码、日志、健康检查和重启策略定位重启循环。
排查容器反复重启
容器持续处于 Restarting 时,先固定退出码、最后日志、OOM 标记、健康状态和重启策略,再判断是主进程退出、资源耗尽、启动命令错误还是依赖未就绪。不要先提高重启次数,否则关键错误会被快速滚动的日志淹没。
快速抓取证据
下面的命令适用于普通 Compose 服务,也会逐个检查扩容后的容器。把 app 改成目标服务名;时间、容器名和重启次数会因现场不同而变化。
SERVICE=app
docker compose ps -a "$SERVICE"
docker compose logs --tail=120 --timestamps "$SERVICE"
for CID in $(docker compose ps -a -q "$SERVICE"); do
docker inspect "$CID" --format 'name={{.Name}} status={{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}} restarts={{.RestartCount}} error={{json .State.Error}} health={{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}} restart-policy={{.HostConfig.RestartPolicy.Name}}'
done预期输出示例:
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
myproj-app-1 myapp:latest "./start.sh" app <TIME> ago Restarting (1) <TIME> ago
myproj-app-1 | <TIME> ERROR: database connection refused
name=/myproj-app-1 status=restarting exit=1 oom=false restarts=12 error="" health=none restart-policy=always该结果表示主进程以退出码 1 结束,未发生 OOM,并被 always 策略重新拉起。真正原因应从每轮退出前的最后几行日志继续追踪,而不是把“反复重启”本身当作根因。
读取退出码
退出码 0 表示主进程正常结束;若服务本应常驻且策略为 always 或 unless-stopped,通常是启动脚本把后台进程放走后自己退出。退出码 1 是通用应用错误,应结合日志定位配置、连接或迁移失败。
退出码 126 常见于文件存在但不可执行,127 常见于命令或解释器不存在。退出码 137 表示收到 SIGKILL;只有同时看到 oom=true 才能确认是内存不足,手工 kill -9 也可能得到 137。退出码 143 通常是收到 SIGTERM,需判断是否由人工停止、部署替换或超时触发。
容器处于 unhealthy 不会单独触发本地 Docker Engine 的 Compose 重启策略;必须同时确认主进程是否退出。若有健康检查,可读取最近探测记录。
SERVICE=app
CID="$(docker compose ps -a -q "$SERVICE" | head -n 1)"
docker inspect "$CID" --format '{{if .State.Health}}{{range .State.Health.Log}}{{println .End "exit=" .ExitCode .Output}}{{end}}{{else}}no-healthcheck{{end}}'预期输出示例:
<TIME> exit= 1 curl: (7) Failed to connect to localhost port 8080
<TIME> exit= 1 curl: (7) Failed to connect to localhost port 8080健康检查连续失败说明探测路径、端口或启动时序有问题,但仍需回到退出码确认它是否参与了重启循环。
暂停循环并前台复现
先停止原服务,再用临时覆盖文件关闭重启策略并以前台方式启动,能保留第一轮完整错误。下面示例假设主文件为 compose.yaml、服务名为 app。
services:
app:
restart: "no"将其保存为 compose.debug.yaml 后执行:
docker compose stop app
docker compose -f compose.yaml -f compose.debug.yaml up --no-deps app预期输出示例:
app-1 | ERROR: database connection refused
app-1 exited with code 1--no-deps 用于避免同时重启其他服务;若故障与数据库、缓存等依赖启动顺序有关,应去掉该参数复现完整链路。排查完成后删除临时覆盖文件,并用正常配置重新创建服务。
常见根因与修复
退出码 0 且服务应常驻时,让主进程以前台方式运行,不要在入口脚本末尾使用 & 后直接退出。126 或 127 时检查入口文件执行位、shebang、镜像内路径和 Windows CRLF 换行。
oom=true 时先确认内存限制、峰值和泄漏,再调整限制;仅提高内存可能延后再次崩溃。日志出现连接拒绝时,检查依赖服务状态、服务名 DNS、端口和就绪条件,不要只增加固定 sleep。
健康检查过早失败时,修正探测命令,并设置符合实际冷启动时间的 start_period、interval 和 timeout。应用配置或密钥错误时,使用 docker compose config 检查变量展开,但避免把包含敏感值的完整结果粘贴到工单或公共日志。
风险与排障清单
把策略改为 always 只能隐藏崩溃,不能修复崩溃;安全替代是先关闭自动重启抓取第一轮证据,再按退出码修复。不要为排障直接执行 docker compose down -v,它会删除命名卷并可能造成不可恢复的数据丢失。
速查顺序:保存最后日志;记录退出码、OOM 和重启次数;检查入口命令;核对健康检查与依赖就绪;前台复现第一轮失败;修复后确认 RestartCount 不再增长。
区分容器已启动与应用可用状态并修正就绪等待逻辑。
排查依赖服务未就绪
容器显示 Up 只代表主进程仍在运行,不等于数据库、缓存或接口已经能接收请求。排查时先读取健康状态和依赖方日志,再用 healthcheck 与 depends_on.condition: service_healthy 把启动顺序改成可验证的就绪等待。:contentReference[oaicite:0]{index=0}
先区分启动与就绪
先检查项目状态、依赖服务日志和容器健康状态。最后一条命令返回 starting、healthy、unhealthy;未配置健康检查时返回 no-healthcheck。
docker compose ps
docker compose logs --tail=50 db api
DB_ID="$(docker compose ps -q db)"
docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}no-healthcheck{{end}}' "$DB_ID"预期输出
NAME SERVICE STATUS
<PROJECT>-db-1 db Up <TIME> (health: starting)
<PROJECT>-api-1 api Restarting (<CODE>) <TIME>
db | <DEPENDENCY_STARTUP_LOG>
api | <CONNECTION_REFUSED_OR_TIMEOUT>
starting若依赖容器是 Up,但依赖方持续出现连接拒绝或超时,通常是短写 depends_on 只保证创建与启动顺序,没有等待应用完成初始化。

用健康检查建立就绪门槛
下面配置可直接运行。数据库使用镜像内置的 pg_isready 检查目标数据库;api 只有在 db 进入 healthy 后才启动。
services:
db:
image: postgres:16-alpine
environment:
POSTGRES_PASSWORD: example
POSTGRES_DB: app
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d app"]
interval: 5s
timeout: 3s
retries: 10
start_period: 10s
api:
image: alpine:3.20
depends_on:
db:
condition: service_healthy
command: ["sh", "-c", "echo 'db is ready'; tail -f /dev/null"]生效行为:Compose 等待 db 的健康检查通过后再创建 api。探针命令在依赖容器内部执行,因此镜像中必须存在 pg_isready 或对应检查工具。:contentReference[oaicite:1]{index=1}
启动并验证等待结果
使用 --wait 让命令在所有服务达到运行或健康状态后再返回;--wait-timeout 防止流水线无限等待。
docker compose up -d --wait --wait-timeout 90
docker compose ps
docker compose logs --no-log-prefix api预期输出
[+] Running 2/2
✔ Container <PROJECT>-db-1 Healthy
✔ Container <PROJECT>-api-1 Started
NAME SERVICE STATUS
<PROJECT>-db-1 db Up <TIME> (healthy)
<PROJECT>-api-1 api Up <TIME>
db is ready--wait 对配置了健康检查的服务等待 healthy,对没有健康检查的服务只等待 running;关键业务服务仍应配置能代表真实可用性的探针。:contentReference[oaicite:2]{index=2}
风险与边界
- 健康检查只测进程存在或端口打开时,应用可能仍未完成迁移、鉴权或数据加载,结果是依赖方仍会提前启动。安全替代是探测真实业务就绪端点或执行最小读写校验。
start_period太短、retries太少会把正常冷启动误判为不健康;设置过宽又会延迟故障暴露。应按历史启动耗时留出余量,并为 CI 配置独立的--wait-timeout。- 不要把密码直接写进
healthcheck.test,该命令可通过容器配置被查看。优先使用无密钥的本地探针、受限账号或容器内已挂载的密钥文件。 - 数据迁移等一次性依赖不要伪装成长期健康服务,应使用
condition: service_completed_successfully,并让任务失败时返回非零退出码。
排障清单
确认合并后的 Compose 配置确实包含健康检查和条件依赖,再读取最近一次探针的退出码与输出。
docker compose config
DB_ID="$(docker compose ps -q db)"
docker inspect --format '{{range .State.Health.Log}}{{println .End "exit=" .ExitCode .Output}}{{end}}' "$DB_ID"预期输出
services:
api:
depends_on:
db:
condition: service_healthy
<END_TIME> exit=0 <HEALTHCHECK_OUTPUT>若配置正确但持续 unhealthy,优先检查探针命令是否存在、目标主机与端口是否正确、启动时间是否超过 start_period,以及探针本身是否依赖未加载的环境变量。
识别删除容器、镜像、网络和数据卷时可能影响的数据范围。
安全清理项目资源
清理前必须先锁定 Compose 项目名,并分别确认容器、网络、镜像和数据卷的归属。默认 docker compose down 只删除当前项目的服务容器与项目网络;加入 --volumes、--rmi 或 --remove-orphans 后,影响范围会明显扩大。:contentReference[oaicite:3]{index=3}
先确认项目范围
不要仅凭目录名猜项目名。先列出项目,再用同一个 -p 值检查容器、卷和网络;Compose 创建的资源带有 com.docker.compose.project 标签,可用于复核归属。:contentReference[oaicite:4]{index=4}
PROJECT=myapp
docker compose ls -a
docker compose -p "$PROJECT" ps -a
docker volume ls --filter "label=com.docker.compose.project=$PROJECT"
docker network ls --filter "label=com.docker.compose.project=$PROJECT"预期输出
NAME STATUS
myapp running(2)
NAME SERVICE STATUS
myapp-db-1 db Up <TIME>
myapp-web-1 web Up <TIME>
DRIVER VOLUME NAME
local myapp_db-data
NETWORK ID NAME DRIVER
<ID> myapp_default bridge结果中出现不属于本次维护窗口的服务或卷时立即停止。-p 指错项目可能操作另一套同机环境;应以 docker compose ls -a、部署参数或顶层 name 为准,而不是依赖当前目录推断。:contentReference[oaicite:5]{index=5}
按风险选择清理命令
| 命令 | 删除范围 | 默认保留 | 主要风险 |
|---|---|---|---|
docker compose down |
当前项目服务容器、项目默认网络和已声明的非外部网络 | 镜像、命名卷、匿名卷、外部资源 | 低;服务停止并中断连接 |
docker compose down --remove-orphans |
上述资源,加上同项目中已不在当前配置里的容器 | 镜像和卷 | 使用了不同 Compose 文件或 Profile 时,可能误删暂时未声明的服务 |
docker compose down --rmi local |
上述资源,加上没有自定义标签的服务镜像 | 命名卷、匿名卷、外部资源 | 后续启动需要重新构建或拉取 |
docker compose down --rmi all |
上述资源,加上服务使用的全部镜像 | 卷、外部资源 | 共享镜像可能被其他项目复用,导致其后续冷启动变慢或重新拉取 |
docker compose down --volumes |
上述资源,加上声明的命名卷和容器匿名卷 | 外部卷、外部网络 | 数据不可逆丢失,数据库和上传文件最危险 |
标记为 external: true 的网络和卷不会被 down 删除;绑定挂载是宿主机路径,也不会由 down 自动清空。不要把全局性的 docker system prune --volumes 当作项目清理命令,它会扫描整台 Docker 主机而不是单个 Compose 项目。:contentReference[oaicite:6]{index=6}
推荐执行顺序
先解析服务清单并做安全的默认清理。只有确认旧配置中的孤立容器也应删除时,才加入 --remove-orphans。
PROJECT=myapp
docker compose -p "$PROJECT" config --services
docker compose -p "$PROJECT" ps -a
docker compose -p "$PROJECT" down --remove-orphans预期输出
db
web
NAME SERVICE STATUS
myapp-db-1 db Up <TIME>
myapp-web-1 web Up <TIME>
[+] Running <COUNT>/<COUNT>
✔ Container myapp-web-1 Removed
✔ Container myapp-db-1 Removed
✔ Network myapp_default Removed默认清理后验证容器和网络已消失、数据卷仍保留。
docker compose -p "$PROJECT" ps -a
docker network ls --filter "label=com.docker.compose.project=$PROJECT"
docker volume ls --filter "label=com.docker.compose.project=$PROJECT"预期输出
<NO_PROJECT_CONTAINERS>
<NO_PROJECT_NETWORKS>
DRIVER VOLUME NAME
local myapp_db-data删除数据卷前的强制检查
先确认卷名、挂载点和备份状态。在线数据库应使用数据库原生备份;直接打包正在写入的卷可能得到不一致副本。完成备份或确认数据可丢弃后,才执行高风险删除。
PROJECT=myapp
docker volume ls --filter "label=com.docker.compose.project=$PROJECT"
docker volume inspect --format 'name={{.Name}} mountpoint={{.Mountpoint}}' myapp_db-data
docker compose -p "$PROJECT" down --remove-orphans --volumes预期输出
DRIVER VOLUME NAME
local myapp_db-data
name=myapp_db-data mountpoint=<PATH>
[+] Running <COUNT>/<COUNT>
✔ Volume myapp_db-data Removed触发条件是明确要求重置数据、销毁临时环境或已经完成可恢复备份;可能后果是数据库、队列状态和用户上传文件永久丢失。安全替代是先执行不带 --volumes 的 down,保留卷到验收结束后再单独删除。
兼容性与速查
优先使用 Compose v2 的 docker compose 子命令。维护脚本执行前记录版本,避免把旧版 docker-compose 的行为和输出样式混入同一流程。
docker compose version预期输出
Docker Compose version v<MAJOR>.<MINOR>.<PATCH>生产环境的最小安全路径是:确认项目名与标签归属,执行默认 down,验证卷仍在;只有在备份可恢复且删除范围经过复核后,才追加 --volumes 或 --rmi all。