CI/CD 与发布

约 1256 字大约 4 分钟

2026-10-19 20:00:00

流水线、产物、版本号规则、发布流程与回滚方案

网页端工作流

工作流	触发	职责
`deploy.yml`	push `main`、手动	构建一次 → GitHub Pages + FTP + OpenList WebDAV 三路发布
`check-updates.yml`	每周五、手动	运行 `check-updates.mjs` 与 `resolve-direct-links.mjs`，可确定的自动写回并触发部署，不可确定的汇总为体检 Issue
`create-review-issue.yml`	push（`submissions/` 有变化）	把提交草稿转为带标签的 Issue；反馈类草稿在建完 Issue 后删除
`review-submission.yml`	Issue 打标签	合并草稿到 `软件数据/apps/` 或 `回声洞/messages/`，或删除草稿；结束主动派发 `deploy.yml`
`update-ignore-command.yml`	Issue 编辑、评论	处理体检 Issue 的复选框与 `/ignore` `/unignore` 命令

关键约束

GITHUB_TOKEN 推送不触发其他工作流（GitHub 防递归规则），因此 review-submission.yml 与 check-updates.yml 写回后必须主动派发 deploy.yml（AGENTS.md:332-335、605-606）。
review-submission.yml 必须用 concurrency: { group: review-submission, queue: max }：不要换成 cancel-in-progress: false（那只保留「1 running + 1 pending」，新 pending 会顶掉旧的，批量评审会静默丢失条目）（AGENTS.md:468-472）。
create-review-issue.yml 必须用事件自带的 before / after SHA 计算 diff 范围：不要回到 git diff HEAD~1 HEAD（checkout 落在那一刻拉到的 tip，两次相近的推送会重复建票或一个都不建），因此 fetch-depth: 0 必需（AGENTS.md:473-476）。
幂等键必须基于草稿文件路径，不能基于 Issue 标题：历史上向日葵远程的第二次提交因标题与已关闭的旧 Issue 相同而被静默跳过，草稿永远留在 submissions/ 而提交者收到「提交成功」（AGENTS.md:312-318）。
deploy.yml 的 concurrency.cancel-in-progress 必须为 false：一次部署要往三个目标发布，中途取消会留下「Pages 是新的、网盘还是旧的」半成品镜像且无任何报错（.github/workflows/deploy.yml:13-22）。
index.html 必须用相对路径引用资源（vite.config.ts 的 base: './'），以适配根目录与子目录两种形态（AGENTS.md:496-501）。
行结尾必须保持原样：check-updates.mjs 逐个重写 JSON 文件以保留原始行结尾（AGENTS.md:607）。

Windows 7 兼容版工作流

.github/workflows/win7-release.yml：

触发	说明
push tag `dv*`	自动构建并创建 Release
`workflow_dispatch`	手动运行，可填版本号、更新说明，勾 `publish` 则一并发 Release

流程

检出源码（fetch-depth: 0，读 tag / 生成变更说明需完整历史）。
安装 .NET 6.0.x。
确定版本号：优先 tag（dv1.0.0 → 1.0.0，兼容历史 win7- 前缀）→ 其次 inputs.version → 最后读 src/Core/ShellConfig.cs 的 ShellVersion。版本号含 insider 则通道为 insider，否则 stable。
dotnet publish 应用本体（WinExe，不带 CshConsoleBuild）。
dotnet publish 启动器。
tools/pack-win7-portable.ps1 组装便携版并打 zip。
Inno Setup 6 编译安装包。
上传构建产物（artifact 留档 30 天）。
生成更新说明（手动未提供时，取上个 dv* tag 至 HEAD 的提交列表）。
创建 GitHub Release（tag 触发或勾选 publish 时）。

产物

形态	文件
便携版	`ClassSoftwareHub-Portable-win7-dv<版本>.zip`
安装版	`ClassSoftwareHub-Setup-win7-dv<版本>.exe`

本地手动发版

$env:GITHUB_TOKEN = "..."     # 需要仓库写权限，不要写进任何文件
node tools\publish-release-win7.mjs `
  --version 1.0.0 --channel stable `
  --installer "dist\installer\ClassSoftwareHub-Setup-win7-dv1.0.0.exe" `
  --portable  "dist\ClassSoftwareHub-Portable-win7-dv1.0.0.zip" `
  --notes "dist\release\notes.md"

加 --dry-run 可先看摘要（只算哈希、写 .md5，不碰 GitHub）（BUILDING.md:85-96）。

版本号规则

网页端

对外版本号 X.Y.Z + 代号后缀（保留，如 - Autumn）：X = 大版本（底层架构 / UI 大改动），Y = 功能更新，Z = 小修小补。
内部版本号 AAAABBCCPRDD（年 / 月 / 日 / 文件版次），例 20260915PR01。
需同步修改：文字设置.ts 的 app.version、home.subtitle、welcome.intro（3 处）；src/gallery/Strings/en-US/Resources.ts 的 app.version；package.json 的 version（裸 2.3.4，无代号 / 内部号）与 package-lock.json 顶部两个 version 字段。
Release tag 命名 vX.Y.Z-<codename>。

Windows 7 兼容版

dv + 主.功能.补丁 + -insider架构.迭代，唯一来源是 ShellConfig.ShellVersion：

位	含义
第一位「架构」	只有整个应用的技术路线发生重大变动才动
第二位「功能」	每叠加一块新功能涨一次
第三位「补丁」	小功能 / 小更新 / 小修复
`insider` 第一位	预览线自己的架构 / 思路基线
`insider` 第二位	这条预览线上的具体更改次数

流程：做出一个能用的版本 → 发 1.0.0-insider1.0 → 用户反馈还有问题 → 继续改成 1.0.0-insider1.1 → 一直改到没问题 → 删掉 -insider 后缀 → 上线正式版 1.0.0。

基数不随便抬

否则旧包会被强制顶掉。

回滚方案

对象	回滚方式
网页端数据	git 提交历史回溯；`git show <父提交>:软件数据/apps/<id>.json` 找回任一历史版本
网页端部署	重新推送历史提交触发 `deploy.yml`；或手动 `workflow_dispatch`
桌面端版本	客户端内置回滚：设置页查看历史版本列表，选择任意版本安装（不校验版本高低）
安装版覆盖安装	启动器 + `app\` 两层结构，安装旧版时替换 `app\` 子目录即可

贡献者

椰汁

更新日志

2026/10/20 06:59

查看所有更新日志

6b8a2-docs: 添加 docs/download.md于 2026/10/20

版权所有

版权归属：ClassSoftwareHub

许可证：GPL-3.0