Files
Morris 22baa6fda9
PR 审核 / 后端编译 (pull_request) Canceled after 0s
PR 审核 / 后端自检 (pull_request) Canceled after 0s
PR 审核 / 前端检查(Flutter) (pull_request) Canceled after 0s
PR 审核 / 安全扫描 (pull_request) Canceled after 0s
PR 审核 / 审核汇总 (pull_request) Canceled after 0s
macOS 的 .GC/bin 也随包分发:守护进程不再落在 .app 根
- pack_launcher 的 macOS 分支把包内 GC-SAVEDOG 移进 .app/Contents/MacOS/.GC/bin,
  与 Windows 布局一致;.GC 位置不变,仍在启动器同级
- package_mac_app 的注释同步:包里只保留 .GC/bin,模板类目录仍由首次启动创建
- README 补 macOS 的 .GC 位置与守护进程路径
2026-11-18 21:10:43 +08:00

357 lines
21 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
天文教学模型**启动器**:管理/启动模型、启动时自动检查并下载最新版模型与启动器、设置语言与内存。
> **分层约定(重要)**
> - `GC/` = 启动器:扫描、下载、开窗口、显示加载进度。**不渲染、不含任何模型内容、发布包不内置模型**。
> - `model/` = 模型的一切:**源码、编译后的 dll、场景数据、封面、语言包、共享引擎、契约**,独立分发、独立版本。
> - 模型相关代码全部直接存在模型目录里,仓库根没有 `model-src/` / `model-sdk/` 这类旁路目录。
> - 想加新内容 = 在 `model/<id>/` 里放模型并推送仓库,启动器一行都不用改,客户端启动自动更新。
> - `GC-SAVEDOG/` = 更新守护进程:验签、原子替换、启动后健康检查、失败回滚。
- UI:C# + .NET 8(可切 .NET 10)+ Avalonia,跨平台
- 模型加载:`AssemblyLoadContext` 加载模型自带 dll,契约与 Avalonia 走默认上下文,关窗即卸载
- 目标平台:**Windows x64 / Windows arm64 / macOS arm64 / Linux x64**
- 更新仓库:<https://git.xhmcl.com/Morris/GC>,模型目录 <https://git.xhmcl.com/Morris/GC/src/branch/main/model>
## GC-UI:前后端分离版(Flutter 前端)
`GC-UI/` 是同一套服务层的**前后端分离**实现,界面改用 Flutter,Windows 与 macOS 共用一套代码:
```
GC-UI/
├── backend/GC.UI.Server/ .NET 8 本地 HTTP 服务(复用 GC/src + GC-DOWNLOAD)+ 模型窗口宿主
└── frontend/ Flutter 桌面应用(windows/ 与 macos/ 原生 runner)
```
- **前端**:Flutter(`flutter create --platforms=windows,macos` 生成两个原生壳),负责首页 / 下载 / 设置 / 关于
- **后端**:.NET 8 最小 API,只监听 `127.0.0.1`,负责模型扫描、下载、更新、设置持久化
- **模型窗口**:仍由 .NET 承载 —— 模型 dll 返回的是 Avalonia `Control`,渲染栈属于模型契约,不能换
`GC-UI/` 的详情、平台选型理由与接口列表见 [`GC-UI/README.md`](GC-UI/README.md)。
「关于」页会直接展示 **源码语言:C#、前端:Flutter**(由后端 `/api/about` 下发)。
```bash
# 后端
dotnet run --project GC-UI/backend/GC.UI.Server
# 前端(另开终端)
cd GC-UI/frontend && flutter pub get
flutter run -d windows # 或 -d macos
```
详见 [GC-UI/README.md](GC-UI/README.md)(含完整接口表、构建脚本与测试说明)。
## 快速开始
```bash
# 依赖:.NET 8 SDK(macOS 另需 Xcode Command Line Tools,用于 .icns / ditto)
dotnet --version # 8.0.x
./build.sh build # 三平台完整发布 -> dist/
./build.sh run # 开发态直接运行(读仓库 model/,跳过在线替换)
./build.sh check # 编译 + 自检 + 离屏渲染 + 产物检查
```
Windows 用 `.\build.ps1`,参数相同(`build / check / models / stamp / run / test / update-test / pack-models / clean / doctor`)。
`build.sh test` 的离屏渲染需要图形栈:Linux CI 上用 `xvfb-run ./build.sh test`。
## 运行目录(发布包里就长这样)
```
<解压出来的目录>/ ← 压缩包里只有这一个文件夹
GCL-<版本>-<平台>.exe 启动器(单文件:服务层 + 本地后端 + .NET 运行时都在里面)
GC-UI.exe Flutter 前端
flutter_windows.dll Flutter 引擎(引擎自带,不在 .NET 单文件里)
data/app.so, data/flutter_assets/ Flutter 资源与 AOT 快照
.GC/bin/GC-SAVEDOG[.exe] 非本体文件:更新守护进程
```
就这些,没有一屏 dll。安装目录根只放 GC 本体,非本体文件(守护进程)一律收在 `.GC/bin`。
macOS 是同一个单文件启动器,只是被放进 `GCL-<版本>-mac-arm64.app/Contents/MacOS/`,
Flutter 前端作为 `GC-UI.app` 放在同一层;`.GC` 位置不变,仍在启动器同级
(`.app/Contents/MacOS/`),守护进程同样收在 `.app/Contents/MacOS/.GC/bin/`。
首次启动后 `.GC` 补齐成:
```
.GC/
bin/ 非本体文件(随包分发,更新时按文件替换)
config/settings.json 用户设置(与缓存分开:删 cache 不会丢配置)
model/ 启动时下载的模型
cache/ 下载暂存 / 原子替换
update/ 待应用的启动器更新(apply-request.json + package.zip)
safedog/GC-SAVEDOG[.exe] 守护进程的运行副本(首次启动从 .GC/bin 复制)
logs/gc-YYYYMMDD.log 日志(中文)
logs/gc-YYYYMMDD.en.log 日志(English)
```
`.GC` 紧挨着主程序,装在哪都便携 —— 整个目录复制走,模型、设置、日志跟着走。
守护进程「`.GC/bin` 放源、`.GC/safedog` 放运行副本」是因为更新要整目录替换:
正在运行的 exe 在 Windows 上换不掉,所以跑副本、换源文件,下次启动再同步。
**发布包不含任何模型**。首次启动联网检查后把模型下载到 `.GC/model/` 并立刻显示;
安装目录不可写时自动退回用户数据目录。`.GC/cache` 与 `.GC/model` 随时可删,程序会重新下载;
`.GC/config/settings.json` 删掉等于恢复出厂设置。
## 自动更新
| 检查项 | 不是最新版时 | 生效时机 |
| --- | --- | --- |
| 模型 | 按文件清单下载到 `cache/`,校验哈希后原子替换 `.GC/model/<id>` | **下载后立即应用**(本次启动首页就刷新) |
| 启动器 | 下载对应平台 zip 到 `.GC/update/`,交给 `GC-SAVEDOG` | **下次启动时应用**(重启后自动替换) |
启动器更新的完整流程:
```
启动器下载 zip -> 校验 sha256 -> 写 apply-request.json -> 启动 .GC/safedog/GC-SAVEDOG -> 自己退出
GC-SAVEDOG: 二次验签 -> 检查 zip 安全性 -> 解压到 .GC/update/stage
-> 整目录替换:旧文件搬到 .GC/update/backup,新文件就位
(.GC 只合并 bin/,config/model/cache/update/logs/safedog 原地不动)
-> 启动新版,等 .GC/update/health.json
-> 收到:删备份、写 last-good.json
-> 没收到/进程退出:撤掉新文件、把备份搬回、重启旧版,写 state.json = rolledback
```
发布包是**整目录**(启动器 + 后端运行时 + Flutter 前端资源),所以更新必须整目录替换:
只替换一个 exe 会留下旧后端 / 旧界面,新前端调不通接口。替换只动程序文件,
`.GC`(模型库、设置、日志、更新目录)和正在运行的 `GC-SAVEDOG.exe` 一律跳过。
也就是说:**新版本起不来,用户不会被卡死**。找不到 `GC-SAVEDOG` 的旧安装会退回脚本流程(过渡用)。
- 默认更新仓库写在 `.GC/config/settings.json` 的 `updateRepository`:
`https://git.xhmcl.com/Morris/GC`(也可换成自己的仓库或 `.../src/branch/main/model` 地址)
- 断网、仓库没推 `version.json`、下载失败:**一律保留本地模型,绝不清空模型库**,底部状态条说明原因
- 首次启动断网且本地无模型:状态条会明确提示「去下载页重试 / 手动放入 `.GC/model/`」,不会白屏干等
- 离线教室:把仓库(含 `version.json` + `model/`)拷到 U 盘,在 `settings.json` 填
`updateLocalRoot` 指向它,即可完全离线更新(同样会验签)
## 安全模型
威胁模型很直接:**模型 dll 会被 `AssemblyLoadContext` 直接执行**,启动器更新包会替换可执行文件。
只要仓库被入侵,攻击者就能让所有客户端跑他的代码。因此信任链是:
```
内置公钥(源码)
└─ 验证 version.json 的 ECDSA P-256 签名
├─ 得到启动器包 sha256 → 校验下载到的 zip
│ └─ GC-SAVEDOG 再次验签 + 复算 sha256 + 检查 zip 结构 → 原子替换
└─ 得到每个模型的 manifestSha256 / filesSha256
└─ 下载后复算,比对通过才安装
└─ 加载 dll 前抽查 dll / json 哈希(.integrity.json)
```
要点:
| 机制 | 防的是什么 | 代码位置 |
| --- | --- | --- |
| 清单签名(ECDSA P-256 / SHA-256) | 仓库被改、清单被替换 | `GC/src/Security/ManifestSignature.cs` |
| 规范化 JSON(键排序、去 signature) | 「同内容不同字节」导致签名不可复现 | `GC/src/Security/CanonicalJson.cs` |
| 包 sha256(取自已签名清单) | 下载被替换 / 传输损坏 | `GC/src/Security/ContentHash.cs` |
| 模型 manifestSha256 / filesSha256 | 下载后、安装前被掉包 | `GC/src/Security/ModelIntegrity.cs` |
| 加载前抽查 dll 哈希 | 本地模型文件被替换 | `GC/src/Services/ModelHost.cs` |
| `SafeArchive`(条目数/体积/压缩比/符号链接/穿越) | zip 炸弹、zip slip、链接攻击 | `GC/src/Security/SafeArchive.cs` |
| `GC-SAVEDOG` 独立进程 | 覆盖失败、断电、新版本起不来 | `GC-SAVEDOG/Applier.cs` |
| 健康标记 + 回滚 | 新版启动即崩 | `GC/src/Security/StartupHealth.cs` |
默认策略:**清单没签名或签名不符一律拒绝更新**。
自建私有构建可临时放开:`settings.json` 里 `requireSignedManifest: false`,
或环境变量 `GC_ALLOW_UNSIGNED_MANIFEST=1`(只建议调试用)。
### 签名密钥
- 私钥:`.signing/gc-signing.pem`(**已在 `.gitignore`,永不入库**;请自行备份)
- 公钥:硬编码在 `GC/src/Security/SignatureKeyring.cs`
- 当前生效:`gc-2026-12`,指纹 `ee6083be47a87907`
- 已停用:`gc-2026-11`,指纹 `b41b1dd6259ea9ed`(私钥遗失,仅保留占位)
- 生成新密钥:`dotnet run --project GC-SAVEDOG -- keygen --key-id gc-YYYY-MM`
- 轮换:把新公钥追加进 `SignatureKeyring.Keys`(保留旧公钥一个版本周期),
同时把 `GC_SIGNING_KEY_ID`(默认值在 `buildsh/lib/build_funcs.sh`)改成新 keyId,
再重新签名清单
- 部署前核对两边公钥一致:
`dotnet run --project GC-SAVEDOG -- verify --manifest version.json`
`build.sh` 在刷新清单后自动调用 `sign_manifest` 签名并同步 `model/version.json`;
`.signing/gc-signing.pem` 不存在时只告警,清单不带签名(客户端会拒绝更新)。
> 换钥匙的代价:老客户端只认识编译进去的那份公钥,所以**用新密钥签出的清单
> 在旧版本上会判成「签名无效」**。密钥一旦丢失,只能靠发一个新版本把新公钥带出去,
> 中间这段时间老客户端无法自动更新 —— 私钥务必备份两处以上。
### zip 解压加固
更新包和模型源 zip 一律当成不可信输入:拒绝 `../`、绝对路径、盘符、UNC、符号链接;
条目数 ≤ 20000、解压后 ≤ 2 GiB、压缩比异常(>200:1 且体积较大)直接判为 zip 炸弹。
## 版本与指纹
- **启动器版本**:`Directory.Build.props` 的 `<Version>`;`./build.sh build -version=1.0.8` 可覆盖,
只影响启动器(程序集版本、关于页、`version.json` 的 `launcher.version`)。
- **模型版本**:模型清单里**作者手写**的 `version`(如 `1.6`),`./build.sh stamp` 不会改它。
客户端按字符串比较是否变化,所以改模型内容后必须手动升版本号,否则用户不会更新。
- **`build` 字段**:模型内容的构建指纹,只用于溯源;`updatedAt` / `build` 都不参与指纹计算,
保证「同一份内容重复构建得到同一个值」。
- **内容哈希算法**(构建端与客户端必须一致):
```
fileHash = SHA256(文件字节)
dirHash = SHA256( 按相对路径 ordinal 升序,对每个文件拼接 "<相对路径>\0<fileHash>\n" )
```
相对路径统一 `/` 分隔,跳过 `.` 开头的文件、`bin/`、`obj/`、`*.user`;
不含时间戳、权限位、文件顺序。实现见 `GC/src/Security/ContentHash.cs`,构建端由
`VersionStamp` 直接链接同一份源码,不会出现两套算法。
## 目录结构
```
Repository/
├── GC.sln
├── Directory.Build.props # 公共构建属性(版本号在这里)
├── version.json # ★ 自动生成并签名的版本清单(推送到仓库后才生效)
├── build.sh / build.ps1 # 构建脚本(实际实现在 buildsh/ 与 buildps1/)
├── GC/ # 启动器
│ └── src/
│ ├── GC.Core.csproj
│ ├── Security/ # ★ 验签、哈希、安全解压、完整性、健康标记
│ ├── Models/ Services/
│ ├── ViewModels/ Views/
│ ├── Assets/i18n/ # 界面语言包
│ └── test/dotnet/GC.Tests/ # 离屏校验 + --update-test 离线更新链路验证
├── GC-BOOT/ # 轻量启动入口
├── GC-DOWNLOAD/ # 源仓库 / 模型 / 启动器下载更新
├── GC-DRAW/PlayerWindow.cs # 模型窗口宿主;绘制由模型提供
├── GC-SAVEDOG/ # ★ 更新守护进程(apply / verify / keygen / sign / status)
├── model/ # ★ 模型的一切
│ ├── version.json # 与根 version.json 完全相同(同一份签名)
│ ├── _sdk/GC.ModelSdk/
│ ├── _engine/{src,PreviewGen,VersionStamp}/
│ ├── earth-rotation/{earth-rotation.json,src/,earth-rotation.model/}
│ └── earth-revolution/
├── dist/ # 发布产物(.gitignore,只通过 Release 分发)
└── .signing/ # 签名私钥(.gitignore,绝不入库)
```
模型库位置:`EMS_MODELS` 覆盖 → 开发态仓库根 `model/` → **发布态 `<可执行文件>/.GC/model/`**。
`dist/` 不进仓库:二进制放 Git 会让 clone 变慢,也会让「仓库被改」的爆炸半径变大。
发布有两种方式,`version.json` 里两条路都写清楚了:
| 方式 | 清单字段 | 说明 |
| --- | --- | --- |
| Release 附件(推荐) | `url` | `.../releases/download/<版本>/GCL-<版本>-<系统>-<架构>.zip` |
| 仓库编译产物 | `path` / `dir` / `name` | `dist/<系统>-<架构>/GCL-<版本>-<系统>-<架构>.zip` |
下载端按 `url` → `path` → `dist/<系统>-<架构>/` 目录扫描的顺序尝试,
**每个候选都必须与清单里的 `sha256` 一致**(`sha256` 由签名保护),
所以「多发一个地方」不会放宽校验,只是让「只提交产物、不发 Release」也能更新。
清单缺 `sha256` 的平台会被直接跳过,不再退化成「只校验非空」。
## 构建与运行
```bash
./build.sh build # 三平台完整发布:启动器 + SAVEDOG + 运行骨架 + 更新包 ZIP
./build.sh check # 编译、自检、离屏渲染及发布 ZIP 完整性检查
./build.sh models # 编译模型 dll、生成封面、更新并签名版本清单
./build.sh stamp # 只重新生成 + 签名 version.json
./build.sh run # Debug 运行启动器
./build.sh test # 离屏校验,截图写入 build/screenshots/
./build.sh update-test # 离线验证自动更新链路(验签 / 立即生效 / 篡改拒绝 / 断网兜底)
./build.sh pack-models # 编译模型并打包 dist/models-<版本>.zip
./build.sh pack-launcher # 把已有平台发布目录打成启动器更新 ZIP
./build.sh doctor # dotnet 环境信息
./build.sh dist # 列出 dist/ 产物
./build.sh clean # 清理 build/ 与 dist/
```
| 产物 | 平台 |
| --- | --- |
| `dist/mac-arm64/GCL-<版本>-mac-arm64.zip` | macOS Apple Silicon(单顶层 `GCL-….app`) |
| `dist/win-amd64/GCL-<版本>-win-amd64.zip` | Windows x64(单顶层 `GCL-…/`,含 Flutter 前端,非本体文件在 `.GC/bin/`) |
| `dist/win-arm64/GCL-<版本>-win-arm64.zip` | Windows on ARM 同上 |
| `dist/linux-arm64/GCL-<版本>-linux-arm64.zip` | Linux ARM64 同上(启动器无扩展名;默认不构建,需 aarch64 主机 + `GC_BUILD_LINUX=1`) |
平台目录就是「该平台的编译产物目录」:打包完成后只留最终 zip(原始 `.app` / `.exe`
会被挪到 `build/trash/`,下次构建时移出,不做递归删除)。
发新版:`./build.sh build` → 把 `dist/<平台>/GCL-<版本>-<平台>.zip`
上传到 Gitea Release(tag `v1.0.8`),**或者**直接提交/上传到仓库的
`dist/<平台>/` 目录 → 提交并推送 `version.json` / `model/version.json`。
两种都能被客户端识别,客户端下次启动就会看到更新。
## 模型契约
```csharp
public interface IModelFactory // 模型入口
{
int ApiVersion { get; } // 目前为 1
IModelRuntime Create();
}
public interface IModelRuntime : IDisposable
{
void Prepare(IModelContext context); // 后台线程:读数据、烘焙纹理、汇报进度
Control CreateView(IModelContext context); // UI 线程:模型自己做界面
}
public interface IModelContext
{
string ModelId { get; }
string ModelDirectory { get; }
string DataDirectory { get; }
string Language { get; }
int MemoryBudgetMb { get; }
void RequestClose();
void ReportProgress(double value, string? message = null);
void Log(string message);
}
```
**线程约定**
| 成员 | 允许的线程 | 说明 |
| --- | --- | --- |
| `Prepare` | 后台线程(调用一次) | 可耗时;用 `ReportProgress` 汇报真实进度;此时**不要**创建控件 |
| `CreateView` | UI 线程(`Prepare` 之后调用一次) | 只在这里创建/操作 Avalonia 控件 |
| `ReportProgress` / `Log` | 任意线程 | 线程安全,内部自行封送到 UI |
| `RequestClose` | 任意线程 | 线程安全,等价于点窗口关闭按钮 |
| `Dispose` | UI 线程 | 释放后不要再调用 `Log` / `ReportProgress` |
**契约版本协商**
- `IModelFactory.ApiVersion` 与启动器支持的版本(当前 `1`)必须相等,否则拒绝加载并提示更新启动器。
- 模型清单可写 `minAppVersion`(如 `"1.0.8"`):启动器版本更低时直接拒绝,并给出明确提示。
- 提升契约版本时必须保留旧接口的适配层,或在启动器里明确「最低启动器版本」,避免老客户端加载新模型后崩溃。
**卸载注意**:关窗即 `Unload()` 收集式 AssemblyLoadContext。只要有静态字段、未解绑的事件、
或缓存里还拿着模型内的类型/控件,程序集就回收不掉(内存持续增长)。
模型作者应避免静态持有 `Control` / `IModelContext`,并在 `Dispose` 里解绑事件。
详细清单字段、数据格式、封面生成见 [`model/README.md`](model/README.md)。
## 模型窗口
- 启动模型 → **带进度条的加载窗**(读取数据 → 生成地表纹理 → 构建界面,真实进度)→ 新开独立窗口
- 主界面保持原页面,可同时开多个模型窗口;关窗即卸载模型程序集
- 所有由启动器打开的窗口(模型窗、加载窗、确认框、更新窗)都是 16px 圆角
## 地球模型(model/_engine + model/<id>/src)
- **地表**:加载时烘焙 1024×512 等经纬度纹理 —— 海洋深度、沙漠/雨林/针叶林/苔原分带、极地冰盖、
山脉起伏(高度梯度参与光照)、云层、夜间城市辉光;每帧只做双线性采样 + 地形光照,60 FPS
- **教材数值**:黄赤交角 / 回归线统一为 **23.5°**,极圈 66.5°;夏至直射 **23.5°N**、冬至 **23.5°S**、
春分秋分 **0°(赤道)**。球面上画出赤道、南北回归线、南北极圈与真实日下点黄圈,读数不受「夸张倾角」影响
- **自转**:球面像素渲染、晨昏线、大气边缘光、经纬网、地轴、太阳直射点;只有自转视角,
**没有节气定位**(节气属于公转)
- **公转**:太阳—轨道—地球全景、地轴方向空间固定、二分二至标记与一键定格、HUD(角度 / 直射纬度 / 日期)
- **触控一体机**:双指捏合缩放(跟手)、滚轮缩放、画布左下角大号 + / − / 复位按钮;
所有工具栏按钮 ≥ 40px。单指或鼠标拖动可直接转动地球,**拖动时画面定格但视角俯仰与轨道平面始终不变**
- **课堂演示**:点二分二至自动暂停定格并显示节气、教材日期、直射纬度与现象说明;
右侧课堂卡含可放大观察到的「地球特写」;`◀ ▶` 步进 5°、教学要点点击自动定格定位;
快捷键 `空格` 播放/暂停、`← →` 步进、`1–4` 二分二至、`F` 全屏、`+ -` 缩放、`0` 复位视角
## 启动时运行内存分配
设置页的「启动时运行内存分配」类似启动器的 `-Xmx`:启动器把这份预算通过 `IModelContext.MemoryBudgetMb`
交给模型,具体怎么用(掩膜分辨率、缓存)由模型自己决定。