lead 192f2a63e9
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
1.1.0:界面重做与 DPI 修复的正式版本号
Directory.Build.props 的 Version 从 1.0.11 提到 1.1.0,启动器程序集版本 / 关于页 / version.json 的 launcher.version 都跟着走。
2026-11-18 22:33:24 +08:00
2026-11-14 18:54:50 +08:00
y
2026-11-08 17:29:32 +08:00

GC

天文教学模型启动器:管理/启动模型、启动时自动检查并下载最新版模型与启动器、设置语言与内存。

分层约定(重要)

  • GC/ = 启动器:扫描、下载、开窗口、显示加载进度。不渲染、不含任何模型内容、发布包不内置模型。
  • model/ = 模型的一切:源码、编译后的 dll、场景数据、封面、语言包、共享引擎、契约,独立分发、独立版本。
  • 模型相关代码全部直接存在模型目录里,仓库根没有 model-src/ / model-sdk/ 这类旁路目录。
  • 想加新内容 = 在 model/<id>/ 里放模型并推送仓库,启动器一行都不用改,客户端启动自动更新。
  • GC-SAVEDOG/ = 更新守护进程:验签、原子替换、启动后健康检查、失败回滚。

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。 「关于」页会直接展示 源码语言:C#、前端:Flutter(由后端 /api/about 下发)。

# 后端
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(含完整接口表、构建脚本与测试说明)。

快速开始

# 依赖:.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 的平台会被直接跳过,不再退化成「只校验非空」。

构建与运行

./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。 两种都能被客户端识别,客户端下次启动就会看到更新。

模型契约

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。

模型窗口

  • 启动模型 → 带进度条的加载窗(读取数据 → 生成地表纹理 → 构建界面,真实进度)→ 新开独立窗口
  • 主界面保持原页面,可同时开多个模型窗口;关窗即卸载模型程序集
  • 所有由启动器打开的窗口(模型窗、加载窗、确认框、更新窗)都是 16px 圆角

地球模型(model/_engine + model//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 交给模型,具体怎么用(掩膜分辨率、缓存)由模型自己决定。

S
Description
天文教学模型启动器:管理/启动模型、启动时自动检查并下载最新版模型与启动器、设置语言与内存。
Readme
414 MiB
1 Stars 1 Watchers 1 Forks
1.1.2发布
Latest
2026-11-21 20:55:57 +08:00
Generate repository badges
Languages
C# 43.2%
Dart 31.2%
Shell 5.7%
JavaScript 5.5%
CSS 2.9%
Other 11.3%