从零到一:KES-MCP Server 实验环境部署完全指南
在数据库与 AI 深度融合的今天,如何让大模型真正"看懂"你的数据库?KES-MCP Server 给出了答案。本文基于 KingbaseES V009R001C010,手把手带你完成从性能调优组件启用、测试数据准备,到 MCP Server 部署与 AI IDE 集成的全流程,一文搞定实验环境搭建。
📋 本文目录
- 实验环境说明与整体流程
- 启用性能调优组件(sys_qualstats / sys_hypo)
- 慢查询统计与负载分析(sys_stat_statements)
- 性能调优核心:sys_kwr 配置详解
- 免密登录与 100 万行测试数据
- 部署 KES-MCP Server 完整步骤
- 常见问题排查与解决
- AI 开发工具集成(TraeCode + Firefox)
01 实验环境说明
本文实验数据库版本为 V009R001C010,支持 KingbaseES V8R6 及以上版本。整个部署可拆分为四个阶段:
- 基础准备 —— 启用性能调优与索引建议组件,配置慢查询统计。
- 核心调优 —— 配置 sys_kwr,开启自动快照与负载分析。
- 数据准备 —— 配置免密登录,生成 100 万行订单测试数据。
- 服务部署 —— 安装 uv、Git,部署 KES-MCP Server 并集成 AI 开发工具。
ℹ️ 全程需要外网连通,用于克隆仓库和安装依赖包。可先执行
ping www.baidu.com验证网络。
02 启用性能调优组件
索引调优是数据库性能优化的核心。KingbaseES 提供了两个实用扩展,帮助你"未卜先知"地评估索引价值。
🔍 sys_qualstats —— 谓词统计与索引建议
收集 SQL 语句中 WHERE 和 JOIN 子句里的谓词(过滤条件)执行信息,据此生成针对性的索引优化建议,找出哪些索引建了能真正提升性能。
🧪 sys_hypo —— 虚拟索引(Hypothetical Indexes)
在不实际创建索引、不消耗磁盘和 CPU 资源的情况下,模拟索引对查询性能的影响,辅助进行索引优化决策。
配置步骤
# kingbase.conf —— 在参数末尾追加
shared_preload_libraries = '.....,sys_qualstats'
# 重启数据库使插件生效
sys_ctl restart -D /data
# 创建插件(sys_stat_statements 默认已创建,无需重复)
create extension sys_qualstats;
create extension sys_hypo;
03 慢查询统计与负载分析
sys_stat_statements 扩展默认已安装/升级,会在所有库上自动创建,用于收集 SQL 执行统计信息、慢 SQL 采集与负载分析。
# 确认插件已加载(二选一)
grep --color=auto sys_stat_statements /data/kingbase.conf
show shared_preload_libraries;
# 查看插件
\dx+ sys_stat_statements
关键参数调优
① sys_stat_statements.max —— 跟踪与存储的最大查询条目数,默认 5000,建议调大至 10000,需重启生效。
show sys_stat_statements.max; -- 5000
alter system set sys_stat_statements.max = 10000;
\! sys_ctl restart &> /dev/null -- 重启
\c -- 重新连接
show sys_stat_statements.max; -- 10000
② sys_stat_statements.track —— 跟踪的语句类型,默认 none(不跟踪任何查询)。可选 top(仅顶层查询)或 all(含嵌套语句)。
show sys_stat_statements.track; -- none
alter system set sys_stat_statements.track = 'all';
select sys_reload_conf();
show sys_stat_statements.track; -- all
⚠️ 生产环境建议:将 track 设为
top,仅跟踪客户端直接发出的顶层语句,避免跟踪所有嵌套查询带来的性能下降。原文中的 “al1” 应为 “all”。
04 性能调优核心:sys_kwr 配置详解
KWR(Kingbase Workload Repository)用于 BIC-QA 执行 KWR 报告分析。由于 KWR SQL 使用了字符串拼接语法,需将 liboracle_parser 配置到预加载库中。
# kingbase.conf
shared_preload_libraries = '.....,liboracle_parser'
# 确认同时包含 parser / kwr / statements 三项
cat /data/kingbase.conf | grep -v ^# | grep -Ei 'parser|kwr|statements'
核心参数一览
| 参数 | 说明 / 建议值 |
|---|---|
track_sql |
统计 SQL 时间、等待事件、SQLIO,默认 off,建议 on |
track_instance |
统计实例级 IO、锁、关键活动,建议 on |
track_wait_timing |
统计累积式等待事件时间,默认 on |
track_counts |
统计数据库活动,默认 on |
track_io_timing |
统计 IO 耗时,默认 off,建议 on |
track_functions |
统计自定义函数使用,默认 none,建议 all |
sys_kwr.enable |
开启自动快照,默认关,重启生效 |
sys_kwr.topn |
报告 Top N 条信息,默认 20(10~100) |
sys_kwr.history_days |
快照保留天数,默认 8(1~1000) |
sys_kwr.interval |
自动快照间隔(分钟),默认 60(10~144000) |
sys_kwr.language |
报告语言,默认 chinese,可选 english |
max_worker_processes |
必须 > 4,否则 KWR 进程无法启动、快照无法生成 |
创建插件并重启
ksql test system
create extension sys_kwr;
# 重启使插件生效
sys_ctl restart -D /data
# 创建快照 & 查看快照列表
select * from perf.create_snapshot();
select * from perf.kwr_snapshots;
✅ 验证参数可用
SELECT name,setting,unit,min_val,max_val FROM sys_settings WHERE name like 'sys_kwr%';,或逐个SHOW参数名确认。
05 免密登录与测试数据
为后续备份配置免密登录:
sys_encpwd -H \* -U system -D \* -W kingbase -P 54321
创建订单测试表并插入 100 万行数据,用于 DTA 索引调优实验。表结构涵盖用户 ID、订单编号、状态、金额、下单/支付时间等典型字段:
CREATE TABLE public.orders (
id bigserial PRIMARY KEY,
user_id bigint NOT NULL,
order_no text NOT NULL,
status smallint NOT NULL, -- 1待支付 2已支付 3已发货 4已完成 5已取消
amount numeric(12,2) NOT NULL,
create_time timestamp NOT NULL DEFAULT now(),
pay_time timestamp,
remark text
);
-- 插入 100 万行
INSERT INTO public.orders
(user_id,order_no,status,amount,create_time,pay_time,remark)
SELECT
(random()*50000)::bigint,
'ORD'||to_char(generate_series,'FM0999999999'),
(random()*4 +1)::smallint,
(random()*10000)::numeric(12,2),
now() - (random() * interval '60 day'),
CASE WHEN random()>0.3 THEN now() - (random() * interval '30 day') ELSE NULL END,
'测试订单数据_'||generate_series
FROM generate_series(1,1000000);
-- 校验:应返回 1000000
SELECT count(*) FROM public.orders;
06 部署 KES-MCP Server
① 安装 uv(Python 项目与包管理工具)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv --version
② 安装 Git 并克隆仓库
yum install git -y
git clone https://gitee.com/king-db/kingbase-mcp.git
cd kingbase-mcp/
ℹ️ 如无法访问外网,可先在能联网的机器下载仓库,再上传到服务器。
③ 创建虚拟环境并安装依赖
uv venv --python 3.13
source .venv/bin/activate
uv pip install .
✅ 执行后当前目录生成
.venv隔离环境,终端提示符将出现(kingbase-mcp)字样。
07 常见问题排查与解决
❌ error: No solution found when resolving dependencies
原因:pypi 源中无 pglast==7.11。解决:备份后编辑 pyproject.toml,将固定版本改为更宽的 pglast>=7.11 或直接写 pglast,让 uv 选用源中存在的 8.x 版本(需自行确认兼容性)。
cp pyproject.toml pyproject.tomlbak
vi pyproject.toml
❌ cause: operation timed out(pypi 请求超时)
网络不稳定所致,多次重试后即可安装成功。
❌ 虚拟机打开报错(硬件版本不兼容)
编辑 node1.vmx(路径:G:\kingbase_AI实操类技能课程\KES-AI虚拟机\cleanK11.zip\cleanK11\),将 virtualHW.version = "XX" 改为较低版本如 "12" 或 "14",保存后重启 VMware。
08 AI 开发工具集成
MCP 宿主机需要支持 MCP 协议的 AI IDE。本文选用 TraeCode;由于麒麟服务器未预装浏览器,需先安装 Firefox 用于首次登录。
① 安装 Firefox
yum -y install wget
wget https://download-installer.cdn.mozilla.net/pub/firefox/releases/153.0.4/linux-x86_64/zh-CN/firefox-153.0.4.tar.xz
tar -xf firefox-153.0.4.tar.xz -C /usr/local/
echo "export PATH=/usr/local/firefox:$PATH" >> /etc/profile
source /etc/profile
firefox --version # Mozilla Firefox 153.0.4
② 安装 TraeCode
wget https://lf-cdn.trae.com.cn/obj/trae-com-cn/pkg/app/releases/stable/2.3.69712/linux/TraeCode_CN-linux-x64.rpm
yum install ./TraeCode_CN-linux-x64.rpm -y
su - kingbase
trae-cn --version
✅ 至此,实验环境已完整就绪:数据库性能调优组件、KWR 报告分析、100 万行测试表、KES-MCP Server 与 AI 开发工具全部到位,可以开始你的数据库 AI 之旅了。
🎯 小结
本文梳理了 KES-MCP Server 实验环境部署的完整链路:组件启用 → 慢查询统计 → KWR 调优 → 数据准备 → 服务部署 → 工具集成。按步骤操作,即可快速搭建一套可用于数据库 AI 与索引调优实验的环境。
- 点赞
- 收藏
- 关注作者
评论(0)