Files
Morris daf218ce71 1.0.11:发布包改为单文件,非本体文件收进 .GC/bin
- 启动器改成 self-contained 单文件(压缩);GC.UI.Server 抽出 BackendServer.Start,
  由启动器在自己的进程内托管,发布包只剩一个 exe,不再复制两套 .NET 运行时
- 后端保留独立入口(GC.UI.Server 仍可单独 dotnet run),开发调试方式不变
- 守护进程等非本体文件统一放 .GC/bin:首次启动复制到 .GC/safedog 再运行;
  更新时只合并 .GC/bin,config/model/cache/update/logs 原地不动
- 压缩包不再预置 .GC 模板,首次启动由 AppPaths.EnsureCreated + RuntimeLayout 生成
- macOS 同样打进 .app 内的单文件启动器
- 版本号 1.0.11,version.json / model/version.json 重签(gc-2026-12)
2026-11-18 21:08:54 +08:00

181 lines
7.7 KiB
Markdown
Raw Permalink 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. 启动后端
发布版里后端不走独立进程:`GC-BOOT` 直接引用本工程,调用
`BackendServer.Start(args, port)` 在自己进程内托管,发布包因此只有一个 exe
(两个自包含进程会把 60MB 运行时复制两份)。下面的独立运行方式只用于开发调试。
```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` 调试界面。