Percona XtraDB Cluster 8.4.11-11 常用 CLI 命令与工具详解

PXC 8.4.11-11 运维命令与工具箱实测：wsrep 状态/系统变量速查、clustercheck 健康检查、percona-toolkit 与 MySQL 8.4 兼容性实测结论、XtraBackup 物理备份。

Percona XtraDB ClusterPercona XtraDB ClusterMySQL数据库2026/10/20

Percona XtraDB Cluster 8.4.11-11 常用 CLI 命令与工具详解

目标：整理 Percona XtraDB Cluster（PXC）8.4.11-11 日常运维的命令与工具箱——wsrep 状态/系统变量速查、集群引导与恢复、clustercheck 健康检查、percona-toolkit 配套工具（含与 MySQL 8.4 的兼容性实测结论）与 XtraBackup 物理备份。全部命令与回显均于 2026-10-20 在三节点集群（Ubuntu 22.04，8.4.11-11）实测通过；集群搭建过程见本专栏《Percona XtraDB Cluster 8.4.11-11 3 节点集群部署指南》，MySQL 通用客户端用法另见《MySQL 8.4 常用 CLI 命令与工具详解》。

一、环境信息

项目值
集群3 节点（pxc1/pxc2/pxc3），pxc-cluster，Synced
软件版本PXC 8.4.11-11（WSREP 26.1.4.3）、XtraBackup 8.4.0-7、percona-toolkit 3.6.0-1.jammy
操作系统Ubuntu Server 22.04 LTS
实测日期2026-10-20

二、wsrep 状态变量速查（SHOW GLOBAL STATUS）

集群实时状态一眼看健康度，实测共 82 个 wsrep_% 状态变量。必看一组：

SHOW GLOBAL STATUS LIKE 'wsrep_cluster%';
SHOW GLOBAL STATUS LIKE 'wsrep_local_state%';
SHOW GLOBAL STATUS LIKE 'wsrep_ready';
SHOW GLOBAL STATUS LIKE 'wsrep_connected';
SHOW GLOBAL STATUS LIKE 'wsrep_last_committed';

实测回显（三节点健康时）：

Variable_name          Value
wsrep_cluster_conf_id  7
wsrep_cluster_size     3
wsrep_cluster_state_uuid  df796f5f-cbe0-11f1-bd19-6f7c18a9d266
wsrep_cluster_status   Primary
wsrep_local_state_uuid    df796f5f-cbe0-11f1-bd19-6f7c18a9d266
wsrep_local_state      4
wsrep_local_state_comment  Synced
wsrep_ready            ON
wsrep_connected        ON
wsrep_last_committed   54

判读要点：

变量含义与判读
wsrep_cluster_statusPrimary 才可写；non-Primary 表示失去仲裁
wsrep_cluster_size当前成员数，3 节点集群少于 2 即失去 quorum
wsrep_local_state_commentSynced（4）健康；Joining/Donor/Desynced 等为过渡或异常态
wsrep_local_state_uuid 与 wsrep_cluster_state_uuid必须一致，不一致说明节点数据视图不属于本集群
wsrep_last_committed各节点已提交位点，持续对比可量化复制延迟

复制吞吐与流控（实测空载集群）：

SHOW GLOBAL STATUS LIKE 'wsrep_replicated%';
wsrep_replicated        25
wsrep_replicated_bytes  9064
SHOW GLOBAL STATUS LIKE 'wsrep_received%';
wsrep_received          19
wsrep_received_bytes    3498
SHOW GLOBAL STATUS LIKE 'wsrep_flow_control%';
wsrep_flow_control_paused       0
wsrep_flow_control_sent         0
wsrep_flow_control_recv         0
wsrep_flow_control_active       false
wsrep_flow_control_status       OFF

判读：wsrep_flow_control_paused 长期大于 0 说明本节点 apply 能力跟不上集群写入节奏（常调大 wsrep_slave_threads）；wsrep_cert_deps_distance 反映可并行认证的 writeset 依赖距离，越大越能吃到并行复制的红利（实测空载为 1）。wsrep_apply_oooe/wsrep_commit_oooe 等 out-of-order 比例反映并行回放效率。

三、wsrep 系统变量速查（SHOW VARIABLES）

实测共 53 个 wsrep_% 系统变量。核心一组（实测值）：

变量实测值说明
wsrep_cluster_addressgcomm://10.89.62.11,10.89.62.12,10.89.62.13集群成员清单；空值 gcomm:// 仅用于引导
wsrep_cluster_namepxc-cluster集群名，三节点必须一致
wsrep_node_name / wsrep_node_addresspxc1 / 10.89.62.11节点标识与通信地址
wsrep_sst_methodxtrabackup-v2全量状态传输方法（默认即此）
wsrep_slave_threads8并行 apply 线程数
wsrep_sync_wait0>0 时启用因果一致性读（按位掩码：1=读，2=更新，4=删除…），实测默认关闭
wsrep_desyncOFF节点脱离流控同步（配合 SST/维护用）
wsrep_OSU_methodTOI在线 DDL 模式：TOI 全集群有序执行 / RSU 节点本地执行
wsrep_auto_increment_controlON自增 increment/offset 集群自动协调（实测生效，见部署指南 7.2）
pxc_strict_modeENFORCINGPXC 严格模式（非 wsrep_ 前缀但属集群关键变量）

注意：wsrep_sst_auth 在 8.4 已移除，配置文件写入会报 unknown variable 拒启；SST 凭据全自动。

Galera 底层参数经 wsrep_provider_options 一览（节选实测值）：

SHOW VARIABLES LIKE 'wsrep_provider_options'\G

base_host = 10.89.62.11; base_port = 4567;
gmcast.listen_addr = ssl://0.0.0.0:4567;
gcache.dir = /var/lib/mysql/; gcache.name = galera.cache;
gcache.size = 128M; gcache.page_size = 128M; gcache.recover = yes;
pc.wait_prim = true; pc.wait_prim_timeout = PT30S; pc.recovery = true;
gcs.fc_limit = 100; gcs.fc_factor = 1.0; gcs.max_throttle = 0.25;
socket.ssl = YES; socket.ssl_ca = ca.pem;
socket.ssl_cert = server-cert.pem; socket.ssl_key = server-key.pem;

运行时调优示例（动态、仅本节点）：

SET GLOBAL wsrep_provider_options='gcs.fc_limit=250';

四、集群引导与恢复工具（Ubuntu 打包）

Ubuntu/Debian 打包不提供上游的 galera_new_cluster/galera_recovery 独立脚本，等价能力内置于 systemd 单元与 mysql-systemd 助手（实测确认 /usr/bin 下无这两个脚本）：

# 首次引导 / 全停后的引导恢复（--wsrep-new-cluster 由环境文件注入）
sudo systemctl start mysql@bootstrap

实测机制链：

  1. mysql@bootstrap 实例读取 /etc/default/mysql.bootstrap，内容为 EXTRA_ARGS=" --wsrep-new-cluster "（可追加参数）；
  2. 单元 ExecStartPre 自动执行 bash /usr/bin/mysql-systemd galera-recovery 计算崩溃后的起始位点并注入 _WSREP_START_POSITION；
  3. 日常启停用 sudo systemctl start mysql / sudo systemctl stop mysql，普通节点不要用 bootstrap 单元。

崩溃位点自查（datadir 下，实测样例）：

sudo cat /var/lib/mysql/grastate.dat
# uuid:    df796f5f-cbe0-11f1-bd19-6f7c18a9d266
# seqno:   -1
# safe_to_bootstrap: 0

seqno=-1 表示上次非干净关闭、位点待 recovery 计算；全停后选 safe_to_bootstrap: 1（或数据最新）的节点引导。gcache 文件默认落 datadir：

ls -lh /var/lib/mysql/galera.cache
# 实测：134M（gcache.size=128M + 头部）

五、clustercheck 健康检查

PXC 自带极简 HTTP 探活工具：Synced 返回 200，否则 503，天然适配负载均衡/LVS/HAProxy 健康检查。

5.1 组件与配置

实测组件位置：

ls /usr/bin/clustercheck /usr/bin/pyclustercheck /etc/mysql/clustercheck.cnf

配置文件 /etc/mysql/clustercheck.cnf（由示例模板复制，权限 0640、属主 root:mysql）：

[client]
user=clustercheckuser
password=clustercheckpassword!

对应数据库账号（首次需手工建，实测）：

CREATE USER 'clustercheckuser'@'localhost' IDENTIFIED BY 'clustercheckpassword!';
GRANT PROCESS ON *.* TO 'clustercheckuser'@'localhost';
FLUSH PRIVILEGES;

5.2 直跑实测

clustercheck
# HTTP/1.1 200 OK
# Content-Type: text/plain
# Percona XtraDB Cluster Node is synced.

节点不在 Synced 态时返回 HTTP/1.1 503 Service Unavailable + Percona XtraDB Cluster Node is not synced.。

5.3 systemd socket 激活（8.4 打包默认方式）

实测 8.4 打包用 systemd socket 单元常驻 9200 端口（无 xinetd 依赖）：

ss -tlnp | grep 9200
# LISTEN 0 4096  *:9200  *:*  users:(("systemd",pid=1,fd=36))

curl -s http://127.0.0.1:9200/
# Percona XtraDB Cluster Node is synced.

由 clustercheck.socket 触发 clustercheck@.service，每次连接拉起一次检查进程，长期空闲零开销。健康检查接入负载均衡时，对三节点 9200 做轮询探活即可。

5.4 附赠工具

/usr/bin/pt-galera-log-explainer（随 PXC 打包）：对 error.log 中的 wsrep/Galera 日志做归因汇总，排障时快速过滤重点（用法 pt-galera-log-explainer --context with-context /var/log/mysql/error.log）。

六、percona-toolkit 配套实测与 8.4 兼容性

jammy 的 tools 仓当前提供 percona-toolkit 3.6.0-1.jammy（apt-cache policy 实测 Installed/Candidate 均为 3.6.0；上游已发布 3.7.1 但仓库尚未跟进）。3.6.0 与 MySQL 8.4 存在明确的语句兼容问题：8.4 移除了 SHOW MASTER STATUS/SHOW SLAVE HOSTS（分别被 SHOW BINARY LOG STATUS/SHOW REPLICAS 取代），实测结论如下。

6.1 pt-heartbeat：--update 模式不可用（3.6.0）

pt-heartbeat --update --database demo --table heartbeat --create-table \
  --host=127.0.0.1 --port=3306 -u root -p --interval=1

实测报错：

DBD::mysql::db selectrow_hashref failed: You have an error in your SQL syntax;
check the manual that corresponds to your MySQL server version for the right syntax to
use near 'MASTER STATUS' at line 1 [for Statement "SHOW MASTER STATUS"] at /usr/bin/pt-heartbeat line 6361.

原因：3.6.0 源码硬编码 SHOW MASTER STATUS（/usr/bin/pt-heartbeat 第 6361 行），8.4 已移除该语句。仓库无法升到 3.7.1 之前，PXC 复制延迟监控建议改用 wsrep_last_committed 对比或 wsrep_flow_control_paused（见二）。

6.2 pt-table-checksum：可用，需 --recursion-method=none

pt-table-checksum --host=127.0.0.1 --port=3306 -u root -p \
  --databases=demo --recursion-method=none

实测输出（ERRORS=1 全部来自上述版本注释告警，非数据不一致；DIFFS=0）：

Checking if all tables can be checksummed ...
Starting checksum ...
            TS ERRORS  DIFFS     ROWS  DIFF_ROWS  CHUNKS SKIPPED    TIME TABLE
10-19T19:15:13      1      0        0          0       1       0   0.002 demo.heartbeat
10-19T19:15:13      1      0        0          0       1       0   0.003 demo.t1

校验结果落表（实测）：

SELECT db,tbl,chunk,this_crc,this_cnt FROM percona.checksums;
db    tbl        chunk  this_crc  this_cnt
demo  heartbeat  1      657ed471  1
demo  t1         1      b98c175d  10

说明：

  • --recursion-method=none 必加：默认的 processlist/hosts 副本发现会触发 8.4 已移除的 SHOW SLAVE HOSTS，直接报语法错误；PXC 场景本来就是同步复制，跳过副本发现无碍。
  • 运行中出现的 MySQL error 4164（/*!99997*/ 版本注释格式告警）为 3.6.0 与 8.4 的兼容提示，校验本身正常执行。

6.3 pt-online-schema-change：可用，需 --recursion-method=none

pt-online-schema-change \
  --alter "ADD COLUMN c1 VARCHAR(32) NOT NULL DEFAULT ''" \
  D=demo,t=t1,h=127.0.0.1,P=3306,u=root,p= \
  --recursion-method=none --execute

实测完整回显：

No slaves found.  See --recursion-method if host pxc1 has slaves.
Not checking slave lag because no slaves were found and --check-slave-lag was not specified.
Operation, tries, wait:
  analyze_table, 10, 1
  copy_rows, 10, 0.25
  create_triggers, 10, 1
  drop_triggers, 10, 1
  swap_tables, 10, 1
  update_foreign_keys, 10, 1
Altering `demo`.`t1`...
Creating new table...
Created new table demo._t1_new OK.
Altering new table...
Altered `demo`.`_t1_new` OK.
2026-10-19T18:48:14 Creating triggers...
2026-10-19T18:48:14 Created triggers OK.
2026-10-19T18:48:14 Copying approximately 7 rows...
2026-10-19T18:48:14 Copied rows OK.
2026-10-19T18:48:14 Analyzing new table...
2026-10-19T18:48:14 Swapping tables...
2026-10-19T18:48:14 Swapped original and new tables OK.
2026-10-19T18:48:14 Dropping old table...
2026-10-19T18:48:14 Dropped old table `demo`.`_t1_old` OK.
2026-10-19T18:48:14 Dropping triggers...
2026-10-19T18:48:14 Dropped triggers OK.
Successfully altered `demo`.`t1`.

PXC 场景实测结论：加列后在新列在其他节点即时可见（同步复制保证），原表 7 行数据无损；触发器 + 建影子表的全流程在 Galera 认证复制下正常工作。大表操作仍建议逐表评估（触发器期间的写放大在多主下同样存在）。

七、XtraBackup 物理备份（8.4 打包内置）

8.4 起 XtraBackup 随 server 包内置（最低 8.4.0-5，--lock-ddl=ON 默认），命令行入口 /usr/bin/xtrabackup（实测 --version 输出 8.4.0-7 based on MySQL server 8.4.0）。

7.1 全量备份 + prepare 实测

xtrabackup --backup --target-dir=/root/bk_full -u root -p'Pxc#2026' \
  --host=127.0.0.1 --port=3306

实测关键回显：

[Note] [Xtrabackup] Done: Writing file /root/bk_full/xtrabackup_info
[Note] [Xtrabackup] Backup size: 74.26 MiB (77866536 bytes)
[Note] [Xtrabackup] Transaction log of lsn (20899017) to (20899037) was copied.
[Note] [Xtrabackup] completed OK!

xtrabackup --prepare --target-dir=/root/bk_full

[Note] [Xtrabackup] completed OK!

cat /root/bk_full/xtrabackup_checkpoints
# backup_type = full-prepared
# from_lsn = 0
# to_lsn = 20899027
# last_lsn = 20899027
# flushed_lsn = 20899017

backup_type = full-prepared 且末行 completed OK! 即恢复就绪。PXC 中从备份恢复新节点的流程与 SST 等价（SST 本身就是 xtrabackup-v2 流式执行），运维中更多用于节点重建前的归档快照与误操作前的物理基线。

7.2 与 SST 的关系

SST 默认方法 xtrabackup-v2 的实际执行者是 /usr/bin/wsrep_sst_xtrabackup-v2（配套 wsrep_sst_common/wsrep_sst_clone），传输通道为 socat（server 包自带依赖 socat/netcat-openbsd）。备份排障时可直接查阅该脚本与 wsrep_sst_debug=1。

八、常用运维 SQL 速查

-- 只在完全 Synced 的节点上做强一致读（规避过期读）
SET SESSION wsrep_sync_wait=1;
SELECT * FROM demo.t1;
SET SESSION wsrep_sync_wait=0;

-- 节点脱离/恢复集群同步（长事务维护用，操作后必须恢复 OFF）
SET GLOBAL wsrep_desync=ON;

-- DDL 模式切换：TOI（默认，全集群有序）↔ RSU（本节点先做，逐节点滚动）
SET SESSION wsrep_OSU_method='RSU';
-- ... DDL ...
SET SESSION wsrep_OSU_method='TOI';

-- 查看当前节点是否可写
SHOW GLOBAL STATUS LIKE 'wsrep_ready';

九、常见问题

9.1 pt-toolkit 报 SLAVE HOSTS / MASTER STATUS 语法错误

3.6.0 与 MySQL 8.4 的语句兼容问题（两语句在 8.4 被移除）。pt-table-checksum / pt-online-schema-change 加 --recursion-method=none 即可；pt-heartbeat --update 无回避参数，等仓库升级 3.7.1+ 或改用 wsrep 状态监控。

9.2 SHOW GLOBAL STATUS LIKE 'wsrep%' 出现大量变量但 wsrep_ready=OFF

节点尚未进入可写状态。结合 wsrep_local_state_comment 判断阶段：Joining=SST/IST 传输中；Donor/Desynced=本节点在供数据或被暂停同步；Initialized=gcomm 未连上任何主组件（检查 wsrep_cluster_address 与对端 4567 连通性）。

9.3 clustercheck 返回 503 但业务连接正常

clustercheck 以 Synced 态为唯一健康标准。503 说明节点处于 Donor/Joining/Desynced 过渡态——业务库此时可能仍可读，但负载均衡应当摘除，等回 200 再放流量。

9.4 SET GLOBAL wsrep_provider_options=... 报错

该变量必须整串赋值且只接受 Galera 认识的键（见三的 wsrep_provider_options 全量回显），写错键名会报 Unknown option；gcache.size 等部分选项为只读需改配置文件重启生效。

参考链接

  1. Percona XtraDB Cluster 8.4 状态变量索引：https://docs.percona.com/percona-xtradb-cluster/8.4/wsrep-status-index.html
  2. Percona XtraDB Cluster 8.4 系统变量索引：https://docs.percona.com/percona-xtradb-cluster/8.4/wsrep-system-index.html
  3. clustercheck 官方说明：https://docs.percona.com/percona-xtradb-cluster/8.4/features.html#clustercheck
  4. XtraBackup 8.4 文档：https://docs.percona.com/percona-xtrabackup/8.4/
  5. percona-toolkit 文档：https://docs.percona.com/percona-toolkit/
  6. MySQL 8.4 复制语句变更（SHOW MASTER/SLAVE 移除）：https://dev.mysql.com/doc/refman/8.4/en/
  7. 本专栏部署篇：《Percona XtraDB Cluster 8.4.11-11 3 节点集群部署指南》
  8. 安装篇：《Ubuntu 22.04 安装 Percona XtraDB Cluster 8.4.11-11 指南》
  9. MySQL 客户端通用命令：《MySQL 8.4 常用 CLI 命令与工具详解》