大模型对话时序数据库:KaiwuDB KGA 3.3构建与AI问答实战实录

文档信息

表格

1 部署架构与组件说明

本系统由 KaiwuDB 时序关系数据库和 KGA（KaiwuDB Guardian Agent）智能问答平台两部分组成。浏览器访问 KGA UI 后，KGA Agent 调用所选大模型；数据库子智能体通过 KGA Server 内置的 KWDB MCP 访问 KaiwuDB。PostgreSQL 仅保存 KGA 自身元数据（用户、模型配置、数据库配置、会话、任务等），不存放业务数据。

1.1 架构拓扑

浏览器 :3000 (KGA UI)
    |
    +-- KGA API :8000  <-->  PostgreSQL :5432 (KGA 元数据)
    |
    +-- KGA Agent :8123
        +-- Knowledge Server   :8002
        +-- KWDB MCP           :8003  <-->  KaiwuDB TLS :26257
        +-- KWDB CMD MCP       :8001
        +-- KGA Vis            :8004  (容器内 3100，图表可视化)

1.2 组件与端口清单

表格

2 服务器准备

2.1 系统与资源检查

安装前确认操作系统版本、CPU、内存和磁盘资源满足要求，并检查端口占用情况。

系统环境检查命令

cat /etc/os-release
uname -mn
proc
free -h
df -h /
ss -lntp | egrep ':(3000|5432|8000|8001|8002|8003|8004|8123|26257|8080)\b' || true

表格

2.2 安装前置依赖

KaiwuDB 安装程序依赖 tar 和 sshpass。缺少 tar 会导致解压出的 switch.sh 不存在；缺少 sshpass 会导致远程执行直接失败。

安装依赖包

dnf install -y tar sshpass unzip curl
tar --version
sshpass -V

测试环境按安装要求关闭 SELinux：

setenforce 0
sed -i 's/^SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
getenforce

3 KaiwuDB 3.2.2 裸机安装

3.1 创建运行用户和目录

# 创建用户与上传安装包
useradd -m kwdb
passwd xxxx
mkdir -p /soft
chown -R kwdb:kwdb /soft
# 上传安装包
scp KWDB-3.2.2-x86_64.run root@192.168.x.x:/soft/
chmod 755 /soft/KWDB-3.2.2-x86_64.run
sha256sum /soft/KWDB-3.2.2-x86_64.run

3.2 执行安装向导

进入安装包目录，使用命令行模式启动安装向导。依次选择 "1 安装 KWDB" 和 "1 单机安装"，确认配置参数后完成部署。

启动安装向导

cd /soft
./KWDB-3.2.2-x86_64.run -h
./KWDB-3.2.2-x86_64.run -c

安装向导确认的核心配置参数

[global]
secure_mode=tls          # 开启 TLS 安全模式
rest_port=8080           # AdminUI 管理端口
kaiwudb_port=26257       # 数据库 SQL 服务端口
brpc_port=27257          # 数据传输端口
data_root=/var/lib/kaiwudb  # 数据目录

[node1]
host=192.168.x.x     # 目标服务器 IP
port=22              # SSH 端口
user=kwdb            # SSH 连接用户
passwd=xxx           # SSH 连接密码

3.3 实际安装操作日志

以下为本次部署在服务器上实际执行的终端操作日志，完整记录了从启动安装程序到部署成功的全过程：

【实际操作日志】KaiwuDB 安装终端记录

[root@kwdb2 soft]# ./KWDB-3.2.2-x86_64.run -h
Usage:
KWDB-3.2.2-x86_64.run [Options]
KWDB-3.2.2-x86_64.run -h|--help
Options:
  -c|--cli                 命令行模式
  -i|--interact            终端图形交互模式

[root@kwdb2 soft]# ./KWDB-3.2.2-x86_64.run -c
============================================================
 🚀 检查更新
============================================================
正在检查更新，请稍候...
发现新版本 3.2.2，是否继续安装(y/N)？
============================================================
 🚀 KWDB 安装向导
============================================================
 1. 安装 KWDB
 2. 卸载 KWDB
 3. 安装KWDB并加入集群
 4. 升级节点
 5. 退出
请输入操作:1
============================================================
 🚀 KWDB 安装向导
============================================================
 1. 单机安装
 2. 单副本集群
 3. 三副本集群
 4. 返回主菜单
请选择:1

[global]
secure_mode=tls
rest_port=8080
kaiwudb_port=26257
brpc_port=27257
data_root=/var/lib/kaiwudb
[node1]
host=192.168.x.x
port=22
user=kwdb
passwd=xxxx

3.4 服务状态验证

安装完成后，检查 KaiwuDB 服务状态、监听端口和证书文件：

systemctl status kaiwudb --no-pager
journalctl -u kaiwudb -n 200 --no-pager
ss -lntp | egrep ':(26257|27257|8080)\b'
ls -l /etc/kaiwudb/certs

验证预期：systemctl 显示 active（running）；26257、27257、8080 三个端口处于 LISTEN 状态；/etc/kaiwudb/certs 目录下存在 TLS 证书文件。

4 KaiwuDB 登录与用户测试

4.1 root 登录与版本检查

root 用户登录 SQL Shell

su - kwdb
kwbase sql --certs-dir=/etc/kaiwudb/certs --host=192.168.x.x -u root

进入 SQL Shell 后执行以下命令验证：

SELECT version();
SHOW DATABASES;

预期返回结果：

Server version: KaiwuDB 3.2.2
Cluster ID: ccaff354-d674-472e-abf5-8adcfb9c5798

4.2 创建业务用户

KaiwuDB 创建或修改密码使用 WITH PASSWORD 语法（不支持 MySQL 风格的ALTER USER ... IDENTIFIED BY）：

-- 创建业务用户 user4
CREATE USER user4 WITH PASSWORD 'xxxxxx';
-- 修改现有用户密码：ALTER USER user4 WITH PASSWORD 'xxxxxx';
\q

业务用户登录验证

kwbase sql --certs-dir=/etc/kaiwudb/certs --host=192.168.x.x -u user4
# 输入密码 xxxxxx
\l

预期数据库列表输出

database_name | engine_type
--------------+-------------
defaultdb     | RELATIONAL
postgres      | RELATIONAL
system        | RELATIONAL
(3 rows)

5 Docker 与 Compose 安装

5.1 安装 Docker Engine

dnf -y install moby-engine moby-client
systemctl enable --now docker
systemctl is-enabled docker
systemctl is-active docker
docker version
docker info --format 'Driver={{.Driver}} Cgroup={{.CgroupDriver}}'

验证预期输出：

enabled
active
Docker 25.0.3  API 1.44
containerd 1.6.22  runc 1.1.8
Driver=overlay2 Cgroup=cgroupfs

5.2 安装 Docker Compose 插件

mkdir -p /usr/local/lib/docker/cli-plugins
cd /tmp
curl -fL -o docker-compose-linux-x86_64 \
  https://github.com/docker/compose/releases/download/v5.6.0/docker-compose-linux-x86_64
curl -fL -o checksums.txt \
  https://github.com/docker/compose/releases/download/v5.6.0/checksums.txt
grep 'docker-compose-linux-x86_64$' checksums.txt | sha256sum -c -
install -m 0755 docker-compose-linux-x86_64 /usr/local/lib/docker/cli-plugins/docker-compose
docker compose version

6 KGA 3.3.0 离线部署

6.1 上传与解压离线包

# 上传安装包到服务器
scp KGA3.3.0.zip root@192.168.x.x:/opt/kga-3.3.0/
scp postgres.tar root@192.168.x.x:/opt/kga-3.3.0/

# 服务器端解压
mkdir -p /opt/kga-3.3.0/package
cd /opt/kga-3.3.0
sha256sum KGA3.3.0.zip postgres.tar
unzip -t KGA3.3.0.zip
unzip -o KGA3.3.0.zip -d package

6.2 导入离线镜像

cd /opt/kga-3.3.0/package
docker load -i kga-server-3.3.0.tar
docker load -i kga-ui-3.3.0.tar
docker load -i kga-vis-3.3.0.tar
docker load -i /opt/kga-3.3.0/postgres.tar

# 打标签
docker tag kga-server:3.3.0 kga-server:latest
docker tag kga-ui:3.3.0 kga-ui:latest

# 验证镜像
docker image inspect kga-server:latest kga-ui:latest kga-vis:3.3.0 postgres:16.13-alpine3.22 \
 --format '{{.RepoTags}} {{.Id}} {{.Size}}'

6.3 注册 OAuth 并生成环境文件

cd /opt/kga-3.3.0/package
umask 077
export INITIAL_ACCESS_TOKEN='OTg5NjE0Mjc0NDcwNjM1NTQ6MXRtVzNKeGtTUVQ3SmJETWlleTZRUm1xU1dBRi9oQTFqTkR1d2IwdmptMHh6bEY0YS93VHNBPT0='
bash setup.sh --register-only \
 --copilot-url=http://192.168.x.x:8123 \
 --backend-url=http://192.168.x.x:8000 2>&1 | tee setup-register.log
unset INITIAL_ACCESS_TOKEN
chmod 600 .env setup-register.log

注册成功预期输出

[INFO] All required ports are available
[INFO] OAuth client registration succeeded
[INFO] Environment file generated

注册成功，环境文件已生成 .env 文件已生成 setup-register.log 已生成

6.4 启动容器服务

cd /opt/kga-3.3.0/package
docker compose config --quiet
mkdir -p /opt/kga-3.3.0/data/inspection-reports
docker compose up -d
docker compose ps

6.5 服务运行效果图

执行 docker ps 查看容器运行状态。下图为本次部署完成后 4 个容器的实际运行状态，全部处于 Up 状态，其中 kga-postgres 显示为 healthy：

docker ps 服务运行状态效果图（4 个容器全部正常运行）

从上图可以确认以下服务均已正常启动：

表格

7 服务验证

7.1 端口监听验证

ss -lntp | egrep ':(3000|5432|8000|8001|8002|8003|8004|8123)\b'

验证预期：以上 8 个端口均处于 LISTEN 状态。

7.2 HTTP 端点验证

curl -o /dev/null -s -w 'UI   %{http_code}\n' http://192.168.x.x:3000/login
curl -o /dev/null -s -w 'API  %{http_code}\n' http://192.168.x.x:8000/docs
curl -o /dev/null -s -w 'Agent %{http_code}\n' http://192.168.x.x:8123/docs
curl -o /dev/null -s -w 'VIS  %{http_code}\n' http://192.168.x.x:8004/health

HTTP 端点验收结果

UI http://192.168.x.x:3000/login ->200
API http://192.168.x.x:8000/docs ->200
Agent http://192.168.x.x:8123/docs -> 200
VIS http://192.168.132.234:8004/health -> 200

7.3 容器日志验证

docker logs --tail 200 kga-server
docker logs --tail 100 kga-postgres
docker logs --tail 150 kga-vis

日志验证预期关键点：kga-server 日志中出现KWDB MCP initialized/listening字样；主 Agent 构建完成输出BUILD_MAIN_AGENT_OK和CompiledStateGraph；kga-postgres 日志显示 database system is ready to accept connections。

8 KGA 网页配置

8.1 KGA AI 能力介绍

KGA（KaiwuDB Guardian Agent）是 KaiwuDB 官方推出的数据库智能守护平台，核心定位是将大语言模型（LLM）与 KaiwuDB 数据库深度融合，使运维人员和业务用户能够通过自然语言对话完成数据库查询、运维巡检和故障诊断，降低 SQL 门槛与数据库使用成本。

8.2 核心 AI 技术架构

KGA 采用 LLM + MCP（Model Context Protocol）+ 数据库的三层架构。用户在浏览器端用自然语言提问后，KGA Server 将问题路由至已配置的大模型；大模型通过内置的 KWDB MCP 工具理解数据库元数据、生成 SQL 并执行查询，最终将结果以自然语言形式返回用户。整个过程对用户透明，用户无需手写 SQL。

KGA AI 问答链路

用户自然语言提问
    |
    v
KGA UI (:3000)  -- 会话管理 / 对话界面
    |
    v
KGA Agent (:8123)  -- 编排调度，选择工具链
    |
    +-- LLM 大模型接口  -- 语义理解、SQL 生成、结果总结
    +-- KWDB MCP (:8003)  -- 数据库元数据感知、SQL 执行
    +-- Knowledge Server (:8002)  -- 知识库检索增强
    +-- KGA Vis (:8004)  -- 查询结果可视化图表
    |
    v
KaiwuDB (:26257, TLS)  -- 实际数据存储与计算

8.3 登录系统

浏览器访问 http://192.168.x.x:3000/login 进入 KGA 登录页面。

8.4 KGA 模型配置

1. 登录 http://192.168.x.x:3000。
2. 在设置中新增模型配置，填写提供商、兼容 API 地址、API Key 和准确模型名。
3. 保存后先执行连接测试；当前界面中已保存的模型名称为 test。
4. 连接测试成功只代表模型接口可用，不代表数据库问答链路已完整。

8.5 配置 KaiwuDB 数据库连接

表格

注意：普通数据库问答不需要再在 "自定义 MCP Server" 页面添加 KWDB MCP。KGA Server 已在 8003 启动内置 KWDB MCP，并根据网页中选择的数据库配置生成工具。TSBS MCP 只用于 TSBS 性能测试。

8.6 普通数据库问答验收

完成模型配置和数据库连接后，在 KGA 对话页面即可直接用自然语言提问。以下为本次实际部署中的真实问答截图：用户用中文询问 "帮我查一下 kwdb 现在的数据库用户和表"，KGA Agent 自动完成任务并返回结构化结果。
第一步：用户输入自然语言问题后，KGA 显示 task success，并可展开查看 AI 的思考过程（包括权限判断、SQL 选择逻辑等）；
第二步：AI 返回用户 / 角色 / 数据库的结构化查询结果。可以看到SHOW USERS因 user4 权限不足而自动降级为查询 pg_catalog 系统目录表，体现了 AI 的自适应纠错能力；
第三步：页面底部展示 AI 实际执行的 SQL 语句列表和最终结论，包括 3 个关系型数据库、3 个可登录用户、1 张业务表，并附权限说明和巡检提醒。

8.7 已具备的 AI 能力

表格

9 AI 技能展望

随着大模型技术演进和 KGA 版本迭代，以下 AI 能力将在后续版本中逐步落地，进一步拓展数据库智能运维的边界。

9.1 智能运维与故障诊断

表格

9.2 知识库与持续学习

表格

9.3 多数据库与生态扩展

表格

9.4 安全与合规展望

后续版本将在数据安全层面持续增强：包括 SQL 执行前自动审查危险操作（DROP、TRUNCATE、DELETE 无 WHERE）并要求二次确认、行列级权限管控（AI 仅能查询用户有权限的数据行）、完整的 AI 操作审计日志（记录每次提问、生成 SQL、执行结果），确保 AI 助手在企业生产环境中安全可控。

10 日常运维与备份

10.1 服务启停

cd /opt/kga-3.3.0/package
docker compose up -d      # 启动
docker compose stop       # 停止
docker compose restart    # 重启
docker compose ps         # 查看状态
docker stats --no-stream  # 资源占用
docker compose logs -f --tail 200 kga-server  # 实时日志

注意：docker compose down不会删除数据卷，但不要随意执行docker compose down -v（会删除数据卷）。

10.2 数据备份

备份脚本

backup_dir=/opt/kga-backup/$(date +%Y%m%d_%H%M%S)
install -d -m 700 "$backup_dir"
cp -a /opt/kga-3.3.0/package/docker-compose.yml "$backup_dir/"
cp -a /opt/kga-3.3.0/package/.env "$backup_dir/"
tar -C /opt/kga-3.3.0 -czf "$backup_dir/kga-data.tgz" data
docker exec kga-postgres pg_dump -U kgaadmin -d kgadb -Fc > "$backup_dir/kgadb.dump"
sha256sum "$backup_dir"/* > "$backup_dir/SHA256SUMS"
chmod 600 "$backup_dir/.env" "$backup_dir/kgadb.dump"

11 最终验收清单

表格