DB-GPT 移动端实战：把数据库AI助手搬进微信小程序的完整部署与定制指南

DB-GPT 移动端实战：把数据库AI助手搬进微信小程序的完整部署与定制指南

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

需要在办公室之外查库、核对数据洞察时，DB-GPT 的微信小程序方案可以让数据库 AI 助手直接上移动端：复用已经部署好的 DB-GPT 服务，加一层轻量的 H5 移动适配页，通过微信或企业微信进入，对话、查数、分析结果全在手机上完成，不需要为移动端单独开发一套后端。

先看它解决什么问题

先说场景。出差时客户临时问这周订单量，你手头只有手机，数据库客户端在电脑上，Web 控制台在手机上又不好操作。DB-GPT 移动端路线的思路是：后端服务不动，前端在web/pages/mobile/下专门做了一套移动端对话页，用小程序或 IM 的 web-view 容器把它包起来即可。

它能做什么，谁适合用：

• 能做：手机上用自然语言连库查询（Text2SQL）、数据问答、分析结果展示，和 Web 端同一套能力
• 适合谁：已经部署 DB-GPT v0.7.0+ 服务、想把数据问答搬到移动端的团队
• 架构：后端服务 + H5 移动端适配层，不额外开发小程序后端，权限体系沿用 Web 端
• 入口：微信小程序、企业微信、钉钉都能进，靠一个带参数的 URL 打开同一个页面

🚀 部署前置条件与四步构建

前置条件一次说清：DB-GPT v0.7.0+ 服务已在运行；有微信公众平台开发者账号；一个备案域名并配好 HTTPS（微信小程序强制要求）。

1. 拿源码并构建（移动端页面就在 web 工程里，跟着主工程一起构建）：

git clone https://gitcode.com/GitHub_Trending/db/DB-GPT cd DB-GPT/web npm install npm run build

2. 配置后端地址。构建时把后端 API 域名注入前端：

# web/.env.local API_BASE_URL=https://your-dbgpt-domain.com

3. 配好 HTTPS 与域名。用 nginx 把前端静态资源和 API 都挂到同一个 HTTPS 域名下，详细部署流程参考 docs/installation/docker.md。

4. 验证入口页。浏览器直接访问移动路由，通了再谈小程序发布：

https://your-dbgpt-domain.com/mobile/chat?chat_scene=chat_agent&app_code=你的app_code

这里有个坑：不要把微信小程序的项目目录直接指向 Next.js 源码，小程序运行时跑不了这套代码。通用做法是小程序里做一个薄壳，用 web-view 组件加载上面的 H5 页面，并把域名登记进小程序的业务域名白名单。

移动端对话页是怎么连上后端的

从你打开链接那一刻说起。URL 上带了chat_scene（对话场景）和app_code（应用编码）两个参数，页面拿到它们之后，先向后端拉三样东西：应用配置、可选模型列表、应用绑定的资源（数据库或知识库）。模型和温度如果不手动改，就默认取应用配置里param_need中指定的值。

发消息走的是流式请求，核心逻辑在 web/pages/mobile/chat/index.tsx：

await fetchEventSource(`${API_BASE_URL}/api/v1/chat/completions`, { method: 'POST', headers: { 'Content-Type': 'application/json', [HEADER_USER_ID_KEY]: getUserId() ?? '' }, body: JSON.stringify(params), onmessage: (event) => { let message = event.data; try { message = JSON.parse(message).vis; } catch { message = message.replaceAll('\\n', '\n'); } setHistory(prev => [...prev, { role: 'view', content: message }]); }, });

HEADER_USER_ID_KEY这个请求头用来标识会话归属，后端按用户维度存历史。整个页面的模型、温度、历史消息等状态放在一个叫MobileChatContext的 React Context 里，输入框、模型选择器、消息列表组件都从它取值，这也是移动端页和 Web 端共享大部分业务逻辑、只换一层布局的原因。

🔧 两个定制例子：自定义工具与企业微信入口

• 自定义工具：让助手不止会写 SQL，还能调用你自己的内部系统或脚本。能做什么：给 Agent 挂一个工具，提问时由模型决定是否调用。关键路径：examples/agents/custom_tool_agent_example.py 是可跑的最小样例；模型与参数侧的配置样例看 configs/dbgpt-app-config.example.toml，更多玩法在 examples/ 目录下。
• 企业微信入口：在应用页一键生成移动端分享链接，企微/钉钉里点击直接拉起对话页（走dingtalk://这类深链跳转）。关键路径：web/pages/construct/app/index.tsx 第 264~284 行附近就是拼接mobile/chat链接的逻辑，抄这段就能给自己的 IM 加入口。

⚠️ 连接失败与卡顿的避坑清单

• 现象：小程序或 web-view 里所有请求超时。原因：微信只允许 HTTPS。解法：申请证书，nginx 统一收口，部署方式见 docs/installation/docker.md。
• 现象：浏览器里正常，小程序里连不上。原因：API_BASE_URL没配或配错。解法：检查.env.local，并确认域名已登记到小程序业务域名白名单。
• 现象：请求被浏览器拦下，报跨域。原因：后端 CORS 白名单没加移动端域名。解法：在服务端配置里把 H5 域名加进白名单。
• 现象：首屏慢、手机上滑动卡。原因：图表等重依赖全量加载、静态图片大。解法：移动端页已对 Content 组件做了next/dynamic懒加载，别把它改成同步引入；同时压缩 web/public/models/ 下的图片资源。
• 现象：模型切了不生效、温度不对。原因：默认值取自应用级参数配置，会覆盖界面选择。解法：到应用管理页确认该应用的param_need里 model / temperature 默认值。

马上可以做的三件事

1. 按上面四步部署，先用浏览器验证/mobile/chat页面能通；
2. 给自己绑定一个数据库资源，在手机上问一条 Text2SQL 把链路跑通；
3. 照着 examples/agents/custom_tool_agent_example.py 挂一个自定义工具，试一次非 SQL 能力。

后续规划上，离线缓存、语音交互和移动端专属图表都在官方路线图上，留意更新即可。入口都在这：部署文档 docs/installation/docker.md、配置样例 configs/、示例代码 examples/、问题排查 docs/faq/。移动端这条路本质不是另一套系统，而是同一套服务多开一个入口——先跑通入口，再谈定制。

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT