企业官网建设流程全解析

• 后端
• 数据库
• 负载均衡

ProxySQL 内置了一套基于 SQLite 的轻量级时序数据库（TSDB）子系统，用于把内建 Prometheus 注册表中的指标与后端服务器 TCP 探针健康数据周期性地落盘存储。本指南将带你从零开始：如何通过tsdb-前缀全局变量启用该功能、如何用管理 SQL 验证状态与表结构，以及如何查询原始样本、小时级聚合与后端探针健康数据，并深入剖析背后的采样、降采样与保留清理机制，让你能直接在自己的 ProxySQL 实例上复现并投入使用。

1. 什么是 ProxySQL 嵌入式 TSDB

TSDB（Time-Series Database）是集成在 ProxySQL 内部的时间序列存储子系统，实现位于ProxySQL_Statistics（见 lib/ProxySQL_Statistics.cpp）。它的职责有两部分：

• 指标记录：周期性从内建 Prometheus 注册表（GloVars.prometheus_registry）采集全部 metric family，归一化后写入 SQLite 表stats_history.tsdb_metrics；
• 后端健康探针：可选地以 TCP 连接方式对mysql_servers/pgsql_servers中的后端服务器做存活探测，结果写入stats_history.tsdb_backend_health。

所有数据存储在statsdb_disk对应的stats_history库中，可通过标准 SQL 直接查询，无需额外部署时序数据库组件。系统级设计细节可参考 doc/tsdb/embedded_tsdb_architecture.md 与 doc/tsdb/embedded_tsdb_overview.md。

2. 启用 TSDB：三步配置命令

TSDB 配置项全部是带tsdb-前缀的全局变量，沿用 ProxySQL 经典的"内存变量 → 运行时 → 磁盘"三段式生命周期管理。启用主开关：

SET tsdb-enabled=1; LOAD TSDB VARIABLES TO RUNTIME; SAVE TSDB VARIABLES TO DISK;

如果你还需要采集后端服务器的连通性健康数据，再开启探针开关：

SET tsdb-monitor_enabled=1; LOAD TSDB VARIABLES TO RUNTIME; SAVE TSDB VARIABLES TO DISK;

命令语义说明：

• LOAD TSDB VARIABLES TO RUNTIME：把当前内存中的 TSDB 变量应用到运行时（等价于LOAD TSDB VARIABLES TO RUN，也支持FROM MEM等别名）；
• SAVE TSDB VARIABLES TO DISK：把运行时/内存值持久化到磁盘（等价于SAVE TSDB VARIABLES FROM RUN）；
• 另有LOAD TSDB VARIABLES FROM CONFIG用于从配置文件回载，SHOW TSDB VARIABLES用于查看当前值。

这些命令的解析逻辑可以在 lib/Admin_Handler.cpp 中找到，其处理流程与MYSQL/PGSQL变量命令保持一致（见 doc/tsdb/embedded_tsdb_architecture.md 的 Configuration Lifecycle 一节）。

2.1 配置变量速查表

上述默认值（retention_days=7、monitor_enabled=0、monitor_interval=10）与取值范围在 lib/ProxySQL_Statistics.cpp 的初始化与变量解析代码中得到印证。完整变量说明参见 doc/tsdb/embedded_tsdb_reference.md。

说明：LOAD TSDB VARIABLES TO RUNTIME与SAVE TSDB VARIABLES TO DISK均需要组合使用才能让变更同时生效并持久化；单独执行SET只修改内存中的管理变量。

3. 验证运行状态：SHOW TSDB STATUS

启用后，可以用管理命令检查子系统运行状态：

SHOW TSDB STATUS;

该命令在 lib/Admin_Handler.cpp 中被解析，最终由ProxySQL_Statistics::get_tsdb_status()（见 lib/ProxySQL_Statistics.cpp）计算返回，内部通过SELECT COUNT(DISTINCT metric_name || labels)统计序列数、SELECT COUNT(*)统计数据点总数，并汇总磁盘占用与最旧/最新数据点时间。同时可用SHOW TSDB VARIABLES核对当前变量值是否与预期一致。

4. 验证表结构：查询 sqlite_master

TSDB 创建的表都位于stats_history库中，且以tsdb_前缀命名。查看当前已存在的 TSDB 表：

SELECT name FROM stats_history.sqlite_master WHERE type='table' AND name LIKE 'tsdb_%';

正常情况下应能看到三张核心表：

• tsdb_metrics：原始采样数据；
• tsdb_metrics_hour：小时级聚合（rollup）数据；
• tsdb_backend_health：后端探针健康数据。

三张表的完整 DDL 定义如下（见 doc/tsdb/embedded_tsdb_specs.md 与 doc/tsdb/embedded_tsdb_reference.md）：

CREATE TABLE tsdb_metrics ( timestamp INT NOT NULL, -- Unix 秒级时间戳 metric_name TEXT NOT NULL, -- 指标名（与 Prometheus 暴露名一致） labels TEXT NOT NULL DEFAULT '{}', -- 标签，JSON 文本 value REAL, -- 采样值 PRIMARY KEY (timestamp, metric_name, labels) ) WITHOUT ROWID; CREATE TABLE tsdb_metrics_hour ( bucket INT NOT NULL, -- 小时桶起点（timestamp/3600*3600） metric_name TEXT NOT NULL, labels TEXT NOT NULL DEFAULT '{}', avg_value REAL, max_value REAL, min_value REAL, count INT, PRIMARY KEY (bucket, metric_name, labels) ) WITHOUT ROWID; CREATE TABLE tsdb_backend_health ( timestamp INT NOT NULL, hostgroup INT NOT NULL, -- 主机组 ID hostname TEXT NOT NULL, -- 后端主机名 port INT NOT NULL, -- 后端端口 probe_up INT NOT NULL, -- 探测是否成功（1/0） connect_ms INT, -- 连接耗时（毫秒） PRIMARY KEY (timestamp, hostgroup, hostname, port) ) WITHOUT ROWID;

三张表都使用WITHOUT ROWID与复合主键设计，避免重复写入同一时间点的同一条序列。

5. 查询原始采样数据（tsdb_metrics）

tsdb_metrics保存的是按tsdb-sample_interval（默认 5 秒）周期采集的原始样本。查询最近 5 分钟的样本：

SELECT datetime(timestamp,'unixepoch') AS ts, metric_name, labels, value FROM stats_history.tsdb_metrics WHERE timestamp > unixepoch() - 300 ORDER BY timestamp DESC LIMIT 50;

字段含义：

• ts：把 Unix 时间戳格式化为可读时间；
• metric_name：指标名，例如process_resident_memory_bytes、mysql_questions_total等；
• labels：该样本携带的 Prometheus 标签（JSON 文本），如{"hostgroup":"1"}，无标签时为{}；
• value：数值采样值。

其写入路径对应源码中的tsdb_sampler_loop()（见 lib/ProxySQL_Statistics.cpp）：采样触发时先调用update_modules_metrics()刷新模块指标，再执行GloVars.prometheus_registry->Collect()拉取全部 metric family，在单个事务（BEGIN/COMMIT）中逐条写入，保证一批样本的原子性。

5.1 指标家族（Metric Family）存储约定

由于指标直接来自 Prometheus 注册表且注册表会随版本演化，TSDB 代码中不维护固定指标清单，而是按类型统一处理（详见 doc/tsdb/embedded_tsdb_metrics_catalog.md）：

这条映射逻辑在 lib/ProxySQL_Statistics.cpp 的switch (family.type)分支中有完整实现，与 doc/tsdb/embedded_tsdb_reference.md 中的 Ingestion Mapping 表一致。

6. 查询小时级聚合（tsdb_metrics_hour）

tsdb_metrics_hour是按小时桶聚合的降采样数据，用于长周期趋势分析，避免直接扫描海量原始数据。查询最近 24 小时的聚合结果：

SELECT datetime(bucket,'unixepoch') AS hour, metric_name, avg_value, max_value, min_value, count FROM stats_history.tsdb_metrics_hour WHERE bucket > unixepoch() - 86400 ORDER BY bucket;

字段含义：hour为小时桶起点；avg_value/max_value/min_value为该小时内样本的平均值、最大值、最小值；count为该小时内的样本条数。

底层降采样由tsdb_downsample_metrics()（见 lib/ProxySQL_Statistics.cpp）驱动，核心 SQL 为：

INSERT OR REPLACE INTO tsdb_metrics_hour SELECT (timestamp/3600)*3600 AS bucket, metric_name, labels, AVG(value) AS avg_value, MAX(value) AS max_value, MIN(value) AS min_value, COUNT(*) AS count FROM tsdb_metrics WHERE timestamp >= <last_hour> AND timestamp < <current_hour> GROUP BY bucket, metric_name, labels;

实现细节值得注意：

• 通过SELECT MAX(bucket) FROM tsdb_metrics_hour找出已处理的最新小时桶，再对边界桶重新聚合，保证在小时边界前后到达的指标也能被正确纳入（INSERT OR REPLACE使重算具有幂等性）；
• 该任务每小时执行一次（tsdb_downsample_timetoget使用3600ULL * 1000000ULL微秒间隔，见 lib/ProxySQL_Statistics.cpp）。

7. 查询后端探针健康（tsdb_backend_health）

若开启了tsdb-monitor_enabled，TSDB 会按tsdb-monitor_interval（默认 10 秒）对runtime_mysql_servers中的后端做 TCP 连通性探测，结果写入tsdb_backend_health。查询最近 1 小时的探针结果：

SELECT datetime(timestamp,'unixepoch') AS ts, hostgroup, hostname, port, probe_up, connect_ms FROM stats_history.tsdb_backend_health WHERE timestamp > unixepoch() - 3600 ORDER BY timestamp DESC;

字段含义：probe_up为 1 表示探测成功、0 表示失败；connect_ms为本次 TCP 连接耗时（毫秒）。

其实现位于tsdb_monitor_loop()（见 lib/ProxySQL_Statistics.cpp），执行流程如下：

1. 通过MyHGM->dump_table_mysql("mysql_servers")与PgHGM->dump_table_pgsql("pgsql_servers")拉取当前 MySQL/PgSQL 后端目标（与运行时表构建走同一 hostgroup-manager 路径，因此也覆盖了 PostgreSQL 后端）；
2. 以每批最多 16 个目标（max_concurrent）的方式，用std::async并发执行probe_backend()探测；
3. 探测函数采用非阻塞connect()+poll()1 秒超时（见 lib/ProxySQL_Statistics.cpp），并精确测量connect_ms；
4. 网络完成阶段不持有 TSDB 互斥锁，全部结果收集完毕后才统一加锁并批量BEGIN/COMMIT写入，避免不可达后端拖慢采样、状态查询与清理任务。

8. 数据保留策略（Retention）

TSDB 按以下规则自动清理过期数据（见 lib/ProxySQL_Statistics.cpp 的tsdb_retention_cleanup()，该任务同样每小时执行一次）：

• 原始指标tsdb_metrics：保留tsdb-retention_days天（默认 7 天，最小强制 1 天）；
• 后端探针tsdb_backend_health：保留tsdb-retention_days天；
• 小时聚合tsdb_metrics_hour：固定保留 365 天。

对应的删除语句形如DELETE FROM tsdb_metrics WHERE timestamp < <now - 86400*retention_days>。因此，查询原始数据的时间窗口不应超过tsdb-retention_days，超过后请改用小时聚合表。

9. 内置 Web 仪表盘与 REST API

除了 SQL 查询，TSDB 还提供 Web 与 REST 两种访问方式（详见 doc/tsdb/ui_endpoints.md）：

• Web 仪表盘：http://<proxysql_host>:6080/tsdb，基于 Chart.js 交互图表，支持选择指标与时间范围（Last Hour / Last Day / Last Week）；
• REST API（返回 JSON，便于外部系统集成）：

10. 使用建议与注意事项

• 所有 TSDB 设置均为tsdb-前缀全局变量，只能通过SET+LOAD TSDB VARIABLES TO RUNTIME生效，务必配合SAVE TSDB VARIABLES TO DISK持久化，否则重启后配置丢失；
• 原始表与探针表受tsdb-retention_days约束，长周期历史分析请使用tsdb_metrics_hour（保留 365 天）；
• 采样与探针都要求tsdb-enabled=1；探针还额外要求tsdb-monitor_enabled=1；
• 探针会额外产生网络连接，若后端规模较大或网络不可靠，请合理设置tsdb-monitor_interval以控制探测频率；
• 若当前仓库版本中ProxySQL_Statistics.cpp的 TSDB 代码被宏开关包裹（文件末尾#endif），确认构建时启用了对应特性，否则相关变量与命令不会生效。

至此，你已经掌握了 ProxySQL 嵌入式 TSDB 从启用、验证到查询的完整闭环，并能结合 lib/ProxySQL_Statistics.cpp 理解其采样、降采样、探针与清理的底层机制。更多细节可继续阅读 doc/tsdb/embedded_tsdb_reference.md（变量与表定义）、doc/tsdb/embedded_tsdb_metrics_catalog.md（指标覆盖）与 doc/tsdb/embedded_tsdb_specs.md（技术规格）。

• 后端
• 数据库
• 负载均衡