# 阶段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秒连接复核会增加内部控制请求,必须实测容量后再扩大设备规模,不外推十万人能力。