后端数据库负载均衡【免费下载链接】proxysqlHigh-performance proxy for MySQL and PostgreSQL项目地址https://gitcode.com/gh_mirrors/pr/proxysql点击查看免费下载ProxySQL 的 MCPModel Context Protocol模块通过 HTTPS 提供 JSON-RPC 2.0 服务将 MySQL/PostgreSQL 代理的配置、观测、查询、管理与 AI 能力开放给 LLM 工具链。本文以 doc/MCP/VARIABLES.md 为主体完整讲解 MCP 模块全部mcp-*配置变量的类型、默认值、取值范围、运行时语义与三层持久化机制并结合仓库源码MCP_Thread.cpp、MCP_Endpoint.cpp、plugin_commands.cpp与表结构定义ProxySQL_Admin_Tables_Definitions.h展开底层原理。阅读本文后你将能够通过管理接口完整配置 MCP 服务、为每个端点正确设置 Bearer Token 认证、理解并排查target_id动态路由与后端凭据模型以及熟练使用 LOAD/SAVE/CHECKSUM 命令族管理变量与 Profile 的持久化。一、MCP 模块与变量体系总览MCP 模块为 LLM 与 ProxySQL 之间提供基于JSON-RPC 2.0 over HTTPS的集成通道包含配置config、观测stats、查询query、管理admin、缓存cache与 AI 功能ai、rag等端点每个端点都配有专门的工具处理器Tool Handler用于数据库探索与 LLM 集成。所有 MCP 配置变量均存放在管理接口的global_variables表中统一使用mcp-前缀可以在运行时通过管理接口修改。从源码看变量清单定义于mcp_thread_variables_names[]数组MCP_Thread.cpp变量读写经由MCP_Threads_Handler::set_variable()/get_variable_string()完成并且全部操作在处理器内部的pthread_rwlock读写锁保护下串行化避免并发读写竞态MCP_Thread.cpp。从架构角度MCP 模块由MCP_Threads_Handler统一管理配置变量、状态变量、HTTPS 服务器ProxySQL_MCP_Server与各端点工具处理器详细组件关系见 doc/MCP/Architecture.md。该模块属于 genai 插件需以PROXYSQL401构建并加载ProxySQL_GenAI_Plugin.so插件生命周期与加载方式见 plugins/genai/README.md。二、服务端配置变量mcp-enabled属性值类型Boolean默认值false运行时是需要重启 MCP 服务器后生效启用或禁用 MCP HTTPS 服务器。示例SET mcp-enabledtrue; LOAD MCP VARIABLES TO RUNTIME;源码中该变量默认值为falseset_variable()接受true/1或false/0两种写法MCP_Thread.cpp。注意开启 MCP 前必须为每个要使用的端点配置认证令牌见第三节否则端点会拒绝所有请求。mcp-port属性值类型Integer默认值6071取值范围1024-65535运行时是需要重启 MCP 服务器后生效MCP 服务器的 HTTPS 监听端口。示例SET mcp-port7071; LOAD MCP VARIABLES TO RUNTIME;源码对端口的校验为port 0 port 65536MCP_Thread.cpp文档建议使用 1024 以上的非特权端口。端口变更后 MCP 监听器需要重启才会在新端口上提供服务。mcp-timeout_ms属性值类型Integer默认值3000030 秒取值范围1000-3000001 秒至 5 分钟运行时是所有 MCP 端点的请求超时时间毫秒。示例SET mcp-timeout_ms60000; LOAD MCP VARIABLES TO RUNTIME;源码默认值为30000set_variable()仅校验timeout 0MCP_Thread.cpp文档建议的取值范围为 1000-300000超时值直接作用于请求处理路径。mcp-use-ssl源码补充变量该变量未在 VARIABLES.md 正文列出但源码定义中存在类型 Boolean默认值true出于安全考虑默认启用 TLS用于开关 MCP 服务器的 SSL/TLSMCP_Thread.cpp。MCP 服务器使用 ProxySQL datadir 中的 SSL 证书详见第七节安全注意事项。观测类上限变量源码补充在变量名数组中还存在三个与观测端点相关的变量MCP_Thread.cppmcp-stats_show_queries_max_rowsstats.show_queries工具保留 Top-K 窗口的运行时上限默认200源码在设置时强制限制在1-1000之间硬性安全上限调用方请求的分页limit offset不得超过该值。mcp-stats_show_processlist_max_rowsstats.show_processlist工具返回行数上限默认200同样在1-1000之间强制收敛。mcp-stats_enable_debug_tools默认false为true时才向常规 MCP 使用暴露主要用于排障与开发诊断的调试类 stats 工具。三、端点认证变量非空 Bearer Token 是强制要求以下变量分别控制/mcp/config、/mcp/stats、/mcp/query、/mcp/admin、/mcp/cache、/mcp/ai、/mcp/rag各端点的 Bearer Token 认证。根据 GHSA-7wh6-2vcc-gcm4 / CVE-2026-48774当某端点的*_endpoint_auth变量为空时该端点会拒绝所有请求。每个端点都必须显式配置非空的 Bearer Token 后才接受请求原先空值 免认证的行为已被移除因为每个端点要么能在后端执行 SQL要么能读取/修改敏感的代理状态。该安全决策在 MCP_Endpoint.cpp 中有直接体现authenticate_request()首先按端点名取对应令牌若为空立即proxy_error并拒绝请求令牌提取支持Authorization: Bearer token请求头RFC 7235auth-scheme 大小写不敏感并保留?tokenxxx查询参数回退便于简单测试MCP_Endpoint.cpp。变量端点默认值说明mcp-config_endpoint_auth/mcp/config必需为空时拒绝所有请求mcp-stats_endpoint_auth/mcp/stats必需为空时拒绝所有请求mcp-query_endpoint_auth/mcp/query必需该端点在配置的 MCP 目标后端上执行 SQL必须设置令牌后才会响应mcp-admin_endpoint_auth/mcp/admin必需管理工具admin_kill_query、admin_flush_cache、admin_reload属高危操作禁止无认证暴露mcp-cache_endpoint_auth/mcp/cache必需为空时拒绝所有请求mcp-ai_endpoint_auth/mcp/ai必需AI 工具可通过 LLM 驱动的工具调用在后端分发 SQLmcp-rag_endpoint_auth/mcp/rag必需RAG 检索端点的令牌源码与 Architecture.md 中定义配置示例SET mcp-config_endpoint_authmy-secret-token; SET mcp-stats_endpoint_authstats-token; SET mcp-query_endpoint_authquery-token; SET mcp-admin_endpoint_authadmin-token; SET mcp-cache_endpoint_authcache-token; SET mcp-ai_endpoint_authai-token; LOAD MCP VARIABLES TO RUNTIME;四、查询工具处理器与动态目标发现Query Tool Handler 为 LLM 提供 MySQL 数据库探索与两阶段发现two-phase discovery能力工具类别包括inventory列出数据库与表targets发现逻辑路由目标list_targetsstructure获取表结构profiling分析查询性能sampling采样表数据query执行 SQL 查询relationships推断表关系catalog目录操作discovery两阶段发现工具静态采集 LLM 分析agentAgent 协调工具llmLLM 交互工具动态目标发现与路由模型查询工具采用逻辑target_id路由模型后端凭据由服务器管理使用list_targets获取可发现的discoverable后端目标。活动目标来自模块内存中的目标-认证联合映射joined target/auth map该映射由LOAD MCP PROFILES TO RUNTIME从main.mcp_target_profiles与main.mcp_auth_profiles安装而来。MCP 服务器将target_id映射到auth_profile_id并在内部应用后端凭据。MCP 客户端绝不能在工具参数中发送后端凭据。客户端应向查询工具传递target_id而不是主机/协议细节。从源码看目标-认证上下文MCP_Target_Auth_Context携带target_id、protocolmysql/pgsql、hostgroup_id、auth_profile_id、db_username、db_password、default_schema、max_rows、timeout_ms、allow_explain、allow_discovery与descriptionMCP_Thread.h查询执行连接池以target_id auth_profile_id为键进行隔离。五、后端凭据模型凭据定义在服务端表中后端凭据定义在 MCP 表中而非客户端请求中mcp_auth_profiles/runtime_mcp_auth_profiles后端认证配置文件服务端持有的数据库用户名/密码、默认 schema、SSL 选项。mcp_target_profiles/runtime_mcp_target_profiles目标路由配置文件target_id到协议、主机组、认证配置与策略的映射。MCP_Threads_Handler将可编辑的main.mcp_auth_profiles与main.mcp_target_profiles表安装进内存中的目标/认证映射查询执行器连接池使用该映射runtime_前缀表则是该模块快照的只读投影仅用于检查。对应的表结构定义ProxySQL_Admin_Tables_Definitions.h-- 认证配置文件 CREATE TABLE mcp_auth_profiles ( auth_profile_id VARCHAR PRIMARY KEY NOT NULL, db_username VARCHAR NOT NULL, db_password VARCHAR NOT NULL, default_schema VARCHAR DEFAULT , use_ssl INT CHECK (use_ssl IN (0,1)) NOT NULL DEFAULT 0, ssl_mode VARCHAR DEFAULT , comment VARCHAR DEFAULT ); -- 目标路由配置文件 CREATE TABLE mcp_target_profiles ( target_id VARCHAR PRIMARY KEY NOT NULL, protocol VARCHAR NOT NULL CHECK (protocol IN (mysql,pgsql)), hostgroup_id INT CHECK (hostgroup_id 0) NOT NULL, auth_profile_id VARCHAR NOT NULL, description VARCHAR DEFAULT , max_rows INT CHECK (max_rows 0) NOT NULL DEFAULT 200, timeout_ms INT CHECK (timeout_ms 0) NOT NULL DEFAULT 2000, allow_explain INT CHECK (allow_explain IN (0,1)) NOT NULL DEFAULT 1, allow_discovery INT CHECK (allow_discovery IN (0,1)) NOT NULL DEFAULT 1, active INT CHECK (active IN (0,1)) NOT NULL DEFAULT 1, comment VARCHAR DEFAULT );值得注意mcp_target_profiles.auth_profile_id与mcp_auth_profiles之间没有外键约束INSERT 时不做存在性校验因此悬空引用必须依靠运行时排查——这正是第十节effective/skip_reason两列存在的意义。从源码实现看ABI-3 分离职责设计将每张表拆成三组操作MCP_Thread.cppinstall_X_from_admin读取main.mcp_X行替换内存快照任一 Profile 表变化都会重建联合映射target_auth_map保证监听器消费的视图始终一致。save_X_to_admin_table将内存快照整体 REPLACE 回可编辑的main.mcp_X表从不读取runtime_X。project_X_to_runtime_view从内存快照 DELETEINSERT 填充runtime_mcp_X由 chassis 在任意管理端 SELECT 命中runtime_mcp_X之前自动触发注册于 plugin_tables.cpp。其中install_profiles_from_admin与save_profiles_to_admin_table对两张表是原子的安装时单次写锁同时交换两个向量并重建一次映射避免 auth_v2 配 target_v1 的错配窗口保存时在单个 BEGIN/COMMIT 事务内先删目标表再删认证表外键删除顺序再先写父表auth后写子表targetMCP_Thread.cpp。六、Catalog 配置目录数据库路径硬编码为 ProxySQL datadir 下的mcp_catalog.db无法在运行时更改。Catalog 存储两阶段发现过程中发现的数据库 schemaLLM 记忆摘要、领域、指标工具使用统计搜索历史七、管理命令查看、修改、Profile 与校验和查看变量-- 查看所有 MCP 变量 SHOW MCP VARIABLES; -- 查看特定变量 SELECT variable_name, variable_value FROM global_variables WHERE variable_name LIKE mcp-%;修改变量-- 设置变量 SET mcp-enabledtrue; -- 加载到运行时 LOAD MCP VARIABLES TO RUNTIME; -- 保存到磁盘 SAVE MCP VARIABLES TO DISK;Profile 命令族面向 MCP 后端 Profile认证 目标一体的统一命令族-- Disk - Memory LOAD MCP PROFILES FROM DISK; LOAD MCP PROFILES TO MEMORY; -- Memory - Runtime LOAD MCP PROFILES TO RUNTIME; LOAD MCP PROFILES FROM MEMORY; -- Runtime - Memory SAVE MCP PROFILES TO MEMORY; SAVE MCP PROFILES FROM RUNTIME; -- Memory - Disk SAVE MCP PROFILES TO DISK;这些命令的实际注册与别名映射见 plugin_commands.cppLOAD MCP X TO RUNTIME是规范命令同时提供FROM MEMORY/FROM MEM/TO RUN等别名LOAD MCP PROFILES TO RUNTIME是整个 Profile 命令族中唯一会应用 Profile 并可能启动/重启 MCP 监听器的动词。校验和命令-- 磁盘变量校验和 CHECKSUM DISK MCP VARIABLES; -- 内存变量校验和 CHECKSUM MEM MCP VARIABLES; -- 运行时变量校验和 CHECKSUM MEMORY MCP VARIABLES;八、变量三层持久化模型变量可在三个层面持久化Diskdisk.global_variables— 持久化存储Memorymain.global_variables— 活动配置Runtimeruntime_global_variables— 当前生效值LOAD MCP VARIABLES FROM DISK → Disk to Memory LOAD MCP VARIABLES TO RUNTIME → Memory to Runtime SAVE MCP VARIABLES TO DISK → Memory to Disk SAVE MCP VARIABLES FROM RUNTIME → Runtime to Memory源码层面LOAD MCP VARIABLES TO RUNTIME将main.global_variables中的mcp-*切片推送进MCP_Threads_Handler并发布plugin_commands.cppLOAD MCP VARIABLES FROM CONFIG则是独立的配置文件工作流重新读取proxysql.cnf中的mcp块、应用变量并重新评估监听器。SAVE MCP VARIABLES TO DISK动词仍由核心core持有属于纯global_variables拷贝。九、Profile 与 Query Rule 的持久化与启动恢复mcp_auth_profiles、mcp_target_profiles与mcp_query_rules遵循同样的三层模型并在重启后自动恢复SAVE MCP PROFILES TO DISK → Memory to Disk SAVE MCP QUERY RULES TO DISK → Memory to Disk (restart) → Disk to Memory, then Memory to Runtime在启动时Admin 在 genai 插件的 start 阶段运行前先把磁盘上的副本复制回main插件再从main安装到运行时因此重启后无需再执行LOAD MCP PROFILES FROM DISKplugins/genai/README.md 中Startup persistence一节对该行为有明确说明。LOAD MCP X FROM DISK以及它的TO MEMORY别名只做 disk → memory 移动不触碰运行时因此可以先暂存stage一份磁盘配置在main.中审阅或编辑后再提交。在 disk/memory/runtime 工作流中LOAD MCP X TO RUNTIME才是应用配置的步骤并可能启动或重启 MCP 监听器LOAD MCP PROFILES FROM DISK; -- 暂存disk - main运行时不受影响 SELECT * FROM mcp_target_profiles; -- 审阅 / 编辑 LOAD MCP PROFILES TO RUNTIME; -- 应用注意在该行为加入之前的版本中只有mcp-*变量存于global_variables会在重启后恢复Profile 与 Query Rules 恢复为空MCP 监听器以无目标状态启动。这些旧版本需要在每次启动后手动执行LOAD MCP PROFILES FROM DISK;与LOAD MCP QUERY RULES FROM DISK;。Query Rules 的表结构支持按username、target_id、schemaname、tool_name等路由感知字段匹配并支持match_pattern正则、negate_match_pattern、re_modifiers默认CASELESS、flagIN/flagOUT、replace_pattern、timeout_ms、error_msg、OK_msg、log、apply等字段ProxySQL_Admin_Tables_Definitions.h。LOAD MCP QUERY RULES TO RUNTIME在安装快照后若监听器在线还会把规则推送到Discovery_Schema的请求热路径缓存MCP_Thread.cpp。十、如何判断哪些目标 Profile 实际可用SELECT * FROM runtime_mcp_target_profiles会列出运行时快照中的每个目标包括 MCP 查询端点无法使用的目标。两个派生列用于区分列含义effective目标是否可被查询端点使用1可用0表示被排除skip_reason当effective1时为空否则为inactive或auth_profile_id not found-- MCP 查询端点不会看到的目标以及原因 SELECT target_id, active, auth_profile_id, skip_reason FROM runtime_mcp_target_profiles WHERE effective 0;LOAD MCP PROFILES TO RUNTIME的回复中也会报告计数每条被排除的行都会以警告形式写入 ProxySQL 错误日志。命令回复示例plugins/genai/README.mdadmin LOAD MCP PROFILES TO RUNTIME; MCP profiles loaded to runtime: 1 auth profile(s), 1 of 3 target(s) effective (1 inactive, 1 with unresolved auth_profile_id; see runtime_mcp_target_profiles.skip_reason and the error log)源码中排除逻辑位于rebuild_target_auth_map_locked()active 0的行以inactive跳过auth_profile_id在mcp_auth_profiles中无对应行时以auth_profile_id not found跳过MCP_Thread.cpp。两个原因常量MCP_SKIP_REASON_INACTIVE与MCP_SKIP_REASON_NO_AUTH_PROFILE在 MCP_Thread.h 中定义TAP 测试与运维脚本可直接按此匹配。需要强调effective1并不代表目标一定可执行。如果目标所属主机组没有 ONLINE 后端或它的认证配置db_username为空请求时仍会失败——这一层由Query_Tool_Handler::format_target_unavailable_error单独诊断工具错误消息会单独描述该场景。十一、状态变量只读MCP 模块提供以下只读状态变量变量说明mcp_total_requests收到的 MCP 请求总数mcp_failed_requests失败的 MCP 请求总数mcp_active_connections当前活动 MCP 连接数查看方式SELECT * FROM stats_mysql_global WHERE variable_name LIKE mcp_%;这三个计数器由MCP_Threads_Handler::collect_status_variables()汇总MCP_Thread.cpp并在请求处理路径中被handle_jsonrpc_request()与认证失败分支递增/递减。此外genai 插件还注册了更丰富的统计表stats_genai_global21 个聚合计数含mcp_*、genai_*、llm_*、anomaly_*、stats_mcp_query_digest工具调用摘要含耗时 min/max/sum、stats_mcp_query_tools_counters按端点工具schema 的调用计数与stats_mcp_query_rules规则命中数相关 schema 与刷新回调见 plugin_tables.cpp。十二、安全注意事项认证生产环境必须为每个端点设置认证令牌当前版本空令牌 拒绝所有请求。HTTPSMCP 服务器使用 HTTPSSSL 证书来自 ProxySQL datadir默认mcp-use-ssltrue除非明确评估过风险不建议关闭 TLS。MySQL 权限为工具处理器创建权限受限的专用 MySQL 用户inventory/structure 工具需要SELECT权限profiling 需要PROCESS权限sampling/query 工具只授予特定表上的受限SELECT。网络访问考虑使用防火墙规则限制mcp-port的访问来源尤其不要将/mcp/admin、/mcp/query、/mcp/ai暴露到不可信网络。十三、版本与相关文档MCP Thread 版本0.1.0源码常量MCP_THREAD_VERSIONMCP_Thread.h协议JSON-RPC 2.0 over HTTPSinitialize握手声明protocolVersion为2025-06-18见 MCP_Endpoint.cpp最后更新2026-01-19相关文档MCP 架构与端点规范 — 模块架构、端点设计与请求流程工具发现指南 — 工具发现与使用文档GenAI 插件参考 — 插件构建、加载、生命周期、命令与统计面赞分享后端数据库负载均衡【免费下载链接】proxysqlHigh-performance proxy for MySQL and PostgreSQL项目地址https://gitcode.com/gh_mirrors/pr/proxysql点击查看免费下载相关推荐Claude Code Haha 环境变量配置完全指南认证、模型路由、Azure 与本地运行时Claude Code Haha 环境变量配置完全指南认证、模型路由、Azure 与本地运行时 本指南围绕 docs/en/cli/env.md https:人工智能AI 应用桌面应用代码智能体MCP ClientsProxySQL DuckDB 插件配置参考duckdb-* 全局变量的完整解析与实战指南ProxySQL DuckDB 插件配置参考 duckdb 全局变量的完整解析与实战指南 本指南系统讲解 ProxySQL v4.0 插件框架中 DuckDB后端数据库负载均衡OneUptime 工作流变量完全指南全局变量、局部变量与组件输出VariablesOneUptime 工作流变量完全指南全局变量、局部变量与组件输出Variables 工作流本质上是在搬运数据——从触发器到第一个组件、从上一个组件到下一可观测性后端运维前端云原生微服务AI Agent上一篇GTE-large-openmind常见问题解答从安装到故障排除下一篇Qwen-Scope对比分析不同模型层间特征激活模式的深度研究创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考