使用 NUMA Node 绑定启动 YMatrix 集群

本文档介绍了在 YMatrix 集群启动时使用 NUMA Node 绑定的方法。通过 mxtool init numa-wrapper 生成 NUMA Wrapper 脚本和 NUMA 映射配置后，可以在 mxstart 启动过程中为 postmaster 进程绑定 NUMA Node，使各实例优先使用本地 NUMA Node 的 CPU 和内存资源。

适用版本：YMatrix 6.8.2 及以上。

1 前提条件

执行前请确认：

集群版本为 YMatrix 6.8.2 或以上。
各节点已安装 numactl。
集群处于正常运行状态。
当前用户具备在各节点写入 Wrapper 脚本和 NUMA 映射配置文件的权限。

2 功能说明

YMatrix 从 6.8.2 开始支持在 mxstart 启动过程中通过 Wrapper 对 postmaster 进程进行 NUMA Node 绑定。

mxtool init numa-wrapper 命令用于根据当前集群拓扑自动生成以下文件，并可部署到各节点：

NUMA Wrapper 脚本，例如 /home/mxadmin/scripts/mxstart_numa_wrapper.sh。
NUMA 映射配置，例如 /home/mxadmin/scripts/mxstart_numa_map.conf。

默认内存策略为 preferred：

优先从绑定的 NUMA Node 分配内存。
当本地 NUMA Node 内存不足时，允许从其他 NUMA Node 分配内存。

如果需要严格限制内存只能从指定 NUMA Node 分配，可以使用 --memory-policy=membind。

注意！ mxtool init numa-wrapper 只生成和部署 Wrapper 文件，不会修改当前运行中的集群，也不会自动重启数据库实例。NUMA Node 绑定需要在下一次使用 mxstart 启动集群时生效。

3 生成 NUMA Wrapper 配置

3.1 预览生成结果

执行以下命令只预览将要生成的 Wrapper 脚本和 NUMA 映射配置，不会修改远端文件：

mxtool init numa-wrapper

输出中出现以下内容表示当前为 Dry Run 模式：

Mode: DRY RUN (no remote files will be changed)

示例输出：

[mxadmin@sdw ~]$ mxtool init numa-wrapper

Mode: DRY RUN (no remote files will be changed)

host=sdw action=would-write wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf memory_policy=preferred
host=sdw-other action=would-write wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf memory_policy=preferred

host=sdw hostname=sdw numa_nodes=0,1
/data/mxdata_20260622122230/master/mxseg-1 0
/data/mxdata_20260622122230/primary/mxseg0 1
/data/mxdata_20260622122230/primary/mxseg1 0
...

host=sdw-other hostname=sdw-other numa_nodes=0,1
/data/mxdata_20260622122230/primary/mxseg8 0
/data/mxdata_20260622122230/primary/mxseg9 1
...

每一行实例映射的含义为：

<数据目录> <NUMA Node ID>

例如：

/data/mxdata_20260622122230/primary/mxseg0 1

表示该实例启动时会绑定到 NUMA Node 1。

3.2 部署 Wrapper 文件

确认 Dry Run 输出符合预期后，执行以下命令将 Wrapper 脚本和 NUMA 映射配置部署到各节点：

mxtool init numa-wrapper --apply

输出中出现以下内容表示当前为 Apply 模式：

Mode: APPLY (remote files will be deployed)

示例输出：

[mxadmin@sdw ~]$ mxtool init numa-wrapper --apply

Mode: APPLY (remote files will be deployed)

host=sdw action=deployed wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf memory_policy=preferred
host=sdw backups=/home/mxadmin/scripts/mxstart_numa_wrapper.sh.bak.20260628130639,/home/mxadmin/scripts/mxstart_numa_map.conf.bak.20260628130639

host=sdw-other action=deployed wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf memory_policy=preferred
host=sdw-other backups=/home/mxadmin/scripts/mxstart_numa_wrapper.sh.bak.20260628130639,/home/mxadmin/scripts/mxstart_numa_map.conf.bak.20260628130639

host=sdw hostname=sdw numa_nodes=0,1
/data/mxdata_20260622122230/master/mxseg-1 0
/data/mxdata_20260622122230/primary/mxseg0 1
/data/mxdata_20260622122230/primary/mxseg1 0
...

host=sdw-other hostname=sdw-other numa_nodes=0,1
/data/mxdata_20260622122230/primary/mxseg8 0
/data/mxdata_20260622122230/primary/mxseg9 1
...

如果目标文件已存在，命令会自动备份原文件。备份文件路径会显示在 backups= 后。

3.3 使用 `membind` 内存策略

如果需要将内存分配严格限制在绑定的 NUMA Node 上，执行：

mxtool init numa-wrapper \
    --memory-policy=membind \
    --apply

注意！ membind 策略更严格。如果绑定的 NUMA Node 内存不足，实例可能无法正常分配内存。生产环境使用前应确认各 NUMA Node 的内存容量和实例分布。

4 常用参数

mxtool init numa-wrapper 支持以下常用参数：

参数	是否必选	默认值	说明
`--apply`	否	不启用	将 Wrapper 脚本和 NUMA 映射配置部署到远端主机。不指定时仅预览，不修改任何远端文件。
`--scope`	否	`all`	指定生成映射的实例范围。支持`all`、`master`、`standby`、`primary`、`mirror`，也支持使用逗号组合，例如 `primary,mirror`。
`--target-dir`	否	`/home/mxadmin/scripts`	指定远端生成目录。
`--script-name`	否	`mxstart_numa_wrapper.sh`	指定 Wrapper 脚本文件名。
`--map-name`	否	`mxstart_numa_map.conf`	指定 NUMA 映射配置文件名。
`--memory-policy`	否	`preferred`	指定 NUMA 内存策略。支持`preferred` 和 `membind`。

5 使用 Wrapper 启动集群

执行 mxtool init numa-wrapper 命令只生成或部署 Wrapper 脚本和 NUMA 映射配置，不会修改正在运行的实例，也不会自动重启集群。

部署完成后，在下一次启动集群时，通过 mxstart 的 --wrapper 和 --wrapper-args 参数启用 NUMA Node 绑定：

mxstart -a \
    --wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh \
    --wrapper-args=/home/mxadmin/scripts/mxstart_numa_map.conf

启动成功后，日志中会显示 Wrapper 参数，例如：

[mxadmin@mxui ~]$ mxstart -a --wrapper=/home/mxadmin/numa_wrapper.sh --wrapper-args=/home/mxadmin/seg_numa_map.csv
2026-06-24:14:04:07.552 mxstart:mxadmin:mxui:2267293-[INFO]:-Starting MatrixDB cluster with: [no-prompt:true wrapper:/home/mxadmin/numa_wrapper.sh wrapper-args:/home/mxadmin/seg_numa_map.csv].
2026-06-24:14:04:07.552 mxstart:mxadmin:mxui:2267293-[INFO]:-Connecting to physical cluster's etcd cluster ...
2026-06-24:14:04:07.556 mxstart:mxadmin:mxui:2267293-[INFO]:-Connected to physical cluster's etcd cluster: [http://192.168.100.57:4679].
2026-06-24:14:04:07.597 mxstart:mxadmin:mxui:2267293-[INFO]:-Collecting database cluster ID ...
2026-06-24:14:04:07.597 mxstart:mxadmin:mxui:2267293-[INFO]:-Collected database cluster ID: Gs7bdQWv3wWeJFfQ8UsCFY
2026-06-24:14:04:07.601 mxstart:mxadmin:mxui:2267293-[INFO]:-Collecting cluster info ...
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:----------------------------
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-Master instance parameters
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:----------------------------
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-Master Host         = mxui
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-Master Port         = 5432
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-Master Directory    = /mxdata_20260624093907/master/mxseg-1
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:----------------------------------------
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-Segment instances that will be started
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:----------------------------------------
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-Host   Port    DBID    DataDir                                 Role
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-mxui   6000    2       /mxdata_20260624093907/primary/mxseg0   PRIMARY
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-sdw    7000    4       /mxdata_20260624093907/mirror/mxseg0    MIRROR
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-sdw    6000    3       /mxdata_20260624093907/primary/mxseg1   PRIMARY
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-mxui   7000    5       /mxdata_20260624093907/mirror/mxseg1    MIRROR
2026-06-24:14:04:07.604 mxstart:mxadmin:mxui:2267293-[INFO]:-Commencing parallel primary and mirror segment instance startup, please wait ...
2026-06-24:14:04:07.607 mxstart:mxadmin:mxui:2267293-[DEBUG]:-[Finder] resolved hostname sdw to IP 192.168.100.99
2026-06-24:14:04:07.608 mxstart:mxadmin:mxui:2267293-[INFO]:-Send start to cluster service
2026-06-24:14:04:09.859 mxstart:mxadmin:mxui:2267293-[INFO]:-stopping master in utility mode...
2026-06-24:14:04:12.109 mxstart:mxadmin:mxui:2267293-[INFO]:-awaiting data shard startup finish... still waiting 4 data segments to be started...
2026-06-24:14:04:12.858 mxstart:mxadmin:mxui:2267293-[INFO]:-awaiting data shard startup finish... still waiting 4 data segments to be started...
2026-06-24:14:04:13.330 mxstart:mxadmin:mxui:2267293-[INFO]:-finishing update cluster state...
[M ◐ : 1 ◉  | - -][0 ◉ : 2 ◉  | 4 ◉][1 ◉ : 3 ◉  | 5 ◉]
2026-06-24:14:04:13.330 mxstart:mxadmin:mxui:2267293-[INFO]:-DB instances process started. Waiting for status in-sync ...
2026-06-24:14:04:13.332 mxstart:mxadmin:mxui:2267293-[INFO]:-Database instance started and status is in sync.
2026-06-24:14:04:13.335 mxstart:mxadmin:mxui:2267293-[DEBUG]:-[Finder] resolved hostname sdw to IP 192.168.100.99
2026-06-24:14:04:13.335 mxstart:mxadmin:mxui:2267293-[INFO]:-Send reload request to cluster service
2026-06-24:14:04:14.369 mxstart:mxadmin:mxui:2267293-[INFO]:-Cluster GUC reloaded.
2026-06-24:14:04:14.381 mxstart:mxadmin:mxui:2267293-[INFO]:-MatrixDB cluster successfully started.

6 验证 NUMA Node 绑定

集群启动后，可以通过 postmaster 进程的 /proc 信息确认绑定是否生效。

6.1 查看 CPU 绑定

先获取目标实例的 postmaster 进程 ID，然后执行：

cat /proc/<postmaster_pid>/status | grep Cpus_allowed_list

如果 CPU 绑定生效，Cpus_allowed_list 会显示该进程允许使用的 CPU 范围。

6.2 查看内存策略

执行：

cat /proc/<postmaster_pid>/numa_maps

如果使用默认 preferred 策略，可以看到类似内容：

prefer:0

如果使用 membind 策略，可以看到类似内容：

bind:0

其中数字表示当前实例绑定的 NUMA Node ID。

7 常见问题

7.1 如果目标脚本和配置文件已经存在，会如何处理？

执行 --apply 时，如果目标 Wrapper 脚本或 NUMA 映射配置已存在，命令会先备份旧文件，再部署新文件。

备份文件名会包含时间戳，例如：

[mxadmin@sdw ~]$ ./mxtool init numa-wrapper
Mode: DRY RUN (no remote files will be changed)
host=sdw action=would-write wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf
host=sdw-other action=would-write wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf
host=sdw hostname=sdw numa_nodes=0,1
/data/mxdata_20260622122230/master/mxseg-1 0
/data/mxdata_20260622122230/primary/mxseg0 1
/data/mxdata_20260622122230/primary/mxseg1 0
/data/mxdata_20260622122230/primary/mxseg2 1
/data/mxdata_20260622122230/primary/mxseg3 0
/data/mxdata_20260622122230/primary/mxseg4 1
/data/mxdata_20260622122230/primary/mxseg5 0
/data/mxdata_20260622122230/primary/mxseg6 1
/data/mxdata_20260622122230/primary/mxseg7 0
host=sdw-other hostname=sdw-other numa_nodes=0,1
/data/mxdata_20260622122230/primary/mxseg8 0
/data/mxdata_20260622122230/primary/mxseg9 1
/data/mxdata_20260622122230/primary/mxseg10 0
/data/mxdata_20260622122230/primary/mxseg11 1
/data/mxdata_20260622122230/primary/mxseg12 0
/data/mxdata_20260622122230/primary/mxseg13 1
/data/mxdata_20260622122230/primary/mxseg14 0
/data/mxdata_20260622122230/primary/mxseg15 1
[mxadmin@sdw ~]$ ./mxtool init numa-wrapper --apply
Mode: APPLY (remote files will be deployed)
host=sdw action=deployed wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf
host=sdw backups=/home/mxadmin/scripts/mxstart_numa_wrapper.sh.bak.20260628130639,/home/mxadmin/scripts/mxstart_numa_map.conf.bak.20260628130639
host=sdw-other action=deployed wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh map=/home/mxadmin/scripts/mxstart_numa_map.conf
host=sdw-other backups=/home/mxadmin/scripts/mxstart_numa_wrapper.sh.bak.20260628130639,/home/mxadmin/scripts/mxstart_numa_map.conf.bak.20260628130639
host=sdw hostname=sdw numa_nodes=0,1
/data/mxdata_20260622122230/master/mxseg-1 0
/data/mxdata_20260622122230/primary/mxseg0 1
/data/mxdata_20260622122230/primary/mxseg1 0
/data/mxdata_20260622122230/primary/mxseg2 1
/data/mxdata_20260622122230/primary/mxseg3 0
/data/mxdata_20260622122230/primary/mxseg4 1
/data/mxdata_20260622122230/primary/mxseg5 0
/data/mxdata_20260622122230/primary/mxseg6 1
/data/mxdata_20260622122230/primary/mxseg7 0
host=sdw-other hostname=sdw-other numa_nodes=0,1
/data/mxdata_20260622122230/primary/mxseg8 0
/data/mxdata_20260622122230/primary/mxseg9 1
/data/mxdata_20260622122230/primary/mxseg10 0
/data/mxdata_20260622122230/primary/mxseg11 1
/data/mxdata_20260622122230/primary/mxseg12 0
/data/mxdata_20260622122230/primary/mxseg13 1
/data/mxdata_20260622122230/primary/mxseg14 0
/data/mxdata_20260622122230/primary/mxseg15 1
Tip: mxstart -a --wrapper=/home/mxadmin/scripts/mxstart_numa_wrapper.sh --wrapper-args=/home/mxadmin/scripts/mxstart_numa_map.conf

← 上一篇

负载分析

查询统计