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平台管理端本文主体端口3001src/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 startstart脚本实际执行的是vite见 platform/package.json 的scripts字段开发服务器默认运行在http://localhost:3001host: 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 预签名SigV4URL 是按 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 buildbuild脚本执行vite build构建产物输出到build目录。vite.config.mts中对产物做了细致的分包优化输出目录build静态资源统一放入assets/js、assets/[ext]等带 hash 的路径自动分包pdfjs-dist独立为vendor-pdfxlsx/mammoth相关合并为vendor-xlsxreact-ace/ace-builds/vditor等编辑器依赖合并为vendor-editorreact-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.1Upgrade/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_TARGEThttp://127.0.0.1:8180 VITE_MINIO_PROXY_TARGEThttp://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:9100MinIO必须通过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_TARGEThttp://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 --fromfrontend_build /app/client/build/ /usr/share/nginx/html/client COPY --fromfrontend_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 代理。掌握这套链路后无论是本地联调、网关子路由接入还是容器化发布都可以快速定位与解决代理与部署相关问题。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考