Release 流水线产出容器镜像并推送 registry.237575.xyz

[RiriAgent]

必须先读的关联 issue

Umbrella: mouriya-s-lab/homelab-tf#401。继承契约（逐字快照）：

§1 GitOps-first：凡技术上可走 Komodo git-source ResourceSync 的 stack 必须走 ResourceSync；komodo-stacks 的 ansible file_contents 推送是被收敛的遗留机制，不再新增使用者。

分工：本 issue 只管"release → 镜像进 registry"；stack 侧消费（compose 换镜像、poll 自动部署）归 homelab-tf 的 hapi 迁移 child（umbrella 范围区 B3）。

目标

每个 fork release 自动产出容器镜像并推送 registry.237575.xyz，无人工步骤。

使用场景

维护者给 fork 打 tag 发 release 后不做任何别的事；homelab 侧（B3 落地后）由 auto_update 自动运行新版本。

上下文

• Repo: mouriya-s-lab/hapi（fork；官方发 npm @twsxtd/hapi，fork 不发 npm、发 GitHub Release 单可执行文件，如 hapi-linux-x64-baseline.tar.gz——homelab-tf#290 与其实施 comment）。
• 现有 Release workflow 已产全平台二进制（homelab-tf#290："Release workflow 产全平台单可执行文件并挂 GitHub Release"）；本 issue 在其后追加/并行镜像 job。
• 生产在用版本 v0.20.2-fork.2，由 homelab-tf komodo 模板硬编码消费（komodo/roles/komodo-stacks/templates/hapi/compose.yaml.j2，注释 "Upgrade both via a separate PR"——这就是被消灭的人工步骤）。
• registry push 的已验证模板：runner-canary 的 publish.yml 与 moat-browser 的 deploy.yml——GARM runner label [self-hosted, linux, vctcn]（需 netbird 时加 netbird），keycloak-token-action 换 token 后 docker login registry.237575.xyz。
• GARM：mouriya-s-lab/hapi 需注册 GARM pool（garm-cli on VM 181，runtime state；注册后更新 pve-vctcn/apps/runner/README.md 的清单 pointer）。
• 运行形态：hub 单二进制，容器内 hapi hub --no-relay，监听 3006（现行 compose 同款行为）。
• 实施前自行核对上述 workflow / 模板的现行内容。

已裁决的目标级决策

• 双 tag 发布：不可变 tag vX.Y.Z-fork.N + channel tag stable，两者同 digest。B3 的 compose pin stable，Komodo auto_update = true 检测 channel tag digest 变化并自动 redeploy（upstream client/core/rs/src/entities/stack.rs 字段注释："Whether to automatically redeploy when newer images are found. Will implicitly enable poll_for_updates"；注意单开 poll_for_updates 只产生更新提示不触发 redeploy）。自动重部署机制在 homelab 尚无在产实例，由 B3 首验。不可变 tag 供回滚与审计。
• 不采用 CI 直调 DeployStack（moat-browser 形态）：那会要求本 repo CI 持有 homelab Komodo API key；auto_update 形态把部署权限留在 Core 拉取侧，hapi repo 的信任面只到 registry。若 B3 验证 auto_update 对私有 registry 不可行，fallback 即切 moat-browser 形态（CI 追加 UpdateStack + DeployStack job）——双 tag 发布在两种形态下都需要，本 issue 不被该未知阻塞。

问题

fork 只发二进制 tarball，没有镜像 artifact；homelab 消费端只能用 buildpack-deps 基础镜像在容器启动时 curl 下载（运行时装配），版本升级被迫走"改模板 tag+sha → submodule PR → parent bump → make hapi"的三步人工链。

"hapi现在非常愚蠢的每次都是手动更新" — 操作员方向（2026-07-06）

预期结果

性质表述：release 事件之后，registry.237575.xyz/hapi/hub:stable 的 digest 在无人工介入下等于该 release 内容构建出的镜像；镜像自包含（运行不再下载任何 artifact），入口行为与现行 hapi hub --no-relay 等价。

不应残留

• 范围内：无（本 repo 只增一个 workflow job + Dockerfile；不删现有二进制 release 产物——其他消费者可能在用）。
• 范围外不得改动：homelab-tf / homelab-komodo 的任何文件（stack 侧是 B3）；registry 服务端配置（pve-vctcn/apps/registry 冻结，仅按既有 keycloak client 流程拿 push 权限）。

约束

• registry 凭据走既有 keycloak-token-action 流程，不在 repo secrets 存长期 registry 密码。
• 镜像必须 self-contained：禁止入口脚本在运行时从 GitHub 下载二进制（那只是把现状搬进镜像）。
• Dockerfile 基底 / 分层属实现细节（b 类），留 PR；但镜像内必须可跑 hapi hub --no-relay 且监听 3006。

验收标准

Dimension	Check	Command	Env	Expect
function	release 触发全自动	发一个测试 release，观察 workflow	GitHub	workflow 由 release 事件触发并 green，无手动输入
function	双 tag 同 digest	docker buildx imagetools inspect registry.237575.xyz/hapi/hub:{stable,vX.Y.Z-fork.N}	mesh 内主机	两 tag digest 相同
integration	镜像可拉可跑	mesh 内主机 docker run --rm -p 3006:3006 …:stable 后 curl -sI localhost:3006	mesh 内主机	容器起动无下载动作，端口应答
assumption	GARM pool 生效	workflow job 落在 [self-hosted, linux, vctcn] runner	GitHub	job 由 GARM runner 执行（run log 可见 runner 名）

依赖关系

• Depends on: 无。
• Blocks: hapi 迁移 child（B3，见 umbrella feat(voice): pluggable voice backend with Gemini Live & Qwen Realtime tiann/hapi#401 范围区）。

[RiriAgent]

现场核对

• repo shape：mouriya-s-lab/hapi = rebase-style fork（upstream=tiann/hapi）。根目录无 Dockerfile；upstream .github/workflows/ = codex-mention-response.yml, codex-pr-review.yml, issue-auto-response.yml, release.yml, test.yml, webapp.yml；fork 追加了 sync-upstream.yml。新增 Dockerfile + .github/workflows/publish-image.yml = fork-only 新文件，不动 upstream 源码，符合 fork-features/ 放置规约。
• release 现状：release.yml 在 tag v* 触发，bun run build:single-exe:all 产出 cli/dist-exe/bun-<target>/hapi（linux 默认 bun-linux-x64-baseline）。运行时入口 hapi hub --no-relay；hub 尊重 HAPI_LISTEN_HOST=0.0.0.0 / HAPI_LISTEN_PORT=3006（hub/src/config/serverSettings.ts:173-190），与 homelab-tf hapi compose 已用契约一致。
• GARM 现状（docker exec garm garm-cli on VM 181 vctcn-runner）：cross-owner onboarding 已 proven，现存 pool 覆盖 mouriya-s-lab/{runner-canary,nanoclaw,claude-code-pr-bridge-e2e,homelab-trading,mattermost-plugin-openusage} + moat-lab/{moat-browser,fulcrum,mattermost-plugin-*}。mouriya-s-lab/hapi 未 onboard。docker-flavor 标准形态 = image=ubuntu:24.04, flavor=docker, tags=self-hosted,linux,x64,vctcn,netbird, extra_specs 走 /opt/runner/scripts/build-extra-specs.sh --docker（含 01-docker-prepull.sh + registry-mesh-hosts.sh 让 registry.237575.xyz → 100.85.231.90 mesh 直推）。
• registry 凭据链：pve-vctcn/apps/registry/main.tf 已有 github_actions_secret.registry_client_secret 对 var.registry_consumer_repos 做 KEYCLOAK_REGISTRY_CLIENT_SECRET 同步；provider 走 GITHUB_OWNER env（当前 Mouriya-Emma），是 单 owner 作用域。mouriya-s-lab/hapi 是 cross-owner，需要 pve-vctcn 侧一个 targeted TF 变更：加一个 aliased provider "github" + 一个新 var.registry_consumer_repos_mouriya_s_lab + 第二个 github_actions_secret 块。这是 state-authority-map §"New image push consumer" 显式许可的扩展路径，不属于"vctcn 大改"。
• release image 命名：验收表定义为 registry.237575.xyz/hapi/hub:{stable,vX.Y.Z-fork.N}，两 tag 同 digest。
• auto_update 消费：hapi stack 侧现由 homelab-tf/komodo/roles/komodo-stacks/templates/hapi/compose.yaml.j2 用 buildpack-deps + 运行时 curl 下载二进制（v0.20.2-fork.2 pinned）—— 属 B3 (homelab-tf#405) 范围，本 issue 只到"镜像进 registry"为止，不动 homelab-tf/komodo submodule。

交付计划

PR-A（pve-vctcn — 前置条件）

新 issue 链 hapi#72 描述 cross-owner secret sync 扩展。TF 变更：

• 加 aliased provider "github" { alias = "mouriya_s_lab", owner = "mouriya-s-lab" }（PAT 已有 admin:org 覆盖两 org）。
• 加 var.registry_consumer_repos_mouriya_s_lab (list(string), default ["hapi"])。
• 加 第二个 github_actions_secret 资源块 for_each = toset(var.registry_consumer_repos_mouriya_s_lab), provider = github.mouriya_s_lab, 同 secret_name = "KEYCLOAK_REGISTRY_CLIENT_SECRET" 和同 plaintext_value = keycloak_openid_client.registry.client_secret。
• pve-vctcn/apps/runner/README.md "已 onboard 的仓" 清单补 hapi。

tofu plan/apply 在 pve-vctcn 仓库层执行。apply 后 gh secret list --repo mouriya-s-lab/hapi 应出现 KEYCLOAK_REGISTRY_CLIENT_SECRET。

PR-B（本 issue：mouriya-s-lab/hapi）

新增两个文件：

1. Dockerfile（根目录，新文件）—— 多阶段自包含镜像：

   • builder: oven/bun:1.3.14-debian，bun install --frozen-lockfile + bun run build:single-exe（linux/x64 host 自动定位 bun-linux-x64-baseline）。
   • runtime: debian:bookworm-slim + ca-certificates，COPY --from=builder /src/cli/dist-exe/bun-linux-x64-baseline/hapi /usr/local/bin/hapi，ENV HAPI_LISTEN_HOST=0.0.0.0 HAPI_LISTEN_PORT=3006，EXPOSE 3006，ENTRYPOINT ["/usr/local/bin/hapi","hub","--no-relay"]。
   • 镜像内不 curl / 不下载任何 GitHub artifact —— 满足"self-contained"约束。

2. .github/workflows/publish-image.yml（fork-only 新工作流）：

   • Trigger: push tags: v*（与 release.yml 并行；两者独立触发，失败隔离）。
   • runs-on: [self-hosted, linux, x64, vctcn, netbird]（GARM docker-flavor pool）。
   • Steps:
     • actions/checkout@v4
     • docker/setup-buildx-action@v3 + driver-opts: network=host（沿用 moat-browser 已验证形态，让 buildkit 继承 /etc/hosts mesh override）。
     • Mouriya-Emma/keycloak-token-action@v1 → 取 access token。
     • docker login registry.237575.xyz -u sa-registry --password-stdin。
     • docker/build-push-action@v5 —— 一次 build，两个 tag 同 push：registry.237575.xyz/hapi/hub:${{ github.ref_name }} + registry.237575.xyz/hapi/hub:stable（build-push-action 保证同 build 出的多 tag 指向同一 digest）。
     • docker buildx imagetools inspect 双 tag，assert digest 相同。
     • docker pull 两 tag 做 pull verification（sanity）。
   • PR body Closes #72。

GARM 注册（runtime state on VM 181）

ssh root@vctcn-runner.mouriya.lan：

docker exec garm garm-cli repository add --owner mouriya-s-lab --name hapi \
  --credentials vctcn-pat --random-webhook-secret --install-webhook \
  --pool-balancer-type roundrobin
docker exec garm garm-cli pool add --repo <repo-id> --enabled \
  --provider-name lxd_local --flavor docker --image ubuntu:24.04 \
  --max-runners 2 --min-idle-runners 0 --runner-bootstrap-timeout 60 \
  --os-arch amd64 --os-type linux \
  --tags self-hosted,linux,x64,vctcn,netbird \
  --extra-specs "$(/opt/runner/scripts/build-extra-specs.sh --docker \
    --extra-packages 'unzip,zip,jq,git,make,wget,gnupg,ca-certificates,xz-utils,build-essential')"

（README 清单 pointer 更新已包含在 PR-A 里。）

运行时验证（PR-B Layer 4 硬门槛）

1. push 一个 canary release tag（不覆盖 prod 生产 tag；用 v0.20.2-fork.3-canary 之类）。
2. 观测 workflow run URL：green，run log 首行 runner name garm-* 前缀（GARM-created LXD instance）。
3. 从 mesh 内主机（laptop 已 mesh enrolled）：
   • docker pull registry.237575.xyz/hapi/hub:vX.Y.Z-fork.N-canary
   • docker pull registry.237575.xyz/hapi/hub:stable
   • docker inspect --format '{{.Id}}' 两 tag 对比 → 同一 digest。
4. docker run --rm -p 3006:3006 …:stable，等待启动日志（应无 curl / 下载动作，直接 [Hub] Listening on 0.0.0.0:3006）。
5. curl -sI localhost:3006 → HTTP 应答。
6. 上述命令原始输出全部贴 PR body Layer 4。

停点契约

PR-A + PR-B 开完 + 证据齐 → SendMessage 回报 main（PR URL + CI run URL + digest 对比原始输出 + 任何计划偏差），等核验后再合并。红线：不动 homelab-tf / komodo / hapi 的 upstream 源码文件，远端不写 /tmp。