浏览器后台开发与发布

约 1108 字大约 4 分钟

当前生产目标是仓库中的 React 浏览器管理后台 fronted_admin_web/，并非创作者使用的 Web 网站端。它采用 Vite、React 19 和 React Router。fronted_admin_web_vue/ 是旧版 Vue 对照项目，仅在需要比对旧页面时启动。

前置条件

Node.js 20+。
FrameAI Gateway 已启动；本地默认地址为 http://127.0.0.1:9999。
管理员账户已由后端准备。
运行命令的目录是仓库根目录下的 fronted_admin_web/。

本地启动

Set-Location D:\work\go\FrameAI\fronted_admin_web
npm ci
npm run dev

Vite 开发服务器默认监听 http://127.0.0.1:5000/。启动后先访问登录页，再完成一次管理员登录验证。

开发环境的 .env.development 使用 VITE_API_BASE_URL 指向 Gateway。Vite 会将下列浏览器请求代理到该地址，并移除对应前缀：

浏览器请求前缀	用途
`/system-api`	REST API 请求。
`/system-ws`	WebSocket 请求。
`/system-file`	文件与媒体请求。

前端请求拦截器会为相对 API 请求自动补上 /system-api，并在存在登录令牌时携带 Authorization: Bearer <token>。不要把真实生产令牌、第三方密钥或支付凭证写入 .env、页面源码或前端构建产物。

开发调试顺序

在仓库根目录启动 Gateway 和所需服务。
启动 Web 管理后台，访问 http://127.0.0.1:5000/login。
登录后确认默认路由跳转到 /admin/workspaces。
打开浏览器网络面板，确认请求经过 /system-api 且目标是本地 Gateway，不直接访问业务服务端口。
依次验证工作空间、AI 任务、支付配置等你本次修改涉及的页面。
对深层路由进行直接访问，例如 http://127.0.0.1:5000/admin/ai-channels，确认开发服务器和前端路由都能正确渲染。

构建与质量检查

Set-Location D:\work\go\FrameAI\fronted_admin_web
npm run type:check
npm run build

npm run build 会先执行 TypeScript 无输出检查，再产出 dist/ 静态文件。构建成功不等于接口行为正确，发布前仍要完成实际登录、列表读取、一次保存操作和至少一条关键业务流程的验证。

生产静态托管与路由回退

浏览器管理后台使用浏览器端路由。生产服务器收到 /admin/workspaces、/admin/ai-channels 等深层地址时，必须回退到 index.html，让 React Router 接管渲染。缺少该回退时，刷新页面或直接打开书签会出现服务端 404。

将 dist/ 部署到 Web 服务器后，Nginx 站点可采用以下核心配置。域名、证书和静态目录按实际环境替换：

server {
  listen 80;
  server_name ADMIN_HOST;

  root /srv/frameai-admin/dist;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
  }

  location /system-api/ {
    proxy_pass http://GATEWAY_HOST:9999/;
    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 /system-ws/ {
    proxy_pass http://GATEWAY_HOST:9999/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
  }

  location /system-file/ {
    proxy_pass http://GATEWAY_HOST:9999/;
    proxy_set_header Host $host;
  }
}

proxy_pass 的尾部斜杠会影响前缀重写。部署后应从浏览器网络面板确认 Gateway 实际收到的路径，确保没有保留多余的 /system-api 前缀。

发布验收

访问 /login、/ 和一个深层地址 /admin/ai-channels，刷新后都不应返回 404。
未登录访问受保护路由时，应跳回登录页并保留原目标地址。
管理员登录成功后，打开工作空间、用户、AI 任务、支付配置等关键页面，确认请求成功且无跨域错误。
切换蓝白和暗黑主题，刷新页面后当前用户的主题选择仍保留。
执行一次只读查询和一次经过审批的配置保存，确认成功提示、刷新后的数据和审计记录一致。
通过 HTTPS 域名复测支付回调相关配置，确认回调地址、反向代理和安全头符合部署规范。

旧版 Vue 对照项目

需要核对旧版页面时才启动：

Set-Location D:\work\go\FrameAI\fronted_admin_web_vue
npm install
npm run dev

不要将 Vue 对照项目与 React 管理后台同时发布到同一个站点根路径。两者路由、构建配置和维护状态不同；正式入口应始终以 fronted_admin_web/ 的构建产物为准。