ProxySQL（六）—— ProxySQL 集群

目录

一、官方文档核心内容解读

1. 集群概述

2. 核心概念

（1）集群角色（Cluster Roles）

（2）真相源（Source of Truth）

3. 同步的配置模块

4. 同步机制：基于拉取的模型

5. 集群管理命令

6. 集群变量

（1）节点间认证

（2）检查与间隔

（3）同步阈值（宽限期）

（4）配置持久化

7. 统计表

（1）stats_proxysql_servers_checksums

（2）stats_proxysql_servers_metrics

（3）stats_proxysql_servers_status

（4）stats_proxysql_servers_clients_status

（5）stats_proxysql_message_metrics

（6）stats_proxysql_message_metrics_reset

二、环境准备

1. 服务器信息

2. 前置检查

三、集群搭建

1. 配置集群认证（三台节点逐一执行）

2. 配置同步参数（三台节点逐一执行）

3. 配置集群节点列表（三台节点逐一执行）

4. 等待业务配置自动同步

5. 验证集群状态

四、验证测试

1. 多向同步

2. 单节点故障模拟

3. 故障节点恢复上线

4. 恢复后配置同步

五、JDBC 接入配置

1. 方式一：JDBC 原生多主机（推荐 MySQL Connector/J）

2. 方式二：使用 HAProxy（生产环境推荐）

3. 方式三：DNS 轮询

六、故障排查指南

1. 问题：stats_proxysql_servers_checksums 为空或行数不足

2. 问题：diff_check 持续增长不归零

3. 问题：节点间连接失败

4. 关于 stats_proxysql_servers_clients_status 的误解

七、生产环境最佳实践

1. 使用配置文件预定义集群节点

2. 监控与告警建议

3. 定期备份

八、总结

参考文档

本文基于官方四篇核心文档，结合三台真实服务器（172.18.3.122、172.18.3.232、172.18.4.109） 的完整实操经验编写，所有实操步骤均经过 ProxySQL 2.6.5 版本实际验证。

一、官方文档核心内容解读

1. 集群概述

根据 ProxySQL Cluster 官方文档，ProxySQL 集群是一个去中心化的横向扩展方案，提供原生的点对点同步机制。它能确保用户、后端服务器、查询规则等配置变更自动在所有节点间传播。

2. 核心概念

（1）集群角色（Cluster Roles）

• 核心节点（Core Nodes）：持有并传播“配置真相源”。它们在彼此的 proxysql_servers 表中显式定义。当核心节点执行 LOAD ... TO RUNTIME 时，版本号递增，触发全局同步。
• 卫星节点（Satellite Nodes）：从核心节点拉取配置，但不会主动传播自己的变更。

（2）真相源（Source of Truth）

ProxySQL 使用基于版本号（version） 和时间戳（epoch） 的系统来识别最新配置。版本号每次 LOAD 后递增，epoch 记录配置创建时间。其他节点通过比较这两个值判断是否需要同步。

3. 同步的配置模块

根据官方文档，以下模块会被同步：

重要提示：根据实际验证，proxysql_servers需要在每个节点手动配置，不会自动从其他节点拉取。这是 ProxySQL 2.6.5 的实际行为。

4. 同步机制：基于拉取的模型

官方文档描述的四步同步过程：

1. 变更检测：每个节点以 admin-cluster_check_interval_ms（默认1000ms）为间隔，与其他节点比较配置校验和。
2. 宽限期（Grace Period）：由 diffs_before_sync 参数控制。连续多次检测到同一差异（默认3次）后才触发同步，避免网络抖动。
3. 数据拉取：达到阈值后，节点向远程对等节点的 runtime_ 表执行 SELECT 语句获取新配置。
4. 生效与持久化：数据加载到本地内存并激活。若 admin-cluster_<module>_save_to_disk 为 true（默认），自动保存到磁盘。

5. 集群管理命令

根据 Cluster Commands 文档，proxysql_servers表需要使用特定命令：

6. 集群变量

根据 Cluster Variables 文档：

（1）节点间认证

要求：这些凭证必须同时存在于每个节点的admin-admin_credentials列表中。

（2）检查与间隔

（3）同步阈值（宽限期）

（4）配置持久化

7. 统计表

根据 Stats Cluster Tables 文档：

以下表包含有关 ProxySQL 集群操作的统计信息，涵盖节点监控、配置同步和节点间通信。它们由集群健康检查线程填充，并反映每个 ProxySQL 实例对其对等节点的实时视图。

（1）stats_proxysql_servers_checksums

属于同一集群的 ProxySQL 实例会定期相互监控，以了解是否需要触发重新配置。通过此表可以查询集群的当前视图。每一行代表特定集群节点上特定配置模块的最后已知校验和。

字段描述:

• hostname: 代理的地址（远程或本地）

• port: 代理的端口（远程或本地）

• name: 正在同步的模块名称

• version: 每次（本地）加载配置时，其版本号增加 1

• epoch: 特定配置创建的时间（无论是在本地创建，还是在导入前远程创建）

• checksum: 配置本身的校验和。这是代理用来检测配置变更的信息

• changed_at: 特定配置在本地加载的时间。请注意，它与表示配置创建时间的epoch不同

• updated_at: 本地 ProxySQL 上次检查远程 ProxySQL 实例校验和的时间。如果此值没有增加，意味着本地 ProxySQL 无法从远程 ProxySQL 获取数据

• diff_check: 检测到远程配置与本地配置不同的连续检查次数。当达到阈值时，将触发自动重新配置

（2）stats_proxysql_servers_metrics

集群中的 ProxySQL 实例定期交换全局状态。其中一些状态在此表中可见。每一行代表单个集群节点的最新观察到的运行时指标。

字段描述:

• hostname: 集群节点的地址，在proxysql_servers表中定义

• port: 集群节点的端口，在proxysql_servers表中定义

• weight: 集群节点的权重，在proxysql_servers表中定义

• comment: 与集群节点关联的注释，在proxysql_servers表中定义

• response_time_ms: 响应集群检查的最新时间，单位为毫秒

• Uptime_s: 集群节点的当前运行时间，单位为秒

• last_check_ms: 处理集群检查的最新时间，单位为毫秒

• Queries: 集群节点已处理的查询数量

• Client_Connections_connected: 集群节点上当前打开的前端客户端连接数

• Client_Connections_created: 集群节点上随时间创建的前端客户端连接总数

（3）stats_proxysql_servers_status

当前未使用 — 此表旨在显示与proxysql_servers表中配置的所有服务相关的常规统计信息。架构已定义，但在当前 ProxySQL 版本中未填充数据行。

字段描述:

• hostname: 集群节点的地址

• port: 集群节点的端口

• weight: 在proxysql_servers中定义的集群节点权重

• master: 指示此节点当前是否充当集群 master

• global_version: 最后在此节点上看到的全局配置版本

• check_age_us: 距离上次健康检查执行已经过去多久（以微秒为单位）

• ping_time_us: 到此节点的 ping 往返延迟（以微秒为单位）

• checks_OK: 成功健康检查的累计计数

• checks_ERR: 失败健康检查的累计计数

注意:此表当前未使用。它旨在公开每个节点的健康统计信息，但当前实现未填充数据。

（4）stats_proxysql_servers_clients_status

跟踪 ProxySQL 集群客户端（已连接到此实例的其他 ProxySQL 节点）的状态。每一行代表一个由其 UUID 和网络端点标识的远程 ProxySQL 节点。此表对于验证哪些对等节点正积极参与集群非常有用。

字段描述:

• uuid: 分配给远程 ProxySQL 实例的唯一标识符；重启后持续存在

• hostname: 远程 ProxySQL 节点的主机名或 IP 地址

• port: 远程节点接受集群连接的 Admin 端口

• admin_mysql_ifaces: 远程节点为管理连接通告的 MySQL 兼容 Admin 接口地址

• last_seen_at: 记录该节点最后一次成功与本地实例通信的 Unix 时间戳

（5）stats_proxysql_message_metrics

跟踪内部 ProxySQL 日志和诊断消息及其频率。每一行代表由其源位置（文件名、行号和函数名）标识的唯一消息。此表对于识别频繁触发的警告或错误，以及了解正在运行的 ProxySQL 实例的内部事件率非常有用。

字段描述:

• message_id: 一个字符串标识符，用于表示消息类别，通常源自源代码中的常量或枚举

• filename: 生成消息的源文件（相对路径）

• line: 源文件中发出消息的行号

• func: 发出消息的函数或方法名称

• count_star: 自 ProxySQL 启动以来（或自最后一次通过stats_proxysql_message_metrics_reset重置以来）所有出现次数的累计计数

• first_seen: 在当前会话中首次记录此消息的 Unix 时间戳

• last_seen: 此消息最近一次出现的 Unix 时间戳

（6）stats_proxysql_message_metrics_reset

这是stats_proxysql_message_metrics的“读取后重置”变体。查询此表会返回与stats_proxysql_message_metrics相同的数据，然后自动将所有计数器（count_star）和时间戳（first_seen,last_seen）原子地重置为零。当希望观察特定时间间隔内的消息速率，而不累积先前周期的计数时，使用此变体。

二、环境准备

1. 服务器信息

2. 前置检查

# 1. 确认三台机器 ProxySQL 版本均为 2.6.5 proxysql --version # 2. 确认网络互通（在每台机器上执行） telnet 172.18.3.122 6032 telnet 172.18.3.232 6032 telnet 172.18.4.109 6032 # 3. 确认老节点已有业务配置 mysql -u admin -padmin -h 172.18.3.122 -P 6032 -e " SELECT COUNT(*) FROM mysql_servers; SELECT COUNT(*) FROM mysql_users; SELECT COUNT(*) FROM mysql_query_rules; "

三、集群搭建

1. 配置集群认证（三台节点逐一执行）

mysql -u admin -padmin -h 127.0.0.1 -P 6032 -- 设置集群通信用户名和密码（三台必须完全一致） SET admin-cluster_username='cluster_sync'; SET admin-cluster_password='SyncPass2024'; -- 将集群用户添加到管理凭证列表（保留原有 admin） SET admin-admin_credentials='admin:admin;cluster_sync:SyncPass2024'; -- 加载并持久化 LOAD ADMIN VARIABLES TO RUNTIME; SAVE ADMIN VARIABLES TO DISK;

2. 配置同步参数（三台节点逐一执行）

-- 检查间隔（毫秒） SET admin-cluster_check_interval_ms=1000; -- 详细状态检查频率 SET admin-cluster_check_status_frequency=10; -- 同步阈值（实验环境设为1，生产建议3） SET admin-cluster_mysql_servers_diffs_before_sync=1; SET admin-cluster_mysql_users_diffs_before_sync=1; SET admin-cluster_mysql_query_rules_diffs_before_sync=1; SET admin-cluster_proxysql_servers_diffs_before_sync=1; -- 启用自动持久化 SET admin-cluster_mysql_servers_save_to_disk=true; SET admin-cluster_mysql_users_save_to_disk=true; SET admin-cluster_mysql_query_rules_save_to_disk=true; SET admin-cluster_proxysql_servers_save_to_disk=true; LOAD ADMIN VARIABLES TO RUNTIME; SAVE ADMIN VARIABLES TO DISK;

3. 配置集群节点列表（三台节点逐一执行）

-- 每台机器都执行 DELETE FROM proxysql_servers; INSERT INTO proxysql_servers (hostname, port) VALUES ('172.18.3.122', 6032), ('172.18.3.232', 6032), ('172.18.4.109', 6032); LOAD PROXYSQL SERVERS TO RUNTIME; SAVE PROXYSQL SERVERS TO DISK; -- 验证配置成功 SELECT * FROM proxysql_servers; -- 预期输出：3 行

4. 等待业务配置自动同步

完成前三步后，等待 30-60 秒。业务配置（mysql_servers、mysql_users、mysql_query_rules 等）会自动从老节点（122）同步到其他节点。

5. 验证集群状态

-- 验证1：节点列表（应有3行） SELECT hostname, port FROM proxysql_servers; -- 验证2：同步状态（应有21行 = 7模块 × 3节点） SELECT hostname, name, version, checksum, diff_check FROM stats_proxysql_servers_checksums ORDER BY hostname, name; -- 验证3：业务配置数量（应与老节点一致） SELECT COUNT(*) FROM mysql_servers; SELECT COUNT(*) FROM mysql_users; SELECT COUNT(*) FROM mysql_query_rules; -- 验证4：节点间连接状态 SELECT hostname, port, response_time_ms, Uptime_s, Queries FROM stats_proxysql_servers_metrics; -- 验证5：客户端连接状态 SELECT uuid, hostname, port, admin_mysql_ifaces FROM stats_proxysql_servers_clients_status;

预期结果：

例如本例在 172.18.3.122 的输出如下：

ProxySQL Admin> -- 验证1：节点列表（应有3行） ProxySQL Admin> SELECT hostname, port FROM proxysql_servers; +--------------+------+ | hostname | port | +--------------+------+ | 172.18.3.122 | 6032 | | 172.18.3.232 | 6032 | | 172.18.4.109 | 6032 | +--------------+------+ 3 rows in set (0.00 sec) ProxySQL Admin> ProxySQL Admin> -- 验证2：同步状态（应有21行 = 7模块 × 3节点） ProxySQL Admin> SELECT hostname, name, version, checksum, diff_check -> FROM stats_proxysql_servers_checksums -> ORDER BY hostname, name; +--------------+-------------------+---------+--------------------+------------+ | hostname | name | version | checksum | diff_check | +--------------+-------------------+---------+--------------------+------------+ | 172.18.3.122 | admin_variables | 16 | 0x63C746F9F2F60E6F | 0 | | 172.18.3.122 | mysql_query_rules | 7 | 0xE66348BB01D2F950 | 0 | | 172.18.3.122 | mysql_servers | 9 | 0x5F53686125CB2B69 | 0 | | 172.18.3.122 | mysql_servers_v2 | 9 | 0x5A93717081BE827D | 0 | | 172.18.3.122 | mysql_users | 8 | 0x1126A0FE45A91FBB | 0 | | 172.18.3.122 | mysql_variables | 5 | 0x9DB45288B713CCC7 | 0 | | 172.18.3.122 | proxysql_servers | 9 | 0x33DBD8F9E5DCAB61 | 0 | | 172.18.3.232 | admin_variables | 3 | 0x63C746F9F2F60E6F | 0 | | 172.18.3.232 | mysql_query_rules | 2 | 0xE66348BB01D2F950 | 0 | | 172.18.3.232 | mysql_servers | 2 | 0x5F53686125CB2B69 | 0 | | 172.18.3.232 | mysql_servers_v2 | 2 | 0x5A93717081BE827D | 0 | | 172.18.3.232 | mysql_users | 2 | 0x1126A0FE45A91FBB | 0 | | 172.18.3.232 | mysql_variables | 2 | 0x9DB45288B713CCC7 | 0 | | 172.18.3.232 | proxysql_servers | 2 | 0x33DBD8F9E5DCAB61 | 0 | | 172.18.4.109 | admin_variables | 3 | 0x63C746F9F2F60E6F | 0 | | 172.18.4.109 | mysql_query_rules | 2 | 0xE66348BB01D2F950 | 0 | | 172.18.4.109 | mysql_servers | 2 | 0x5F53686125CB2B69 | 0 | | 172.18.4.109 | mysql_servers_v2 | 2 | 0x5A93717081BE827D | 0 | | 172.18.4.109 | mysql_users | 2 | 0x1126A0FE45A91FBB | 0 | | 172.18.4.109 | mysql_variables | 2 | 0x9DB45288B713CCC7 | 0 | | 172.18.4.109 | proxysql_servers | 2 | 0x33DBD8F9E5DCAB61 | 0 | +--------------+-------------------+---------+--------------------+------------+ 21 rows in set (0.00 sec) ProxySQL Admin> ProxySQL Admin> -- 验证3：业务配置数量（应与老节点一致） ProxySQL Admin> SELECT COUNT(*) FROM mysql_servers; +----------+ | COUNT(*) | +----------+ | 8 | +----------+ 1 row in set (0.00 sec) ProxySQL Admin> SELECT COUNT(*) FROM mysql_users; +----------+ | COUNT(*) | +----------+ | 2 | +----------+ 1 row in set (0.00 sec) ProxySQL Admin> SELECT COUNT(*) FROM mysql_query_rules; +----------+ | COUNT(*) | +----------+ | 30 | +----------+ 1 row in set (0.00 sec) ProxySQL Admin> ProxySQL Admin> -- 验证4：节点间连接状态 ProxySQL Admin> SELECT hostname, port, response_time_ms, Uptime_s, Queries -> FROM stats_proxysql_servers_metrics; +--------------+------+------------------+----------+---------+ | hostname | port | response_time_ms | Uptime_s | Queries | +--------------+------+------------------+----------+---------+ | 172.18.4.109 | 6032 | 3 | 225 | 0 | | 172.18.3.232 | 6032 | 2 | 219 | 0 | | 172.18.3.122 | 6032 | 2 | 77931 | 29 | +--------------+------+------------------+----------+---------+ 3 rows in set (0.00 sec) ProxySQL Admin> ProxySQL Admin> -- 验证5：客户端连接状态 ProxySQL Admin> SELECT uuid, hostname, port, admin_mysql_ifaces -> FROM stats_proxysql_servers_clients_status; +--------------------------------------+--------------+-------+--------------------+ | uuid | hostname | port | admin_mysql_ifaces | +--------------------------------------+--------------+-------+--------------------+ | 8c9c8e3f-c56e-43f1-a768-5d62c10865f0 | 172.18.4.109 | 16234 | 0.0.0.0:6032 | | b519cd8e-d30a-4321-86c9-d924680181f0 | 172.18.3.122 | 56436 | 0.0.0.0:6032 | | 97fd2be3-f4c4-4443-98db-9d5b57615fac | 172.18.3.232 | 54096 | 0.0.0.0:6032 | +--------------------------------------+--------------+-------+--------------------+ 3 rows in set (0.00 sec) ProxySQL Admin>

判断集群健康的标准：

• ✅ 每个节点都能在stats_proxysql_servers_clients_status中看到其他节点

• ✅最重要：验证2 中所有diff_check= 0，checksum完全一致

四、验证测试

1. 多向同步

在任意节点创建测试用户：

INSERT INTO mysql_users (username, password, default_hostgroup, comment) VALUES ('cluster_test_2026', 'test123', 0, 'sync_verification'); LOAD MYSQL USERS TO RUNTIME;

等待10秒，查询其他节点：

SELECT * FROM mysql_users WHERE username='cluster_test_2026'; -- 预期：能看到新增的用户

清理（可以在任一节点执行）：

DELETE FROM mysql_users WHERE username='cluster_test_2026'; LOAD MYSQL USERS TO RUNTIME;

2. 单节点故障模拟

模拟节点3（109）故障：

pkill -9 proxysql ps -ef | grep proxysql

在任意正常节点检查：

SELECT hostname, port, response_time_ms, Uptime_s FROM stats_proxysql_servers_metrics; -- 109 的 Uptime_s 应停止增长

3. 故障节点恢复上线

恢复节点3（109）：

proxysql -c /etc/proxysql.cnf ps -ef | grep proxysql

等待 30 秒后重新检查：

SELECT hostname, port, Uptime_s, response_time_ms FROM stats_proxysql_servers_metrics; -- 109 重新出现，Uptime_s 从零开始

4. 恢复后配置同步

在老节点（122）创建临时规则：

INSERT INTO mysql_query_rules (rule_id, active, match_pattern, destination_hostgroup, comment) VALUES (9999, 1, 'HEALTH_CHECK$', 0, 'temp_rule'); LOAD MYSQL QUERY RULES TO RUNTIME;

在恢复的节点3（109）上验证：

SELECT * FROM mysql_query_rules WHERE rule_id=9999; -- 预期：能看到新增的规则（已自动同步）

清理（可以在任一节点执行）：

DELETE FROM mysql_query_rules WHERE rule_id=9999; LOAD MYSQL QUERY RULES TO RUNTIME;

五、JDBC 接入配置

1. 方式一：JDBC 原生多主机（推荐 MySQL Connector/J）

String jdbcUrl = "jdbc:mysql:loadbalance://" + "172.18.3.122:6033," + "172.18.3.232:6033," + "172.18.4.109:6033/your_database?" + "loadBalanceStrategy=bestResponseTime&" + "autoReconnect=true&" + "failOverReadOnly=false&" + "connectTimeout=3000"; HikariConfig config = new HikariConfig(); config.setJdbcUrl(jdbcUrl); config.setUsername("app_user"); config.setPassword("app_password"); config.setMaximumPoolSize(20); config.setMinimumIdle(5); HikariDataSource dataSource = new HikariDataSource(config);

2. 方式二：使用 HAProxy（生产环境推荐）

HAProxy 配置 (/etc/haproxy/haproxy.cfg)：

frontend mysql_frontend bind :6033 mode tcp default_backend mysql_backend backend mysql_backend mode tcp balance roundrobin option tcp-check server node1 172.18.3.122:6033 check inter 2000 rise 2 fall 3 server node2 172.18.3.232:6033 check inter 2000 rise 2 fall 3 server node3 172.18.4.109:6033 check inter 2000 rise 2 fall 3

// 应用连接 HAProxy String jdbcUrl = "jdbc:mysql://haproxy-vip:6033/your_database";

3. 方式三：DNS 轮询

# DNS 配置 proxysql-cluster.example.com IN A 172.18.3.122 IN A 172.18.3.232 IN A 172.18.4.109

String jdbcUrl = "jdbc:mysql://proxysql-cluster.example.com:6033/your_database";

六、故障排查指南

1. 问题：stats_proxysql_servers_checksums 为空或行数不足

可能原因：集群线程未启动或节点列表不完整。

解决：确保步骤三已执行（每个节点都有完整节点列表），并执行LOAD PROXYSQL SERVERS TO RUNTIME。

2. 问题：diff_check 持续增长不归零

含义：节点检测到配置差异但无法完成同步。

诊断：

SELECT message_id, filename, func, count_star, datetime(last_seen, 'unixepoch', 'localtime') as last_time FROM stats_proxysql_message_metrics WHERE filename LIKE '%Cluster%' ORDER BY last_seen DESC LIMIT 20;

3. 问题：节点间连接失败

测试命令：

mysql -u cluster_sync -pSyncPass2024 -h 172.18.3.122 -P 6032 -e "SELECT 1"

4. 关于 stats_proxysql_servers_clients_status 的误解

现象：不同节点查询结果不一样。

结论：这是正常现象，不是故障！判断集群健康应主要看：

• stats_proxysql_servers_checksums是否有 21 行且diff_check=0

• stats_proxysql_servers_metrics是否显示所有节点在线

七、生产环境最佳实践

1. 使用配置文件预定义集群节点

在 /etc/proxysql.cnf 中添加：

proxysql_servers = ( { hostname="172.18.3.122", port=6032, weight=0 }, { hostname="172.18.3.232", port=6032, weight=0 }, { hostname="172.18.4.109", port=6032, weight=0 } )

2. 监控与告警建议

1. 节点在线状态：确保所有节点 Uptime_s > 0
2. 配置同步状态：设置 diff_check 持续大于 10 的告警
3. 集群错误消息：监控 stats_proxysql_message_metrics 中相关计数

3. 定期备份

sudo cp /var/lib/proxysql/proxysql.db /backup/proxysql_$(date +%Y%m%d).db

八、总结

关键结论：

最终验证命令：

SELECT COUNT(DISTINCT hostname) as node_count, COUNT(DISTINCT name) as module_count, SUM(diff_check) as total_diff FROM stats_proxysql_servers_checksums;

预期结果：node_count=3，module_count=7，total_diff=0

参考文档

1. ProxySQL Cluster Overview

2. Cluster Commands

3. Cluster Variables

4. Stats: ProxySQL Cluster Tables