feat: implement custom WebUI support with dynamic frontend replacement

- Add WebUI service and controller for managing custom frontend packages - Allow overriding default static assets when custom WebUI is activated - Add Make commands for packing custom WebUI distributions - Update UI settings to support uploading, activating and deleting WebUIs - Document WebUI feature in README and changelog
2026-05-29 11:49:01 +08:00
parent 41af3cf9e0
commit 323a58e041
19 changed files with 1004 additions and 35 deletions
@@ -52,6 +52,7 @@ export default defineConfig({
                text: '部署配置',
                items: [
                    { text: '系统配置', link: '/guide/configuration' },
+                    { text: '前端定制(WebUI)', link: '/guide/webui' },
                    { text: '反向代理', link: '/guide/nginx' }
                ]
            },
@@ -4,6 +4,12 @@

 ## 最近更新概览

+### 2026.05.29 - 前端定制与 WebUI 插件化
+- **自定义 WebUI 支持 (New)**：新增了前端自定义打包与热切换功能。面板系统彻底解耦前后端静态资源，用户可以在“系统设置 - 前端定制”中上传并管理自定义前端资源包，实现深度的主题替换与定制。
+- **打包工具链整合**：提供了一键构建前端定制包的 `make pack-webui` 快捷命令与规范（自动生成 `uimanifest.json`）。
+- **动态资源托管**：Go 后端引入动态静态资源拦截机制，可无缝接管系统入口与单页应用渲染，同时向下兼容内置面板。
+
+
 ### 2026.04.16 - 内建脚本助手库 (Built-in SDK)
 - **内建助手库 (Built-in SDK) (New)**：新增 Python 与 Node.js 的轻量级助手库 `baihu`。通过环境自动注入机制实现“零配置”通知投递，开发者无需在脚本中显式配置 TOKEN 或 URL。
 - **环境自动初始化**：新增 `baihu builtininstall` 命令行工具，支持一键为 `mise` 管理的所有多语言版本同步安装/刷新内建包依赖。
@@ -0,0 +1,126 @@
+# 前端定制 (WebUI)
+
+白虎面板支持完全接管和替换默认系统面板界面。你可以开发自己专属的前端主题，甚至添加自定义的前端交互功能，并打包为独立的 WebUI 资源包上传至系统应用。
+
+> [!IMPORTANT]
+> **安全与一致性维护声明**：
+> 更换前端包后，系统无法自动保障自定义前端的安全性，亦无法确保其与后续更新的后端 API 接口始终保持一致。**自定义前端包的更新、向后兼容维护与漏洞修复需完全由该前端资源提供者（或开发者）负责**。
+
+---
+
+## 快速使用
+
+### 1. 网页端上传与切换
+1. 进入系统后，点击导航栏的 **系统设置**。
+2. 切换到 **前端定制** 面板。
+3. 点击右上角的 **上传前端资源包**，选择你打包好的 `.zip`、`.tar.gz` 或 `.tgz` 格式的前端资源包。
+4. 上传成功后，列表会显示该包的信息（名称、版本、作者、状态等）。
+5. 点击操作栏中的 **启用** 按钮，系统将自动重载并切换至你的自定义前端包。
+
+> [!WARNING]
+> 自定义前端包若存在 Bug 或打包不完整可能导致界面白屏。如果不慎应用了错误或不兼容的包，请使用下方命令行工具恢复。
+
+### 2. 命令行 (CLI) 运维
+当界面因异常白屏无法访问时，可以进入白虎面板容器/服务器终端，使用 `baihu webui` 命令一键管理或恢复：
+
+- **一键恢复默认内置界面**：
+  ```bash
+  baihu webui reset
+  ```
+- **查看已安装的资源包列表**：
+  ```bash
+  baihu webui list
+  ```
+- **手动切换/启用前端包**：
+  ```bash
+  baihu webui set <包名>
+  ```
+- **删除指定的前端包**：
+  ```bash
+  baihu webui delete <包名>
+  ```
+
+---
+
+## 开发自定义前端
+
+你可以使用 React, Vue, Angular 或任何纯静态 HTML/JS 技术来开发自定义的白虎面板前端。
+
+### 1. 核心校验规则
+白虎面板后端提取并启用前端资源时，会执行以下强校验：
+1. **压缩包根目录下必须包含 `index.html`**：作为单页应用 (SPA) 的静态入口文件。
+2. **压缩包根目录下必须包含 `uimanifest.json`**：声明该前端包的元数据信息。
+
+### 2. 配置文件 `uimanifest.json` 规范
+在前端打包产物的根目录下（与 `index.html` 同级），必须创建一个 `uimanifest.json` 文件。格式示例如下：
+
+```json
+{
+  "name": "custom-neon-theme",
+  "version": "1.0.2",
+  "author": "YourName",
+  "description": "白虎面板霓虹暗黑风定制前端主题",
+  "min_panel_version": "1.0.0"
+}
+```
+
+*注：`name` 字段不能设置为 `"default"`（default 被保留作为内置前端的系统标识）。*
+
+### 3. API 请求地址与开发环境代理
+在独立开发自定义前端时，需要配置请求与后端的通信地址及代理：
+
+- **后端默认服务地址与端口**：
+  白虎面板后端服务默认运行在端口 `8052` 上，本地调试 API 的基础 URL 通常为：
+  `http://127.0.0.1:8052/api/v1`
+  
+- **本地开发环境代理配置（以 Vite 为例）**：
+  为了避免跨域问题（CORS），推荐在前端开发服务器中设置代理。在 `vite.config.ts` 中配置示例如下：
+  ```typescript
+  export default defineConfig({
+    server: {
+      proxy: {
+        '/api/v1': {
+          target: 'http://127.0.0.1:8052', // 本地运行的白虎面板后端地址
+          changeOrigin: true
+        }
+      }
+    }
+  })
+  ```
+
+- **生产环境线上适配（相对路径）**：
+  前端包部署生效后，与后端处于同端口同域名下。后端会在返回的 `index.html` 的 `<head>` 中自动注入以下配置变量：
+  ```html
+  <script>
+    window.__BASE_URL__ = "";          // 部署子路径前缀 (根据实际反代配置)
+    window.__API_VERSION__ = "/api/v1"; // API 接口版本前缀
+  </script>
+  ```
+  建议在封装 Axios 或 Fetch 时，直接通过浏览器环境变量拼接相对路径作为 API 地址：
+  ```typescript
+  const baseURL = `${window.location.origin}${window.__BASE_URL__ || ''}${window.__API_VERSION__ || '/api/v1'}`;
+  ```
+
+- **接口定义与类型参考**：
+  默认系统中已经定义好了所有的后端 API 接口签名、传参格式以及 TS 类型声明。你在二次开发或自定义前端时，可以直接参考项目源码中的前端接口定义文件： `web/src/api/index.ts`。
+
+---
+
+## 打包前端资源包(现成)
+
+你可以利用白虎面板项目自带的 `Makefile` 脚本，在现在的前端页面进行修改，将开发好的前端项目快速编译打包成标准的 `.tar.gz` 前端资源包, 自己使用或者分享使用。
+
+### 使用 Makefile 打包
+
+在项目根目录下，运行以下指令（参数必须填写完整）：
+
+```bash
+make pack-webui NAME=neon-theme VERSION=1.0.2 AUTHOR=MyName DESC="霓虹定制主题包"
+```
+
+该指令会自动执行以下步骤：
+1. 进入 `web/` 目录并安装依赖；
+2. 编译构建前端静态资源（默认输出到 `web/dist`）；
+3. 在 `web/dist` 中自动按参数生成校验所需的 `uimanifest.json`；
+4. 将该目录下所有文件使用 `tar` 命令进行 gzip 压缩打包；
+5. 输出归档文件在项目根目录的 `bin/webui-neon-theme-1.0.2.tar.gz`，此包即可直接在面板中上传安装。