容器排障的难点不在命令数量,而在证据的归属:现象出现在容器内,产生现象的资源却由宿主机与内核提供。本文按起源、原理、实现、总结四部分组织,原理部分说明命名空间与 cgroup 的分工、限额的生效路径、退出码语义与状态机,实现部分给出十一个排查场景的命令、判读依据与处置方式。命令参数细节参见同目录 ./container_management.html,日志驱动与日志命令细节参见 ./container_logs.html,网络驱动与端口映射细节参见 ./docker_nets.html,本文不重复展开。
一、起源:容器故障与主机故障的定位差异
1.1 现象在容器,根因可能在宿主机或内核
容器是宿主机上的普通进程集合,其资源全部来自宿主机内核。同一个现象在不同层级有完全不同的处置动作,误判的代价体现在两方面:动作无效,或者动作破坏了唯一可用的证据。
常见的错层现象:
| 容器侧现象 | 可能根因层级 | 错层处置的后果 |
|---|---|---|
容器内写入报 No space left on device | 宿主机 data-root 所在分区空间或 inode 耗尽 | 反复重启容器不恢复,反复重建容器丢失可写层数据 |
| 容器被终止,退出码 137 | 容器 cgroup 内存超限,或宿主机全局内存不足,或人工 docker kill | 只调大 --memory 而不核对宿主机可用内存,扩容后仍然被杀 |
| 请求延迟升高但容器 CPU 使用率不高 | CPU 配额触发节流,或宿主机 I/O 等待,或宿主机 CPU 被其他容器抢占 | 在应用侧做无收益的性能优化 |
| 容器内文件不可写 | 挂载属主与容器内 uid 不一致,或 AppArmor/SELinux 拦截,或根文件系统只读 | 反复调整文件权限,掩盖安全模块的拒绝记录 |
| 容器网络不通 | 容器内监听地址错误,或 iptables 规则被防火墙重写,或上游安全组拦截 | 反复重建网络,未触及真实阻断点 |
判断归属的一个基本事实:容器与宿主机共享内核,内核状态、内核版本、非命名空间化的内核参数只有一份。容器内的 free、/proc/meminfo、部分 /proc/cpuinfo 读数来自宿主机而非容器限额;容器内的 df 反映的是容器挂载命名空间内的挂载表,不是宿主机的全部分区。以容器内的数字直接判断宿主机状态,或者以宿主机的数字直接判断容器是否受限,都会得出错误结论。
1.2 排查手段分散带来的效率问题
容器排障所用的命令分布在四个层面,文档与经验的割裂造成三类浪费:
- 入口分散:容器自身的状态与配置在
docker inspect,限额在 cgroup 接口文件,进程视图在docker top与宿主机ps,网络视图在docker network inspect与iptables,同一故障需要在多个入口之间来回切换,容易漏项。 - 无 shell 场景缺少固定路径:镜像为 distroless、scratch 或应用镜像,容器内没有 shell 与调试工具,
docker exec直接失败,此时如果没有nsenter、docker cp、/proc/<PID>/root这类替代路径,排查会中断。 - 止损与取证顺序无约束:容器可写层与日志会随
docker rm一并消失,先删容器再分析根因的做法使同类问题重复发生。
因此需要一份按固定顺序组织的排查链路:先取状态与退出码确定方向,再取事件与配置确认变更,最后进入容器或命名空间做细粒度诊断;在每个环节明确判读依据与可回退的处置动作。
二、原理:隔离、限额、退出码与状态机
2.1 容器的隔离机制
容器由两组内核机制组合而成,二者职责不同,排障时的观察对象也不同。
命名空间与 cgroup 的分工
| 机制 | 作用范围 | 决定的内容 | 排障观察点 |
|---|---|---|---|
| 命名空间(namespace) | 隔离资源的可见性 | 容器内看到什么 | 容器内 ps、ip addr、mount、/etc/resolv.conf |
| cgroup | 限制与计量资源用量 | 容器能用多少 | 宿主机 /sys/fs/cgroup/... 下的接口文件与计数 |
涉及的命名空间类型:
- mount(mnt):容器拥有独立的挂载表,这是容器内
df与宿主机df不一致的直接原因 - PID:容器内的 1 号进程是容器入口进程在容器命名空间内的映射,宿主机上它有另一个 PID
- network(net):容器拥有独立的网卡、路由表、iptables 表与端口空间
- IPC:独立的 System V IPC 与 POSIX 消息队列
- UTS:独立的主机名与域名,
--hostname即作用于此处 - user:uid/gid 映射,
userns-remap启用后容器内的 root 在宿主机上是普通用户 - cgroup:决定
/sys/fs/cgroup的视图根。cgroup v2 下容器内读取memory.max看到的是容器自身的限额;--cgroupns=host时看到的是宿主机视图 - time:时钟偏移隔离,仅部分运行时与较新内核支持,未作为默认隔离项
容器与宿主共享内核带来的影响
- 内核版本只有一份:容器镜像内的 glibc、内核头文件或 io_uring、eBPF 等特性依赖宿主内核版本。在较新发行版上构建、在较旧内核上运行,可能出现系统调用缺失导致启动失败。
- 非命名空间化的内核参数不可在容器内修改:
--sysctl只接受已命名空间化的参数(如net.core.somaxconn、net.ipv4.tcp_tw_reuse),vm.swappiness、fs.file-max、kernel.pid_max等必须在宿主机设置。 - 内核级故障影响所有容器:内核 panic、内核模块缺陷、宿主机全局 OOM、存储设备错误会同时影响该主机上全部容器,现象表现为多个不相关容器同时异常。
- 内核日志是共享的:容器内一般看不到内核日志,
dmesg在容器内通常被限制;OOM、I/O error、AppArmor 拒绝等记录需在宿主机执行dmesg -T或journalctl -k查看。
PID 1 与信号处理
- 容器内的 1 号进程是镜像入口进程(
ENTRYPOINT或CMD),不是init。内核对该进程的信号处理有特殊语义:未注册处理函数的信号默认动作被忽略,SIGKILL与SIGSTOP除外。 - 由此产生两个后果:其一,
docker stop发送的SIGTERM如果没有被 PID 1 显式捕获,进程不会退出,守护进程等待宽限期后发送SIGKILL,退出码为 137;其二,PID 1 不承担回收职责,父进程已退出的子进程被 PID 1 收养后不被wait()回收,长期运行会累积僵尸进程。 - 判断信号是否被转发,观察 1 号进程是否为应用本体:
docker top <容器名> -o pid,ppid,stat,cmd
docker exec <容器名> cat /proc/1/cmdline | tr '\0' ' '
若 1 号进程是 /bin/sh -c "..." 而应用是其子进程,则 SIGTERM 只到达 shell,应用收不到终止信号。
2.2 容器资源限制的生效路径
Docker 的限额参数最终以 cgroup 接口文件的形式落地,读取这些文件是判断"限制是否生效、是否触限"的唯一可靠方式。
cgroup 版本与挂载位置
| 对比项 | cgroup v1 | cgroup v2 |
|---|---|---|
| 挂载结构 | 每个子系统一个挂载点,如 /sys/fs/cgroup/memory/、/sys/fs/cgroup/cpu/ | 单一挂载点 /sys/fs/cgroup/,控制器逐级启用 |
| 容器路径(systemd 驱动) | /sys/fs/cgroup/<子系统>/docker/<容器ID>/ | /sys/fs/cgroup/system.slice/docker-<容器ID>.scope/ |
| 容器路径(cgroupfs 驱动) | /sys/fs/cgroup/<子系统>/<容器ID>/ | /sys/fs/cgroup/<容器ID>/ |
| 判断方式 | mount \| grep cgroup 出现多行 | mount \| grep cgroup2 有输出,/proc/<PID>/cgroup 只有一行 |
cgroup 机制、v1 与 v2 的接口差异、systemd 单元与 cgroup 的映射、PSI 压力指标与委托机制,参见 ../../linux/processManagement/process_management.html 的 cgroup 章节,本节只保留与容器参数对应的部分。
docker run 参数与接口文件的对应关系
| 运行参数 | cgroup v2 接口文件 | cgroup v1 接口文件 | 语义 |
|---|---|---|---|
--memory | memory.max | memory.limit_in_bytes | 硬上限,触达即触发组内 OOM |
--memory-reservation | memory.low | memory.soft_limit_in_bytes | 软限制,回收时优先保护 |
--memory-swap | memory.swap.max | memory.memsw.limit_in_bytes | 内存与 swap 的总量口径 |
--cpus | cpu.max(配额 周期) | cpu.cfs_quota_us 与 cpu.cfs_period_us | 绝对配额,--cpus 1.5 对应 150000 100000 |
--cpu-shares | cpu.weight | cpu.shares | 相对权重,仅在竞争时生效 |
--pids-limit | pids.max | pids.max | 进程与线程总数上限 |
--blkio-weight | io.weight | blkio.weight | 块设备相对权重 |
--device-read-bps 等 | io.max | blkio.throttle.* | 块设备读写速率硬限 |
参数对进程行为的实际影响
- CPU 配额是节流而非拒绝:配额在周期内用尽后,组内任务被强制暂停到下一周期,表现为响应时间出现周期性的毛刺与延迟抬高,而 CPU 使用率显示为一个接近配额上限的平台。单线程应用的限额若低于一个核,进程永远无法跑满一个核。
- 内存上限触发的是组内 OOM:
memory.max触达时,内核在该 cgroup 内选择进程终止(memory.oom.group决定是否整组终止),不会等待宿主机全局内存耗尽。memory.high触达时执行限速回收,表现为分配变慢与直接回收增加,不直接杀进程。 - swap 的默认口径容易误判:只设置
--memory 2g时,容器可用的内存与 swap 总量默认为 2 倍的--memory,仍可使用 swap;--memory 2g --memory-swap 2g表示禁用 swap。宿主机内存紧张而容器允许 swap 时,容器进程会被换出,表现为延迟升高但容器不被杀。 - 限额之外的宿主机约束同样生效:容器限额宽松而宿主机物理内存不足时,全局 OOM 可能选中容器内占用最高的进程,此时容器 cgroup 的
memory.events中oom_kill不增长,需在宿主机内核日志中确认。 - 内存统计口径:
memory.current与docker stats的内存数值包含页缓存等文件页,与进程 RSS 之和不相等。判断是否内存泄漏应读取memory.stat的anon(匿名页,即进程实际占用)而非总量。
2.3 退出码语义
退出码是排查的第一个分流点,取值规则由 Shell 与信号约定决定:被信号终止时,退出码为 128 加信号编号。
| 退出码 | 含义 | 常见成因 | 排查入口 |
|---|---|---|---|
| 0 | 入口进程正常结束 | 一次性任务执行完毕;前台应用启动即结束 | 检查 Cmd 是否为后台命令或短时任务 |
| 1 | 应用自身错误 | 未捕获异常、配置解析失败、依赖连接失败 | 容器日志 |
| 126 | 命令存在但不可执行 | 文件无可执行权限、挂载带 noexec、以非 root 用户运行脚本 | ls -l 核对权限位与挂载选项 |
| 127 | 命令不存在 | ENTRYPOINT 路径错误、脚本解释器缺失、PATH 不含目标目录 | 核对 Config.Entrypoint 与镜像内路径 |
| 137 | 128 + 9,被 SIGKILL 终止 | 容器 cgroup 内存超限被杀;docker kill;docker stop 超时后强杀 | State.OOMKilled、memory.events、内核日志 |
| 139 | 128 + 11,SIGSEGV | 原生代码越界、栈溢出、JIT 缺陷、二进制与 CPU 特性不匹配 | 应用崩溃日志与 core dump 配置 |
| 143 | 128 + 15,收到 SIGTERM | docker stop 正常路径、宿主机 kill、编排层缩容 | 确认是否为预期终止,检查是否缺少优雅退出逻辑 |
需要严格区分的两点:
- 137 不等于 OOM。137 只说明进程收到
SIGKILL,来源有三种:容器内存超限、人工或编排层强制终止、docker stop宽限期结束后的兜底强杀。区分依据见 3.4 节。 - 143 不等于故障。若退出发生在执行
docker stop之后,143 属预期结果;若为无人工干预的自发退出,则说明有外部信号来源,需查宿主机审计日志与编排层事件。
2.4 状态机与重启策略
容器状态与 --restart 策略共同决定"容器是否还会自动起来",排查中需要先确认二者的组合。
状态取值与含义
| 状态 | 含义 | 排障要点 |
|---|---|---|
created | 已创建,进程未启动 | 常由创建成功而启动失败导致,核对 State.Error |
running | 主进程在运行 | 不等于服务可用,需结合健康检查状态 |
paused | 所有进程被冻结(docker pause) | 不释放资源,不参与重启策略,被暂停时健康检查会转为失败 |
restarting | 处于重启等待或重启过程中 | docker ps 显示 Restarting (n) Seconds ago,是重启风暴的直接证据 |
exited | 主进程已退出 | 结合退出码与 FinishedAt 判断,容器仍保留可写层与日志 |
dead | 运行时不接受该容器的操作 | 常见于挂载残留、存储驱动异常、删除过程被中断,需先处理挂载再删除 |
重启策略的判定依据
| 策略 | 触发条件 | 与状态的配合 |
|---|---|---|
no | 不自动重启 | 退出后停留 exited |
on-failure[:n] | 退出码非 0 时重启,可限制最大次数 | 需区分 137 是 OOM 还是强杀,否则可能在内存不足时循环重启 |
always | 任何退出都重启;守护进程重启后也恢复 | 手动 docker stop 后不会立即重启,但守护进程重启后会再次拉起 |
unless-stopped | 除手动停止外都重启 | 手动停止的状态会被记录,守护进程重启后不再拉起,生产环境常用 |
重启策略的关键限制:
- 判定依据只有退出码,不参考健康检查结果。应用活着但不可用(如连接池耗尽、线程全部阻塞)不会触发重启。
- 重启风暴的成因是策略与依赖不可用叠加:应用启动即因依赖不可达而退出,
on-failure或always反复拉起。RestartCount与docker events中的restart事件是判断依据。 - 运行时可动态调整:
docker update --restart=no <容器>可立即止损,无需重建容器。 - 守护进程重启对容器的影响由
live-restore决定,该配置位置参见 ../config/docker_on_ubuntu_config.html。
三、实现:排查链路与处置
3.1 现场信息采集顺序
采集顺序按"成本从低到高、破坏性从无到有"排列。前四步只读,不改变容器状态,应先完成。相关命令的参数细节参见 ./container_management.html 的查看与检查章节。
第一步:状态与退出码
# 容器清单与状态
docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}"
# 状态机关键字段
docker inspect <容器名> --format '{{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}} err={{.State.Error}}'
docker inspect <容器名> --format 'restarts={{.RestartCount}} started={{.State.StartedAt}} finished={{.State.FinishedAt}}'
# 健康检查状态
docker inspect <容器名> --format '{{if .State.Health}}{{.State.Health.Status}} fails={{.State.Health.FailingStreak}}{{else}}no-healthcheck{{end}}'
判读依据:Status 为 exited 时以 ExitCode 分流(0 与 1 看日志,126/127 看路径与权限,137 转入 3.4 节,143 确认信号来源);RestartCount 大于 0 且持续增长说明存在重启循环;State.Error 非空时优先读取,其中包含运行时启动失败的原因,例如挂载错误或 OCI 运行时错误。
处置方式:exited 状态的容器保留可写层与日志,先采集再操作;需要复现时使用 docker start 而非 docker run 新建容器,避免配置差异干扰。
第二步:配置与限额
# 入口与运行配置
docker inspect <容器名> --format '{{json .Config.Entrypoint}} {{json .Config.Cmd}}'
docker inspect <容器名> --format '{{json .Config.Env}}'
docker inspect <容器名> --format 'user={{.Config.User}} workdir={{.Config.WorkingDir}}'
docker inspect <容器名> --format '{{json .HostConfig.RestartPolicy}}'
docker inspect <容器名> --format 'mem={{.HostConfig.Memory}} cpus={{.HostConfig.NanoCpus}} pids={{.HostConfig.PidsLimit}}'
docker inspect <容器名> --format '{{json .HostConfig.LogConfig}}'
docker inspect <容器名> --format 'ro={{.HostConfig.ReadonlyRootfs}} privileged={{.HostConfig.Privileged}}'
docker inspect <容器名> --format '{{json .HostConfig.SecurityOpt}} {{json .HostConfig.CapDrop}}'
判读依据:Memory 与 NanoCpus 为 0 表示未设置限额,此时容器不受内存与 CPU 上限约束,资源类故障需转向宿主机层面;PidsLimit 为 0 或负数表示不限制进程数;ReadonlyRootfs 为 true 时应用写临时文件必然失败;SecurityOpt 中出现 apparmor=unconfined、seccomp=unconfined 说明安全模块被显式关闭,此时文件访问类故障不应归因于安全模块。
处置方式:限额缺失属于配置缺陷,使用 docker update 动态补齐(--memory、--cpus),重启策略同理;ReadonlyRootfs 场景通过 --tmpfs 提供可写临时目录,需重建容器。
第三步:事件流
# 最近的容器事件
docker events --since 1h --until 0m --filter container=<容器名>
# 只看生命周期与资源类事件
docker events --since 2h --filter container=<容器名> --filter event=die --filter event=kill --filter event=oom --filter event=restart --filter event=health_status
判读依据:oom 事件说明容器 cgroup 触发了 OOM;die 事件附带退出码;health_status: unhealthy 给出健康状态翻转的时刻,可与应用日志时间线对齐;start 与 die 的时间间隔若固定,说明是周期性的启动失败或探针导致的重启。事件流可回溯依赖服务的动作,例如数据库容器在应用容器退出前是否发生过重启。
处置方式:事件只记录行为不记录原因,将其作为时间线骨架,原因仍需回到日志、cgroup 计数与内核日志。
第四步:日志
docker logs --tail 200 -t <容器名>
docker logs --since 30m <容器名> 2>&1 | grep -iE "error|fatal|panic|exception|refused|denied"
判读依据:以 -t 的时间戳与事件流对齐,确定失败发生在挂载、依赖连接还是监听阶段;日志为空时先确认日志驱动类型,驱动为 journald、syslog、fluentd、none 时 docker logs 不提供读取能力,详见 3.7 节与 ./container_logs.html。
处置方式:日志被轮转覆盖时,从宿主机 /var/lib/docker/containers/<容器ID>/ 目录下按时间顺序读取归档文件;日志文件过大导致读取阻塞时使用 --tail 与 --since 限制范围。
第五步:资源与进程
# 一次性资源快照
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.PIDs}}\t{{.NetIO}}\t{{.BlockIO}}"
# 容器内进程(宿主 PID 视角)
docker top <容器名> -o pid,ppid,user,stat,%cpu,%mem,etime,cmd
# cgroup 计数(systemd 驱动,cgroup v2)
CID=$(docker inspect -f '{{.Id}}' <容器名>)
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/memory.current
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/memory.events
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/cpu.stat
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/pids.current
判读依据:docker stats 的内存包含页缓存,与 RSS 不等,趋势判断可用,容量判断以 cgroup 文件为准;docker top 的 PID 为宿主机 PID,可用于后续 strace、lsof、/proc/<PID> 检查;mem_limit 与 mem_used 的比值接近 1 说明限额是瓶颈。
处置方式:确认限额为瓶颈时,先核对宿主机可用内存再调整限额,禁止在宿主机内存不足时单纯调大容器上限,否则故障从容器级 OOM 转移到宿主机级 OOM。
3.2 容器内诊断
docker exec 与 docker attach 的区别
| 对比项 | docker exec | docker attach |
|---|---|---|
| 作用 | 在容器命名空间内新建进程 | 附加到容器 1 号进程的标准输入输出 |
| 对容器生命周期的影响 | 无,进程退出不影响容器 | 有,Ctrl+C 会把 SIGINT 发给 PID 1,可能导致容器退出 |
| 信号与作业控制 | 独立进程,不受 PID 1 影响 | 收到终端的信号,Ctrl+Z 会挂起容器主进程 |
| 安全退出方式 | 直接退出 | Ctrl+P 后 Ctrl+Q 分离 |
| 适用场景 | 常规排查 | 观察前台进程的实时输出 |
判读依据:任何可能产生交互式信号的操作都不要在 attach 会话中执行;需要观察标准输出时优先用 docker logs -f。
镜像无 shell 或为 distroless 时的诊断手段
- 借助
/proc从宿主机侧观察,不需要容器内存在任何工具:
PID=$(docker inspect -f '{{.State.Pid}}' <容器名>)
sudo ls -l /proc/$PID/root/ # 容器根文件系统视图
sudo cat /proc/$PID/mountinfo # 容器挂载表
sudo tr '\0' '\n' < /proc/$PID/environ # 容器环境变量
sudo cat /proc/$PID/status | grep -E 'State|VmRSS|Threads|Uid'
sudo ls -l /proc/$PID/fd | wc -l # 打开的文件描述符数量
sudo ls -l /proc/$PID/ns # 各命名空间的编号
判读依据:/proc/<PID>/root 与 /proc/<PID>/mountinfo 给出容器内文件系统与挂载的真实情况,可用于核对 bind mount 是否按预期生效、配置目录是否为空;/proc/<PID>/ns/* 的编号可用于确认两个容器或进程是否处于同一命名空间。
nsenter进入指定命名空间(需要宿主机 root):
PID=$(docker inspect -f '{{.State.Pid}}' <容器名>)
# 进入容器的挂载、网络、PID、IPC、UTS 命名空间执行命令
sudo nsenter -t $PID -m -u -i -n -p -- ps -eo pid,ppid,stat,cmd
sudo nsenter -t $PID -n -- ss -tlnp
sudo nsenter -t $PID -m -- ls -la /
判读依据:进入后执行的命令使用容器视角的资源,输出与容器内执行等价。涉及 user 命名空间时需要附加 -U,同时配合 --setuid 0 --setgid 0 --preserve-credentials,否则可能因凭据映射失败而报错。
- 临时调试容器共享目标容器的命名空间(宿主侧需要有调试镜像):
docker run --rm -it \
--net=container:<容器名> \
--pid=container:<容器名> \
--ipc=container:<容器名> \
--volumes-from <容器名> \
--cap-add NET_RAW --cap-add NET_ADMIN --cap-add SYS_PTRACE \
nicolaka/netshoot
判读依据:调试容器与目标容器共享网络与 PID 命名空间后,ss、tcpdump、strace -p 的输出即为目标容器的视图,无需在业务镜像内安装任何工具。--cap-add 仅在调试会话期间生效,调试容器退出即消失。
- 不进入容器完成文件检查与修改:
docker cp <容器名>:/etc/app/config.yml ./config-from-container.yml
docker cp ./config-fixed.yml <容器名>:/etc/app/config.yml
docker export <容器名> -o /tmp/container-snapshot.tar # 导出容器文件系统快照
判读依据:docker cp 双向可用,已停止的容器同样可复制,这是无 shell 场景下取证据的主力手段;复制到容器内的文件属主默认为 root,可能引起权限问题,需要与容器内运行用户核对。
处置方式:可写层只读(--read-only)时无法通过 docker cp 写入,此时改用共享卷或将文件复制到容器内的 tmpfs 挂载点。
3.3 进程与信号问题
PID 1 不转发信号导致无法优雅退出
现象:执行 docker stop 后容器在宽限期结束被强制杀死,退出码 137,应用日志中没有优雅关闭记录,数据库等有状态服务出现未完成的写入。
定位:
# 1 号进程与进程树
docker exec <容器名> ps -eo pid,ppid,stat,cmd
docker exec <容器名> cat /proc/1/cmdline | tr '\0' ' '
# 观察停止过程的时间
time docker stop -t 30 <容器名>
docker inspect <容器名> --format '{{.State.ExitCode}}'
判读依据:1 号进程为 shell 时,SIGTERM 只到达 shell;应用日志中缺少关闭流程的输出即为未收到信号的证据;退出码 137 说明宽限期耗尽后收到 SIGKILL。
处置方式:
- 镜像层面使用 exec 形式的入口,避免 shell 作为 PID 1:
ENTRYPOINT ["java", "-jar", "/app/app.jar"]
- 若必须使用 shell 脚本,脚本末尾使用
exec替换 shell 进程:
#!/bin/sh
set -e
# 初始化动作
exec "$@"
- 使用
--init注入轻量 init 作为 1 号进程,由它转发信号并回收孤儿进程:
docker run -d --init --name app myimage
判读依据:--init 生效后 1 号进程变为 /sbin/docker-init 或对应实现,应用成为其子进程,信号转发与僵尸回收由 init 承担。
docker kill 与 docker stop 超时后的 SIGKILL
docker kill <容器名> # 默认发送 SIGKILL,等价于强制终止
docker kill -s SIGTERM <容器名> # 手动触发优雅停止
docker stop -t 60 <容器名> # 延长宽限期
docker inspect <容器名> --format '{{.State.ExitCode}}'
判读依据:docker kill 默认 SIGKILL,退出码必然为 137;docker stop 先发 SIGTERM,宽限期(默认 10 秒)内进程未退出才发送 SIGKILL,因此 docker stop 得到的 137 说明优雅退出未生效。
处置方式:有状态服务延长宽限期并修复信号处理;送 SIGTERM 前先从负载均衡摘除流量,避免仍在途的请求被中断。
僵尸进程与 --init
docker top <容器名> -o pid,ppid,stat,cmd | grep -w Z
docker exec <容器名> ps -eo stat,pid,ppid,cmd | grep -w Z
docker inspect <容器名> --format '{{.State.Pid}}' | xargs -I{} sudo cat /proc/{}/status | grep Threads
判读依据:状态为 Z 的进程不占用 CPU 与内存,但占用 PID 表项;若数量持续增长,最终会触达 pids.max,表现为 fork 失败、新连接无法创建,日志出现 Cannot allocate memory 或 Resource temporarily unavailable。
处置方式:使用 --init 由 init 回收孤儿进程;应用内部正确 wait() 子进程;确认存在数量增长时检查 pids.current 与 pids.max 的比值,必要时通过 --pids-limit 调整上限并定位泄漏来源。
进程处于不可中断状态
docker top <容器名> -o pid,stat,wchan,cmd
PID=$(docker inspect -f '{{.State.Pid}}' <容器名>)
sudo cat /proc/$PID/stack 2>/dev/null
判读依据:STAT 为 D 表示进程在内核态等待 I/O,SIGKILL 也无法立即终止;wchan 给出等待的内核函数,指向存储或网络子系统。此时容器层面的操作无效,需转入宿主机层的存储与网络检查,见 3.11 节。
3.4 资源限制引发的故障
容器被 OOM Kill 的判定
# 1. 容器侧的 OOM 标记
docker inspect <容器名> --format '{{.State.OOMKilled}} {{.State.ExitCode}}'
# 2. cgroup 计数(systemd 驱动,cgroup v2)
CID=$(docker inspect -f '{{.Id}}' <容器名>)
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/memory.events
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/memory.max
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/memory.stat | grep -E '^(anon|file|pgmajfault) '
# 3. 内核日志
sudo dmesg -T | grep -iE 'memory cgroup out of memory|oom_group_kill|killed process'
journalctl -k --since "2 hours ago" --no-pager | grep -iE 'out of memory|oom'
判读依据:
| 证据 | 含义 |
|---|---|
State.OOMKilled 为 true | 容器 cgroup 内发生了 OOM |
memory.events 中 oom_kill 计数大于 0 | 该容器被组内 OOM 终止过,计数大于 1 说明反复发生 |
内核日志出现 Memory cgroup out of memory | 组内 OOM,日志中记录被终止进程的内存占用 |
内核日志出现 Out of memory: Killed process 而无 cgroup 字样 | 宿主机全局 OOM,根因在宿主机内存总量而非容器限额 |
memory.current 贴近 memory.max | 限额确实被触达,属于限额不足 |
| 应用日志无任何输出即中断 | OOM 无机会执行日志落盘,属 OOM 的典型特征 |
处置方式:
- 先核对宿主机可用内存与压力,再决定调整方向:
free -h
cat /proc/meminfo | grep -E 'MemTotal|MemAvailable|SwapTotal|SwapFree'
cat /proc/pressure/memory
- 确认容器限额不足时提升上限,同时按峰值加余量设置:
docker update --memory 4g --memory-swap 4g <容器名>
- 宿主机全局 OOM 时,扩大容器限额无效,需降低同宿主其他容器的内存占用,或迁移部分容器到其他主机;内存机制与回收行为参见 ../../linux/memoryManagement/memory_management.html。
- JVM 类应用需确认 JVM 能感知 cgroup 限额,否则堆大小按宿主机内存计算,容器限额会被提前触达。Java 8u191 及以上可通过
-XX:MaxRAMPercentage=70按限额比例设置堆上限。 - 需要更早感知内存压力而非直接被杀时,可设置
memory.high(通过运行时的内存预留参数近似实现),代价是分配变慢。
CPU 节流(throttle)的判读
CID=$(docker inspect -f '{{.Id}}' <容器名>)
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/cpu.max
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/cpu.stat
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/cpu.pressure
判读依据:
| 字段 | cgroup v2 | cgroup v1 | 判读 |
|---|---|---|---|
nr_periods | 有 | 有 | 已过去的调度周期总数 |
nr_throttled | 有 | 有 | 被节流的周期数,与 nr_periods 的比值反映节流频率 |
throttled_usec / throttled_time | throttled_usec(微秒) | throttled_time(纳秒) | 累计被强制等待的时间,持续增长说明配额为瓶颈 |
nr_throttled 与 nr_periods 的比值明显大于 0,且 throttled_usec 在观测窗口内持续增长,即可判定 CPU 配额不足。此时 docker stats 的 CPU 使用率通常稳定在配额上限附近,延迟呈周期性毛刺。
处置方式:
docker update --cpus 2 <容器名>
--cpu-shares 只在多容器竞争同一 CPU 时决定分配比例,不构成绝对上限,用它处理"使用率被压在某个值"的问题无效。
磁盘 IO 被限流的判定
CID=$(docker inspect -f '{{.Id}}' <容器名>)
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/io.max
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/io.stat
cat /sys/fs/cgroup/system.slice/docker-$CID.scope/io.pressure
docker inspect <容器名> --format '{{json .HostConfig.BlkioDeviceReadBps}} {{json .HostConfig.BlkioDeviceWriteBps}} {{.HostConfig.BlkioWeight}}'
判读依据:io.max 非空说明设置了速率硬限,io.stat 中的 rios、wios、rbytes、wbytes 与 dbytes(丢弃)可用于核对实际速率是否贴合限额;io.pressure 中 some 行的占比升高说明任务在等待 I/O。未设置任何 IO 参数时不存在 IO 限流,写延迟升高应转向宿主机设备层,参考 3.11 节的设备检查命令。
处置方式:解除或放宽限流建议重建容器(io.max 类参数并非全部可通过 docker update 动态修改),调整前先确认宿主设备本身不是瓶颈,否则解除限流只是把排队位置从容器移到设备。
宿主机内存与 swap 的影响
- 宿主机内存不足会放大容器侧表现:页缓存被回收导致容器内读文件变慢;直接回收导致分配延迟上升;最终触发全局 OOM 终止容器内进程,退出码 137 而容器
oom_kill计数不增长。 - swap 未禁用时延迟与内存统计都会失真:容器进程被换出后 RSS 下降,
docker stats的内存数值随之下降,容易被误读为"内存问题已缓解",实际表现为延迟升高。判断依据是宿主机 swap 的换入换出速率:
vmstat 1 5
grep -E 'pswpin|pswpout' /proc/vmstat
- 区分匿名页与文件页:
memory.stat中anon持续增长指向应用内存泄漏,file增长通常由读写文件与日志产生,可通过增大限额或减少缓存压力缓解,不属泄漏。 - 内存与压力的完整机制、回收与 PSI 指标参见 ../../linux/memoryManagement/memory_management.html,OOM 的宿主机侧案例参见 ../../linux/troubleshooting/fault_case_library.html。
3.5 存储与挂载故障
volume 与 bind mount 的权限与属主问题
# 容器内运行用户
docker exec <容器名> id
# 宿主机源目录的属主与权限
stat -c '%u:%g %a %n' /host/data
# 容器内挂载点视角
docker exec <容器名> ls -ln /app/data
docker inspect <容器名> --format '{{json .Mounts}}'
判读依据:容器内进程 uid 与挂载点属主 uid 不一致且容器用户无写权限时,写入返回 Permission denied;ls -ln 使用数字 uid 显示,避免容器内没有对应用户名时出现误判。启用 userns-remap 时宿主机侧属主为映射后的高位 uid,需按映射偏移量核对。
处置方式:调整宿主机目录属主为容器内 uid,或通过 --user 以匹配的 uid 运行容器,或镜像内创建与宿主机一致的 uid。完整排查流程与四种处置方案参见 ./container_management.html 的 Bind Mount 权限章节,卷、绑定挂载与 tmpfs 的选型与备份恢复参见 ./container_data_persistance.html。
SELinux 或 AppArmor 拦截
# SELinux 环境
getenforce
sudo ausearch -m avc -ts recent | tail -n 20
# AppArmor 环境
aa-status
sudo dmesg -T | grep -i apparmor
journalctl -k --since "1 hour ago" --no-pager | grep -i apparmor
判读依据:应用报 Permission denied 而文件权限位与属主均正确时,需检查安全模块。SELinux 环境中的典型证据是 avc: denied 记录,容器绑定挂载带 :z 或 :Z 标签即可自动重标记,:z 用于多容器共享,:Z 用于容器独占。AppArmor 环境中的证据是内核日志出现 apparmor="DENIED" 与 profile="docker-default"。安全模块机制参见 ../../linux/securitySystem/apparmor.html。
处置方式:优先按最小改动放开,而不是整体关闭安全模块。
# SELinux:重标记为容器可用
docker run -d -v /data/app:/app/data:z --name app myimage
# AppArmor:改用自定义策略
docker run -d --security-opt apparmor=my-profile --name app myimage
将 --security-opt apparmor=unconfined 或 --privileged 作为定位手段是可行的,但 高危,会移除容器的默认防护,使容器内的越权行为直接作用于宿主机。兜底与回滚方式:仅在离线复现环境使用,定位完成后立即以不带该参数的配置重建容器;生产容器禁止保留该参数,可通过 docker inspect <容器名> --format '{{json .HostConfig.SecurityOpt}} {{.HostConfig.Privileged}}' 巡检确认。
inode 与磁盘空间在宿主机的表现
# 宿主机:空间与 inode 同时看
df -hT; df -i
# 容器内:看到的挂载表属于容器命名空间
docker exec <容器名> df -hT
docker exec <容器名> findmnt -o TARGET,SOURCE,FSTYPE,OPTIONS
# Docker 自身的占用分布
docker system df -v
du -xh --max-depth=1 $(docker info -f '{{.DockerRootDir}}') | sort -h | tail -n 10
判读依据:
| 现象 | 结论 |
|---|---|
容器内 df 显示 / 为 overlay | 容器可写层位于宿主机 data-root 所在分区,空间由该分区决定 |
容器内 df 显示某挂载点为 ext4/xfs | 该挂载为 bind mount 或卷,容量由对应宿主机分区决定 |
容器内 df 空间充足但仍报 No space left on device | 检查宿主机 df -i,可能为 inode 耗尽 |
宿主机 df 与 du 差异巨大 | 存在已删除但仍被进程持有的文件,用 lsof +L1 定位 |
| 容器内看不见宿主机的其他分区 | 属正常现象,容器挂载命名空间只包含自己的挂载 |
处置方式:空间类故障的止损与处置顺序参见 ../../linux/fileSystem/disk_storage_and_file_system_operation.html 与 ../../linux/troubleshooting/fault_case_library.html;Docker 侧的空间释放与 data-root 规划参见 ../config/docker_on_ubuntu_config.html。清理卷与镜像的破坏性操作在 3.10 节说明。
数据卷被其他容器占用
# 哪些容器引用了该卷(含已停止容器)
docker ps -a --filter volume=<卷名>
docker volume inspect <卷名> --format '{{.Mountpoint}} {{.UsageData}}'
# 尝试删除时的返回
docker volume rm <卷名>
判读依据:卷被任何容器(包括已停止容器)引用时,docker volume rm 返回 volume is in use;卷的 Mountpoint 位于宿主机 data-root 目录下,直接删除目录不会同步 Docker 的元数据,会造成状态不一致。
处置方式:先在引用方停止写入,再从最后一个引用容器解除挂载后删除卷。删除前如需保留数据,按 ./container_data_persistance.html 的方式用临时容器打包备份。docker volume rm 与 docker volume prune 为 高危 操作,删除后无回收途径。兜底方式:删除前执行一次全量打包,并确认备份文件可读取后再执行删除。
# 备份后再删除(高危动作前的兜底)
docker run --rm -v <卷名>:/source -v $(pwd):/backup alpine \
tar -czf /backup/<卷名>-$(date +%Y%m%d).tar.gz -C /source .
tar -tzf ./<卷名>-$(date +%Y%m%d).tar.gz | head
挂载失效的静默表现
docker inspect <容器名> --format '{{range .Mounts}}{{.Type}} {{.Source}} -> {{.Destination}} ro={{not .RW}}{{"\n"}}{{end}}'
findmnt -T <宿主机源路径>
判读依据:使用 -v /host/path:/container/path 时,若宿主机源路径不存在,Docker 会自动创建空目录,容器正常启动但读取到空目录,应用可能以默认配置启动而不报错;源为文件而容器内目标已存在同名目录时,启动报 not a directory。核对方式是比对 Mounts 中的 Source 与 findmnt 输出,确认源存在且为非空。
处置方式:修正源路径或先在宿主机创建内容再启动容器;生产环境使用 --mount 形式,源不存在时直接报错而不会静默创建空目录。
3.6 网络故障
端口未监听与映射失败的区别
# 1. 容器内是否真的在监听,以及绑定地址
docker exec <容器名> ss -tlnp
docker exec <容器名> netstat -tlnp 2>/dev/null
# 2. 宿主机侧端口归属
ss -tlnp | grep ':<端口>'
docker port <容器名>
docker inspect <容器名> --format '{{json .NetworkSettings.Ports}}'
# 3. NAT 规则
sudo iptables -t nat -L DOCKER -n --line-numbers
sudo iptables -t nat -L DOCKER-USER -n --line-numbers
sudo iptables -t nat -L PREROUTING -n | head
# 4. 转发与连通性
cat /proc/sys/net/ipv4/ip_forward
curl -sS -m 3 -o /dev/null -w '%{http_code}\n' http://127.0.0.1:<宿主机端口>/
docker exec <容器名> curl -sS -m 3 -o /dev/null -w '%{http_code}\n' http://127.0.0.1:<容器端口>/
判读依据:
容器内 ss | 宿主机访问容器端口 | 结论与方向 |
|---|---|---|
| 无监听 | 失败 | 应用未启动或监听在其他端口,回到应用日志与配置 |
仅监听 127.0.0.1 | 失败 | 应用只绑定回环,外部流量到达容器 eth0 时无进程接收,改为监听 0.0.0.0 |
监听 0.0.0.0 | 失败 | 检查 iptables 规则是否存在、ip_forward 是否为 1、上游防火墙是否放行 |
监听 0.0.0.0 | 成功但外部失败 | 阻断点在宿主机之外,检查安全组、上游负载均衡与云防火墙 |
| 端口被其他进程占用 | 容器启动即失败 | docker run 报 address already in use,先用 ss -tlnp 定位占用进程 |
补充判读:docker run 成功后宿主机端口可能由 docker-proxy 进程持有,也可能仅由 iptables 的 DNAT 规则实现(取决于 userland-proxy 配置),两种情况 ss 输出不同,判读时以 iptables 规则与容器内监听状态为准,避免因看不到监听进程而误判。
处置方式:应用绑定地址错误需修改应用配置;端口冲突需释放端口或改用其他映射;规则被防火墙重写的情形参见 ../config/docker_on_ubuntu_config.html 的防火墙共存章节。网络驱动选型、自定义网络与默认桥接的 DNS 差异、端口映射实现与 docker network 命令细节参见 ./docker_nets.html,本节不重复。
容器间 DNS 解析失败
docker exec <容器名> cat /etc/resolv.conf
docker exec <容器名> getent hosts <目标服务名>
docker exec <容器名> nslookup <目标服务名>
docker network inspect <网络名> --format '{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'
docker inspect <容器名> --format '{{json .NetworkSettings.Networks}}'
判读依据:
/etc/resolv.conf中出现127.0.0.11表示使用 Docker 内嵌 DNS,具备容器名解析能力;该文件被挂载覆盖或指向不可达的外部 DNS 时,解析失败与此有关。- 默认
bridge网络只提供 IP 互通,不提供容器名解析(历史--link除外);自定义网络提供基于容器名与--network-alias的解析。同名别名对应多个容器时返回结果在多个 IP 间轮询,表现为间歇性连接失败。 getent hosts无输出而nslookup报SERVFAIL时,问题在 DNS 解析;两者均正常而连接仍失败时,问题在端口或防火墙。
处置方式:将相关容器接入同一自定义网络;为服务显式设置 --network-alias 并保证唯一;覆盖了 resolv.conf 的容器改为通过 --dns 参数指定上游 DNS。
iptables 链与 Docker 规则的关系
sudo iptables -t nat -S | grep -E 'DOCKER|MASQUERADE' | head -n 20
sudo iptables -S DOCKER-USER
sudo iptables -S FORWARD | head
sudo iptables -t nat -S POSTROUTING | grep -i docker
判读依据:Docker 在启动与容器网络变更时写入自有链与规则,端口映射体现为 nat 表的 DOCKER 链 DNAT 规则,出网流量体现为 POSTROUTING 的 MASQUERADE。DOCKER-USER 链在 DOCKER 链之前被遍历,是放置自定义放行与限流规则的位置,Docker 不会自动清空该链。宿主防火墙工具(ufw、firewalld)重载时可能清空或重排规则,导致容器网络中断,表现为全部容器同时不通。
处置方式:自定义规则写在与 Docker 约定保留位置,避免依赖规则的插入顺序;防火墙重载后校验规则是否仍存在;在 daemon.json 中关闭 Docker 的 iptables 管理前,必须自行补齐 NAT 与转发规则,否则端口映射整体失效。
抓包位置的选择
| 抓包位置 | 命令 | 能观察到什么 |
|---|---|---|
| 容器内协议栈 | docker exec <容器名> tcpdump -i eth0 -nn -s0 -w /tmp/c.pcap | 容器实际收发的报文,用于确认请求是否到达 |
| 宿主机网桥 | sudo tcpdump -i docker0 -nn -s0 -w /tmp/b.pcap | 默认桥接网络上的容器间与出网流量 |
| 容器 veth 对端 | sudo tcpdump -i vethXXXX -nn -s0 -w /tmp/v.pcap | 单容器出入口流量,可通过 ip -d link show 关联所属容器 |
| 宿主机物理网卡 | sudo tcpdump -i <物理网卡> -nn -s0 -w /tmp/p.pcap | DNAT 前后与 SNAT 后的真实报文 |
| 共享网络命名空间的调试容器 | --net=container:<容器名> 后在调试容器内抓包 | 业务镜像内无 tcpdump 时的替代方案 |
判读依据:容器内抓不到包说明请求未到达容器,问题在 NAT、防火墙或上游;容器内抓到 SYN 而无 SYN-ACK 说明对端或回程路径有问题;宿主机物理网卡有包而容器内无包,说明 DNAT 未生效或目标端口不匹配。Wireshark 侧的分析方法与 tcpdump 的完整参数参见 ../../linux/network/network_diagnosis_and_remote_connection.html。
3.7 日志相关问题
日志驱动导致的 docker logs 无输出
docker inspect <容器名> --format '{{.HostConfig.LogConfig.Type}} {{json .HostConfig.LogConfig.Config}}'
docker info --format '{{.LoggingDriver}}'
journalctl CONTAINER_NAME=<容器名> --since "1 hour ago" --no-pager
判读依据:docker logs 只对支持读取的驱动有效(json-file、local、journald)。驱动为 syslog、fluentd、loki、none 时命令返回 configured logging driver does not support reading;驱动为 none 时容器输出被直接丢弃。journald 驱动的日志需通过 journalctl 按 CONTAINER_NAME 字段查询。
处置方式:查询目标日志系统而不是反复执行 docker logs;需要同时保留可读取能力时,将驱动改回 json-file 并配置轮转,重建容器生效。驱动选型、结构化输出与集中收集架构参见 ./container_logs.html。
日志暴涨与容器磁盘占用
du -sh /var/lib/docker/containers/*/*-json.log | sort -h | tail -n 10
docker system df -v
docker inspect <容器名> --format '{{json .HostConfig.LogConfig}}'
grep -E 'max-size|max-file' /etc/docker/daemon.json
# 定位刷屏来源
docker logs --since 5m <容器名> 2>&1 | awk '{print $1,$2,$3}' | sort | uniq -c | sort -rn | head
判读依据:du 输出中单个 -json.log 超过数百 MB 说明未配置轮转;docker inspect 的 LogConfig 为空表示继承 daemon.json;日志写入速率异常通常对应应用循环报错,日志内容按行统计可快速定位刷屏来源。日志占满的是 data-root 所在分区,容器内同时报 No space left on device。
处置方式:立即释放空间可截断日志文件,truncate -s 0 <日志文件> 为 高危 操作,会永久丢弃历史日志。兜底方式:截断前先复制一份到宿主机其他分区,并确认应用确实不在该时间窗口内需要回溯日志。根治方式是配置 max-size 与 max-file,配置位置与生效方式参见 ./container_logs.html 与 ../config/docker_on_ubuntu_config.html;同时修复应用侧循环报错,否则清理后仍会再次打满。
时间与时区不一致
docker exec <容器名> date
docker exec <容器名> cat /etc/timezone 2>/dev/null
docker logs -t --tail 20 <容器名>
date
timedatectl
判读依据:容器默认使用 UTC,docker exec date 与宿主机 date 相差固定小时数即为时区差异;docker logs -t 的时间戳由守护进程生成,与应用自身输出的时间戳可能分属不同时区,两者对齐分析前需先确认基准。宿主机时间漂移会造成比时区差异更严重的后果,例如证书校验失败与集群认证失败。
处置方式:运行容器时设置 -e TZ=Asia/Shanghai 并挂载 /etc/localtime,具体参数参见 ./container_management.html;宿主机时间同步的检查与修复参见 ../../linux/troubleshooting/fault_case_library.html 中时间偏移案例,容器内时间由宿主机内核提供,容器内无法独立校时。
3.8 启动即退出的排查路径
启动即退出是频率最高的一类问题,按下列顺序推进,每步以退出码与日志为分流依据,避免无序尝试。
第一步:配置与命令
docker inspect <容器名> --format '{{json .Config.Entrypoint}} {{json .Config.Cmd}}'
docker inspect <容器名> --format 'user={{.Config.User}} workdir={{.Config.WorkingDir}}'
docker inspect <容器名> --format '{{json .Config.Env}}'
docker run --rm -it --entrypoint /bin/sh <镜像名> # 覆盖入口,进入镜像做静态检查
判读依据:退出码 126 指向权限(文件无可执行位、以非 root 用户执行需要特权的脚本、挂载带 noexec);127 指向路径(ENTRYPOINT 拼写、解释器不存在、PATH 不含该目录);1 指向应用自身。Cmd 为 bash、sh 等交互式命令而无 -i 时,标准输入立即结束,进程随之退出,退出码为 0。
处置方式:修正入口路径与权限位;交互式调试用 -it 运行;不需要交互的命令改为前台运行的应用进程。
第二步:依赖服务未就绪
docker logs --tail 100 <容器名> | grep -iE 'refused|timeout|no such host|connection'
docker exec <容器名> getent hosts <依赖服务名>
docker exec <容器名> nc -z -w 2 <依赖主机> <依赖端口>
docker ps -a --filter name=<依赖容器名>
判读依据:日志中出现 connection refused 说明依赖进程未监听;no such host 说明 DNS 解析失败;超时说明链路被阻断或依赖过载。依赖容器本身在反复重启时,应用容器的退出是结果而非原因。
处置方式:应用侧增加启动重试与退避;编排层使用健康检查作为依赖条件,depends_on 的 condition 取值与 healthcheck 配置参见 ../orchestration/orchestration.html;不依赖编排时以显式等待脚本替代固定 sleep。
第三步:挂载缺失
docker inspect <容器名> --format '{{range .Mounts}}{{.Type}} {{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'
ls -la <宿主机源路径>
docker exec <容器名> ls -la <容器内目标路径>
判读依据:Source 路径在宿主机不存在时,-v 形式会自动创建空目录,容器正常启动但读不到配置,应用可能以默认配置启动或直接报配置缺失;只读挂载(:ro)后的写入尝试会失败并可能中断启动流程。
处置方式:修正源路径,改为 --mount 形式以获得显式报错,启动脚本中对关键配置做存在性检查并输出明确错误。
第四步:权限
docker exec <容器名> id # 容器无法启动时使用 --entrypoint 覆盖后检查
docker inspect <容器名> --format 'ro={{.HostConfig.ReadonlyRootfs}} user={{.Config.User}}'
docker inspect <容器名> --format '{{json .HostConfig.SecurityOpt}}'
判读依据:报 Permission denied 时区分三类来源:文件属主与运行 uid 不匹配、根文件系统只读(ReadonlyRootfs 为 true 时写 /tmp、/var/run 会失败)、安全模块拦截(安全模块的拒绝会同时出现在内核日志中,见 3.5 节)。退出码 126 结合权限位判断。
处置方式:改用匹配的 uid,或提供可写的 --tmpfs 挂载点,或按 3.5 节处理安全模块;不要用 chmod 777 掩盖属主问题。
第五步:入口脚本换行符
file entrypoint.sh
head -n 5 entrypoint.sh | cat -A
判读依据:Windows 环境编辑的脚本带 CRLF 换行时,shebang 行末尾的 \r 使解释器路径变为 /bin/bash\r,内核报错 standard_init_linux.go: exec user process caused: no such file or directory,或在 shell 内报 bad interpreter: No such file or directory,同时容器内确实存在该文件,容易被误判为文件缺失。cat -A 输出行尾出现 ^M$ 即为证据。
处置方式:
# 修正已有文件
sed -i 's/\r$//' entrypoint.sh
# 在构建阶段统一转换
# RUN sed -i 's/\r$//' /app/entrypoint.sh && chmod +x /app/entrypoint.sh
# 仓库层面约束换行策略
# .gitattributes: *.sh text eol=lf
第六步:镜像架构不匹配
uname -m
docker inspect <镜像名> --format '{{.Os}}/{{.Architecture}} {{.Variant}}'
docker image inspect <镜像名> --format '{{json .RepoDigests}}'
docker run --rm --platform linux/amd64 <镜像名> uname -m
判读依据:宿主为 aarch64 而镜像为 amd64 时,启动报 exec format error 或用 qemu 模拟时表现为异常退出;宿主 CPU 缺少镜像要求的指令集特性时,进程在运行期收到 SIGILL 并以 132 退出。docker inspect 的 Architecture 字段给出镜像声明的平台。
处置方式:按目标平台拉取或构建镜像,跨平台运行通过 --platform 指定并确认已配置模拟器;镜像架构与平台参数的用法参见 ../imageManagement/images_management.html。
3.9 健康检查与编排层的影响
HEALTHCHECK 的判定逻辑
docker inspect <容器名> --format '{{json .Config.Healthcheck}}'
docker inspect <容器名> --format '{{.State.Health.Status}} fails={{.State.Health.FailingStreak}}'
docker inspect <容器名> --format '{{range .State.Health.Log}}{{.Start}} exit={{.ExitCode}} {{.Output}}{{"\n"}}{{end}}'
判读依据:健康状态取值 starting、healthy、unhealthy。start_period 期间的失败不计入 retries,一旦检查成功即进入正常判定;interval、timeout、retries 三者共同决定从故障发生到状态翻转为 unhealthy 的时长。State.Health.Log 中保存最近若干次检查的退出码与输出,是判断探针失败原因的第一手材料。
需要明确的一点:健康检查只改变状态,不改变容器生命周期。unhealthy 的容器不会因此被 Docker 自动重启,重启由 --restart 策略或编排层决定。参数含义与配置示例参见 ./container_management.html 的健康检查章节。
反复 unhealthy 的定位
# 1. 取出探针命令并在容器内手工执行
docker inspect <容器名> --format '{{json .Config.Healthcheck.Test}}'
docker exec <容器名> curl -sS -m 5 -o /dev/null -w '%{http_code}\n' http://127.0.0.1:<端口>/health
# 2. 对照应用真实监听
docker exec <容器名> ss -tlnp
# 3. 对照日志时间线
docker logs --since 30m -t <容器名> | tail -n 50
判读依据:先区分"应用真的不可用"与"探针本身有误"。常见探针缺陷包括:镜像内没有探针所依赖的命令(curl、wget 不存在,探针恒失败);探针端口与实际监听端口不一致;探针路径要求认证或返回 404、405;应用启动慢而 start_period 过短,容器长期停留在 starting 后被判定为 unhealthy;使用 localhost 而应用绑定地址为非回环地址导致探针连接失败。
处置方式:修正探针命令与时间参数;确属应用启动慢时延长 start_period;探针改为使用镜像内确实存在的工具,或改用应用自带的健康端点。
重启风暴的止损
# 1. 确认风暴规模
docker ps --filter status=restarting
docker inspect <容器名> --format '{{.RestartCount}} {{json .HostConfig.RestartPolicy}}'
docker events --since 30m --filter container=<容器名> --filter event=restart
# 2. 首先解除自动重启
docker update --restart=no <容器名>
# 3. 停止容器并保留现场
docker stop <容器名>
判读依据:docker ps 显示 Restarting 状态、RestartCount 快速增加、事件流中出现密集的 restart 即为风暴。风暴期间容器反复启动会持续产生日志、反复发起依赖连接,可能拖垮依赖服务,因此止损优先级高于根因分析。使用 docker update --restart=no 而非直接删除容器,可保留可写层与日志。
处置方式:止损后按 3.1 节顺序采集信息,定位启动失败原因,修复后再恢复重启策略。on-failure 策略可附加最大重试次数以避免无限循环:
docker update --restart=on-failure:3 <容器名>
编排层的对应关系:Compose 中 restart 与 depends_on 的组合决定级联行为,配置位置参见 ../orchestration/orchestration.html;Kubernetes 中以 CrashLoopBackOff 与重启退避机制表现同类问题,此时应通过 kubectl logs --previous 获取上一次崩溃的日志,而非依赖当前实例的日志。
3.10 止损与恢复原则
保留现场
止损与取证的冲突在容器场景中比宿主机更尖锐:容器的可写层与日志随删除一并消失,且没有回收站。原则与 ../../linux/troubleshooting/fault_case_library.html 中的先止损后定位一致,容器场景下补充以下动作:
# 现场快照:配置、状态、事件、日志、挂载、网络一次取全
mkdir -p /tmp/fault-<容器名>
docker inspect <容器名> > /tmp/fault-<容器名>/inspect.json
docker logs --timestamps <容器名> > /tmp/fault-<容器名>/logs.txt 2>&1
docker events --since 24h --until 0m --filter container=<容器名> > /tmp/fault-<容器名>/events.txt
docker top <容器名> aux > /tmp/fault-<容器名>/top.txt 2>&1
docker stats --no-stream <容器名> > /tmp/fault-<容器名>/stats.txt 2>&1
docker diff <容器名> > /tmp/fault-<容器名>/diff.txt 2>&1
CID=$(docker inspect -f '{{.Id}}' <容器名>)
cp -r /sys/fs/cgroup/system.slice/docker-$CID.scope /tmp/fault-<容器名>/cgroup 2>/dev/null
判读依据:inspect.json 记录容器创建时的全部参数,是复现容器的唯一完整依据;docker diff 列出可写层相对镜像的文件变更,用于判断故障前是否有人改动容器内文件;cgroup 目录快照保留限额与计数。
复制容器文件与保留镜像
# 已停止容器仍可复制文件
docker cp <容器名>:/app/logs /tmp/fault-<容器名>/app-logs
# 保留可写层现场(仅用于留存证据,不作为交付镜像的构建方式)
docker commit -m "fault snapshot before fix" <容器名> <仓库前缀>/<镜像名>:fault-<日期>
# 导出容器文件系统
docker export <容器名> -o /tmp/fault-<容器名>/rootfs.tar
判读依据:docker commit 会把可写层固化为新镜像,代价是镜像中包含运行期产生的临时文件,仅用于保留现场;docker export 导出的是文件系统快照,不含镜像历史与元数据。
回滚镜像与迁移流量
# 1. 从当前容器提取启动参数用于复现
docker inspect <容器名> --format '{{json .HostConfig}}' | jq . # 需安装 jq,或用 grep 分段读取
# 2. 以旧版本镜像重建(先摘流量,再停容器)
docker stop <容器名>
docker run -d --name <容器名>-rollback <旧版本镜像>
# 3. 验证通过后切换名称与流量
docker rename <容器名> <容器名>-broken
docker rename <容器名>-rollback <容器名>
判读依据:回滚以镜像与运行参数为准,二者缺一不可;仅回滚镜像而不回滚环境变量、挂载与网络配置,故障可能依旧存在,因此复现前必须核对 Config 与 HostConfig。迁移流量应在停止容器之前完成摘除,避免在途请求失败。
避免直接删除容器导致证据丢失
下列操作在未完成取证前执行会造成不可逆的现场损失,均为 高危 操作:
| 操作 | 破坏的内容 | 兜底与回滚方式 |
|---|---|---|
docker rm -f <容器名> | 可写层、容器日志、inspect 元数据、退出码记录 | 删除前完成本节第一段的全量快照,必要时 docker commit 留存可写层 |
docker container prune | 全部已停止容器及其日志 | 先对目标容器逐个快照,禁止在故障排查期间执行 |
docker system prune --volumes | 停止的容器、悬空镜像、未使用网络与卷 | 卷中数据无回收途径,执行前按 3.5 节方式打包备份并验证归档可读 |
truncate -s 0 <日志文件> | 日志历史,含故障时间窗口内的记录 | 先复制日志文件到其他分区再截断 |
docker volume rm <卷名> | 卷内全部数据 | 同上,备份可用性验证通过后再删除 |
处置方式:把"快照"作为删除类操作的前置步骤固化下来,可写成脚本前置检查,避免依赖人工记忆。
3.11 与宿主机排查的衔接
容器层面确认无异常后,继续在容器内寻找原因不会有效果。移交宿主机排查的判定条件:
- 容器限额充足且
memory.events、cpu.stat无触限记录,但延迟或错误率仍异常 - 容器内进程处于
D状态,等待时间与容器自身负载不成比例 - 宿主机内核日志出现
I/O error、EXT4-fs error、Out of memory、apparmor="DENIED"等硬件、文件系统或安全模块记录 - 同一宿主机上多个不相关容器同时异常
移交路径与文档索引:
| 宿主机检查项 | 命令 | 对应文档 |
|---|---|---|
| 磁盘空间、inode、文件系统只读、设备 I/O 错误 | df -hT; df -i; mount \| grep ' / '; journalctl -k \| grep -iE 'ext4\|i/o error' | ../../linux/fileSystem/disk_storage_and_file_system_operation.html、../../linux/troubleshooting/fault_case_library.html |
| 内存、OOM、swap、页缓存回收 | free -h; cat /proc/pressure/memory; vmstat 1 5; journalctl -k \| grep -i 'out of memory' | ../../linux/memoryManagement/memory_management.html |
| 进程状态、信号、句柄与进程数上限 | ps -eo pid,ppid,stat,%cpu,%mem,etime,cmd --sort=-%mem; sudo lsof -p <PID>; cat /proc/sys/fs/file-nr | ../../linux/processManagement/system_and_process_manage.html |
| cgroup 结构、限额生效路径、PSI 压力 | systemctl status docker-<容器ID>.scope; cat /sys/fs/cgroup/.../cpu.stat | ../../linux/processManagement/process_management.html |
| 宿主日志、日志轮转与容量治理 | journalctl -u docker --since '1 hour ago'; journalctl --disk-usage | ../../linux/log/log_query_and_audit.html、../../linux/log/system_log_management.html、../../linux/log/logrotate.html |
| 网络设备、路由、端口、抓包 | ip -s link; ss -tanp; iptables -S; tcpdump -i any -nn port <端口> | ../../linux/network/network_diagnosis_and_remote_connection.html |
| 安全模块拦截记录 | aa-status; dmesg -T \| grep -i apparmor; getenforce | ../../linux/securitySystem/apparmor.html |
| 指标与告警规则、阈值设定 | 容器与主机指标、告警表达式 | ../../linux/monitoring/monitoring_and_alerting.html |
移交时的命令口径差异需要注意:
- 容器内
free通常反映宿主机内存,判定容器内存是否受限必须读取容器 cgroup 接口文件 - 容器内
ps只列出容器 PID 命名空间内的进程,宿主机ps才是完整视图;docker top输出的 PID 是宿主机 PID,可用于宿主机侧的工具 - 容器内
df只反映容器挂载命名空间,宿主机df覆盖全部分区;排查"空间不足"必须回到宿主机执行 - 内核参数与内核日志只在宿主机可见,容器内
dmesg通常被限制;--sysctl仅接受已命名空间化的参数 - cgroup 版本的差异会影响接口文件命名(
throttled_time与throttled_usec、memory.limit_in_bytes与memory.max),读取前先确认版本 - 修复后按监控指标复核,而不是仅确认容器重新处于
running状态;告警规则与阈值设置参见 ../../linux/monitoring/monitoring_and_alerting.html
四、总结
- 容器排障的第一个动作是取状态与退出码,第二个动作是取事件与配置,第三步才进入容器内部;顺序颠倒会破坏现场或增加无效动作
- 命名空间决定容器内看到什么,cgroup 决定容器能用多少;前者解释"容器内外数字不一致",后者解释"是否触限"
- 容器与宿主机共享内核,内核版本、非命名空间化参数、内核日志、内核级故障只有一份,这是错层判断的根源
- 1 号进程不承担信号转发与孤儿回收,使用 exec 形式入口、脚本末尾
exec或--init可同时解决无法优雅退出与僵尸进程累积 - 退出码是分流工具而非结论:137 必须结合
State.OOMKilled、memory.events的oom_kill计数与内核日志区分容器 OOM、宿主机全局 OOM 与强制终止;143 在人工停止场景下属预期结果 - 重启策略只依据退出码,不参考健康检查;重启风暴先以
docker update --restart=no解除自动重启并保留现场,再定位启动失败原因 - 资源类判读以 cgroup 接口文件为准:内存看
memory.current与memory.events,CPU 看nr_throttled与throttled_*,IO 看io.max与io.stat;docker stats的内存包含页缓存,适合看趋势不适合定容量 - 存储类故障需区分容器视图与宿主机视图:容器内
df对应挂载命名空间,No space left on device可能来自宿主机分区空间或 inode 耗尽;bind mount 源不存在时 Docker 会静默创建空目录,使用--mount可获得显式报错 - 网络类故障先分清"容器内是否监听(含绑定地址)"与"映射与防火墙是否放行",抓包位置按容器内、网桥、veth、物理网卡逐层确定阻断点
- 日志类故障先确认日志驱动是否支持
docker logs读取,再处理暴涨与时间口径问题;日志写满的是宿主机data-root分区 - 启动即退出按配置与命令、依赖就绪、挂载、权限、脚本换行符、镜像架构六步顺序推进,退出码 126、127 与
exec format error、no such file or directory是最高效的近路 - 止损与取证在容器场景下不可分割:删除容器、删除卷、截断日志均不可逆,须先完成
inspect、日志、事件、diff、cgroup 快照与必要文件复制 - 容器侧无异常而宿主机侧有内核记录时立即移交,移交时注意容器内
free、ps、df的口径与宿主机不同,cgroup 版本差异会影响接口文件命名 - 相关文档索引:命令与参数见 ./container_management.html,日志见 ./container_logs.html,网络见 ./docker_nets.html,持久化见 ./container_data_persistance.html,守护进程与生产配置见 ../config/docker_on_ubuntu_config.html,编排见 ../orchestration/orchestration.html,镜像见 ../imageManagement/images_management.html,宿主机侧原理与案例见 ../../linux/processManagement/process_management.html、../../linux/memoryManagement/memory_management.html、../../linux/fileSystem/disk_storage_and_file_system_operation.html、../../linux/troubleshooting/fault_case_library.html