企业官网建设流程全解析

DB-GPT 如何单独启动并调试 Web 前端（npm run dev 指向 API_BASE_URL）

【免费下载链接】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 默认把 Web UI 打包进后端服务，随uv run dbgpt start webserver一起运行在http://localhost:5670。当你需要修改或调试前端页面时，可以把web/目录下的 Next.js 应用独立跑起来：它在本地3000端口启动开发服务器，所有接口请求通过环境变量API_BASE_URL指向已运行的 DB-GPT 后端。完成这条路径后，你会得到一个热更新的前端开发环境，页面功能（Chat、Knowledge Base 等）与5670端口内置 UI 由同一个后端提供服务。

前置条件：后端服务与 Node 环境

单独调试前端的前提是 DB-GPT 后端已经在运行，API_BASE_URL必须能访问到这个后端。后端按 快速开始 或 源码部署 流程启动：

uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml

启动成功的判断方式在文档中给出：终端日志显示 webserver 正常启动，且浏览器访问http://localhost:5670能加载 Web UI。

Node 环境要求来自 web/README.md：

• Node.js >= 16
• npm >= 8
• 支持 Linux、macOS、Windows

安装前端依赖

进入仓库根目录下的web/目录安装依赖。web/README.md 给出的是：

cd web && npm install

文档同时推荐用 Yarn 做依赖管理（要求 yarn >= 1.22），也可执行yarn install。

配置 API_BASE_URL 指向后端

web/目录下有一个 .env.template 模板文件，内容为一行：

API_BASE_URL=http://127.0.0.1:5670

按文档步骤复制成实际生效的.env文件并检查地址：

cd web cp .env.template .env # 编辑 .env — 确认 API_BASE_URL 指向你的后端地址，例如 API_BASE_URL=http://localhost:5670

两点需要注意：

• 模板默认值是http://127.0.0.1:5670，quick-start 中的示例写的是API_BASE_URL=http://localhost:5670，两者在本机部署下等效；如果后端不在本机或端口不同，把它改成 web/README.md 所说的 "the real address"。
• 这个变量是怎么进入前端构建的：next.config.js 在env字段中读取process.env.API_BASE_URL并暴露给客户端代码，例如 web/utils/index.ts 中transformFileUrl拼接文件服务 URL 时就使用了process.env.API_BASE_URL。next.config.js还声明了GITHUB_CLIENT_ID、GOOGLE_CLIENT_ID、GET_USER_URL、LOGIN_URL、LOGOUT_URL等可选环境变量，与登录功能相关，本机调试时可以不管。

启动开发服务器并验证

启动前端开发模式（web/package.json 中dev脚本为NODE_OPTIONS=--max_old_space_size=16384 next dev，即 Next.js 13 的开发服务器）：

npm run dev

启动后按文档说明访问：

http://localhost:3000

验证方式：打开页面后，文档对整套 DB-GPT 的判定标准是 "Web UI loads and you can start a chat conversation"。单独调试时同理——3000端口页面能加载、且能发起一次聊天请求（请求经API_BASE_URL打到5670后端）即说明前端开发环境与后端连通。

出问题时检查什么

• 页面加载但接口不通：确认5670端口的后端进程还在，API_BASE_URL的协议、主机、端口与后端实际监听一致；文档提示排查时检查启动 DB-GPT 的那个终端里的服务端日志。
• 后端根本没起来：回到 源码部署 的 "Server starts but UI is blank" 一节：确认终端显示 webserver 正常启动，并检查是否有其他进程已占用端口5670。
• 前端修改不生效：npm run dev是热更新的开发模式，改动web/下代码后刷新http://localhost:3000即可看到效果；npm run dev只是本地调试入口，不要用它替代生产构建。

下一步：把改动构建回服务端

调试完前端、需要让改动出现在5670内置 UI 中时，web/README.md 给出的方式是执行仓库提供的构建脚本：

bash ../scripts/build_web_static.sh

该脚本位于 scripts/build_web_static.sh，用于把web/构建产物输出到 DB-GPT 服务端的静态目录；执行前确认web/依赖已安装，构建完成后再重启 webserver 验证页面变化。

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