Files
GC-XH/GC-UI/README.md
T
Morris a361c889f8 修复审计发现的问题,默认构建即带 Flutter 前端
P0
- GC-SAVEDOG:更新改为整目录替换(旧文件备份到 .GC/update/backup,
  失败可完整回滚),不再只搬一个 exe;回滚会删掉新包独有文件
- GC-SAVEDOG:包名校验放宽为单文件名模式,Linux 启动器(无扩展名)可更新
- GC-DOWNLOAD:测速全失败时不再回退 GitCode,改为返回「不可用」并保留上次可用源
- GC-DOWNLOAD:识别并赋予 Linux 无扩展名启动器可执行位;兼容脚本清理旧版时
  也覆盖无扩展名产物
- CI:删除 nightly-prerelease(绕开 build.sh,产出无前端空壳);alpha 工作流
  去掉非法 cron,只保留手动触发

P1
- 前端:主题设置真正生效(深色/浅色/跟随系统 + 持久化),去掉死字段
- 前端:下载页轮询改为自适应单次链,页面不可见或任务结束后降频/停止
- 前端:下载完成 / 删除模型后首页列表自动刷新
- 前端:复用 http.Client,不再每次轮询新建连接
- 后端:/api/models 走缓存,不再每次全盘递归统计体积
- 设置页:外部改动能同步进表单,不再只同步一次

P2
- 错误响应统一为 ErrorDto,不再复用 LaunchResultDto
- 限流桶定期清理,避免无限增长
- 播放器窗口去重,避免同一模型重复开窗
- 封面按实际格式返回,去掉错误的 image/png 与 no-store
- 端口集中到 GcUiContract,前端可用 GC_UI_PORT 或 ui-backend.json 发现后端
- 构建:Windows 包改为散开发布,与后端共用运行时(体积约 109MB -> 72MB)
- 文档:更新仓库地址与更新流程说明

测试:dotnet build 全绿;GC.Tests 更新链路全通过;flutter analyze 无问题;
flutter test 11 项全通过。
2026-11-18 20:10:03 +08:00

177 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# GC-UI
GC 启动器的**前后端分离**实现:界面用 Flutter,服务层留在 .NET。
```
GC-UI/
├── backend/GC.UI.Server/ # .NET 8 后端:本地 HTTP API + 模型窗口宿主
│ ├── Program.cs # 所有接口(最小 API)
│ ├── ApiModels.cs # 前后端 JSON 契约
│ └── AvaloniaHost.cs # 模型窗口宿主(Avalonia,惰性启动)
└── frontend/ # Flutter 前端(Windows / macOS 桌面)
├── lib/
│ ├── main.dart # 应用入口
│ ├── shell.dart # 侧边栏 + 内容区 + 更新状态条
│ ├── pages.dart # 首页 / 下载 / 设置 / 关于
│ ├── controller.dart # 外壳状态(设置、健康、更新)
│ ├── api_client.dart # 后端 HTTP 客户端 + DTO
│ ├── i18n.dart # zh-CN / en 文案
│ └── theme.dart # 配色与通用组件
├── windows/ # Windows 原生 runner(flutter create 生成)
├── macos/ # macOS 原生 runner(flutter create 生成)
└── test/ # 单元测试 + 后端契约测试 + 截图脚本
```
## 为什么这样切
原来的 GC 是「Avalonia 界面 + 服务层」一体式应用。拆分时唯一不能动的是**模型契约**:
模型 dll 通过 `IModelRuntime.CreateView` 返回的是 Avalonia `Control`,渲染栈是契约的一部分。
把渲染换成 Flutter 等于让所有已发布模型失效。
所以切法是:
| 层 | 归属 | 说明 |
|---|---|---|
| 首页 / 下载 / 设置 / 关于 | **Flutter 前端** | 纯界面,通过 HTTP 调后端 |
| 模型扫描、下载、更新、设置持久化 | **.NET 后端** | 直接复用 `GC/src`(GC.Core)与 `GC-DOWNLOAD` |
| 模型自己的窗口 | **.NET 后端** | 模型返回 Avalonia 控件,由后端承载 |
前端只发一条「启动模型」的指令,模型窗口由后端在自己的 UI 线程上打开。
## 前端方案:为什么是 Flutter
Windows 与 macOS 用**同一套 Flutter 代码 + 各自的原生 runner**:
- **一套代码两个平台**:`flutter create --platforms=windows,macos` 生成 `windows/`(CMake + Win32 窗口)与 `macos/`(Xcode + Cocoa 窗口)两个原生壳,业务代码 100% 共用。
- **原生桌面窗口**:不是 WebView 套壳,两个平台都是真正的原生窗口,可设置最小尺寸、标题栏、DPI 缩放。
- **渲染一致**:Skia/Impeller 自绘,两个平台像素级一致,不需要为 WinUI / AppKit 各写一套控件。
- **热重载**:`flutter run -d windows` / `-d macos` 改界面即时生效,迭代比 XAML 快。
- **对比过的替代方案**:
- *继续用 Avalonia*:跨平台没问题,但那就不是「前后端分离 + Flutter 前端」了。
- *WinUI 3 + SwiftUI 各写一套*:两套 UI 代码、两套状态管理,维护成本翻倍。
- *Electron / Tauri*:WebView 套壳,包体大(Electron ~150MB)或需要 Rust 工具链,且与 .NET 后端通信仍要额外桥接。
## 运行
### 1. 启动后端
```bash
# 仓库根目录
dotnet run --project GC-UI/backend/GC.UI.Server
# 指定端口(默认 17890)
dotnet run --project GC-UI/backend/GC.UI.Server -- --port 17890
# 或
GC_UI_PORT=17890 dotnet run --project GC-UI/backend/GC.UI.Server
```
端口约定集中在 `GC.Services.GcUiContract`(`DefaultPort` / `PortEnvVar`):
正式启动时由 GC-BOOT 选端口(17890 被占用就往后试 9 个),再通过 `GC_UI_PORT`
环境变量同时传给后端和前端,所以**不需要为了换端口重新编译前端**。
启动后后端会在 `~/.GC/ui-backend.json` 写入 `{ port, pid, url, version, platform }`,
排查问题时可以据此确认实际端口。
### 2. 启动前端
```bash
cd GC-UI/frontend
flutter pub get
# Windows
flutter run -d windows
# macOS
flutter run -d macos
# 后端不在默认端口时
flutter run -d windows --dart-define=GC_UI_BASE_URL=http://127.0.0.1:18000
```
### 3. 打包
```bash
cd GC-UI/frontend
flutter build windows --release # build/windows/x64/runner/Release/
flutter build macos --release # build/macos/Build/Products/Release/
```
或直接用仓库根目录的脚本:
```bash
./GC-UI/build-ui.sh # macOS / Linux 上构建(macOS 产物)
GC-UI\build-ui.cmd # Windows 上构建(Windows 产物)
```
## HTTP 接口
后端只监听 `127.0.0.1`,不对外暴露。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/health` | 健康检查 + 模型窗口宿主是否可用 |
| GET | `/api/models` | 已安装模型 |
| GET | `/api/models/{id}/preview` | 模型封面图(PNG) |
| POST | `/api/models/{id}/launch` | 启动模型(打开模型自己的窗口) |
| DELETE | `/api/models/{id}` | 删除模型 |
| GET | `/api/settings` | 读取设置 |
| POST | `/api/settings` | 修改设置(补丁式,只改传入字段) |
| GET | `/api/sources` | 模型源列表 |
| POST | `/api/sources/select` | 双源测速并切到最快 |
| GET | `/api/remote/models?sourceId=&force=` | 远端可下载模型 |
| POST | `/api/download` | 入队下载 `{ sourceId, modelId }` |
| GET | `/api/download/jobs` | 下载任务列表 |
| POST | `/api/download/{id}/cancel` | 取消 |
| POST | `/api/download/{id}/retry` | 重试 |
| POST | `/api/download/{id}/remove` | 移除任务 |
| POST | `/api/download/clear-finished` | 清除已完成 |
| POST | `/api/update/check` | 检查模型 / 启动器更新 |
| GET | `/api/about` | 版本 + 贡献者 |
| POST | `/api/shell/open-folder` | 打开目录(仅限启动器自己的目录) |
| POST | `/api/shell/open-url` | 打开 http/https 链接 |
契约定义见 `backend/GC.UI.Server/ApiModels.cs`,前端对应 `frontend/lib/api_client.dart`。
## 测试
```bash
# 后端编译
dotnet build GC-UI/backend/GC.UI.Server
# 前端静态检查 + 单元测试
cd GC-UI/frontend
flutter analyze
flutter test
# 前后端联调(需要后端正在运行;后端没起时自动跳过)
flutter test test/backend_contract_test.dart
# 生成界面截图到 test/shots/(视觉检查用)
flutter test tool/render_shots_test.dart
```
截图脚本覆盖四个页面(首页 / 下载 / 设置 / 关于)再加一整套外壳:
`test/shots/home.png`、`download.png`、`settings.png`、`about.png`、`shell.png`。
需要先在本机 17890 端口跑起后端;脚本用 `runAsync` 给真实 HTTP 留出时间,
否则 `flutter_test` 的假时钟会让页面停在加载态。
## 「关于」页展示的技术栈
「关于」页的版本卡片里直接写明这套实现的两个关键点:
| 行 | 值 | 来源 |
|---|---|---|
| 源码语言 | **C#** | 后端 `/api/about` 返回 `sourceLanguage` |
| 前端 | **Flutter** | 后端 `/api/about` 返回 `frontend` |
| 架构 | Flutter 前端 + .NET 后端(本地 HTTP) | 前端 i18n 文案 |
两个字段由后端下发(而不是前端写死),所以将来换实现时只改后端一处,
前端和「关于」页自动跟着变。契约字段见 `ApiModels.cs` 的 `AboutDto`,
前端解析在 `lib/api_client.dart` 的 `AboutInfo`。
## 安全边界
- 后端只绑定 `127.0.0.1`,不接受外部连接。
- `open-folder` 只允许打开模型库 / 数据目录 / 应用目录之内的路径,避免被当成任意路径执行器。
- `open-url` 只允许 `http` / `https`。
- CORS 只放行 `localhost` / `127.0.0.1` 来源,方便 `flutter run -d chrome` 调试界面。