# GitHub 版本升级

官方发布源为 `https://github.com/Lsamien/yaoyao.git`。检查使用公开稳定 Release，不需要 GitHub 账号、访问令牌或安装 GitHub CLI；尚未发布的标签和预发布版本不会被选为更新。

## Web

进入设置中的“更新与回滚”即可检查版本，页面显示实际发布源与发布说明。检查会解析标签提交，并从固定提交读取 `release.json`；安装时再次校验下载提交。GitHub 限流、网络失败或清单异常会显示错误，不能据此宣称已是最新版。

macOS 独立 Web 继续使用现有升级事务：构建新版本、等待任务空闲、备份、切换并验证，失败恢复。回滚仍保留已写入的新数据，数据库不兼容时拒绝降级。检查和升级不依赖 9119；只以 Web 自身健康判断升级结果。Docker 显示最新版本与发布页，由部署者重新构建镜像和容器。

通过 `HERMES_YAOYAO_RELEASE_SOURCE` 可指定自定义仓库；自定义源（包括其他 GitHub 仓库）保留现有 Git 标签流程。官方 GitHub 仓库必须提供稳定 Release 和版本一致的 `release.json`。同一语义版本在 GitHub 与内网拥有不同提交编号，不会单凭编号触发升级。

## macOS App

App 更新直接显示在小铃铛旁边的更新图标，没有更新时隐藏，不再打开独立窗口。发现新版本后显示“可更新”标识，点击后在同一位置显示圆形下载进度，准备完成后变为“重新启动”。“夭夭 → 检查 App 更新…”也在当前窗口检查；尚未连接服务器时，状态显示在启动页内。连接旧版服务器时，客户端会补上原地更新入口，无需先升级服务器。客户端与服务器模式均可使用，不依赖账号的管理员权限、本机 Web 或 Hermes。此入口更新当前电脑的 App；远程服务器升级仍由服务器管理员管理。更新直接连接官方 GitHub，不受 Web 自定义源设置影响。

正式安装的 App 使用 `electron-updater`，从 `app-update.yml` 配置的官方源读取稳定版本的 `latest-mac.yml`，下载当前架构的 ZIP 并验证 SHA-512，再交由 Squirrel.Mac 检查签名、准备安装。启动约 15 秒后检查一次，随后每小时检查；下载由用户点击开始。进入原生准备阶段后不可取消。准备成功后提供“重新启动”，由用户点击后先关闭 App 的设备通道和子进程，再安装和重新启动；独立 Web 后台服务不随客户端更新而停止。

收起账号菜单、切换聊天或刷新页面不取消下载，侧栏仍显示当前进度和重启入口。后台检查不会覆盖下载、已准备的更新或用户操作失败的状态。网络失败可在原处重试；原生准备或安装失败后需要退出并重新打开 App，避免晚到的原生回调触发重复安装。缺少更新清单或 ZIP 时显示明确错误。

开发运行和隔离测试保留 DMG 手动下载：发布需要 `Yaoyao-{版本}-{架构}.dmg` 与 `SHA256SUMS.txt`；通过大小、SHA-256 和 DMG 完整性检查后才提供“打开安装包”。文件保存在应用数据目录的 `updates/desktop-downloads`。正式自动更新缓存由 electron-updater 管理，不使用 Web 的升级事务。

服务器模式安装后首次启动会同步较旧的本机 Web，保留较新的独立服务；客户端模式只连接原先的远程服务器。同版本构建关系不明时，可使用“使用当前 App 覆盖同版本 Web”，详见 [同步与覆盖规则](app-web-sync.md)。

更新接口只授权给当前主窗口的主框架：本机启动页或当前连接的服务器页面。其他窗口、子框架和其他来源的页面不能调用。错误和状态按纯文本显示，不执行远端 HTML 或脚本。

旧版 App 没有自动安装代码，首次需要手动安装包含此功能的正式签名包。历史 Apple Development 包不能作为正式自动更新发布基线；改用 Developer ID Application 签名并公证后，再以相同应用标识和持续有效的签名身份发布后续版本。旧标签和旧附件不改写。

## 旧安装迁移

加载新版本后，空发布源、`github.com/Lsamien/hermes-yaoyao`（包括 HTTPS 与 SSH）以及官方旧仓库 `git.samien.cn/samien/hermes-yaoyao`、`192.168.153.8:3000/samien/hermes-yaoyao` 的无凭据 HTTP(S) 地址会映射到 GitHub；兼容 `.git` 后缀、尾部斜杠和既有 `git@git.samien.cn:samien/hermes-yaoyao.git` 地址。其他用户自定义仓库保持原样。

运行时先使用归一化后的源；下次生成或更新本应用管理的 LaunchAgent 配置时持久化，保留地址、TLS、上游等其他环境变量。不会直接改写用户维护的环境文件。

旧程序不会凭空获得迁移能力：首次需手动安装包含此功能的新 App，或更新源码并重启。既有发布标签和安装包不会被改写。

从 v0.4.4 起默认应用数据为 `~/.yaoyao`，兼容读取旧配置并迁移 `~/.hermes-yaoyao`。迁移按服务所有权和 SQLite 锁检查，旧升级事务完成后才改名；上传与缓存索引、通知配置及更新记录中的内部路径一起更新。新旧目录都已有数据时不覆盖。`YAOYAO_HOME` 可覆盖默认值，既有 `HERMES_YAOYAO_HOME` 继续有效。

现有 LaunchAgent 标识和 `~/.local/share/hermes-yaoyao` 程序目录用于延续服务与回滚历史，不是 Web 应用数据目录。客户端历史缓存与身份命名空间也保留兼容。