容器排障的难点不在命令数量,而在证据的归属:现象出现在容器内,产生现象的资源却由宿主机与内核提供。本文按起源、原理、实现、总结四部分组织,原理部分说明命名空间与 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 排查手段分散带来的效率问题

容器排障所用的命令分布在四个层面,文档与经验的割裂造成三类浪费:

  1. 入口分散:容器自身的状态与配置在 docker inspect,限额在 cgroup 接口文件,进程视图在 docker top 与宿主机 ps,网络视图在 docker network inspect 与 iptables,同一故障需要在多个入口之间来回切换,容易漏项。
  2. 无 shell 场景缺少固定路径:镜像为 distroless、scratch 或应用镜像,容器内没有 shell 与调试工具,docker exec 直接失败,此时如果没有 nsenter、docker cp、/proc/<PID>/root 这类替代路径,排查会中断。
  3. 止损与取证顺序无约束:容器可写层与日志会随 docker rm 一并消失,先删容器再分析根因的做法使同类问题重复发生。

因此需要一份按固定顺序组织的排查链路:先取状态与退出码确定方向,再取事件与配置确认变更,最后进入容器或命名空间做细粒度诊断;在每个环节明确判读依据与可回退的处置动作。

二、原理:隔离、限额、退出码与状态机

2.1 容器的隔离机制

容器由两组内核机制组合而成,二者职责不同,排障时的观察对象也不同。

命名空间与 cgroup 的分工

机制 作用范围 决定的内容 排障观察点
命名空间(namespace) 隔离资源的可见性 容器内看到什么 容器内 ps、ip addr、mount、/etc/resolv.conf
cgroup 限制与计量资源用量 容器能用多少 宿主机 /sys/fs/cgroup/... 下的接口文件与计数

涉及的命名空间类型:

  1. mount(mnt):容器拥有独立的挂载表,这是容器内 df 与宿主机 df 不一致的直接原因
  2. PID:容器内的 1 号进程是容器入口进程在容器命名空间内的映射,宿主机上它有另一个 PID
  3. network(net):容器拥有独立的网卡、路由表、iptables 表与端口空间
  4. IPC:独立的 System V IPC 与 POSIX 消息队列
  5. UTS:独立的主机名与域名,--hostname 即作用于此处
  6. user:uid/gid 映射,userns-remap 启用后容器内的 root 在宿主机上是普通用户
  7. cgroup:决定 /sys/fs/cgroup 的视图根。cgroup v2 下容器内读取 memory.max 看到的是容器自身的限额;--cgroupns=host 时看到的是宿主机视图
  8. time:时钟偏移隔离,仅部分运行时与较新内核支持,未作为默认隔离项

容器与宿主共享内核带来的影响

  1. 内核版本只有一份:容器镜像内的 glibc、内核头文件或 io_uring、eBPF 等特性依赖宿主内核版本。在较新发行版上构建、在较旧内核上运行,可能出现系统调用缺失导致启动失败。
  2. 非命名空间化的内核参数不可在容器内修改:--sysctl 只接受已命名空间化的参数(如 net.core.somaxconn、net.ipv4.tcp_tw_reuse),vm.swappiness、fs.file-max、kernel.pid_max 等必须在宿主机设置。
  3. 内核级故障影响所有容器:内核 panic、内核模块缺陷、宿主机全局 OOM、存储设备错误会同时影响该主机上全部容器,现象表现为多个不相关容器同时异常。
  4. 内核日志是共享的:容器内一般看不到内核日志,dmesg 在容器内通常被限制;OOM、I/O error、AppArmor 拒绝等记录需在宿主机执行 dmesg -T 或 journalctl -k 查看。

PID 1 与信号处理

  1. 容器内的 1 号进程是镜像入口进程(ENTRYPOINT 或 CMD),不是 init。内核对该进程的信号处理有特殊语义:未注册处理函数的信号默认动作被忽略,SIGKILL 与 SIGSTOP 除外。
  2. 由此产生两个后果:其一,docker stop 发送的 SIGTERM 如果没有被 PID 1 显式捕获,进程不会退出,守护进程等待宽限期后发送 SIGKILL,退出码为 137;其二,PID 1 不承担回收职责,父进程已退出的子进程被 PID 1 收养后不被 wait() 回收,长期运行会累积僵尸进程。
  3. 判断信号是否被转发,观察 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.* 块设备读写速率硬限

参数对进程行为的实际影响

  1. CPU 配额是节流而非拒绝:配额在周期内用尽后,组内任务被强制暂停到下一周期,表现为响应时间出现周期性的毛刺与延迟抬高,而 CPU 使用率显示为一个接近配额上限的平台。单线程应用的限额若低于一个核,进程永远无法跑满一个核。
  2. 内存上限触发的是组内 OOM:memory.max 触达时,内核在该 cgroup 内选择进程终止(memory.oom.group 决定是否整组终止),不会等待宿主机全局内存耗尽。memory.high 触达时执行限速回收,表现为分配变慢与直接回收增加,不直接杀进程。
  3. swap 的默认口径容易误判:只设置 --memory 2g 时,容器可用的内存与 swap 总量默认为 2 倍的 --memory,仍可使用 swap;--memory 2g --memory-swap 2g 表示禁用 swap。宿主机内存紧张而容器允许 swap 时,容器进程会被换出,表现为延迟升高但容器不被杀。
  4. 限额之外的宿主机约束同样生效:容器限额宽松而宿主机物理内存不足时,全局 OOM 可能选中容器内占用最高的进程,此时容器 cgroup 的 memory.events 中 oom_kill 不增长,需在宿主机内核日志中确认。
  5. 内存统计口径: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、编排层缩容 确认是否为预期终止,检查是否缺少优雅退出逻辑

需要严格区分的两点:

  1. 137 不等于 OOM。137 只说明进程收到 SIGKILL,来源有三种:容器内存超限、人工或编排层强制终止、docker stop 宽限期结束后的兜底强杀。区分依据见 3.4 节。
  2. 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 除手动停止外都重启 手动停止的状态会被记录,守护进程重启后不再拉起,生产环境常用

重启策略的关键限制:

  1. 判定依据只有退出码,不参考健康检查结果。应用活着但不可用(如连接池耗尽、线程全部阻塞)不会触发重启。
  2. 重启风暴的成因是策略与依赖不可用叠加:应用启动即因依赖不可达而退出,on-failure 或 always 反复拉起。RestartCount 与 docker events 中的 restart 事件是判断依据。
  3. 运行时可动态调整:docker update --restart=no <容器> 可立即止损,无需重建容器。
  4. 守护进程重启对容器的影响由 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 时的诊断手段

  1. 借助 /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/* 的编号可用于确认两个容器或进程是否处于同一命名空间。

  1. 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,否则可能因凭据映射失败而报错。

  1. 临时调试容器共享目标容器的命名空间(宿主侧需要有调试镜像):
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 仅在调试会话期间生效,调试容器退出即消失。

  1. 不进入容器完成文件检查与修改:
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。

处置方式:

  1. 镜像层面使用 exec 形式的入口,避免 shell 作为 PID 1:
ENTRYPOINT ["java", "-jar", "/app/app.jar"]
  1. 若必须使用 shell 脚本,脚本末尾使用 exec 替换 shell 进程:
#!/bin/sh
set -e
# 初始化动作
exec "$@"
  1. 使用 --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 的典型特征

处置方式:

  1. 先核对宿主机可用内存与压力,再决定调整方向:
free -h
cat /proc/meminfo | grep -E 'MemTotal|MemAvailable|SwapTotal|SwapFree'
cat /proc/pressure/memory
  1. 确认容器限额不足时提升上限,同时按峰值加余量设置:
docker update --memory 4g --memory-swap 4g <容器名>
  1. 宿主机全局 OOM 时,扩大容器限额无效,需降低同宿主其他容器的内存占用,或迁移部分容器到其他主机;内存机制与回收行为参见 ../../linux/memoryManagement/memory_management.html。
  2. JVM 类应用需确认 JVM 能感知 cgroup 限额,否则堆大小按宿主机内存计算,容器限额会被提前触达。Java 8u191 及以上可通过 -XX:MaxRAMPercentage=70 按限额比例设置堆上限。
  3. 需要更早感知内存压力而非直接被杀时,可设置 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 的影响

  1. 宿主机内存不足会放大容器侧表现:页缓存被回收导致容器内读文件变慢;直接回收导致分配延迟上升;最终触发全局 OOM 终止容器内进程,退出码 137 而容器 oom_kill 计数不增长。
  2. swap 未禁用时延迟与内存统计都会失真:容器进程被换出后 RSS 下降,docker stats 的内存数值随之下降,容易被误读为"内存问题已缓解",实际表现为延迟升高。判断依据是宿主机 swap 的换入换出速率:
vmstat 1 5
grep -E 'pswpin|pswpout' /proc/vmstat
  1. 区分匿名页与文件页:memory.stat 中 anon 持续增长指向应用内存泄漏,file 增长通常由读写文件与日志产生,可通过增大限额或减少缓存压力缓解,不属泄漏。
  2. 内存与压力的完整机制、回收与 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}}'

判读依据:

  1. /etc/resolv.conf 中出现 127.0.0.11 表示使用 Docker 内嵌 DNS,具备容器名解析能力;该文件被挂载覆盖或指向不可达的外部 DNS 时,解析失败与此有关。
  2. 默认 bridge 网络只提供 IP 互通,不提供容器名解析(历史 --link 除外);自定义网络提供基于容器名与 --network-alias 的解析。同名别名对应多个容器时返回结果在多个 IP 间轮询,表现为间歇性连接失败。
  3. 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 与宿主机排查的衔接

容器层面确认无异常后,继续在容器内寻找原因不会有效果。移交宿主机排查的判定条件:

  1. 容器限额充足且 memory.events、cpu.stat 无触限记录,但延迟或错误率仍异常
  2. 容器内进程处于 D 状态,等待时间与容器自身负载不成比例
  3. 宿主机内核日志出现 I/O error、EXT4-fs error、Out of memory、apparmor="DENIED" 等硬件、文件系统或安全模块记录
  4. 同一宿主机上多个不相关容器同时异常

移交路径与文档索引:

宿主机检查项 命令 对应文档
磁盘空间、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

移交时的命令口径差异需要注意:

  1. 容器内 free 通常反映宿主机内存,判定容器内存是否受限必须读取容器 cgroup 接口文件
  2. 容器内 ps 只列出容器 PID 命名空间内的进程,宿主机 ps 才是完整视图;docker top 输出的 PID 是宿主机 PID,可用于宿主机侧的工具
  3. 容器内 df 只反映容器挂载命名空间,宿主机 df 覆盖全部分区;排查"空间不足"必须回到宿主机执行
  4. 内核参数与内核日志只在宿主机可见,容器内 dmesg 通常被限制;--sysctl 仅接受已命名空间化的参数
  5. cgroup 版本的差异会影响接口文件命名(throttled_time 与 throttled_usec、memory.limit_in_bytes 与 memory.max),读取前先确认版本
  6. 修复后按监控指标复核,而不是仅确认容器重新处于 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