ProxySQL 仓库开发指南：构建体系、Feature Tier、TAP 测试与双协议架构详解

后端数据库负载均衡【免费下载链接】proxysqlHigh-performance proxy for MySQL and PostgreSQL项目地址https://gitcode.com/gh_mirrors/pr/proxysql点击查看免费下载ProxySQL 是一个用 C17 编写的高性能、协议感知的 MySQL / PostgreSQL 代理提供连接池、查询路由、缓存与监控能力基于 GPL 协议开源。本文以仓库根目录的 CLAUDE.md 为骨架结合源码、Makefile 与测试基础设施系统讲解本仓库的构建管线、Feature Tier 编译模型、TAP 测试流程、双协议架构与编码规范帮助开发者和 AI 编码代理快速、正确地在本仓库中完成构建、测试与代码提交。构建系统总览deps → lib → src 三段式管线ProxySQL 的构建系统基于 GNU Make采用经典的三段式流水线全部通过根目录的 Makefile 驱动deps/ → 构建 25 个 vendored 第三方依赖产物为静态库 lib/ → 编译 lib/ 下约 128 个 .cpp 文件产出 lib/libproxysql.a src/main.cpp → 链接 libproxysql.a生成最终 proxysql 可执行文件根 Makefile 负责编排三段并向下传递编译参数OPTZ、PROXYSQL*系列特性开关等deps/中的依赖均以源码形式 vendored例如jemalloc、sqlite3、mariadb-client-library、postgresql、libev、re2、libinjection、lz4/zstd、prometheus-cpp、libscram等src/main.cpp 是程序入口负责守护进程初始化与线程启动CLAUDE.md 中标注约 95K 行当前实际 3513 行——注意文档数据偏旧以仓库现状为准。常用构建命令取自 CLAUDE.md 并补充说明# 完整 release 构建自动根据 nproc/hw.ncpu 检测 -j make # Debug 构建-O0、-ggdb、-DDEBUG make debug # 带 ASAN 的构建必须 NOJEMALLOC1因为 jemalloc 与 ASAN 不兼容 NOJEMALLOC1 WITHASAN1 make build_deps_debug make debug make build_tap_test_debug # 构建 TAP 测试二进制前提先构建出 proxysql 可执行文件 make build_tap_tests # release 版测试 make build_tap_test_debug # debug 版测试 # 清理 make clean # 清理 src/lib 的目标文件与 libproxysql.a make cleanall # 全量清理包括 deps 下的第三方依赖 # 构建发行包rpm/deb/tar 等见 Makefile 中 amd64-packages/arm64-packages 目标 make packages注意 Makefile 中build_tap_tests/build_tap_test_debug均依赖build_src/build_src_debug即测试二进制必须在 proxysql 二进制构建成功之后才能编译。Feature Tier同一份代码编译出三种产品形态本仓库最具辨识度的构建机制是Feature Tier特性层级通过编译期特性开关同一份代码库产出三种产品形态。每个 Tier 都继承更低一层的全部特性。Tier开关标志对应版本追加特性Stable默认不传标志v3.0.x核心代理连接池、路由、缓存、监控InnovativePROXYSQL311v3.1.xFFTO、TSDBPlugin ChassisPROXYSQL401v4.0.x插件加载器 ABI4 阶段生命周期、query-hook、共享 Prometheus并构建打包全部 v4.0 插件含 mysqlx 与 genai/MCP标志蕴含关系源码级证据见根 MakefilePROXYSQL401 ⇒ PROXYSQL311 ⇒ PROXYSQLFFTO1 PROXYSQLTSDB1 PROXYSQLED255191Makefile 中的ifeq链自动完成上述蕴含展开设置PROXYSQL401会同时开启PROXYSQL31设置PROXYSQL311会同时开启 FFTO、TSDB 与 ED25519。关键澄清与很多新贡献者的直觉相反没有独立的PROXYSQLGENAI标志。所有 AI / MCP / RAG / LLM 功能都位于 plugins/genai/通过PROXYSQL401统一构建与打包运行时以.so插件形式通过dlopen加载默认的裸make编译的是Stable Tier明确不含 FFTO 与 TSDBMySQLFFTO.cpp/PgSQLFFTO.cpp被排除#ifdef PROXYSQLFFTO保护的符号如mysql_thread___ffto_max_buffer_size不会定义因此 CI 从不构建裸默认版本每个 CI 包构建/测试构建都会设置 Tier 标志PROXYSQL311或PROXYSQL401这在 .github/workflows/CI-*.yml 中有大量实例例如PROXYSQL311 make -j$(sysctl -n hw.ncpu)macOS v31 构建与PROXYSQL401 make ${{ env.MAKE_TARGET }}AlmaLinux genai 包构建。切换 Tier 必须 cleanstale-object tier mismatchMakefile 不会在两次调用之间追踪 Tier 标志。在某 Tier 下编译出的目标文件与lib/libproxysql.a会在下一次不同 Tier或他人构建过的目录树下被静默复用。经典症状是链接失败undefined reference to mysql_thread___ffto_max_buffer_size undefined reference to pgsql_thread___ffto_max_buffer_size这不是真实损坏也不是默认构建的 bug——它是陈旧的Tier 不匹配例如启用了 FFTO 的libproxysql.a链接了未带PROXYSQLFFTO编译的main.o。不要试图通过去掉 Tier 标志来“修复”。正确做法CLAUDE.md 原文强调是切换 Tier 时先清理并且在一个会话中对每次 make 都传递同一个Tier 标志# 切换 Tier或不确定目录树上次用什么 Tier 构建先 clean make clean # 清除 lib/ src/ 目标文件与 libproxysql.a PROXYSQL311 make -j$(nproc) # 然后统一用想要的 Tier 构建 # 如果 deps 也是在别的 Tier 下构建的还需要make cleanall会重建 deps较慢构建标志速查NOJEMALLOC1— 禁用 jemalloc 内存分配器WITHASAN1— 启用 AddressSanitizer要求NOJEMALLOC1WITHGCOV1— 启用代码覆盖率采集PROXYSQLCLICKHOUSE1— 当前构建中默认启用根 Makefile 在 deps/lib/src 各阶段均显式传入。架构MySQL 与 PostgreSQL 的双协议并行设计ProxySQL 的核心架构特点是双协议并行MySQL 与 PostgreSQL 使用同一套架构设计、但各自协议专属的实现类形成镜像的类层级架构层MySQL 实现PostgreSQL 实现协议MySQL_ProtocolPgSQL_Protocol会话MySQL_SessionPgSQL_Session线程MySQL_ThreadPgSQL_ThreadHostGroupsMySQL_HostGroups_ManagerPgSQL_HostGroups_Manager监控MySQL_MonitorPgSQL_Monitor查询处理器MySQL_Query_ProcessorPgSQL_Query_Processor日志MySQL_LoggerPgSQL_Logger上述类均有对应的 include/ 头文件与 lib/ 实现文件例如MySQL_Session.h/MySQL_Session.cpp与PgSQL_Session.h/PgSQL_Session.cpp读者可直接对照阅读。核心组件Admin 接口lib/ProxySQL_Admin.cpp、lib/Admin_Handler.cpp——基于 SQLite3 的 SQL 式配置管理支持无需重启的运行期配置变更配置库 schema 版本在 include/ProxySQL_Admin_Tables_Definitions.h 中追踪。HostGroups Manager——按 hostgroup 分配路由连接支持 master-slave、Galera、Group Replication 与 Aurora 拓扑。Query Processor——解析查询、匹配路由规则通过Query_Cache处理查询缓存。Monitor——对后端做健康检查监测复制延迟、read-only 状态与连通性。线程模型——基于 libev 的事件驱动 I/OBase_Thread为基类协议专属的线程管理器派生其上。HTTP/RESTProxySQL_HTTP_Server、ProxySQL_RESTAPI_Server——提供指标与管控端点。条件编译组件FFTOFast Forward Traffic Observer——lib/MySQLFFTO.cpp / lib/PgSQLFFTO.cppTSDB——时序指标与内嵌 DashboardClickHouse——原生 ClickHouse 协议支持GenAI / MCP / RAG / LLM——自插件拆分carve-out完成后全部位于 plugins/genai/不属于libproxysql.a与proxysql二进制本体。其加载路径可通过源码确认src/main.cpp 使用dlopen加载插件src/proxysql.cfg 中的genai_variables用于相关配置注释明确指出 GenAI 的变量初始化、handler 构造与 shutdown 均已移交至 genai 插件的 init/start 回调见 src/main.cpp 相关注释。测试TAP 协议 Docker 后端基础设施测试采用 TAPTest Anything Protocol协议运行在 Docker 化的后端基础设施之上。测试代码位于 test/tap/基础设施脚本位于 test/infra/。铁律不要手动搭建 Docker 环境永远使用run-tests-isolated.bash它统一负责基础设施搭建、ProxySQL 启动、测试执行与清理。绝不要手动创建 Docker 网络、启动容器或运行 init 脚本——runner 会全部代劳。被测试的 proxysql 二进制必须是 DEBUG 构建。隔离测试 harnessproxysql-tester.py会下发 debug-only 的 admin 命令LOAD DEBUG FROM DISK、admin-debug变量两者均为#ifdef DEBUG保护release 二进制会报Unknown global variable: admin-debug或near LOAD: syntax error而无法重新配置。这一点在 test/infra/README.md 中有同步印证。标准流程# 1) 先构建 DEBUG 版二进制并保持 Tier 标志一致 PROXYSQL311 make debug # 2) 搭建基础设施后端 ProxySQL 容器 WORKSPACE$(pwd) INFRA_IDdev-$USER TAP_GROUPmysql84-g1 test/infra/control/ensure-infras.bash # 3) 运行一个 TAP group 的全部测试 WORKSPACE$(pwd) INFRA_IDdev-$USER TAP_GROUPmysql84-g1 test/infra/control/run-tests-isolated.bash # 4) 运行组内单个测试 —— 用 TEST_PY_TAP_INCL 正则过滤器 # 不要为隔离单个测试而临时建组测试仍属于其真实分组只是做过滤 # 详见 test/infra/SKILL.md 与 test/infra/README.md WORKSPACE$(pwd) INFRA_IDdev-$USER TAP_GROUPlegacy-g4 \ TEST_PY_TAP_INCLpgsql-reg_test_5866_result_format-t \ test/infra/control/run-tests-isolated.bash # 5) 在不拆除后端的情况下换入重建的二进制 # ProxySQL 容器运行的是工作区构建的二进制重建后需重新执行此脚本 # 它只重建 ProxySQL 容器保留后端普通 ensure-infras.bash 不会拾取 # 已运行 ProxySQL 的重建二进制docker restart 也不是受支持的机制 WORKSPACE$(pwd) INFRA_IDdev-$USER TAP_GROUPmysql84-g1 test/infra/control/start-proxysql-isolated.bash可用的 TAP group 定义在 test/tap/groups/groups.json组名遵循infra-gN模式如mysql84-g1、legacy-g2、pgsql16-g1、unit-tests-g1等。TEST_PY_TAP_INCL是与组内测试名匹配的正则——这是文档规定的运行单个测试的方式。从 groups.json 可以看到测试条目可携带版本门控注解如proxysql_min_version:4.0同一测试可同时挂到多个组。DO NOT 清单不要手动创建 Docker 网络docker network create不要手动启动容器docker start、docker run不要直接运行docker-compose-init.bash——请用ensure-infras.bash不要在 worktree 之间符号链接构建产物——每个 worktree 单独构建不要在 worktree 或仓库之间复制源文件不要直接cd test/tap/tests make并期望无基础设施也能通过。测试文件约定测试文件位于 test/tap/tests/命名遵循test_*.cpp或*-t.cpp模式。测试二进制通过 test/tap/tests/Makefile 中的模式规则构建make testname-t会把testname-t.cpp编译成testname-t。新增测试无需改 Makefile——只要添加.cpp文件并在groups.json中注册即可。CI/测试失败的处理纪律项目的测试质量要求极高永远不要把 CI 失败当作pre-existing或flaky来打发——这些词是观察而非分析把它们当结论会让真实 bug 存活下来。当分支或 PR 上的 CI 失败时阅读真实失败打开失败的测试日志、其产生的 proxysql 服务日志与测试源码定位具体的断言、超时、崩溃或非零退出并在报告中引用相关行。陈述根因而非症状Test X failed 是症状根因是为什么——竞态条件、陈旧 fixture、资源泄漏、协议回归、环境不匹配等。拆成两个独立问题并分别用证据回答本次改动是否导致该失败——通过逐 commit 推理与代码路径分析回答而不是只对比基线的通过/失败率该测试是否与本次改动无关地本身就是坏的——这是独立问题早于本改动就存在的失败仍是要修复或登记的问题而不是带病合并的理由。若本次会话内无法确定根因明确说出来并给出下一步调查建议带日志重跑、插桩测试、登记跟踪 issue不要用flaky掩盖不确定性。反复失败的测试是更高优先级的 bug而不是更低优先级的——复现本身就是失败模式可复现的证据这正是它能被修复的原因。单元测试 harness单元测试位于 test/tap/tests/unit/通过自定义 harness 链接libproxysql.a。测试必须使用test_globals.h与test_init.h完整模式见 doc/agents/project-conventions.md其中明确要求#include test_globals.h与#include test_init.h。从单元测试文件即可看到大量直接面向内部类的用例例如auth_unit-t.cpp、connection_pool_unit-t.cpp、backend_sync_unit-t.cpp、caching_sha2_rsa_unit-t.cpp、duckdb_config_unit-t.cpp等。关键依赖一览deps/下 vendored 的第三方依赖及其用途见 CLAUDE.md 与 deps/Makefilejemalloc— 内存分配器可用NOJEMALLOC1关闭ASAN 构建必须关闭sqlite3— admin 配置存储mariadb-client-library— MySQL 协议postgresql— PostgreSQL 协议re2、pcre2— 正则引擎libev— 事件循环libinjection— SQL 注入检测lz4、zstd— 压缩curl、libmicrohttpd、libhttpserver— HTTPprometheus-cpp— 指标libscram— SCRAM 认证。代码布局include/ — 全部头文件.h/.hpp头文件保护采用#ifndef __CLASS_*_H风格lib/ — 核心库源码约 128 个 .cpp通常一文件一类src/main.cpp — 程序入口、守护进程初始化、线程启动test/tap/ — TAP 测试框架与用例test/infra/ — 基于 Docker 的测试环境.github/workflows/ — CI/CD 流水线selftests、TAP 测试、包构建、CodeQL架构总览见 doc/GH-Actions/README.mdProxySQL 使用双分支 caller/reusable 拆分CI-*.yml在v3.0ci-*.yml在GH-Actions分支该文档是权威参考。Agent 协作指南与编码规范仓库为 AI 编码代理准备了专门文档doc/agents/doc/agents/project-conventions.md — ProxySQL 专属规则目录、构建、测试 harness、git 工作流doc/agents/task-assignment-template.md — 可分配给 AI agent 的 issue 编写模板doc/agents/common-mistakes.md — 已知的 agent 失败模式及预防/检测方法。编码约定类名PascalCase并带协议前缀MySQL_、PgSQL_、ProxySQL_成员变量snake_case常量/宏UPPER_SNAKE_CASE必须 C17条件编译使用#ifdef PROXYSQL31、#ifdef PROXYSQL40、#ifdef PROXYSQLFFTO、#ifdef PROXYSQLTSDB、#ifdef PROXYSQLCLICKHOUSEPROXYSQLGENAI已不再守卫任何核心代码GenAI 插件拆分完成后它只存在于 plugins/genai/ 内部性能关键代码注意对热路径的影响资源管理使用 RAII内存分配使用 jemalloc同步使用 pthread mutex计数器使用std::atomic。总结给开发者的最小正确工作流把以上要点浓缩成一个可复制的起步流程# 1) 选好目标 Tier并保持一致 PROXYSQL311 make -j$(nproc) # 日常开发推荐 v3.1或 PROXYSQL401 用于 genai 插件 # 2) 切换 Tier 时务必先 clean make clean PROXYSQL401 make -j$(nproc) # 3) 跑 TAP 测试debug 二进制 隔离 runner PROXYSQL311 make debug make build_tap_test_debug WORKSPACE$(pwd) INFRA_IDdev-$USER TAP_GROUPmysql84-g1 \ test/infra/control/run-tests-isolated.bash遵循同一 Tier 贯穿构建会话 切换即 clean 始终用隔离 runner 跑测试 以根因分析对待 CI 失败这几条纪律即可避免本仓库绝大多数构建与测试陷阱。更详细的规则请随时回查 CLAUDE.md、doc/agents/project-conventions.md 与 test/infra/SKILL.md。赞分享后端数据库负载均衡【免费下载链接】proxysqlHigh-performance proxy for MySQL and PostgreSQL项目地址https://gitcode.com/gh_mirrors/pr/proxysql点击查看免费下载相关推荐Streamlit 仓库开发指南架构布局、uv/make 构建策略与四层测试体系详解Streamlit 仓库开发指南架构布局、uv/make 构建策略与四层测试体系详解 本文以仓库根目录 AGENTS.md https://link.gitc数据可视化后端前端Trigger.dev 仓库开发协作指南读懂 AGENTS.md 与 CLAUDE.md 分层的构建、测试与架构体系Trigger.dev 仓库开发协作指南读懂 AGENTS.md 与 CLAUDE.md 分层的构建、测试与架构体系 本指南以 Trigger.dev 开源仓AI Agent后端任务调度开发工具可观测性AI 应用Uppy 仓库开发指南Monorepo 架构、插件体系与构建测试实践Uppy 仓库开发指南Monorepo 架构、插件体系与构建测试实践 本文是基于 Uppy 开源仓库根目录 CLAUDE.md https://link.gi前端UI组件后端上一篇基于 Vercel 仓库 Jekyll 示例从 Front Matter 到静态站点构建的完整实战解析下一篇Ovine用JSON构建企业级管理系统的利器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考