nekonest-cloud/docs/provisioning-worker.md

区域共享 Relay 调度边界

旧的“每租户 Docker Server + manifest provisioner”路径已经退出 Cloud 控制面，相关执行器、公开 activation 接口和管理员操作入口均已删除。本文件描述当前共享 Relay 节点与租户 placement；历史 migration 只为现有 D1 升级保留，不得重新接入生产 API。

控制面对象

• relay_regions：稳定公开 origin 所覆盖的区域。
• relay_nodes：区域内的 Go Relay 节点、状态、容量和 heartbeat generation。
• tenant_placements：tenant → home_region → relay_node，带单调 generation 与状态。
• tenant_authorization_state：租户授权状态与单调 revision。
• relay_node_credentials：节点 mTLS SPIFFE ID、证书指纹、签发/到期和撤销时间；不保存共享 bearer。
• relay_signing_keys：kid、Ed25519 公钥、私钥引用和轮换窗口；不得保存私钥。

首版每个租户固定一个 home region、一个可写节点和一个 Engine。没有 active-active、跨节点 SQLite 共享或双写。tenant_placements.state 为 active，或切换后目标节点独占写入的 draining，且目标节点 status=active 时，设备注册报告 connection_state=ready。

节点身份与 heartbeat

Cloud Worker 不能直接读取客户端证书。部署必须在 Worker 前使用 mTLS 终止层，剥离不受信的身份头，并注入绑定 method/path 的短时 HMAC 断言。控制面验证该断言，并把 node ID、SPIFFE ID、证书指纹与 D1 中未撤销、未过期的证书身份行绑定；任一不匹配均 fail closed。内部 API 不要求也不接受共享节点 bearer 作为身份替代。heartbeat generation 不能回退。

生产部署仍必须增加：

• mTLS 终止层、受信头剥离与 ingress assertion secret 的部署实证；
• 独立的证书 bootstrap/轮换操作面；
• Secret Manager/KMS 内的 Ed25519 私钥；
• 节点容量、过期 heartbeat 与 placement 队列告警。

Placement 与迁移

迁移状态固定为：

active → quiescing → copying → switching → draining → active

迁移在复制和切换前停止新写，校验每租户 SQLite 与附件快照，再原子递增 placement generation 并切换目标节点。切换前失败时旧节点保持权威；切换后 draining 由目标节点作为唯一写入者，不能回切到可能落后的源数据。同一 generation 不得在两个节点同时可写。

当前仓库已经包含 Go Relay、租户 Engine Registry、授权刷新、稳定 Connect 数据面、节点间转发、备份恢复、迁移与 Purge 原语；它们仍需经过真实 mTLS ingress、WSS、共享备份传输和跨区演练，才能表述为公开上线服务。具体配置见 docs/relay-operations.md。

Relay 每 60 秒以 tenant ID + placement generation 拉取完整快照，默认每 5 秒拉 revision delta，delta 和随后的完整刷新各有 3 秒超时；完整刷新不携带客户端设备 token。手机撤销由当前 placement 节点调用内部 revoke，原子撤销 phone principal 与全部 route handle、推进 authorization revision 并写审计后，Relay 才关闭 Engine 内身份。