Hex 在 Anomaly 发布服务上¶

Hex 的发布工作流（publishing）与 Hex 应用内更新器（client）之间的契约。该服务及其规则位于 anomalyco/release（docs/protocol.md、docs/publishing.md）；本文件固定 Hex 使用的名称。

名称¶

https://anoma.ly/release/hex/              the service (its dev stage, dev.anoma.ly/release, only tests the service)
├─ index.json                              download page and installers
└─ desktop/<channel>.json                  the manifest the app polls; channels stable, beta, dev
   └─ release.targets
      ├─ macos-arm64          Hex.zip         ditto zip, root Hex.app (updater)
      ├─ macos-arm64-dmg      Hex.dmg         notarized DMG (download page)
      ├─ windows-x64          hex.exe         bare executable (updater)
      ├─ windows-x64-cli      hex.com         console entry point beside hex.exe (updater)
      ├─ windows-x64-setup    HexSetup.exe    Inno Setup installer (download page)
      ├─ windows-arm64        hex.exe
      ├─ windows-arm64-cli    hex.com
      ├─ windows-arm64-setup  HexSetup.exe
      ├─ linux-x64            hex             bare executable (updater, installer, AUR)
      ├─ linux-x64-deb        hex.deb         Debian/Ubuntu package (package manager updates it)
      ├─ linux-x64-rpm        hex.rpm         Fedora/openSUSE package
      ├─ linux-arm64          hex
      ├─ linux-arm64-deb      hex.deb
      └─ linux-arm64-rpm      hex.rpm

发布的名称不携带版本或目标平台：每个文件都存放在 /release/hex/files/<sha256>/<name>，以此区分彼此；服务使用 Content-Disposition: attachment; filename="<name>" 提供下载，因此下载会保存为 hex、Hex.dmg 等。构建产物和 GitHub 发布镜像保留带版本号的名称（hex-<v>-macos-arm64.dmg，……），这些名称在该处必须唯一；.github/release/release-service.sh 负责映射它们。（是 HexSetup.exe，不是 Hex Setup.exe：服务的文件名不允许有空格。）

• 应用 hex，构件 desktop。stable 是公开频道；每次推送到 dev 都会在 dev 频道发布 0.0.0-dev-<run number>。beta 已注册供以后使用。
• 每个可执行文件和归档文件在上传前都会签名（macOS 上使用 Developer ID + 公证，Windows 上使用 Authenticode）；服务存储字节及其大小和 SHA-256，但清单文件不签名。Linux 可执行文件带有基于其 SHA-256 的 ed25519 签名，作为 linux-<arch>-sig 目标（hex.sig），更新器和安装程序都要求此签名。
• 在 stable 上，版本号为 X.Y.Z。服务会拒绝相同或更低的版本，除非当前版本已被撤销。

分发¶

记录在每次发布中；包管理器条目只有在该任务成功后才获得 version（即 distribution 操作）：

直接安装回执¶

安装程序在用户拥有的安装根目录写入 install.json（{"app":"hex","artifact":"desktop","channel":"stable","method":"direct","root":"<root>"}），并且只有在该文件存在且根目录仅由该用户可写时，客户端才会自行更新：

• Linux：~/.local/share/hex/install.json（install-linux.sh；scripts/install-linux.sh 源码构建不会写入任何内容，并保留其 source-build 标记）。
• Windows：%APPDATA%\hex\install.json（install-windows.ps1 和 Setup.exe）。
• macOS：客户端根据应用包的位置判断（可写的、非 translocated 的 Hex.app 即为直接安装）。

HEX_RELEASE_BASE_URL（仅 HTTPS）可将构建指向另一个服务源，用于针对 fixture 服务进行本地测试；默认情况下不会指向其他源。

旧客户端（2.3.1 及更早版本）¶

https://anoma.ly/hex/files/{linux-update.json,windows-update.json,appcast.xml} 在 hex-production-files 存储桶中保持固定为 2.3.1。在该服务上的首次发布时，appcast 会增加一个信息性条目，指向 https://anoma.ly/hex（参见 docs/releasing.md）。

客户端¶

src/updater.rs（所有三个操作系统）在启动 10 秒后轮询 <origin>/hex/desktop/<channel>.json，此后每小时轮询一次（Dev 频道每 10 分钟轮询一次，并在窗口获得焦点时轮询，但每分钟至多一次），以及在点击“立即检查”时轮询；请求携带 If-None-Match 和 User-Agent: hex/<channel>/<version>（构建自身的频道和版本，例如 hex/dev/0.0.0-dev-171、hex/stable/2.3.1），服务将其计为一次正在运行的安装；失败的检查会退避，但间隔不会超过一小时。客户端依据协议的客户端规则进行决策（updater/protocol.rs，它通过了复制到 tests/fixtures/release-protocol 的服务端 test-vectors/）。从不比较版本：只要频道的当前发布版本不是正在运行的构建，Hex 就采用它；在 Linux 和 Windows 上，通过可执行文件的 SHA-256（即目标文件本身）识别正在运行的构建，在 macOS 上则通过其精确版本识别。required 发布版本会跳过分阶段发布。被检查的频道是“更新频道”设置，否则就是该构建发布时所在的频道（HEX_BUILD_CHANNEL，由 Release 打上；旧构建：dev 版本为 dev，否则为回执中的频道）。如果设置不同于构建的频道，则视为切换：设置、Windows 托盘和 macOS 菜单会提供“切换到 Stable 2.3.1”的选项，并且在用户确认之前不会下载任何内容。

install method              distribution   channel           acts on install
macOS writable Hex.app      direct         stable            unzip beside it, codesign -R app/update-requirement.txt, swap at restart/quit
macOS read-only/translocated direct        stable            Download update → macos-arm64-dmg URL
Linux versions/ + receipt   direct         receipt's         copy into versions/<v>, switch current
Linux pacman / Nix          aur / nix      stable            show the distribution's command
Windows versions/ + receipt direct         receipt's         Authenticode (AUTHENTICODE_SIGNER), versions\<v>, current-version
source and test builds      (never check)
anything else               unknown        stable            Download update → notes_url

目标 URL 是绝对路径引用（/release/hex/files/<sha256>/<name>），依据清单 URL（RFC 3986）进行解析，因此会保留清单所在的主机（anoma.ly 或 dev.anoma.ly）。下载会写入 <support>/updates/<sha256>/，并且在用于任何其他用途之前，会先与 size 和 sha256 进行比对校验。滚动发布桶为 <support>/update-bucket。