BISHENG Platform 前端启动与部署指南：开发调试、Nginx 代理与生产构建全解析-港品优选

BISHENG Platform 前端启动与部署指南：开发调试、Nginx 代理与生产构建全解析

【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng

导读

本文以 BISHENG 开源平台前端工程（src/frontend/platform）的启动与部署为核心，系统讲解从本地开发调试、Vite 代理配置到生产环境构建、Nginx 反向代理与 Docker 化部署的完整链路。读完本文，你将掌握：如何快速拉起开发服务器并让/api、/bisheng等请求正确转发到后端与文件服务，如何通过环境变量灵活切换代理目标，以及如何将构建产物部署到生产环境并配置支持 WebSocket 与子路由的 Nginx 规则。

一、环境准备

BISHENG 前端基于 Vite + React 构建，开始之前请确保本机已安装：

Node.js：建议使用 LTS 版本。工程engines字段声明要求node >= 18，见 platform/package.json。
包管理工具：npm或yarn均可，下文以npm为例。

工程目录结构上，src/frontend下包含两套前端：

目录	说明
`src/frontend/platform`	平台管理端（本文主体），端口`3001`
`src/frontend/client`	工作台客户端，构建产物挂载在`/workspace`路径下

二、安装依赖

克隆仓库后进入平台前端目录安装依赖：

git clone https://gitcode.com/GitHub_Trending/bi/bisheng cd src/frontend/platform npm install # 或者使用 yarn # yarn install

注意：工程依赖中包含本地私有包vditor（通过file:local-packages/vditor-3.11.1.tgz引入），local-packages目录已随仓库提交，因此常规npm install即可完成解析，无需额外配置私有源。

三、本地启动开发服务器

安装完成后，启动开发服务器：

npm run start # 或者使用 yarn # yarn start

start脚本实际执行的是vite（见 platform/package.json 的scripts字段），开发服务器默认运行在http://localhost:3001（host: '0.0.0.0'允许局域网访问，端口在 vite.config.mts 的server块中定义）。

此外工程还提供了几个实用脚本：

npm run dev:docker # 以 vite --host 0.0.0.0 方式启动，供 Docker 开发容器使用 npm run build # 生产构建，产物输出到 build 目录 npm run serve # 本地预览生产构建产物（vite preview） npm run test # 运行 vitest 单元测试

3.1 开发代理配置

开发环境下，Vite 通过server.proxy将前端请求转发到后端，核心路由在 vite.config.mts 中定义：

API 路由：/api/与/health→ 代理到后端接口（默认http://127.0.0.1:7860）；
文件服务路由：/bisheng与/tmp-dir→ 代理到文件服务器（默认http://127.0.0.1:9100，即 MinIO 对象存储）；
子路由支持：开启子路由后（app_env.BASE_URL设置为/custom等前缀），需要配置/custom_base/api代理，并通过rewrite将路径/custom_base/api重写为/api。

所有代理统一使用commonProxyOptions，关键参数为：

const commonProxyOptions = { changeOrigin: true, // 改写请求 Host 为目标主机 withCredentials: true, // 携带跨域 Cookie secure: false, // 允许自签名证书 ws: true // 支持 WebSocket 升级 };

3.2 MinIO 预签名 URL 的 Host 一致性陷阱

vite.config.mts中对文件服务代理做了特殊处理：MinIO 预签名（SigV4）URL 是按 Host 签名的，如果代理改写后的 Host 与签名时的 Host 不一致，对象请求会返回 403（典型场景是127.0.0.1与localhost不互通）。源码中通过warnMinioSignatureMismatch在收到 403 时输出告警，提示将VITE_MINIO_PROXY_TARGET配置为与后端config.yaml中object_storage.minio.sharepoint完全一致的主机。遇到图片/文件加载 403 时，请优先检查这一项。

四、正式环境部署

4.1 构建项目

npm run build # 或者使用 yarn # yarn build

build脚本执行vite build，构建产物输出到build目录。vite.config.mts中对产物做了细致的分包优化：

输出目录：build，静态资源统一放入assets/js、assets/[ext]等带 hash 的路径；
自动分包：pdfjs-dist独立为vendor-pdf，xlsx/mammoth相关合并为vendor-xlsx，react-ace/ace-builds/vditor等编辑器依赖合并为vendor-editor，react-markdown/mathjax等 Markdown 相关依赖合并为vendor-markdown，其余第三方包归入vendor，有效利用浏览器缓存并减小首屏体积；
createHtmlPlugin负责向index.html注入baseUrl与 Ace 编辑器脚本地址。

4.2 部署静态文件

将build目录下的所有文件上传到你的静态文件服务器（或 Web 服务器根目录）即可。若按仓库 Dockerfile 的方式构建，产物会被复制到 Nginx 的/usr/share/nginx/html/platform下。

4.3 配置服务器代理

生产环境需要为 API 请求与文件服务请求配置反向代理。以下是仓库 platform/nginx.conf 给出的生产配置要点：

前端静态资源用try_files $uri $uri/ /index.html回退到 SPA 入口，并设置X-Frame-Options: SAMEORIGIN；
/api代理到后端，需开启 WebSocket 升级（proxy_http_version 1.1+Upgrade/Connection头），并设置client_max_body_size 1024m以支持大文件上传；
在http区域使用map $http_upgrade $connection_upgrade动态决定是否升级连接。

更完整的示例配置（对应原文档）如下：

map $http_upgrade $connection_upgrade { default upgrade; '' close; } server { listen 80; server_name your-domain.com; root /path/to/your/build; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass [backend url]; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $server_name; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } location /bisheng/ { proxy_pass [file server url]; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location /custom_base/api/ { rewrite ^/custom_base/api/(.*)$ /api/$1 break; proxy_pass [backend url]; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

其中：

/使用try_files保证前端路由刷新不 404；
/api/同时承载 REST 请求与 WebSocket 长连接，Upgrade头必须正确传递；
/bisheng/代理到文件服务器（MinIO 对象存储）；
/custom_base/api/用于子路由场景，先rewrite去掉子路由前缀再转发。

仓库实际运行在 Docker 编排中的 Nginx 配置（见 docker/nginx/conf.d/default.conf）还额外支持了/workspace客户端路径与minio:9000上游，是这套代理逻辑的多应用落地范本。

4.4 环境变量

生产环境可通过设置环境变量VITE_PROXY_TARGET配置 API 代理目标地址。仓库在 env.development.gateway.example 中给出了开发环境的推荐取值：

# 复制为 .env.development.local 后生效（Vite 会加载） # 前端 API 走本机 Gateway，由 Gateway 再代理到 bisheng :7860 VITE_PROXY_TARGET=http://127.0.0.1:8180 VITE_MINIO_PROXY_TARGET=http://127.0.0.1:9100

从 vite.config.mts 的实现可以看到变量的读取逻辑：

const env = loadEnv(mode, path.resolve(__dirname), ""); const target = env.VITE_PROXY_TARGET || "http://127.0.0.1:7860"; const fileServiceTarget = env.VITE_MINIO_PROXY_TARGET || "http://127.0.0.1:9100";

关键结论（均有源码依据）：

未设置变量时回落到http://127.0.0.1:7860（后端）与http://127.0.0.1:9100（MinIO）；
必须通过loadEnv从.env.development.local等文件加载，仅使用process.env时配置阶段读不到VITE_变量，会导致/api/department-limit/*这类仅由 Gateway 提供的接口 404（源码注释中明确说明了这一点）；
另一个可选变量为VITE_WORKSPACE_ORIGIN，用于注入工作台源地址，通过define.__APP_ENV__注入到构建产物中，前端代码中以__APP_ENV__.BASE_URL/__APP_ENV__.BISHENG_HOST形式访问（见 client/readme.md）。

五、常见问题

5.1 如何修改代理目标地址？

通过修改.env文件中的VITE_PROXY_TARGET变量即可：

VITE_PROXY_TARGET=http://new-target-address:port

修改后，重新启动开发服务器或重新构建项目以应用新的代理目标地址。注意 Vite 约定本地个人配置应命名为.env.development.local（仓库示例文件即如此命名），并确保文件位于src/frontend/platform目录下。

5.2 如何添加新的代理路径？

在 vite.config.mts 的proxyTargets对象中添加新的代理路径即可：

proxyTargets['/new-path'] = { target: "http://new-target-address:port", changeOrigin: true, withCredentials: true, secure: false };

更优雅的做法是复用源码中已有的createProxyConfig(target, rewrite, isMinio)工厂函数（它统一处理了ws: true、路径rewrite以及 MinIO 403 告警），并将新路径加入apiRoutes或fileServiceRoutes数组。配置保存后开发服务器会自动热更新代理配置。

5.3 开发模式下无法访问到静态资源

如果开发模式下静态资源加载异常，可检查node_modules/vite-plugin-html/dist/index.mjs中的历史中间件（约 150 行server.middlewares.use(history...）。vite-plugin-html注入的 history 回退中间件可能拦截静态资源请求，此时可临时注释该行后重启开发服务器。这是插件层面的兼容性处理，仅在本地开发遇到资源 404 时需要干预。

六、容器化部署补充

仓库在 Dockerfile 中提供了完整的多阶段构建方案，与实际生产链路一致：

FROM node:18-alpine as frontend_build ARG BACKEND WORKDIR /app COPY . /app RUN cd /app/client && npm install --force && npm run build RUN cd /app/platform && npm install --force && npm run build FROM nginx COPY --from=frontend_build /app/client/build/ /usr/share/nginx/html/client COPY --from=frontend_build /app/platform/build/ /usr/share/nginx/html/platform COPY /nginx.conf /etc/nginx/conf.d/default.conf

该流程依次构建 client 与 platform 两套前端，再由 Nginx 统一托管；platform 管理端与 client 工作台分别挂载到/platform与/workspace路径（后者在 docker/nginx/conf.d/default.conf 中通过alias与try_files实现）。整个平台的后端、数据库、Redis、MinIO、Nginx 等组件的完整编排可参考 docker/docker-compose.yml 及 docker/deploy.sh。

七、小结

BISHENG 平台前端以 Vite 为构建核心，将「后端 API 代理、文件服务代理、子路由重写、WebSocket 升级」全部收敛到 vite.config.mts 一处管理，配合VITE_PROXY_TARGET/VITE_MINIO_PROXY_TARGET环境变量即可在开发与生产环境间无缝切换。生产部署只需三步：npm run build产出build目录、将静态文件部署到 Web 服务器、按本文第 4.3 节配置 Nginx 代理。掌握这套链路后，无论是本地联调、网关子路由接入还是容器化发布，都可以快速定位与解决代理与部署相关问题。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析