Hodor

Appearance

发布与更新 ​

代码从 GitHub 到线上 Worker 的路径，与消息链路相互独立。本页同时覆盖两条线：维护者如何发布新版本，fork 用户如何跟随更新。

发布流水线 ​

维护者 push main ──┬─→ GitHub Actions（release-please）：
                   │     自动维护「Release PR」= 版本号 bump + CHANGELOG
                   └─→ CF Workers Builds：立即构建部署，代码上线
                        （/health 版本号待 Release PR 合并后才更新）

合并 Release PR ───┬─→ Actions：自动打 tag vX.Y.Z + 发布 GitHub Release
                   └─→ main 版本号变更 → CF 再次构建部署，版本号生效

版本管理 ​

版本号唯一记录在 package.json 的 version 字段，由 Release Please（GitHub Actions）自动维护——任何人都不需要手动改版本号。

发布新版本（维护者） ​

普通功能 PR 只采用 Squash and merge，PR 标题使用约定式提交格式，例如 feat: ... 或 fix: ...。

合并时将 squash commit title 设为 PR 标题。这样每个 PR 在 main 上只有一个供 Release Please 解析的提交，分支内的提交不会分别计入 changelog。

仓库管理员需在 Settings → General → Pull Requests 中仅开启 Allow squash merging，并关闭 Allow merge commits 与 Allow rebase merging。

同时将 Squash merge commit title 设为 Pull request title。PR 模板仅作提醒，不会强制校验标题或合并方式。

Release Please 的版本映射保持不变：feat: 升 MINOR，fix: 升 PATCH，BREAKING CHANGE 升 MAJOR。PR 标题应准确表达该 PR 的版本级别。

  1. 按上述约定提交并合并普通 PR
  2. push 到 main 后，release-please 自动开出（或更新）一个 Release PR，内容为版本号 bump + CHANGELOG
  3. 此时 CF 已用最新代码完成部署（代码先上线）；合并 Release PR 即完成发布：
    • Actions 自动打 tag vX.Y.Z、发布 GitHub Release（正文即 changelog）
    • main 版本号变更再次触发 CF 部署，/health 显示新版本

TIP

代码上线与版本号生效是两次部署：可以攒若干 feature 后再合并 Release PR 集中发版；窗口期内 /health 显示的仍是上一个已发布的版本号，属正常现象。

跟随更新（fork 用户） ​

部署实例默认手动跟随官方更新，官方发版不会自动波及任何用户实例：

  1. 收到官方 Release 通知（在官方仓库点 Watch → Releases 可订阅发版通知）
  2. 打开自己 fork 的 GitHub 页面，点 Sync fork（无需终端；或命令行 git fetch upstream && git merge upstream/main && git push）
  3. 自己的 Cloudflare 随即自动构建、执行数据库迁移并部署
  4. 访问 /selfcheck 复查自检全绿、/health 版本号已更新

可选：自动跟随更新 ​

仓库自带 Sync fork from upstream workflow（.github/workflows/sync-fork.yml），提供可选的每周定时同步 + 手动触发。

默认关闭——GitHub 对 fork 仓库的 Actions 与定时工作流默认禁用，不主动启用就不会运行，对手动跟随的用户零影响。

开启（自己 fork 的 GitHub 页面，三步）：

  1. 点开 Actions 标签
  2. 首次会提示 fork 未启用 Actions，点 I understand my workflows, go ahead and enable them
  3. 左侧列表找到 Sync fork from upstream，进入后点 Enable workflow，即开启每周定时同步

关闭：同一页面该 workflow 右侧 ⋯ → Disable workflow（设置随上游同步持久保留，日后想恢复再 Enable 即可）。

手动立即同步：该 workflow 页面右上 Run workflow 按钮，不必等每周定时。

行为边界：

  • 同步用 git merge --ff-only 快进：改过自己 fork 的 main（有本地提交）时同步失败并明确报错，绝不自动制造合并提交或解冲突——按上一节手动流程处理，或自行解冲突后再同步
  • GitHub 对 60 天无活动的仓库会自动停用定时工作流（邮件通知），到 Actions 页重新 Enable 即恢复
  • workflow 用 GITHUB_TOKEN 推送不会重触发 GitHub Actions 的 on:push，但会触发 Cloudflare Workers Builds 构建部署；极端未触发时手动点一次 Sync fork 兜底
  • 同步只动代码：D1 数据、面板「变量和机密」等部署产物不受影响

多实例的更新传播与回滚边界 ​

同一 fork 部署了多个实例（不同 Worker 名，见部署多个实例）时：

  • 更新传播：Sync fork / 手动合并产生一次 push，全部实例各自触发构建、一起更新到新版本
  • 回滚边界：Worker 名非 hodor 的额外实例禁止回滚或检出本特性之前的版本——旧版部署管线不识别 Worker 名，会把该实例重新绑定到共享库 hodor（数据串库）
  • 存量注记：若此前已用不同 Worker 名部署过实例（旧版下实际共享了 hodor 库），升级到本版本后新构建会自动改用以 Worker 名命名的独立库，旧共享库的数据不自动迁移；如需维持旧行为，可在该 Worker 的构建环境设 D1_DATABASE_ID 指向原库

发布回归清单 ​

每次发版的固定检查面（维护者执行）：

发版前（合并 Release PR 前）

  • npm test 全绿——包含发布回归套件 test/release-regression.test.ts（端点鉴权 / 入站 / 出站 / 幂等 / 命令 / 限频 / 防毒丸 / 版本一致共 9 个部署链路顺序场景）
  • npm run typecheck 通过

发版后（部署完成、版本号生效后）

  • curl https://<worker-url>/health 返回 ok，且 version == 本次 Release tag（如 v1.2.0）
  • curl https://<worker-url>/selfcheck 全绿返回 {"status":"ok","version":"…"}，且 version 与 /health 一致

相关页面 ​