cgroup v2 io.max怎么配置或排查

给 Linux 工作负载做磁盘限速时，cgroup v2 的 io.max 是直接入口：它按块设备的主次设备号，为一个非 root cgroup 设置读写 BPS 或 IOPS 上限。写入后 I/O 会在达到上限时被延迟，短时突发仍可能出现，所以不要只看一次吞吐就判断配置失败。

排查顺序很固定：先确认目标进程属于哪个 cgroup，再确认设备的 MAJ:MIN，最后把同一个设备号同时对照 io.max、io.stat 和 io.pressure。三者对不上，调大数字也不会解决问题。

先分清 io.max 和 io.weight 的控制目标

如果需求是“这个备份任务写盘不能超过某个速度”，选 io.max；如果需求是“多个 cgroup 竞争同一设备时，让某个服务获得更高比例”，才考虑 io.weight。前者是绝对上限，后者是相对分配，不能用权重推算出固定 MB/s。

io.max 位于非 root cgroup。它的限制可以在父级资源不足时与其他限制叠加，配置值也不等于设备一定能达到的物理性能。对于带缓存的写入，还要留意应用完成写入与底层 writeback 发生的时间差。

先确认 cgroup 层级和块设备，再写入 io.max

下面示例把工作负载放到 demo-io，把 8:16 当作待替换的设备号。这个数字只是格式示例，现场必须从 lsblk 的输出中确认，不能凭磁盘名称猜测。

# 确认当前是 cgroup v2，并检查父级是否能提供 io 控制器
CG_ROOT=/sys/fs/cgroup
CG="$CG_ROOT/demo-io"
test -f "$CG_ROOT/cgroup.controllers" || { echo "未找到 cgroup v2 根目录"; exit 1; }
grep -qw io "$CG_ROOT/cgroup.controllers" || { echo "当前内核未提供 io 控制器"; exit 1; }

# 只有父级已启用 io 时，子 cgroup 才会出现 io.max
grep -qw io "$CG_ROOT/cgroup.subtree_control" || \
  printf '+io\n' | sudo tee "$CG_ROOT/cgroup.subtree_control" >/dev/null
sudo mkdir -p "$CG"
test -f "$CG/io.max" || { echo "io.max 尚未出现在目标 cgroup"; exit 1; }

# 用 lsblk 找到实际 MAJ:MIN；8:16 只是下面命令的占位示例
lsblk -o NAME,MAJ:MIN,MOUNTPOINTS
DEV=8:16

# 读 2 MiB/s、写 1 MiB/s，并把随机 I/O 次数限制为每秒 120 次
printf '%s rbps=2097152 wbps=1048576 riops=120\n' "$DEV" | \
  sudo tee "$CG/io.max" >/dev/null
cat "$CG/io.max"

这里最容易漏掉的是层级关系：io 出现在根目录的 cgroup.controllers，只说明它可用；真正把控制能力分发给子 cgroup，还要看父目录的 cgroup.subtree_control。如果系统由 systemd 管理服务，手工写入也可能在 unit 重载或重启时被上层资源配置覆盖。

用 io.stat 和 io.pressure 判断限制是否落在正确对象

写入成功后先读回 io.max，再读同一 cgroup 的统计。io.stat 的行也以 MAJ:MIN 为键；如果它没有出现你刚配置的设备号，优先怀疑进程没有走这块设备、设备号写错，或统计发生在后代 cgroup。

# 检查目标 PID 的 cgroup 归属，PID 和路径都要替换成现场值
PID=12345
grep '0::' "/proc/$PID/cgroup"
grep -q "0::/demo-io" "/proc/$PID/cgroup" || {
  echo "目标进程不在 demo-io，先修正归属再测 I/O"
  exit 1
}

# 读回实际限制，确认设备号和四个方向字段没有写错
cat /sys/fs/cgroup/demo-io/io.max

# 统计 cgroup 对各个块设备的读写字节数、I/O 次数和丢弃量
cat /sys/fs/cgroup/demo-io/io.stat

# 看工作负载是否因为 I/O 等待而形成压力；只读不修改配置
cat /sys/fs/cgroup/demo-io/io.pressure

可以按三种结果分流。第一，io.max 与 io.stat 都包含同一 MAJ:MIN，而压力在限速后上升，说明规则至少落到了正确的统计对象；接下来要判断阈值是否太低。第二，io.max 有规则但 io.stat 没有同号，说明设备路径或进程归属不对。第三，统计持续增长但 PSI 没明显变化，可能是负载仍未触碰上限，或者 I/O 被页缓存吸收，不能只凭单次测试下结论。

解除某一个方向的限制时，把该键写成 max，不要覆盖整行。例如只取消写 IOPS：printf '%s wiops=max\n' "$DEV" | sudo tee "$CG/io.max"。修改后再次读回整行，确认其他方向的限制仍在。

常见问题

为什么写了 io.max 但速度没有立刻降下来？

内核文档说明达到 BPS 或 IOPS 限制后 I/O 会被延迟，同时允许临时突发。再加上页缓存和测试窗口过短，瞬时吞吐不一定等于长期限制，应该拉长观察时间并对照 io.stat。

io.max 可以写 2M、1G 这样的单位吗？

内核接口字段按数值解释，建议把字节数或每秒 I/O 次数换算成整数后写入。上层工具可能接受带单位的配置，但不能把上层语法直接当作 io.max 文件格式。

读回 io.max 正确，为什么业务仍然卡顿？

先确认进程实际属于目标 cgroup，并确认它访问的设备号与规则行一致；如果两者都正确，再检查阈值是否过低、是否与父级限制叠加，以及 systemd 是否会覆盖手工改动。

调参时建议先记录未限速时的 io.stat 和 io.pressure，再一次只改一个方向。这样能把“规则没有命中”和“规则命中了但额度不合适”分开，后续迁移到 systemd 或容器编排配置时也更容易复现。