【约定】整合包更新机制 — 双通道、版本标识与更新器自更新（变迁记录）

[wochenlong]

帖子说明（2026-05-28）

1. 定位：本帖记录 Windows 便携整合包 的 更新机制约定 与 历史变迁，供维护者与高级用户排障；实现细节以仓库内文档为准。
2. 权威文档：docs/portable-packaging-git-update.md、scripts/portable/README.md
3. 与 Issue 关系：用户可见 bug（如「更新完仍旧版」）走 Issue；本帖汇总 设计约定 与 版本演进，重大行为变更在此追加章节并递增 UPDATER_VERSION。
4. 维护：@wochenlong 主维护；改 Update-*.bat / update_from_release.ps1 / bootstrap 逻辑时 必须 递增 scripts/portable/UPDATER_VERSION 并在下文「变迁记录」追加一行。

---

当前约定（UPDATER_VERSION = 2，commit 4a9cfab）

双更新路径

方式	入口	适用
Git 更新	Update-SD-Trainer.bat、update\update_sd_trainer.bat	7z 内含 SD-Trainer/.git；日常增量跟随 origin/main
Release 更新	Update-SD-Trainer-Release.bat、update\update_from_release.bat	无 .git 旧包；Git 全失败；需与 GitHub Release 7z 字节级对齐；同 VERSION 重发 7z 必须用此路径

版本标识（排障三件套）

标识	路径	含义
产品版本	SD-Trainer/VERSION	如 2.7.0
构建指纹	SD-Trainer/PORTABLE_BUILD	第一行 git short SHA；同 tag 重打 7z 时区分构建
更新器逻辑版本	SD-Trainer/scripts/portable/UPDATER_VERSION	改 bat/ps1 行为时递增；与产品 VERSION 独立

更新开始时会打印：本地 VERSION / PORTABLE_BUILD / git、线上 main VERSION、最新 Release tag、本地 vs 线上 UPDATER_VERSION（show_portable_update_status.ps1）。

更新器自更新（Bootstrap）

每次运行 Update-*.bat 时（除非 --no-bootstrap）：

1. 极旧包若无 bootstrap 脚本，bat 用 curl 拉 bootstrap_portable_updaters.ps1（含 ghfast 镜像回退）
2. bootstrap_portable_updaters.ps1 从 GitHub main raw 同步 manifest 内文件，SHA256 比对，有变更则 exit 10
3. bat 自动 call "%~f0" --no-bootstrap" 重跑，再执行 Git / Release 主流程
4. 网络失败：警告 + 回退本地 bundled 脚本，不阻断更新

同步范围见 portable_updater_common.ps1 → Get-PortableUpdaterManifest（根目录 Update-*.bat、update_from_release.ps1、common/show/bootstrap、UPDATER_VERSION、templates 等）。

设计意图：已安装旧 7z 的用户不必等重打整合包，也能拿到最新更新器逻辑（修复 /XO、.git 检查、版本 banner 等）。

用户数据（永不覆盖）

sd-models/  output/  logs/  huggingface/  tagger-models/
SD-Trainer/extensions/     # 含用户已装的 Anima Fast 插件
SD-Trainer/config/autosave/  SD-Trainer/output/  SD-Trainer/logs/  SD-Trainer/.cache/

Release 合并使用 robocopy /IS /IT（禁止 /XO），并写入 config/.portable_release_sync.json 记录 Release 资产 id。

Git 更新要点

• 无 .git → 明确失败，引导 Release 更新；禁止显示「更新完成」
• 浅克隆：git fetch --deepen=50 后再 --ff-only
• fetch / 子模块：直连 → ghfast → ghproxy → gitmirror
• 本地改动：git stash 后再快进
• dataset-tag-editor 子模块失败仅 warning

维护者 Checklist

动作	要求
改更新 bat/ps1 行为	递增 UPDATER_VERSION；同步 build-scripts/templates/ 与 scripts/portable/templates/
同 VERSION 重发 7z	Release 合并路径必须可用；更新 Release 说明中的 PORTABLE_BUILD
新功能仅 push main、未重打 7z	用户用 Git 更新 可得；仅重打 7z 的修复需 Release 更新
打包前	verify_portable_updaters.ps1 -PortableRoot <构建输出> 全 PASS

---

变迁记录

时期	版本 / 构建	更新板块变化
v2.2～v2.4	早期整合包	根目录 run_gui.bat；flash-attn/triton 移除；tkinter 打包；PYTHONNOUSERSITE 等训练隔离
v2.5.0	UI 大改	侧栏/首页/训练监控分离；整合包仍主要靠 手动换 7z 或简单 git
v2.5.2	Git 更新加固	浅克隆 --deepen=50；GitHub 多镜像 fetch；子模块容错；launch_portable.bat 路径修复；PyTorch 源按吞吐量测速
v2.5.3	#54	启动前依赖健康检查（非仅看 torch 目录）；侧栏显示版本号
v2.5.x→v2.6	双路径萌芽	文档定稿「Git + Release」；update_from_release.ps1 从 Release 7z 合并
v2.7.0 初版 7z	7841f19 前后	Anima Fast 不预装；打标模型迁至 tagger-models/wd14/；Release 更新可用但仍有坑
v2.7.0 热更新	PORTABLE_BUILD=18e15cc	同 VERSION 重发：去掉 robocopy /XO → /IS /IT；新增 PORTABLE_BUILD、.portable_release_sync.json；Release 后显式同步 .git；修复 ps1 引号解析；根目录 bat 从 templates 刷新，避免 v2.5 时代「裸 git pull、无 .git 仍显示完成」
UPDATER_VERSION=1	3b1cd30	更新开始打印本地 VERSION / PORTABLE_BUILD / 更新脚本版本
UPDATER_VERSION=2	4a9cfab	Bootstrap 自更新更新器；统一 portable_updater_common.ps1；打印线上 main / 最新 Release / 本地与线上 UPDATER_VERSION

---

常见问题（排障索引）

现象	可能原因	建议
显示 Pulling latest code + not a git repository 仍「完成」	根目录仍是 v2.5 旧 bat	运行更新（bootstrap 会拉新 bat）或手动从 Release/templates 替换
Release 更新后 VERSION 不变、PORTABLE_BUILD 仍旧	旧脚本 /XO 跳过文件	用 Release 更新 且确认 UPDATER_VERSION ≥ 2
Git 更新报 fast-forward failed	浅克隆缺历史	已内置 --deepen=50；仍失败则 Release 更新
有 .git 但 hotfix 只在重打 7z	fix 未 push main	必须 Release 更新 或下新 7z
bootstrap 失败	无 curl / 网络	用 bundled 脚本继续；或配置代理后重试

---

相关链接

• 打包规范（本地 build 目录，公开摘要见上 doc）
• CHANGELOG — 整合包章节
• v2.5.2→2.5.3 升级说明
• Issues：#54 依赖健康、#66 Fast 安装路径等（v2.7.0 热更新包内已含修复）

---

本帖随 main 更新器变更维护；实现以仓库为准。