# 桌面 GUI（Electron）

> 本文档由 README 拆分而来：Headless 与 Desktop 两种产物、构建与运行。
> 返回 [README](../README.md)。

## 桌面 GUI（Electron）

可选独立产物，面向内网桌面端用户：**内嵌 ModelRouter 核心**（桌面壳形态），
一键启停、系统托盘常驻、开机自启、静默启动，内容区一比一内嵌完整 WebUI
（状态/对话/密钥/优先级/源/适配器 六个页面，免登录）。服务器用户继续使用纯 Go 二进制。

### 两种安装包：Headless 与 Desktop

发布到 Release 的安装包分为两类，面向不同用户：

- **Headless（服务器版）**：纯核心二进制（无 Electron），配置驱动，适合服务器、
  容器、systemd 等无人值守场景。发布包含 `deb` + `rpm`（含 systemd unit、内存调优
  与示例配置）与 `tar.gz`（二进制 + `config.example.yaml` + `adapters/` + README），
  Windows 为 `.zip`。
- **Desktop（桌面版）**：Electron GUI 安装包，内嵌核心，适合个人桌面日常使用。

### 选择 GUI 还是纯后端

| 场景 | 推荐 | 理由 |
| ------ | ------ | ------ |
| 服务器 / 内网网关 / 无人值守常驻 | **Headless**（单二进制） | 极轻量（二进制 ~8MB；RSS 随源数量，单源 ~10MB、16 源 ~32–35MB，见[内存占用](#内存占用实测与调优)），零依赖单进程，直接跑在 systemd/任意容器里，远程管理 |
| 个人桌面日常使用 / 多设备内网共享 | **Desktop**（GUI） | 免登录内嵌 WebUI、系统托盘一键启停、开机自启、静默后台，适合不懂命令行的使用者 |
| Windows 桌面 | **Desktop** | 纯后端在 Windows 上需自行注册服务，GUI 提供原生托盘/自启体验 |
| CI 一键出三平台安装包 | **Desktop 打包脚本** | `make gui-*` 系列出 deb/AppImage/NSIS，可进发行流水线 |

两者完全同源：GUI 内嵌的就是纯后端的同一份 `modelrouter` 核心（LuaJIT 版），
配置/适配器格式完全一致，可随时互换。

### 构建与运行

```bash
cd cmd/gui
npm install
make gui          # 或 npm run dev —— 开发运行（需先 make build 生成 bin/modelrouter）
make gui-deb      # 本机构建 deb（分享给其它 Linux 用户）
make gui-dist     # 构建 deb + rpm + AppImage（linux，rpm 需系统 rpmbuild）
make core-dist    # 构建核心 deb + rpm + tar.gz（服务器版，需 nfpm）
make gui-win      # 构建 Windows nsis 安装包（本机 mingw + wine）
make gui-win-docker  # 构建 Windows nsis 安装包（全 docker 自足，含 wine）
make gui-dist-dir # 仅解包产物（调试用，不产安装包）
```

产物在 `cmd/build/gui-dist/`：`ModelRouter-<ver>.AppImage`、
`modelrouter-gui_<ver>_amd64.deb`、`ModelRouter Setup <ver>.exe`（win）；
核心包在 `cmd/build/dist/`：`modelrouter_<ver>_amd64.deb`、`modelrouter-<ver>.x86_64.rpm`。
rpm 需系统 `rpmbuild`。每次打包后都会跑 `packaging/verify-dist.sh` 产物体检
（大小下限门禁——1.3.0 曾因宿主 wine 损坏产出 264KB 的残缺 exe 却没有被拦住）。
发布时会把产物重命名为 `ModelRouter-Desktop-*`（GUI）与 `ModelRouter-Headless-*`（纯后端）
两类上传到 GitCode Release。

#### Windows 打包（docker 固化方案，推荐）

`make gui-win-docker` 一步完成：交叉编译核心 + NSIS 打包**全在 docker 内**，宿主机
**无需 mingw、无需 wine、无需 node**。镜像内置 wine（含 i386 运行时），修复了
此前宿主 wine 损坏（缺 syswow64 → `c0000135`）导致产出 264KB 残缺 exe 的问题。

- 构建镜像：`cmd/gui/docker/win-builder/Dockerfile`（`golang:1.25` + mingw-w64 +
  node + wine32/wine64 + 预编译 LuaJIT windows 版 `lua51.dll` 与 import lib）。
  LuaJIT 源码取自 gitcode 镜像（国内可达），github 兜底；Go 依赖走 `https://goproxy.cn`。
- 一键发布：`cmd/gui/scripts/dist-win-docker.sh` —— 核心编译 + electron-builder
  NSIS 全部在容器内执行（`USE_SYSTEM_WINE=true` 走镜像内的 wine）；electron-builder
  的 ~400MB 工具链缓存挂到 docker volume，二次构建增量复用。
- 首次运行自动构建 `modelrouter/win-builder` 镜像（约 5–10 分钟）；已存在则直接复用。
- 打包完成后自动跑 `packaging/verify-dist.sh` 门禁：exe 低于 5MB / deb·rpm·7z 低于
  10MB 即失败——残缺安装包不可能再溜进 Release。

```bash
# 全 Windows 发布（核心重编 + NSIS）：
make gui-win-docker
```

### 特性

- **内嵌核心**：自动拉起捆绑的 `modelrouter`（LuaJIT 版），配置/密钥/adapter 存于
  用户数据目录 `<userData>/profile/`，首次运行自动生成随机 admin key 写入 `keys`
  （非 seed）并自注入，WebUI 免登录、不会提示"更换初始密钥"。端口可在设置中更改（默认 8787）。
- **系统托盘**：内核状态点、开机自启/静默启动开关、启停/重启内核、退出。
- **静默启动**：`--silent` 参数或设置项，启动仅驻托盘不弹窗；首次运行始终显示窗口。
- **开机自启**：Windows/macOS 用 `setLoginItemSettings`；Linux 写
  `~/.config/autostart/modelrouter-gui.desktop`，静默开启时自动附加 `--silent`。