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

7.7 KiB
Raw Permalink Blame History

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 运行时复制两份)。下面的独立运行方式只用于开发调试。

# 仓库根目录
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. 启动前端

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. 打包

cd GC-UI/frontend
flutter build windows --release   # build/windows/x64/runner/Release/
flutter build macos --release     # build/macos/Build/Products/Release/

或直接用仓库根目录的脚本:

./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。

测试

# 后端编译
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 调试界面。