当 Docker 宿主机升级到较新的 Linux 发行版后，可能出现容器能够正常启动，但 CPU、内存或进程数限制没有生效，监控数据也与预期不一致的情况。此类问题往往与 cgroup v1、cgroup v2 的接口差异、Docker 版本、cgroup 驱动或控制器状态有关。本文整理一套从识别环境到验证修复的排查流程，帮助大家快速定位问题。🔍
一、先理解 cgroup v2 的关键变化
cgroup 是 Linux 内核用于分组管理进程并分配 CPU、内存、I/O 等资源的机制。与 v1 的多层级结构不同，cgroup v2 使用统一层级，并调整了大量控制文件名称和行为。例如，v1 中常见的 memory.limit_in_bytes，在 v2 中对应 memory.max；CPU 配额则主要通过 cpu.max 管理。具体接口语义可参考 Linux 内核文档[1]。
如果旧版 Docker、运行时组件或监控脚本仍按 v1 路径读取数据，就可能出现“文件不存在”“指标为零”或“限制看似配置成功但无法验证”等问题。需要注意，限制不生效不一定是 cgroup v2 本身故障，也可能是参数没有传递到容器、控制器未启用，或压力测试方法不正确。
二、确认宿主机使用的 cgroup 版本
首先执行以下命令：
stat -fc %T /sys/fs/cgroup/
test -f /sys/fs/cgroup/cgroup.controllers && echo cgroup-v2
docker info | grep -i cgroup
如果第一条命令返回 cgroup2fs，或者存在 cgroup.controllers 文件，说明系统使用 cgroup v2。docker info 应重点检查 Cgroup Driver、Cgroup Version，以及末尾是否存在“No swap limit support”等警告。Docker 官方也建议通过这些信息检查内核能力，详见 运行时指标文档[2]。
三、检查 Docker 与运行时版本
执行 docker version、containerd --version 和 runc --version，确认 Docker Engine、containerd、runc 不是过旧版本。较早版本可能无法完整识别 cgroup v2，常见表现包括 daemon 启动失败、容器创建报错，或资源参数未正确写入统一层级。
升级时不要只替换 Docker 客户端，而应同步检查服务端及底层运行时。生产环境建议使用发行版仓库或 Docker 官方渠道提供的兼容版本，并先在测试节点验证。升级前还应备份 /etc/docker/daemon.json，避免存储驱动、镜像仓库和日志配置丢失。🛠️
四、判断资源参数是否真正写入
创建一个测试容器，并明确设置限制：
docker run -d --name cgroup-test --memory=512m --cpus=0.5 --pids-limit=100 nginx
docker inspect cgroup-test --format '{{json .HostConfig}}'
docker stats cgroup-test
检查 HostConfig 中的 Memory、NanoCpus、CpuQuota、CpuPeriod 和 PidsLimit。如果这些值为空或为零，说明问题发生在 Docker 命令、Compose 配置或上层部署工具，而不是内核执行阶段。Docker 默认不会自动限制容器资源，必须显式配置相关参数，详细说明可查看 Docker 资源限制文档[3]。
如果使用 Compose，应检查 deploy.resources 是否被当前运行方式支持。某些配置主要面向编排场景，直接执行 docker compose up 时应以实际生成的容器 HostConfig 为准，不能只看 YAML 文件判断限制已生效。
五、直接核对 cgroup v2 控制文件
先获取容器主进程 PID：
PID=$(docker inspect -f '{{.State.Pid}}' cgroup-test)
cat /proc/$PID/cgroup
在 cgroup v2 环境中，输出通常包含“0::/某个路径”。将该路径拼接到 /sys/fs/cgroup 后，查看以下文件：
- memory.max：内存硬限制，512 MiB 通常显示为对应字节数。
- memory.current：当前内存占用。
- cpu.max：CPU 配额与周期，例如设置半个 CPU 时会出现相应比例。
- pids.max：容器允许创建的最大进程数。
- memory.events：检查是否发生 max、oom 或 oom_kill 事件。
若这些文件中的限制值正确，说明内核已接收配置。此时应重新检查测试负载、监控工具和统计口径。例如 --cpus=0.5 表示可使用半个 CPU 的计算时间，不代表多核主机上的总 CPU 百分比一定固定显示为 50%。
六、排查控制器和 cgroup 驱动
执行 cat /sys/fs/cgroup/cgroup.controllers，确认 cpu、memory、io、pids 等控制器是否存在。还可检查父级目录的 cgroup.subtree_control。如果目标控制器没有向下启用，子级 cgroup 就无法创建对应资源接口。不要在生产环境中随意手工修改 systemd 管理的层级，否则可能在服务重启后失效。
对于以 systemd 作为初始化系统的宿主机，通常应让 Docker 与系统资源管理方式保持一致。可在 /etc/docker/daemon.json 中配置 exec-opts 为 native.cgroupdriver=systemd，然后执行 systemctl daemon-reload 与 systemctl restart docker。修改前需检查 JSON 语法，并评估重启 Docker 对现有容器的影响。若处于 Kubernetes 环境，节点运行时与 kubelet 的 cgroup driver 也必须保持一致。
七、常见误区与修复顺序
- 不要继续使用只支持 cgroup v1 路径的旧监控脚本，应改为读取 memory.current、cpu.stat、io.stat 等 v2 文件。
- 不要仅通过 docker stats 判断硬限制，应同时核对 docker inspect 和内核控制文件。
- 确认宿主机没有同时存在混合层级、异常启动参数或被其他管理程序接管的控制器。
- 遇到 swap 限制异常时，应分别检查 memory.max、memory.swap.max、宿主机 swap 状态及内核支持。
- 修复后重新创建容器，因为仅重启旧容器不一定会应用已经变更的创建参数。
总结
排查 cgroup v2 兼容问题时，建议按照“确认版本、检查 Docker 信息、核对容器参数、定位 cgroup 路径、读取控制文件、执行压力验证”的顺序处理。✅ 只要对应的 memory.max、cpu.max 或 pids.max 已正确写入，并在压力场景下出现限制、节流或 OOM 事件，就说明内核侧资源控制已经生效。若配置值根本没有写入，应优先检查 Docker、Compose、运行时版本和 cgroup 驱动，而不是直接修改内核参数。
