ProxySQL Cluster 内部机制深度解析:节点监控线程、校验和同步与配置收敛原理

原创2026-10-07 11:43:201,968 阅读
文章标签:后端数据库负载均衡

ProxySQL Cluster 内部机制深度解析:节点监控线程、校验和同步与配置收敛原理

导读

本文深入解析 ProxySQL 高可用集群(ProxySQL Cluster)的内部工作原理,以本仓库 doc/proxysql_cluster/proxysql_cluster_working.md 为骨架,结合 include/ProxySQL_Cluster.hpp 与 lib/ProxySQL_Cluster.cpp 的源码实现展开。你将掌握:集群节点模型(ProxySQL_Node_Entry / ProxySQL_Node_Address 等核心类的职责)、节点列表加载与监控线程生命周期、基于全局校验和 + 模块校验和的配置变化检测机制、以及 diffs_before_sync / save_to_disk 等关键变量如何驱动配置从"发现差异"到"拉取 → 校验 → 应用到运行时 → 持久化"的完整收敛闭环。

本文面向已了解 ProxySQL Cluster 基本概念(proxysql_servers 表、cluster_* 变量、Admin 接口互连等)的读者,聚焦"内部如何工作"这一层。

一、ProxySQL Cluster 的核心类模型

Cluster 功能在代码中由 ProxySQL_Cluster 类体系承载,全部定义于 include/ProxySQL_Cluster.hpp,实现位于 lib/ProxySQL_Cluster.cpp(约 6000 行)。整个体系围绕 5 个核心类组织。

1.1 ProxySQL_Cluster:集群主控

ProxySQL_Cluster 是集群功能的门面与协调者(include/ProxySQL_Cluster.hpp#L594)。它持有:

  • 与每个模块对应的 pthread_mutex_t update_<module>_mutex(如 update_mysql_query_rules_mutex、update_runtime_mysql_servers_mutex、update_mysql_servers_v2_mutex),保证同一模块不会并发同步;
  • 集群凭据 cluster_username / cluster_password,以及本节点对外广播的 admin_mysql_ifaces(在 admin_mysql_ifaces_mutex 保护下读写);
  • 一组 cluster_*_diffs_before_sync 原子整数变量与 cluster_*_save_to_disk 布尔变量,控制每个模块的同步触发阈值与持久化行为;
  • nodes 成员(ProxySQL_Cluster_Nodes),即全量节点表的封装;
  • 每个模块的 pull_<module>_from_peer() 系列方法(如 lib/ProxySQL_Cluster.cpp#L1177 的 pull_mysql_query_rules_from_peer),负责实际从远端拉取配置。

此外,类内还定义了一组被 Admin 接口拦截的 CLUSTER_QUERY_* 宏(见 include/ProxySQL_Cluster.hpp#L71-L239),例如:

-- 运行时 MySQL 服务器列表的校验和查询
PROXY_SELECT hostgroup_id, hostname, port, gtid_port, status, weight, compression,
  max_connections, max_replication_lag, use_ssl, max_latency_ms, comment
  FROM runtime_mysql_servers WHERE status<>'OFFLINE_HARD'
  ORDER BY hostgroup_id, hostname, port

这些查询由 ProxySQL_Admin 拦截(文件头部注释明确说明),其结果集既用于生成校验和,也用于拉取配置后计算"期望校验和",因此必须保持相同的过滤与排序条件——这是校验和对比能够成立的前提。

1.2 ProxySQL_Node_Entry:单个节点的信息容器

ProxySQL_Node_Entry(include/ProxySQL_Cluster.hpp#L288)代表集群中的一个节点,持有:

  • hostname / port / weight / comment 等注册信息,以及解析出的 ip_addr;
  • 活跃标志 active(在 load_servers_list 中被批量标记);
  • 一个 checksums_values 结构体,内含每个模块的 ProxySQL_Checksum_Value_2(admin_variables、mysql_variables、ldap_variables、mysql_query_rules、mysql_servers、mysql_users、proxysql_servers、mysql_servers_v2,以及 PostgreSQL 侧的 pgsql_query_rules / pgsql_servers / pgsql_users / pgsql_servers_v2 / pgsql_variables);
  • 节点级的 global_checksum(全局校验和);
  • 一个环形指标缓冲区 ProxySQL_Node_Metrics *metrics<a href="https://link.gitcode.com/i/7ac82a48a0624f028062caf58ebaa1a9" target="_blank">](长度 PROXYSQL_NODE_METRICS_LEN = 5,[include/ProxySQL_Cluster.hpp#L16),用于滚动记录相邻两次采样的节点状态指标。

1.3 ProxySQL_Node_Address:线程间传递的节点地址

ProxySQL_Node_Address(include/ProxySQL_Cluster.hpp#L271)封装 hostname、port、uuid、admin_mysql_ifaces 与可选 ip_addr,并包含线程句柄 thrid。它的典型用途是作为监控线程的参数:每次新节点入表时,load_servers_list 会构造一个 ProxySQL_Node_Address 并传给新创建的 ProxySQL_Cluster_Monitor_thread。

1.4 ProxySQL_Cluster_Nodes:节点集合管理器

ProxySQL_Cluster_Nodes(include/ProxySQL_Cluster.hpp#L395)是节点总表,核心是 std::unordered_map<uint64_t, ProxySQL_Node_Entry *> umap_proxy_nodes——以 generate_hash(hostname, port) 生成的 64 位哈希为键。它提供:

  • load_servers_list(SQLite3_result *, bool _lock):加载 proxysql_servers 结果集;
  • Update_Global_Checksum() / Update_Node_Checksums():接收监控线程拉回的校验和结果集并落到对应节点;
  • 一组 get_peer_to_sync_<module>():遍历 map,选出"版本大于 1 且 epoch 最大"的节点作为同步源。

值得注意,lib/ProxySQL_Cluster.cpp#L4585 的 get_peer_to_sync_variables_module 采用数据驱动的统一实现:用一张 ModuleConfig 表把模块名、对应的 diffs_before_sync 变量、校验和字段访问器、是否携带双校验和(V2 类模块同时返回 mysql_servers_v2 与 runtime_mysql_servers 两份校验和)统一映射起来,取代了历史上每个模块一套独立函数。

1.5 ProxySQL_GlobalVariables 与 ProxySQL_Checksum_Value

  • ProxySQL_GlobalVariables:聚合当前实例各模块的 checksum、epoch、version(代码中即 GloVars.uuid 所引用的全局对象),并提供对外访问入口;监控线程注册节点时使用的正是 ProxySQL_GlobalVariables::uuid。
  • ProxySQL_Checksum_Value 及其子类 ProxySQL_Checksum_Value_2(include/ProxySQL_Cluster.hpp#L241):除 version / epoch / checksum 外,_2 版本还增加 last_updated、last_changed、diff_check 三个时间/计数字段——diff_check 即"连续检测到差异的次数",是 diffs_before_sync 阈值机制的核心输入。

二、节点列表加载与监控线程初始化

2.1 触发时机与数据来源

两个时机触发节点列表加载:

  1. ProxySQL 实例启动;
  2. 在 Admin 接口执行 LOAD PROXYSQL SERVERS TO RUNTIME。

届时,proxysql_servers 表的最新记录(hostname, port, weight, comment,按 hostname, port 排序)被取出,结果集交给 ProxySQL_Cluster::load_servers_list,后者直接转发给 ProxySQL_Cluster_Nodes::load_servers_list(include/ProxySQL_Cluster.hpp#L656)。

2.2 load_servers_list 的六步流程

ProxySQL_Cluster_Nodes::load_servers_list 的完整实现位于 lib/ProxySQL_Cluster.cpp#L4380,流程与文档描述完全吻合:

  1. 加锁(pthread_mutex_lock(&mutex)),随后调用 set_all_inactive()(lib/ProxySQL_Cluster.cpp#L4347)把 umap_proxy_nodes 中所有节点标记为 inactive;
  2. 遍历结果集:对每一行取 fields[0..3] 作为 host、port、weight、comment,用 generate_hash(h_, p_) 计算键;
  3. 查 map:若键存在,则对该节点执行 resolve_hostname()、set_active(true),并更新 set_weight() / set_comment();
  4. 若键不存在:new ProxySQL_Node_Entry(h_, p_, w_, c_) 插入 map 并 set_active(true);随后创建 ProxySQL_Node_Address 并 pthread_create 一个 detached 的 ProxySQL_Cluster_Monitor_thread(lib/ProxySQL_Cluster.cpp#L4404),把节点 host/port 作为参数传入;
  5. 删除 inactive 节点:remove_inactives()(lib/ProxySQL_Cluster.cpp#L4355)把仍处于 inactive 的条目 delete 并从 map erase;
  6. 解锁。

由此得到一个关键语义:每个集群节点对应一个常驻监控线程,且线程只在节点首次入表时创建;之后该节点每次 LOAD PROXYSQL SERVERS TO RUNTIME 只会被更新属性,而不会重复开线程。 若某节点从 proxysql_servers 表中被删除,下一次加载时它会被标记 inactive 并连同其监控线程(通过 GloProxyCluster->Update_Node_Metrics(..., NULL, 0) 的哨兵调用判定节点已不存在,见 lib/ProxySQL_Cluster.cpp#L402)一起被清理。

文档给出的整体流程图(mermaid)可归纳为:

flowchart TD
  start[Start] --> load[LOAD PROXYSQL SERVERS TO RUNTIME]
  load --> select[SELECT hostname, port, weight, comment FROM proxysql_servers ORDER BY hostname, port]
  select --> test[Set all nodes to inactive state]
  test --> check[Next node available in resultset?]
  check -- NO --> preend[Remove all inactive nodes] --> END[END]
  check -- YES --> check_map{Node exists in map?}
  check_map -- YES --> update[Update node weight, comment, set active] --> check
  check_map -- NO --> create[Create ProxySQL_Node_Entry, insert in map<br>Create monitoring thread with ProxySQL_Node_Address] --> check

三、监控线程的工作循环

ProxySQL_Cluster_Monitor_thread(入口位于 lib/ProxySQL_Cluster.cpp#L170)是每个节点的专职监控者。它启动后先通过 proxysql_startup_gate_wait_for_runtime 等待插件生命周期完成,随后进入 while (glovars.shutdown == 0 && rc_bool == true) 主循环。每一轮循环按以下顺序执行。

3.1 版本核对:SELECT @@version

线程以 get_credentials() 拿到的 cluster_username / cluster_password 连接远端(MYSQL_OPT_CONNECT_TIMEOUT = 1 秒),然后发送版本查询。在启用 PROXYSQL40 宏的构建中,实际发送的是 SELECT @@version, @@proxysql_plugin_set_hash(宏 PROXYSQL_CLUSTER_PEER_IDENTITY_QUERY,见 include/ProxySQL_ClusterPluginHash.h#L37),除了比对版本字符串,还会比对插件集哈希,确保双方插件集合兼容(lib/ProxySQL_Cluster.cpp#L244-L258)。

  • 版本/插件集不一致:打印告警日志,关闭连接,并硬编码 sleep 30 秒后重试(lib/ProxySQL_Cluster.cpp#L283);
  • 一致:进入注册与同步阶段。

3.2 节点注册:PROXYSQL CLUSTER_NODE_UUID

版本匹配后,线程发送命令:

PROXYSQL CLUSTER_NODE_UUID <ProxySQL_GlobalVariables::uuid> <ProxySQL_Cluster::admin_mysql_ifaces>

其中 uuid 来自全局对象 GloVars.uuid,admin_mysql_ifaces 在 admin_mysql_ifaces_mutex 保护下读取(lib/ProxySQL_Cluster.cpp#L264-L269)。该命令让远端把当前节点登记为集群客户端,从而实现双向识别。

3.3 全局校验和比对:SELECT GLOBAL_CHECKSUM()

线程发送 SELECT GLOBAL_CHECKSUM(),结果集交给 ProxySQL_Cluster_Nodes::Update_Global_Checksum(lib/ProxySQL_Cluster.cpp#L4442)。该函数在 map 中定位本节点,取出结果集第一行的 64 位校验和 v,与 node->global_checksum 比较:

  • 相同:返回 false,本轮只做轻量检查;
  • 不同:覆盖本地保存的 node->global_checksum 并返回 true,表示至少一个模块的配置发生了变化,需要继续拉取模块明细。

3.4 模块校验和明细:SELECT * FROM runtime_checksums_values

当全局校验和变化时,线程执行 SELECT * FROM runtime_checksums_values ORDER BY name(query3,lib/ProxySQL_Cluster.cpp#L192),把结果交给 Update_Node_Checksums → ProxySQL_Node_Entry::set_checksums。runtime_checksums_values 的表结构定义在 include/ProxySQL_Admin_Tables_Definitions.h#L43:

CREATE TABLE runtime_checksums_values (
  name VARCHAR NOT NULL,
  version INT NOT NULL,
  epoch INT NOT NULL,
  checksum VARCHAR NOT NULL,
  PRIMARY KEY (name)
);

set_checksums 的处理逻辑(对应文档的详细流程图)对每个模块执行:

  1. 若结果集中存在该模块记录:用远端值更新本地 version、epoch、last_updated;
  2. 比较本地模块校验和与远端校验和:相同则 diff_check += 1(连续差异计数递增);不同则更新校验和、置 last_changed 为当前时间并把 diff_check 重置为 1;
  3. 若本地自身模块校验和 == 远端校验和(即自己已经是最新),则把 diff_check 清零;
  4. 若结果集中不存在某模块记录(resultset == NULL 分支):对每个模块置 last_updated = now,并按"本地校验和 == 自身版本校验和"决定 diff_check 置 0 或自增。

3.5 同步判定:diffs_before_sync 阈值

set_checksums 之后进入同步判定,条件严格按文档描述串行执行:

  1. cluster_<module>_diffs_before_sync != 0?为 0 则跳过该模块;
  2. 本地模块 version > 1?(version 为 1 表示模块配置刚从初始状态加载,通常不参与抢占式同步);
  3. own_version == 1 || local epoch > own_epoch?(即实例刚启动、或远端 epoch 更新);
  4. local diff_check >= cluster_<module>_diffs_before_sync?

只有四个条件全部满足,该模块才进入真正的拉取阶段。 这就是文档所述"差值累积到一定次数才同步"的去抖设计:diff_check 必须连续超过阈值(默认 3 次),避免瞬时抖动触发频繁的全量同步。

3.6 选择同步源:最大 epoch 节点

同步源选择由 ProxySQL_Cluster_Nodes::get_peer_to_sync_<module>(统一走 get_peer_to_sync_variables_module,lib/ProxySQL_Cluster.cpp#L4585)完成。算法遍历 umap_proxy_nodes:

  • 过滤条件:模块 version > 1;
  • 择优条件:epoch 最大的节点(且要求其 diff_check >= diff_threshold);
  • 记录该节点的 host/port、IP,以及(对带校验和的模块)其校验和值。

选出的节点即"事实来源"(source of truth)。V2 类模块(mysql_servers_v2)还会额外携带 runtime_mysql_servers 的次级校验和,用于双表一致性校验。

3.7 拉取配置、校验并应用

选中同步源后,线程用 get_credentials() 建立新连接,调用 ProxySQL_Cluster::pull_<module>_from_peer(如 lib/ProxySQL_Cluster.cpp#L1177 的 pull_mysql_query_rules_from_peer)拉取该模块最新配置。关键安全步骤:

  1. 本地对拉回的配置重新计算校验和;
  2. 与同步源返回的校验和比较;
  3. 一致才应用:清空本地模块配置表 → 插入远端数据 → 发出内部 LOAD <module> TO RUNTIME;
  4. 不一致则丢弃(防止拉取过程中远端又变更导致数据错位)。

3.8 持久化:save_to_disk

配置成功应用到运行时后,检查 cluster_<module>_save_to_disk:

  • true:发出内部 SAVE <module> TO DISK,把配置写入磁盘数据库,保证重启后依然生效;
  • false:仅保留在内存运行时,重启后丢失。

3.9 周期性的状态指标采样

每轮循环末尾还有一个独立于校验和逻辑的指标通道(详见 3.10 流程图):cluster_check_status_frequency_count 每轮自增,当累计达到 cluster_check_status_frequency 时清零并执行:

SELECT * FROM stats_mysql_global ORDER BY Variable_Name

结果交给 Update_Node_Metrics → ProxySQL_Node_Entry::set_metrics(lib/ProxySQL_Cluster.cpp#L4482),提取 Client_Connections_connected、Client_Connections_created、ProxySQL_Uptime、Questions、Servers_table_version 五项,写入环形指标缓冲区(metrics_idx 在 0..4 间滚动)。这些指标被用于 stats_proxysql_servers_metrics 统计表以及 Prometheus 指标(p_cluster_nodes_dyn_*,include/ProxySQL_Cluster.hpp#L362-L384)。

3.10 完整循环与节流

每轮循环结束后计算耗时,若小于 cluster_check_interval_ms 则 usleep 补齐,保证轮询频率受控(lib/ProxySQL_Cluster.cpp#L371-L379);连接异常时也会按该间隔 sleep 后重连。

文档提供的详细流程图(mermaid)完整描述了上述全部状态,核心链路可压缩为:

graph TB
  A[Start] --> B[SELECT @@version]
  B --> C{版本一致?}
  C -- No --> CLOSE[关闭连接]
  C -- Yes --> D[PROXYSQL CLUSTER_NODE_UUID 注册]
  D --> E[SELECT GLOBAL_CHECKSUM]
  E --> F{全局校验和变化?}
  F -- No --> METRICS[按 cluster_check_status_frequency 采样 stats_mysql_global]
  F -- Yes --> G[SELECT * FROM runtime_checksums_values]
  G --> H{模块校验和变化?}
  H -- No --> METRICS
  H -- Yes --> I[diff_check += 1]
  I --> J{diff_check >= diffs_before_sync?}
  J -- No --> METRICS
  J -- Yes --> K[选择 version>1 且 epoch 最大的节点]
  K --> L[拉取模块配置并本地计算校验和]
  L --> M{校验和一致?}
  M -- No --> DISCARD[丢弃]
  M -- Yes --> APPLY[清空+插入+LOAD TO RUNTIME]
  APPLY --> N{save_to_disk?}
  N -- Yes --> SAVE[SAVE TO DISK]
  N -- No --> METRICS

四、关键配置变量与默认值

集群行为由 Admin 变量控制,全部可在 GLOBAL VARIABLES 中查看与修改,在 lib/ProxySQL_Admin.cpp 中解析,默认值在 lib/ProxySQL_Cluster.cpp#L5888-L5917 的构造函数中初始化。

变量 默认值 含义
cluster_username 空字符串 监控/同步时用于连接远端节点的用户名;为空则线程不执行任何监控(lib/ProxySQL_Cluster.cpp#L206)
cluster_password 空字符串 对应密码
cluster_interface / admin_mysql_ifaces 空 节点注册时向远端广播的 Admin 接口地址
cluster_check_interval_ms 1000 每轮轮询的最小间隔(毫秒),实际间隔为该值与单轮耗时的较大者
cluster_check_status_frequency 10 每多少次轮询执行一次节点状态指标(stats)采样
cluster_<module>_diffs_before_sync 3 各模块(mysql_query_rules、mysql_servers、mysql_users、proxysql_servers、mysql_variables、admin_variables、ldap_variables、pgsql_query_rules、pgsql_servers、pgsql_users、pgsql_variables)连续检测到差异的阈值;0 表示禁用该模块同步
cluster_<module>_save_to_disk true 模块配置应用到运行时后是否 SAVE TO DISK 持久化
cluster_mysql_servers_sync_algorithm 1 runtime_mysql_servers 与 mysql_servers_v2 的同步算法选择(详见下节)

4.1 mysql_servers_sync_algorithm 的三种模式

enum class mysql_servers_sync_algorithm(include/ProxySQL_Cluster.hpp#L556)定义了服务器模块的特殊同步策略:

  • runtime_mysql_servers_and_mysql_servers_v2 = 1:同时同步运行时服务器状态与配置,Monitor 产生的运行时变更(如连接池状态变化)也会触发同步;
  • mysql_servers_v2 = 2:只同步 mysql_servers_v2 静态配置,仅用户显式执行的配置变更触发同步;
  • auto_select = 3:依据是否以 -M 标志启动决定——未带 -M 选模式 1,带 -M 选模式 2。

该模块也因此是唯一携带双校验和(mysql_servers_v2 校验和 + runtime_mysql_servers 校验和)的同步对象。

五、从源码看设计要点

5.1 校验和是同步的"唯一事实"

整个同步系统不依赖时间戳对账,而是以校验和 + epoch + version 三元组为唯一事实来源。runtime_checksums_values 表(见 include/ProxySQL_Admin_Tables_Definitions.h#L43)保存的就是这三个维度。这也解释了为何文档与代码反复强调"拉取配置后必须在本地重新计算校验和并与远端比对"——它是防止同步过程中数据错位、半更新状态污染集群的最后防线。

5.2 去抖与收敛:diff_check 的双重角色

diff_check 既在 set_checksums 中单调递增(连续发现差异),又在节点自身已与远端一致时清零。这构成一个"软状态":只有差异持续存在超过 diffs_before_sync 轮次才触发拉取,从而容忍单次网络抖动或瞬时不一致,同时保证配置最终收敛到 epoch 最大节点所代表的最新状态。

5.3 并发安全:模块级互斥锁

每个模块在 ProxySQL_Cluster 中都有独立的 update_<module>_mutex,多个节点的监控线程可能同时尝试同步同一模块,锁保证了"同一时刻只有一个拉取+应用操作在执行",避免配置表被并发写入撕裂。

5.4 线程生命周期与故障自愈

监控线程以 detached 方式创建(lib/ProxySQL_Cluster.cpp#L4403),连接失败时解析主机名并 sleep 后重试(lib/ProxySQL_Cluster.cpp#L390-L398);节点从 proxysql_servers 表消失后,通过 Update_Node_Metrics(..., NULL, 0) 哨兵调用感知并终止线程(lib/ProxySQL_Cluster.cpp#L402,对应 bug #1323 的修复)。这保证了集群拓扑变化后监控资源能自动回收。

六、验证与观测

集群的健康状态与同步进度可以从以下入口观测(均为仓库中已确认的实现):

结语

ProxySQL Cluster 的内部机制可以概括为一条清晰的链路:proxysql_servers 表驱动节点地图与监控线程 → 每轮以 GLOBAL_CHECKSUM() 做轻量比对 → 变化时拉取 runtime_checksums_values 明细 → 以 diff_check 与 diffs_before_sync 做去抖判定 → 从最大 epoch 节点拉取配置 → 本地校验和复核 → LOAD TO RUNTIME → SAVE TO DISK。本文所有流程均与 doc/proxysql_cluster/proxysql_cluster_working.md 及 lib/ProxySQL_Cluster.cpp 中的实际实现相互印证,读者可结合这两份材料深入每一处细节,并借助第六节的统计表与日志对生产集群进行观测验证。

登录后查看全文
proxysql