• 适用对象：OceanBase 运维、交付和性能排查人员。
• 不同OB版本的参数默认值、动态生效属性和内核要求可能不同，执行前请以目标版本文档与实际参数为准。

一、概览

cgroup（Control Groups）是 Linux 内核提供的资源分组与约束机制。OceanBase 可将租户工作线程和大部分租户后台线程归入对应的 cgroup 目录，并通过 Linux cgroup 对 CPU 等资源进行约束。

OceanBase 的 observer 是单一进程，但内部线程既有租户级线程，也有进程级共享线程。因此，租户 Unit 的 CPU 规格、租户线程池大小和 Linux cgroup CPU 配额是三个不同层面的概念：

• Unit CPU 规格：OceanBase 的租户资源规格和调度基础。
• 线程池与并行线程参数：决定租户可并发持有、调度或申请的线程数量。
• cgroup CPU 配额：Linux 内核对归入某个租户 cgroup 的线程施加的实际 CPU 使用上限或竞争权重。

二、版本兼容性

2.1 OceanBase 版本

V$OB_CGROUP_CONFIG / GV$OB_CGROUP_CONFIG 的支持起始版本如下：

2.2 Linux cgroup 版本

本文使用的文件接口为：

cpu.cfs_period_us
cpu.cfs_quota_us
cpu.shares

这些属于 cgroup v1 的 cpu 控制器。若操作系统采用纯 cgroup v2，CPU 接口通常是 cpu.max、 cpu.weight，不能直接套用本文步骤。部署前应确认目标 OceanBase 版本对操作系统 cgroup 形态的兼容性。

三、cgroup 如何限制租户 CPU

3.1 租户目录与线程归属

启用 cgroup 且软链接有效后，OceanBase 会在以下目录下创建租户及资源组目录：

/sys/fs/cgroup/cpu/oceanbase/
├── other/
├── tenant_0001/
│   ├── OBCG_DEFAULT/
│   ├── OBCG_ELECTION/
│   └── OBCG_STORAGE/
└── tenant_1001/
    ├── OBCG_DEFAULT/
    ├── OBCG_WR/
    └── ...

其中：

• 租户工作线程和大部分租户后台线程可按租户、资源组归类。
• 网络线程是共享线程，不在租户级 cgroup 隔离范围内。
• 租户目录下可进一步存在 OBCG_* 资源组目录，以支持 User、SQL、Function 级资源隔离。

3.2 硬上限：CFS 配额

cpu.cfs_period_us 定义 CPU 调度周期， cpu.cfs_quota_us 定义该周期内允许使用的总 CPU 时间。

租户可持续使用的逻辑 CPU 核数上限 ≈ cfs_quota_us / cfs_period_us

示例：将 tenant_1001 限制在约 2 个逻辑 CPU 核内。

TENANT_CGROUP=/sys/fs/cgroup/cpu/oceanbase/tenant_1001




echo 100000 > 
"
${TENANT_CGROUP}/cpu.cfs_period_us"


echo 200000 > 
"
${TENANT_CGROUP}/cpu.cfs_quota_us"

示例：限制在约 0.2 个逻辑 CPU 核内。

TENANT_CGROUP=/sys/fs/cgroup/cpu/oceanbase/tenant_1001




echo 50000 > 
"
${TENANT_CGROUP}/cpu.cfs_period_us"


echo 10000 > 
"
${TENANT_CGROUP}/cpu.cfs_quota_us"

cpu.cfs_quota_us=-1 通常表示不施加 CFS CPU 硬上限。

3.3 相对权重： cpu.shares

cpu.shares 用于 CPU 竞争时的相对分配， 不是硬上限。

echo 1024 > /sys/fs/cgroup/cpu/oceanbase/tenant_1001/cpu.shares


echo 512  > /sys/fs/cgroup/cpu/oceanbase/tenant_1002/cpu.shares

当两个租户同时满载时，理论竞争比例约为：

tenant_1001：1024 / (1024 + 512) ≈ 66.7%
tenant_1002： 512 / (1024 + 512) ≈ 33.3%

当其他租户空闲时，当前租户仍可使用空闲 CPU。因此，需要绝对 CPU 上限时应使用 cpu.cfs_quota_us 与 cpu.cfs_period_us。

V4.3.5 官方文档将直接修改这些文件定位为应急操作。生产环境应优先使用 DBMS_RESOURCE_MANAGER 创建资源组、资源计划及映射关系，避免 Linux 文件配置与数据库资源策略不一致。

四、开启与关闭的区别

4.1 V4.2.1 实践中的线程数计算

以下为 OceanBase 企业版 V4.2.1、2C Unit、32C 服务器环境中的实践结论；它用于理解 cgroup 关闭时的弹性 CPU 使用，不应替代其他版本的容量评估。

该实践中：

• 关闭 cgroup 后，未启用并行时，2C 租户的工作线程可能并发消耗约 8 个 CPU 核的算力；启用并行后，工作线程与并行线程合计可能达到约 8 + 20 = 28 个 CPU 核的运行规模。
• 开启 cgroup 后，线程数量不会因此减少，但归入租户 cgroup 的线程总 CPU 使用会被限制在约 2 个 CPU 核。
• 文中 OCP 的 400%、1400%、100% 为该 2C Unit 场景下的 租户 CPU 使用率口径：例如 8C 相对于 2C 为 400%，28C 相对于 2C 为 1400%。不要将该百分比直接理解为整台 32C 主机的 CPU 使用率。

这说明： 限制线程数不等于限制 CPU 使用率。线程数仅限制可并发执行的规模；只有开启 cgroup 并正确设置 CPU 配额后，才会由内核对租户 CPU 时间实施硬约束。

4.2 相关线程参数

下列参数说明来自 V4.2.1 相关实践，升级或变更版本前应通过 SHOW PARAMETERS 核实当前版本的实际取值、范围和是否动态生效。

五、配置 cgroup

以下以 /home/admin/oceanbase 为 OceanBase 安装目录、 admin 为运行用户举例。所有 OBServer 节点均需配置。

5.1 检查现有挂载

mount | grep cgroup

ls -ld /sys/fs/cgroup /sys/fs/cgroup/cpu

若系统已经由 systemd 挂载了可用的 cgroup v1 CPU 控制器，不要重复挂载或覆盖已有层级。

5.2 创建 cgroup v1 CPU 层级

仅在尚未存在可用 cgroup v1 CPU 控制器时，按官方示例创建：

sudo mount -t tmpfs cgroups /sys/fs/cgroup



sudo mkdir /sys/fs/cgroup/cpu

sudo chown admin:admin -R /sys/fs/cgroup/cpu



sudo mount -t cgroup -o cpu cpu /sys/fs/cgroup/cpu



sudo mkdir /sys/fs/cgroup/cpu/oceanbase

sudo chown admin:admin -R /sys/fs/cgroup/cpu/oceanbase

若 cpu、 cpuacct、 cpuset 合并挂载在同一层级，还需继承父组的 CPU 和 NUMA 内存节点配置：

sudo sh -c 
'cat /sys/fs/cgroup/cpu/cpuset.cpus > /sys/fs/cgroup/cpu/oceanbase/cpuset.cpus'

sudo sh -c 
'cat /sys/fs/cgroup/cpu/cpuset.mems > /sys/fs/cgroup/cpu/oceanbase/cpuset.mems'

设置子 cgroup 继承属性：

sudo sh -c 
'echo 1 > /sys/fs/cgroup/cpu/oceanbase/cgroup.clone_children'

5.3 建立软链接

cd /home/admin/oceanbase

ln -sfn /sys/fs/cgroup/cpu/oceanbase cgroup

ls -l cgroup

预期结果：

cgroup -> /sys/fs/cgroup/cpu/oceanbase

5.4 开启功能

使用 root 登录 sys 租户执行：

ALTER 
SYSTEM 
SET enable_cgroup = 
true;

检查参数是否已在所有节点生效：

SELECT svr_ip, svr_port, 
name, 
value


FROM oceanbase.GV$OB_PARAMETERS


WHERE 
name = 
'enable_cgroup';

V4.3.5 中，软链接建立且功能开启后无需额外重启 OBServer；V3.2.4 则需要在建立软链接后重启 observer。

六、验证与监控

6.1 主机侧验证

mount | grep -E 
'cgroup|/sys/fs/cgroup/cpu'

ls -ld /sys/fs/cgroup/cpu/oceanbase

readlink -f /home/admin/oceanbase/cgroup

find /sys/fs/cgroup/cpu/oceanbase -maxdepth 2 -
type d

检查指定租户的实际配置和限流统计：

TENANT_CGROUP=/sys/fs/cgroup/cpu/oceanbase/tenant_1001



cat 
"
${TENANT_CGROUP}/cpu.cfs_period_us"

cat 
"
${TENANT_CGROUP}/cpu.cfs_quota_us"

cat 
"
${TENANT_CGROUP}/cpu.shares"

cat 
"
${TENANT_CGROUP}/cpu.stat"

当 CPU 配额生效且发生限流时， cpu.stat 中的 nr_throttled、 throttled_time 会增长。

6.2 数据库侧验证

在用户租户中执行：

SELECT *


FROM oceanbase.GV$OB_CGROUP_CONFIG


ORDER 
BY svr_ip, cgroup_path;

重点检查：

• 各 OBServer 是否均返回记录；
• CGROUP_PATH 是否包含 /oceanbase/tenant_ 及 OBCG_* 目录；
• CFS_QUOTA_US、 CFS_PERIOD_US、 SHARES 是否符合预期。

6.3 线程与 CPU 异常排查

按线程查看 observer 的 CPU 消耗：

top -H -p 
"
$(pidof observer)"

排查时应结合以下维度，而不是仅看租户 Unit 规格：

1. enable_cgroup 是否开启；
2. cgroup 目录和软链接是否有效；
3. 租户 cpu.cfs_quota_us、 cpu.cfs_period_us、 cpu.shares；
4. cpu_quota_concurrency、 workers_per_cpu_quota；
5. px_workers_per_cpu_quota 与是否存在并行 SQL；
6. cpu.stat 是否显示 cgroup 限流；
7. OCP 租户 CPU 指标的统计口径，以及主机整体 CPU 使用率。

七、重启或升级后的恢复

OceanBase 官方文档明确指出：

• OBServer 主机重启后， /sys/fs/cgroup/ 下创建的 cgroup 子目录可能被清除；
• OceanBase 升级后，需要重新配置 cgroup；
• 每台 OBServer 都必须单独恢复。

7.1 恢复清单

在每台完成重启或升级的 OBServer 上执行：

[ ] 确认 cgroup v1 CPU 控制器仍已挂载
[ ] 重新创建 /sys/fs/cgroup/cpu/oceanbase 并恢复 admin 的目录权限
[ ] 若为 cpuset 联合挂载，重新初始化 cpuset.cpus 和 cpuset.mems
[ ] 重新设置 cgroup.clone_children=1
[ ] 检查新 OceanBase 安装目录的 cgroup 软链接
[ ] 确认 enable_cgroup=true
[ ] 验证 GV$OB_CGROUP_CONFIG、租户目录和 cpu.stat

示例：

sudo mkdir -p /sys/fs/cgroup/cpu/oceanbase

sudo chown admin:admin -R /sys/fs/cgroup/cpu/oceanbase

sudo sh -c 
'echo 1 > /sys/fs/cgroup/cpu/oceanbase/cgroup.clone_children'




cd /home/admin/oceanbase

ln -sfn /sys/fs/cgroup/cpu/oceanbase cgroup

升级后若 OceanBase 安装路径发生变化，必须在新安装目录中重新建立 cgroup 软链接。

八、使用建议

1. 先明确隔离目标：需要硬限制 CPU 使用率时启用 cgroup；只希望在资源空闲时让租户弹性抢占 CPU，则需评估关闭 cgroup 的风险。
2. 不要把 Unit CPU 当作天然硬上限：关闭 cgroup 时，线程并发和并行执行可能使实际 CPU 消耗显著高于 Unit 规格。
3. 生产优先资源计划：通过 DBMS_RESOURCE_MANAGER 管理资源组和资源计划；直接写 cgroup 文件仅作为受控的应急手段。
4. 按节点检查：cgroup 是 OBServer 主机本地资源，任何一台节点配置缺失都会造成隔离不一致。
5. 变更后做压测：同时验证业务延迟、CPU 限流次数、合并、复制、日志归档及其他后台任务是否受到影响。
6. 关注小规格租户的权衡：官方文档不建议在单租户、租户强依赖或 2C/4C 小规格租户场景中轻易使用 cgroup；但关闭 cgroup 也可能带来租户 CPU 弹性超用。应基于业务隔离需求和压测结果决策。