Files
ecs-relay-service/deployable/BINDING_TASK_LIFECYCLE.md
T
ex_tianzy d1ab834ecb feat(lifecycle): add stage 4 authoritative unbind and durable task routing
Unify broker-mode binding changes in database transactions: advance device
generation, invalidate pending authorizations/tasks and prior pairing-code
epochs, and persist audit plus invalidation outbox. Add authenticated device
unbind alongside robot/admin paths. Pairing codes are hashed, generation-
fenced and consumed atomically with binding.

Replay Redis invalidation effects without undoing committed unbind. Guard
online cleanup and delayed kill events by generation. Introduce a separate
router admission credential with no platform-event injection authority.
Router verifies signed nonce-bound internal admission on handshake, task
traffic and periodic checks; reject stale sessions and control-plane outages.

Persist task owner/device/generation/session/worker and original message
mapping. Sign routing metadata, verify late results, claim replies once and
mark ambiguous/crashed tasks unknown instead of replaying writes. Fence
notifications across same-user rebind. Release in-memory slots/waiters even
when database or Redis cleanup fails.

Validation: 213 passed, 3 skipped (real PostgreSQL not configured), 30 existing
uvicorn/websockets deprecation warnings. New lifecycle coverage: 28 tests,
including real loopback WebSocket isolation, reverse completion, missed kill,
periodic unbind checks, outbox recovery, transaction rollback and cleanup
failures. Syntax, docs and staged diff checks pass.

Default legacy mode remains unchanged. Broker mode now requires coordinated
router admission configuration and a v2 client handshake. No production ECS
configuration, real credentials or client installer was changed. PostgreSQL,
real Redis multi-node, ARM64 and actual Work/client rollout remain stage 5.
2026-11-04 11:43:53 +08:00

70 lines
8.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 阶段4:解绑、连接准入与任务关联指导
日期:2026-11-04;适用模式:显式`credential_mode=broker`。本文描述服务端开发结果和后续部署/客户端适配要求,不表示现机已切换。
## 1. ECS权威解绑
机器人`/解绑`、管理员`/admin/devices/{host}/unbind`、新设备接口`POST /work/v2/device/unbind`和吊销路径,共用`BindingState`事务逻辑。设备接口沿用v2设备签名和基础字段,不允许自行指定其他设备/用户;校验的owner/generation作为解绑条件,不能在并发重绑后清除新的关系。
数据库事务完成以下操作:清空owner或标记revoked,推进binding_generation,作废原设备未完成授权事务,终止该绑定版本在途/待回消息任务,推进用户配对码epoch,记录审计与失效outbox。事务中任意一步失败整体回滚,不返回假“已解绑”。解绑不删除CA/设备私钥,也不撤销用户平台OAuth。
解绑命令即使当前已无设备,也推进owner epoch,使其此前未消费的配对码失效。broker模式配对码以摘要存数据库,绑定时在事务中核验epoch/有效期并一次性消费,和实际设备绑定一起提交;无效设备签名不消费配对码。旧legacy Redis配对码在broker路径不被接受。
原设备后续Token领取、授权回调/状态恢复、通知及内部连接准入都核验当前绑定/代次;正常业务入口不依赖客户端自行清理才算解绑。Broker没有独立后台刷新调度,已无有效绑定时没有认证调用可触发正常领取刷新;后续后台保活仍须遵守同一绑定策略。
## 2. 失效事件补偿
`work_binding_events_v2`记录待执行失效事件。提交数据库后尝试删除旧在线presence、写吊销标记、发布带generation的断连通知;失败保留记录,当前或其他connector可补偿。维护周期5秒,每轮处理最多100条,未处理完继续后续轮次。
解绑接口返回`status=unbound`、`propagation=published/pending`;published只说明Redis失效动作已被接受,不表示PC已确认或所有在途平台调用已撤回。数据库始终是凭据和任务判定依据。
旧事件不允许删除较新generation的在线presence;使用比较删除避免竞争。新router也忽略不比自身generation新的断连事件,防止重试的旧通知误断新连接。事件发布成功但数据库确认失败时可以重复发布,不能据此重复业务任务。
## 3. Router独立内部准入
新配置`HN_ROUTER_ADMISSION_SECRET`只用于router查询绑定/任务准入,至少32字符,不能复用管理员、事件内部Secret或App Secret。connector和router各自获得该凭据,router不需要获得机器人事件接入Secret或应用Secret。新配置及挂载的正式Compose接线在阶段5完成。
router还需要公开`HN_FEISHU_APP_ID`、同环境标识、`HN_CONNECTOR_INTERNAL_URL`(默认`http://connector:8000`)及已有connector签名公钥。内部URL为固定运维配置,禁止用户名密码/query/fragment和自动重定向;请求禁用环境代理,超时3秒。
内部接口:`POST /internal/devices/{host}/admission`,头为`X-Router-Admission-Secret`,正文是随机nonce及可选turn_id/session_id。它不返回用户Token,只返回connector签名的环境/应用、设备/owner、当前generation/证书指纹、nonce/任务/session和5秒期限。router验证签名、nonce、用途上下文与期限;不能拿事件Secret调用该接口,也不能拿准入Secret注入`/internal/events`。
准入在握手、订阅后、每次指令下发、结果上行以及8秒周期检查时重新核对ECS状态。任务校验还要求当前generation、原session、inflight状态、deadline及所属worker仍存活。控制服务不可用时关闭或拒绝连接/转发,不继续用陈旧缓存接受任务;这牺牲部分可用性换取绑定控制。
即时断连优先走outbox通知;通知丢失时周期检查可在下一个检查周期发现无效绑定,实际时延还包括内部请求和调度。不能承诺数据库提交瞬间物理连接同步消失;已提交到平台的写操作也不能撤回。
## 4. 新设备WSS握手与任务信封
broker模式设备proof保留host_id、challenge、session_id、kx、ts,并增加严格整数`protocol_version=2`、environment、app_id、binding_owner、binding_generation;全部由设备签名。旧握手在broker模式拒绝,legacy模式保持旧协议。
connector下行消息新增routing签名,绑定turn_id、host、session、环境/应用、generation和完整密文envelope摘要。router验证后向内部接口查询该任务的当前准入,再下发原密文。密文内task_context包含task_id、environment、app_id、owner、host、generation、conversation_id、chat_id、source_message_id及Work通道。
**客户端尚未在本阶段修改。** 后续PC桥接必须发送新握手,将可信task_context传入原生API、MCP/工具运行时,并保留Profile与工具禁用限制。本机旧适配器的稳定单聊session键不能替代这个上下文,也不能把服务端路由测试说成已完成客户端Agent记忆/并发隔离。
当前仍只接受p2p文本事件;新模式要求有效chat_id,不截断后混用会话键。conversation_id按环境、应用、用户、chat_id和Work单聊通道确定。群聊、话题和多Profile产品行为未擅自扩展。
## 5. 持久任务状态与原路回复
`work_tasks_v2`保存原消息/会话、owner、设备、generation、session、worker、deadline和状态,**不保存明文任务或回答正文**。同一turn_id不重复建立/执行。密文结果必须通过设备签名/解密、原turn、原session及数据库当前状态验证,才能完成本进程pending future。
典型状态为`inflight → completed → replying → replied`。completed仅表示已收到有效结果,replying表示单次平台回复已认领;回复出错为reply_unknown,不因消息重复投递自动重发。诊断任务无原消息时可标记finished。解绑/吊销变为unbound/revoked,超时或任务所有者失联为unknown,迟到结果不能改变终态。
机器人回复位置从数据库原消息映射取得并进行单次认领,不接受客户端/模型改写chat_id/message_id。不同用户或同用户不同任务逆序返回仍回原消息;取消/解绑后不把旧结果投到新消息。解绑命令自身的确认回复不等于继续发送被取消任务的答案。
worker采用随机进程ID与30秒Redis租约,每5秒续期。维护扫描轮转检查活跃任务;进程退出或租约消失后遗留任务在后续维护/准入检查中拒绝。进程恢复不重放旧任务,不声称恢复已丢失的内存结果或提供持久消息队列。已发到平台但回复结果未知时保留reply_unknown,不承诺exactly-once。
连接/请求退出时先释放内存连接槽和pending记录;数据库状态更新或Redis清理失败不得阻止本地释放,遗留在线键由TTL清理、任务由持久状态维护处理,不凭遗留presence继续放行旧绑定。
## 6. 通知与凭据的解绑边界
broker模式`/device/notifications`新增必填binding_generation并纳入原work-notify-v1签名payload;缺失/陈旧代次拒绝。取得应用Token后发送前再查owner/generation,防止等待期间同用户重绑导致旧请求继续发消息。legacy可不传该字段,原签名格式保持不变。
授权卡仍引用server-owned事务,发送前再查事务状态和代次。设备解绑后停止再次发Token和通知,但**已发出的用户Bearer access token仍可能有效到期**;是否即时撤销取决于平台能力,不能把DB解绑称为平台授权撤销。正常客户端停止重连、清access缓存的交互需要后续客户端适配。
## 7. 配置、测试与待办
默认legacy及现有客户端不切换。启用阶段4 broker之前,必须同时准备router独立准入配置、内部网络、公钥、产品权限和新PC协议;新旧broker握手不混跑。不能为了旧客户端放开无绑定准入或重新下发refresh。
本地使用平台桩、加密合成凭据、SQLite、FakeRedis和真实回环WebSocket,验证协议和并发。PostgreSQL用例扩充配对epoch/outbox检查,但没有真实连接时明确skipped;FakeRedis不等于真实Redis多节点/故障演练。
阶段5待做:Compose与初始化密钥/权限参数接线、内部网络/证书检查、候选ARM64构建、客户端握手与上下文适配交接、数据留存清理、outbox/worker/任务监控、旧模式迁移和真实平台/双用户/规模验收。8秒连接复核会增加内部控制请求,必须实测容量后再扩大设备规模,不外推十万人能力。