企业官网建设流程全解析

DB-GPT-Web 前端实战指南：基于 Next.js 与 Tailwind 构建 LLM 到 Vision 的 AI 数据助手 UI

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

导读

本文以 web/README.md 为核心主线，系统讲解 DB-GPT 项目中前端交互层DB-GPT-Web的定位、技术栈、本地启动流程，以及如何将前端产物集成进 DB-GPT 服务端整体发布。读完本文，你将掌握：在本地一键跑起 DB-GPT 对话界面、通过API_BASE_URL对接后端服务、理解 Markdown 与 AI 特定场景的渲染增强机制，并看懂前端构建产物如何被打包进 scripts/build_web_static.sh 完成前后端一体化交付。

一、DB-GPT-Web 是什么：DB-GPT 的 LLM to Vision 前端

根据 web/README.md 的定位说明，DB-GPT-Web是 DB-GPT 的开源对话界面（Chat UI），同时也是一个 "LLM to Vision" 的解决方案：它不只是一块把大模型文字回复渲染出来的面板，更要把 LLM 生成的结构化数据（表格、SQL、图表指令等）转化为可视化的图表与交互界面，让用户在对话中"看见"数据。

在技术选型上，它建立在两条明确的技术基线上：

• Tailwind CSS + Next.js：基于原子化 CSS 与 React 服务端渲染框架搭建 UI 骨架；
• AI 场景的 Markdown 增强渲染：一方面对标准 Markdown 标签（table、thead、th、td、code、h1、h2、ul、li、a、img）做了大量美化；另一方面定义了面向 AI 场景的自定义标签，例如插件运行状态（plugin running）、知识库名称（knowledge name）、图表视图（Chart view）等。

从 web/package.json 可以看到这套方案背后的依赖清单，直接印证了 README 中列出的核心组件：@antv/gpt-vis负责 Markdown 渲染支持、antd提供 UI 组件、next承担服务端渲染、@antv/g2与@antv/ava负责图表绘制。此外还集成了reactflow（DAG 流程画布）、@monaco-editor/react（SQL/代码编辑器）、remark-gfm与remark-math（GFM 与数学公式支持）等面向 AI 应用的高频能力。

二、环境要求与前置条件

开始安装前，请先确认本机满足 web/README.md 列出的最低环境要求：

说明：依赖版本以当前仓库为准。仓库内同时提供了 web/package-lock.json 与 web/yarn.lock 两份锁文件，分别对应 npm 与 yarn 两条安装链路，实际使用时建议只选一条，避免依赖树不一致。

三、安装依赖：Yarn 优先

web/README.md 明确建议使用Yarn管理依赖，两条命令等价：

# 使用 npm 安装 npm install # 使用 yarn 安装（推荐） yarn install

安装后你可以通过 web/package.json 中预置的脚本快速验证环境，例如执行npm run lint（基于 ESLint + Prettier 的代码检查与自动修复）或npm run test（运行react-agent-final与final-presentation两组基于 TypeScript 编译的单元测试，对应 web/utils/react-agent-final.test.ts 与 web/utils/final-presentation.test.ts）。

四、本地启动：配置 API_BASE_URL 并运行开发服务器

4.1 复制环境变量模板

web/README.md 给出的启动第一步是复制环境变量模板：

cp .env.template .env

仓库中的 web/.env.template 内容非常简洁，只有一个关键配置项：

API_BASE_URL=http://127.0.0.1:5670

API_BASE_URL是前端与后端对话的核心桥接配置，表示前端向哪个地址发起 HTTP 请求。默认值http://127.0.0.1:5670恰好对应 DB-GPT 后端服务在 configs/dbgpt-app-config.example.toml 中的默认监听地址：

[service.web] host = "0.0.0.0" port = 5670 # CORS allowed origins: '*' allows all; set comma-separated origins to restrict. cors_allowed_origins = "${env:DBGPT_CORS_ALLOWED_ORIGINS:-*}"

也就是说：本地同时启动 DB-GPT 后端（默认 5670 端口）与 DB-GPT-Web 前端（Next.js 默认 3000 端口）后，前端通过API_BASE_URL直连后端，即可完成对话。如果后端部署在远程机器，只需把.env中的地址改为真实的服务地址即可。

该环境变量会在构建期通过 web/next.config.js 注入到前端运行时环境：

env: { API_BASE_URL: process.env.API_BASE_URL, GITHUB_CLIENT_ID: process.env.GITHUB_CLIENT_ID, GOOGLE_CLIENT_ID: process.env.GOOGLE_CLIENT_ID, GET_USER_URL: process.env.GET_USER_URL, LOGIN_URL: process.env.LOGIN_URL, LOGOUT_URL: process.env.LOGOUT_URL, },

由此可以看出，除API_BASE_URL外，.env还预留了 GitHub/Google 第三方登录、用户信息获取与登录/登出地址等可选配置位，用于对接带用户体系的部署场景（对应 web/pages/index.tsx 中的登录与会话管理逻辑）。

4.2 启动开发模式

web/README.md 给出的开发模式命令：

# npm 方式 npm run dev # yarn 方式（推荐） yarn dev

对应 web/package.json 中的脚本定义为：

"dev": "NODE_OPTIONS=--max_old_space_size=16384 next dev"

注意两点：

• 开发模式会启动 Next.js 的热更新服务，修改.tsx/.ts代码后页面即时刷新；
• 脚本显式把 Node 堆内存上限调到 16GB（--max_old_space_size=16384），这是因为本项目依赖了monaco-editor、@antv/g6、@antv/graphin等重量级前端库，构建期内存占用较高，若你的机器内存有限，可留意这一参数的作用。

五、前端如何对接后端：请求层与错误处理

理解API_BASE_URL之后，值得进一步看下前端请求层是如何消费它的。以 web/utils/request.ts 为例，所有 API 调用统一经过 axios 封装，并做了两件关键事情：

1. 统一注入身份标识：每次请求默认携带User-Id请求头（取自 web/utils/constants 中的 cookie 工具），保证后端能区分不同会话用户；
2. 友好的错误提示：对网络层失败（超时ECONNABORTED、断网/CORS 被拦截等）与 HTTP 层失败（优先取服务端返回的err_msg/message字段）分别归类，并通过 i18n 输出可读文案。

从源码结构看，web/client/api 目录下按模块拆分了app、chat、evaluate、flow、knowledge、models_evaluation、prompt、tools、user等 API 封装，分别对应 DB-GPT 后端的应用管理、对话、评测、流程编排、知识库、模型评测、Prompt 管理等接口，前端页面均通过这套封装与后端交互。

六、Markdown 增强与 AI 场景可视化：LLM to Vision 的实现路径

web/README.md 花了较多篇幅强调 DB-GPT-Web 的两类渲染能力：

• 标准 Markdown 美化：对table、code、标题、列表、图片等常规标签做样式增强，让大模型输出的 Markdown 在页面上"开箱即美"；
• AI 场景自定义标签：插件运行、知识库名称、图表视图等特殊组件，让 AI 返回的"结构化意图"被渲染成真正的交互组件而非纯文本。

从源码可以确认这套能力的落点。以图表视图为例，web/components/chat/chat-content/chart-view.tsx 实现了 "Chart / SQL / Data" 三个 Tab 的联动渲染：

• Chart：调用@antv/ava的AutoChart组件，根据后端返回的BackEndChartType（getChartType(type)）自动选择合适的图表类型；
• SQL：通过formatSql对后端生成的 SQL 做格式化，并使用CodePreview（语法高亮）展示；
• Data：将结果集直接渲染为 antdTable。

其核心思路是：后端（DB-GPT 的 Chat Data / Chat Excel 等能力）把"查询结果 + 图表类型 + 原始 SQL"结构化返回，前端负责把数据"画"出来——这就是 README 中 "LLM to Vision" 的含义。类似的渲染组件还有 web/components/chat/chat-content/vis-chart.tsx、vis-code.tsx、vis-plugin.tsx以及agent-messages.tsx（Agent 消息流）等，共同构成对话内容区的可视化家族。

页面级的编排入口在 web/pages/index.tsx：主聊天页聚合了模型选择器（ModelSelector）、数据连接器（useConnectors）、会话文件上传预览（@/modules/session-files）以及 Manus 风格的双栏 Agent 执行面板（ManusLeftPanel/ManusRightPanel）等能力，读者可在该文件中直观感受前端功能面的广度。

七、集成进 DB-GPT：一键构建静态产物

web/README.md 的 "Use In DB-GPT" 一节给出了前端与后端一体化集成的入口命令：

bash ../scripts/build_web_static.sh

这条命令的实际行为定义在仓库根目录的 scripts/build_web_static.sh 中，其流程可以拆解为四步：

1. 环境变量暂存：若web/.env存在，先复制为.env.copy临时文件；
2. 安装并构建：在web/目录执行yarn install，随后执行yarn compile（即 web/package.json 中的next build && next export，生成web/out/静态目录）；
3. 拷贝产物：清空并重建目标目录packages/dbgpt-app/src/dbgpt_app/static/web，把web/out/*全部拷贝进去；
4. 恢复环境变量：构建完成后把.env.copy还原为.env。

最终产物被放置到packages/dbgpt-app/src/dbgpt_app/static/web下，由 dbgpt-app 包（后端应用层）作为静态资源对外提供访问——这正是 DB-GPT 一体化部署时"前端已内置"的实现基础。值得注意的是，next export为纯静态导出模式，因此 web/next.config.js 中开启了trailingSlash: true与images: { unoptimized: true }，以保证静态托管环境下路由与图片资源均可正常工作。

八、构建与发布脚本速查

除开发模式外，web/package.json 还预置了多套面向不同阶段的脚本，整理如下：

九、常见问题与排查建议

结合上述流程，给出几条基于当前仓库实际配置的排障思路：

1. 页面空白 / 接口 404：优先检查web/.env中的API_BASE_URL是否指向了真实可访问的 DB-GPT 后端，并确认后端确实监听在对应端口（默认见 configs/dbgpt-app-config.example.toml 的[service.web]段）；
2. 跨域报错：后端cors_allowed_origins默认为*（允许所有来源），若被限制为指定域名列表，需把前端地址加入白名单；
3. 构建内存不足：next build/next dev均设置了较大的--max_old_space_size，如果构建中途因内存被 OOM 终止，请确认 Node 版本满足要求并适当释放内存；
4. 依赖安装冲突：仓库同时提供package-lock.json与yarn.lock，请全程只用一种包管理器，避免两套锁文件互相覆盖。

十、许可证与后续阅读

DB-GPT-Web 以MIT License开源（对应仓库根目录 LICENSE）。如果想继续深入：

• 前端组件与页面源码位于 web/components、web/pages、web/new-components，其中new-components下的 chat 目录集中了较新的对话组件实现；
• 核心交互逻辑沉淀在 web/hooks（如use-chat.ts、use-subagent-stream.ts）与 web/utils（如 SSE 流解析 web/utils/react-sse-parser.ts）；
• 前端产物的服务端集成入口位于 packages/dbgpt-app/src/dbgpt_app/static/web（该目录在运行 scripts/build_web_static.sh 后生成）。

理解 DB-GPT-Web 的启动、配置与构建链路，是二次开发 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