Gitea RunnerService -> scheduler -> JetStream ci.runner.pod
                                      |
                                      v
                              homelab Kubernetes Pod
                                      |
                         SPIFFE mTLS RunnerService facade
                                      |
                                      v
                                     Gitea

Pod backend 不经过 OpenSandbox。VM backend 后续启用时才访问 VyOS 暴露的 OpenSandbox Lifecycle API；本目录不修改 sandbox 平台侧 ESO、Bao Terraform 或 OpenSandbox chart 所有权边界。

Canary 安全边界

Deployment 为单副本，滚动策略固定 maxSurge: 1、maxUnavailable: 0，保证新 facade Ready 后才终止旧实例。scheduler 必须通过 Kubernetes Lease 保持单 leader，不能依赖 Recreate 避免重复领取。
scheduler 使用一个 runner registration，并按总容量启动并发 FetchTask goroutine； POD_CAPACITY=4 与 VM_CAPACITY=1 分别限制两个 durable consumer 和 backend admission pool。池满时 assignment 保持 JetStream pending，任一 backend 不占用另一方的执行槽位，也不会创建超出容量的 workload。
rollout 重叠期间只有持有 Lease/dynamic-runner-scheduler 的 controller 执行 FetchTask；所有 Ready 实例都可通过 backend metadata 恢复 claim 并服务 facade。
executor 镜像使用 digest；Pod 以 UID 2000 运行，SPIRE ClusterStaticEntry 同时绑定具体 Pod UID 与 unix:uid:2000。
facade 通过仅内网可路由的 192.168.10.127:30443 NodePort 提供给 sandbox executor；双方使用 Workload API X509-SVID mTLS，并按 SPIFFE ID 而不是 IP/DNS 名验证服务端。该入口不经过公网或 Cloudflare Tunnel。
controller 的 SPIFFE ID 固定为 spiffe://ddupan.top/ns/dynamic-runner/sa/dynamic-runner-controller。
NATS 保留既有最小权限分离：ci-producer 仅 publish，ci-worker 仅 pull/ACK。

facade claim registry 在启动时从 Pod/OpenSandbox metadata 恢复；scheduler leadership 由 Kubernetes Lease 持久化协调。Deployment 仍保持 replicas: 1，滚动更新期间允许一个额外 Pod 提供 facade 连续性。

Secret 边界

ExternalSecret/dynamic-runner 从既有 ClusterSecretStore/openbao 读取：

kv/k8s/nats：producer/worker 密码；
kv/k8s/opensandbox-api:api_key：保留给后续 VM worker；
kv/k8s/gitea-runner:token：保留的 runner registration token；
kv/k8s/dynamic-runner：scheduler UUID/token、facade HMAC key 和回滚所需 webhook secret。

scheduler credential 由官方 Gitea Runner v3.5.0 一次注册生成；它只挂载到 controller，不会进入 executor。facade capability key 至少 32 字节，controller 为每个 assignment 确定性生成独立 capability。不要打印 Secret、创建静态 Bao token或把 credential 写入 Git。OpenBao 写入使用本机 SPIFFE JWT 换取的短期 local-development token。

Workflow 身份与依赖配置

workflow 可复用 panxiao81/ci-actions 中的 spiffe-openbao-login@v1 和 setup-nexus@v1。这不改变 runner 的权限边界： runner 仅提供 Node.js 20、spire-agent 与 Workload API socket，workflow 负责声明 Bao role、audience 和具体用途，目标服务 policy 决定是否授权。短期 Bao token 会进入 Actions job 临时文件，因此这些 Action 只允许在本目录管理的一次性 Pod/VM executor 中使用，不能迁移到共享或持久 runner。

匿名读取 Nexus public repository 只需 setup-nexus@v1，不应为了依赖下载额外申请 Bao 凭据；需要发布制品时再为对应 repository 建立独立 service account 与最小权限 policy。

首次验收

合并后先观察 Flux 与 controller，不要立即开启 VM：

flux reconcile kustomization dynamic-runner --with-source
kubectl -n dynamic-runner wait externalsecret/dynamic-runner \
  --for=condition=Ready --timeout=2m
kubectl -n dynamic-runner rollout status deploy/dynamic-runner-controller --timeout=5m
kubectl -n dynamic-runner logs deploy/dynamic-runner-controller -f

确认 scheduler 只领取一条 [self-hosted,pod] task，然后验证：

assignment message 进入并离开 durable pod consumer；
gitea-task-<task-id> Pod 创建，取得实际 Pod UID；
同名 ClusterStaticEntry 的 parent ID 包含该 UID，SPIFFE ID 使用 repository/job key；
官方 runner v3.5.0 经 facade claim 精确 task，Gitea 实时收到日志和终态；
Pod consumer 达到 capacity 时 VM consumer 仍可独立接受任务。

Pod 与 VM 都在 Gitea 接受终态后先把 terminal marker 写入各自 backend metadata，再由 lifecycle reconciler 删除执行器。首次 VM 测试仍须观察 BatchSandbox、Pod 与 ClusterStaticEntry 全部消失；完整自动清理通过前不得提高 POD_CAPACITY 或 VM_CAPACITY。

回滚

若 controller 在领取 task 前失败，回滚到前一 commit 的 Python controller/Pod worker manifests。若已经创建 gitea-task-* Pod，先保留现场并核对 Gitea task 状态，不能直接重启 scheduler 造成重复执行。scheduler registration 和 capability key 保留在 Bao，回滚不需要删除或打印它们。

README.md Unescape Escape

Gitea dynamic runner

Canary 安全边界

Secret 边界

Workflow 身份与依赖配置

首次验收

回滚

README.md