添加GC-SAVEDOG项目,降低隐患

This commit is contained in:
2509_92447106 committed 2026-11-14 19:42:02 +08:00
1 parent 791db4fe12
commit 2f3a8682c9
54 files changed
+3642 -320

No files matched your search

+182 -80
View File
@@ -3,121 +3,214 @@
天文教学模型**启动器**:管理/启动模型、启动时自动检查并下载最新版模型与启动器、设置语言与内存。
> **分层约定(重要)**
> - `src/` = 启动器:扫描、下载、开窗口、显示加载进度、自检更新。**不渲染、不含任何模型内容、发布包不内置模型**。
> - `GC/` = 启动器:扫描、下载、开窗口、显示加载进度。**不渲染、不含任何模型内容、发布包不内置模型**。
> - `model/` = 模型的一切:**源码、编译后的 dll、场景数据、封面、语言包、共享引擎、契约**,独立分发、独立版本。
> - 模型相关代码全部直接存在模型目录里,仓库根没有 `model-src/` / `model-sdk/` 这类旁路目录。
> - 想加新内容 = 在 `model/<id>/` 里放模型并推送仓库,`src` 一行都不用改,客户端启动自动更新。
> - 想加新内容 = 在 `model/<id>/` 里放模型并推送仓库,启动器一行都不用改,客户端启动自动更新。
> - `GC-SAVEDOG/` = 更新守护进程:验签、原子替换、启动后健康检查、失败回滚。
- UI:C# + .NET 8(可切 .NET 10)+ Avalonia,跨平台
- 模型加载:`AssemblyLoadContext` 加载模型自带 dll,契约与 Avalonia 走默认上下文,关窗即卸载
- 目标平台:**macOS arm64 / Windows x64 / Windows arm64**,一条命令全部编译
- 目标平台:**macOS arm64 / Windows x64 / Windows arm64**(Linux 可自行编译,未列入发布矩阵)
- 更新仓库:<https://gitcode.com/Morris_1/GC>,模型目录 <https://gitcode.com/Morris_1/GC/tree/main/model>
## 快速开始
```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`。
## 运行目录(发布包里就长这样)
Windows 用 `.\build.ps1`(参数相同);PowerShell 实现位于 `buildps1/`,不依赖 Git Bash 或 WSL。
```
<安装目录>/
GC.exe | GC.app/
GC-SAVEDOG[.exe] 更新守护进程(与主程序同目录,macOS 在 .app/Contents/MacOS 内)
.GC/
settings.json 设置 + 已安装版本记录
model/ 启动时下载的模型
cache/ 下载暂存 / 原子替换
update/ 待下次启动应用的启动器更新
config/settings.json 用户设置(与缓存分开:删 cache 不会丢配置)
model/ 启动时下载的模型
cache/ 下载暂存 / 原子替换
update/ 待应用的启动器更新(apply-request.json + package.zip)
```
**发布包不含任何模型**。首次启动联网检查后把模型下载到 `.GC/model/` 并立刻显示;
安装目录不可写时自动退回用户数据目录。`.GC/` 可以随程序一起搬迁,也可以整个删掉重新下载。
安装目录不可写时自动退回用户数据目录。`.GC/cache` 与 `.GC/model` 随时可删,程序会重新下载;
`.GC/config/settings.json` 删掉等于恢复出厂设置。
## 自动更新
| 检查项 | 不是最新版时 | 生效时机 |
| --- | --- | --- |
| 模型 | 从 gitcode 下载到 `cache/`,校验后原子替换 `.GC/model/<id>` | **下载后立即应用**(本次启动首页就刷新) |
| 启动器 | 下载对应平台 zip 到 `.GC/update/payload`,写 `pending.json` | **下次启动时应用**(独立脚本覆盖程序并重启) |
| 模型 | 按文件清单下载到 `cache/`,校验哈希后原子替换 `.GC/model/<id>` | **下载后立即应用**(本次启动首页就刷新) |
| 启动器 | 下载对应平台 zip 到 `.GC/update/`,交给 `GC-SAVEDOG` | **下次启动时应用**(重启后自动替换) |
- 默认更新仓库写在 `.GC/settings.json` 的 `updateRepository`:
启动器更新的完整流程:
```
启动器下载 zip -> 校验 sha256 -> 写 apply-request.json -> 启动 GC-SAVEDOG -> 自己退出
GC-SAVEDOG: 二次验签 -> 检查 zip 安全性 -> 解压到 .GC/update/stage
-> 移入安装目录(绝不覆盖已有版本)
-> 启动新版,等 .GC/update/health.json
-> 收到:删同平台旧版本,写 last-good.json
-> 没收到/进程退出:删新版、重启旧版,写 state.json = rolledback
```
也就是说:**新版本起不来,用户不会被卡死**。找不到 `GC-SAVEDOG` 的旧安装会退回脚本流程(过渡用)。
- 默认更新仓库写在 `.GC/config/settings.json` 的 `updateRepository`:
`https://gitcode.com/Morris_1/GC`(也可换成自己的仓库或 `.../tree/main/model` 地址)
- 版本来自仓库根 `version.json`(由 `./build.sh stamp` 生成):模型版本 = **模型包内容指纹**,
所以**改了模型文件,版本号自动变**;启动器版本 = 构建版本。
- `settings.json` 记录 `installedModelVersions` / `pendingLauncherVersion` / `lastUpdateCheck`。
- 断网、仓库还没推 `version.json`、下载失败:**一律保留本地模型,绝不把模型库清空**,底部状态条说明原因。
- 设置页可关闭自动更新;状态条可手动「检查更新」(忽略开关强制检查)。
- 断网、仓库没推 `version.json`、下载失败:**一律保留本地模型,绝不清空模型库**,底部状态条说明原因
- 首次启动断网且本地无模型:状态条会明确提示「去下载页重试 / 手动放入 `.GC/model/`」,不会白屏干等
- 离线教室:把仓库(含 `version.json` + `model/`)拷到 U 盘,在 `settings.json` 填
`updateLocalRoot` 指向它,即可完全离线更新。
- 发新版:运行 `./build.sh build`,把生成的 `dist/GC-<版本>-*.zip` 上传到 Release / 仓库 `dist/`,
把直链填进 `version.json` 对应平台的 `url`(构建会生成 zip 并自动写入 `sha256` / `size`)。
更新包只含程序文件,**不会覆盖 `.GC/` 里的模型与设置**。
`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`,指纹 `b41b1dd6259ea9ed`
- 生成新密钥:`dotnet run --project GC-SAVEDOG -- keygen`
- 轮换:把新公钥追加进 `SignatureKeyring.Keys`(保留旧公钥一个版本周期),再重新签名清单
- 部署前核对两边公钥一致:
`dotnet run --project GC-SAVEDOG -- verify --manifest version.json`
### 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/ # POSIX shell 构建实现
├── buildps1/ # 原生 PowerShell 构建实现
├── GC/ # 启动器主要代码
├── Directory.Build.props # 公共构建属性(版本号在这里)
├── version.json # ★ 自动生成并签名的版本清单(推送到仓库后才生效)
├── build.sh / build.ps1 # 构建脚本(实际实现在 buildsh/ 与 buildps1/)
├── GC/ # 启动器
│ └── src/
│ ├── GC.Core.csproj
│ ├── Models/ Services/ # 清单/设置/目录探测/i18n/模型库/下载/自动更新
│ ├── ViewModels/ Views/ # 主页、下载、设置和启动更新状态
│ ├── Assets/i18n/ # 启动器界面语言包
│ ├── Security/ # ★ 验签、哈希、安全解压、完整性、健康标记
│ ├── Models/ Services/
│ ├── ViewModels/ Views/
│ ├── Assets/i18n/ # 界面语言包
│ └── test/dotnet/GC.Tests/ # 离屏校验 + --update-test 离线更新链路验证
├── GC-BOOT/ # 轻量启动入口
│ ├── GC-BOOT.csproj
│ ├── Program.cs
│ └── app.manifest
├── GC-DOWNLOAD/ # 模型、源仓库与启动器下载更新实现
│ └── GC-DOWNLOAD.csproj
├── GC-DRAW/PlayerWindow.cs # 通用模型窗口宿主;实际绘制由模型提供
├── GC-DOWNLOAD/ # 源仓库 / 模型 / 启动器下载更新
├── GC-DRAW/PlayerWindow.cs # 模型窗口宿主;绘制由模型提供
├── GC-SAVEDOG/ # ★ 更新守护进程(apply / verify / keygen / sign / status)
├── model/ # ★ 模型的一切
│ ├── version.json # 与根 version.json 相同(便于按 model/ 地址读取)
│ ├── version.json # 与根 version.json 完全相同(同一份签名)
│ ├── _sdk/GC.ModelSdk/
│ ├── _engine/
│ │ ├── src/ # 模型专用引擎与渲染,留在 model 内
│ │ ├── PreviewGen/ # 用模型渲染器生成封面
│ │ └── VersionStamp/ # 按内容指纹自动打版本、生成 version.json
│ ├── earth-rotation/
│ │ ├── earth-rotation.json
│ │ ├── src/ # 本模型源码
│ │ └── earth-rotation.model/ # dll + scene.json/land.json + preview.png + i18n
│ ├── _engine/{src,PreviewGen,VersionStamp}/
│ ├── earth-rotation/{earth-rotation.json,src/,earth-rotation.model/}
│ └── earth-revolution/
└── dist/ # 发布产物(只有启动器 + .GC 骨架)
├── dist/ # 发布产物(.gitignore,只通过 Release 分发)
└── .signing/ # 签名私钥(.gitignore,绝不入库)
```
模型库位置:`EMS_MODELS` 覆盖 → 开发态仓库根 `model/` → **发布态 `<可执行文件>/.GC/model/`**。
`dist/` 不进仓库:二进制放 Git 会让 clone 变慢,也会让「仓库被改」的爆炸半径变大。
发布有两种方式,`version.json` 里两条路都写清楚了:
| 方式 | 清单字段 | 说明 |
| --- | --- | --- |
| Release 附件(推荐) | `url` | `.../releases/download/v<版本>/GC-<版本>-<系统>-<架构>.zip` |
| 仓库编译产物 | `path` / `dir` / `name` | `dist/<系统>-<架构>/GC-<版本>-<系统>-<架构>.zip` |
下载端按 `url` → `path` → `dist/<系统>-<架构>/` 目录扫描的顺序尝试,
**每个候选都必须与清单里的 `sha256` 一致**(`sha256` 由签名保护),
所以「多发一个地方」不会放宽校验,只是让「只提交产物、不发 Release」也能更新。
清单缺 `sha256` 的平台会被直接跳过,不再退化成「只校验非空」。
## 构建与运行
```bash
./build.sh build # 完整三平台发布:编译启动器、准备运行目录并生成更新包 ZIP
./build.sh check # 编译、自检、离屏渲染及发布 ZIP 完整性检查;通常在 build 后运行
./build.sh models # 编译模型 dll、生成封面并更新版本清单
./build.sh stamp # 只重新生成根目录与 model/ 下的 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/ 等构建产物
./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/
```
`build` 是完整发布入口,不是单纯的解决方案编译;`check` 会检查至少三个版本化发布 ZIP。
需要指定版本时,可追加 `-version=<版本>`(或 `--version=<版本>`),脚本会同步更新 `Directory.Build.props`。
Windows 用 `.\build.ps1`(参数相同)。
| 产物 | 平台 |
| --- | --- |
| `dist/GC-<版本>-mac-arm64.zip` | macOS Apple Silicon 应用包 |
| `dist/GC-<版本>-win-amd64.zip` | Windows x64 单文件启动器 |
| `dist/GC-<版本>-win-arm64.zip` | Windows on ARM 单文件启动器 |
| `dist/mac-arm64/GC-<版本>-mac-arm64.zip` | macOS Apple Silicon 应用包(含 GC-SAVEDOG) |
| `dist/win-amd64/GC-<版本>-win-amd64.zip` | Windows x64 单文件启动器 + `GC-SAVEDOG.exe` |
| `dist/win-arm64/GC-<版本>-win-arm64.zip` | Windows on ARM 同上 |
Windows 产物是自包含单文件启动器;macOS 产物是 `.app` 的 ZIP。**发布包内不含模型**。
改完模型后运行 `./build.sh models`,再把根目录 `version.json` 和 `model/` 推送到 gitcode,客户端下次启动时自动更新。
平台目录就是「该平台的编译产物目录」:打包完成后只留最终 zip(原始 `.app` / `.exe`
会被挪到 `build/trash/`,下次构建时移出,不做递归删除)。
发新版:`./build.sh build -version=1.0.8` → 把 `dist/<平台>/GC-1.0.8-<平台>.zip`
上传到 gitcode Release(tag `v1.0.8`),**或者**直接提交/上传到仓库的
`dist/<平台>/` 目录 → 提交并推送 `version.json` / `model/version.json`。
两种都能被客户端识别,客户端下次启动就会看到更新。
## 模型契约
@@ -147,8 +240,25 @@ public interface IModelContext
}
```
启动器先弹进度窗,在后台调用 `Prepare`(模型用 `ReportProgress` 汇报真实进度),
再在 UI 线程调用 `CreateView`,把返回的控件直接铺满窗口 —— 除此之外什么都不做。
**线程约定**
| 成员 | 允许的线程 | 说明 |
| --- | --- | --- |
| `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)。
@@ -156,7 +266,7 @@ public interface IModelContext
- 启动模型 → **带进度条的加载窗**(读取数据 → 生成地表纹理 → 构建界面,真实进度)→ 新开独立窗口
- 主界面保持原页面,可同时开多个模型窗口;关窗即卸载模型程序集
- 启动器快捷键 `Esc` 关闭、`F11` 全屏;模型窗口内的快捷键由模型自己定义
- 所有由启动器打开的窗口(模型窗、加载窗、确认框、更新窗)都是 16px 圆角
## 地球模型(model/_engine + model/<id>/src)
@@ -168,20 +278,12 @@ public interface IModelContext
**没有节气定位**(节气属于公转)
- **公转**:太阳—轨道—地球全景、地轴方向空间固定、二分二至标记与一键定格、HUD(角度 / 直射纬度 / 日期)
- **触控一体机**:双指捏合缩放(跟手)、滚轮缩放、画布左下角大号 + / − / 复位按钮;
所有工具栏按钮 ≥ 40px。单指或鼠标拖动可直接转动地球,**拖动时画面定格但视角俯仰与轨道平面始终不变**,
俯视角只由「俯视」按钮显式切换
所有工具栏按钮 ≥ 40px。单指或鼠标拖动可直接转动地球,**拖动时画面定格但视角俯仰与轨道平面始终不变**
- **课堂演示**:点二分二至自动暂停定格并显示节气、教材日期、直射纬度与现象说明;
右侧课堂卡含可放大观察到的「地球特写」;`◀ ▶` 步进 5°、教学要点点击自动定格定位;
快捷键 `空格` 播放/暂停、`← →` 步进、`1–4` 二分二至、`F` 全屏、`+ -` 缩放、`0` 复位视角
- 节气日期、直射纬度、现象说明、教学要点全部写在 `scene.json` 里;夸张倾角只改示意图形,不改教学读数
## 模型源(手动导入)
除了启动时自动更新,「下载」页还支持手动导入普通 git 仓库:
**仓库根目录下的 `model/` 文件夹即模型列表**。支持 GitHub / GitLab / Gitee(zip 归档,
失败回退 `git clone --depth 1`)、zip 直链、本地目录。导入后缓存在 `数据目录/cache/sources/<id>`。
## 启动时运行内存分配
设置页的「启动时运行内存分配」类似启动器的 -Xmx:启动器把这份预算通过 `IModelContext.MemoryBudgetMb`
设置页的「启动时运行内存分配」类似启动器的 `-Xmx`:启动器把这份预算通过 `IModelContext.MemoryBudgetMb`
交给模型,具体怎么用(掩膜分辨率、缓存)由模型自己决定。