Files
ecs-relay-service/deployable/CREDENTIAL_MIGRATION.md
T
ex_tianzy ce965aaf58 fix(deploy): tolerate absent Docker health state during router recovery
Containers without a configured HEALTHCHECK omit State.Health. Direct map
field access in the new inspect template made recovery prechecks fail on
longconn/edge before the router path could be repaired. Use a guarded map
index and report health=none without weakening image/config/key checks.

Distinguish service lookup errors from inspect/template failures instead of
misreporting every query failure as no unique container. Identify the
container-inspect stage in safe command errors.

Add regressions for absent health state through state and the full partial
router repair, plus accurate inspect failure classification. Validation:
265 passed, 3 skipped (no real PostgreSQL), 30 existing warnings; tool tests
52 passed. Python 3.7 syntax and staged diff checks pass.
No remote keys/configuration or containers were changed; rerun the existing
repair-router plan after updating, do not prepare or activate again.
2026-11-04 16:33:35 +08:00

25 KiB
Raw Blame History

集中凭据改造:分阶段交付记录

目标:ECS保存并刷新用户access/refresh token;客户端仅认证领取本人access token,MCP、Skill及业务接口在客户端执行并直连私有化Work。refresh token不下发客户端。

本文件描述开发阶段,不能作为当前现网已切换的证明。每阶段分别开发、测试、提交master并推送;实际ECS部署及客户端升级另有版本和现场验收。

阶段划分

阶段 范围 完成门槛 状态
1 服务端加密凭据存储基础 密文持久化、应用/用户/环境隔离、版本冲突、密钥轮换与篡改检测测试;不接入旧路由 已完成本地开发测试,提交71b9678
2 集中凭据Broker及刷新 应用/用户锁、持锁重读、版本CAS、响应校验、刷新unknown;新授权不受旧刷新覆盖 本次完成本地开发测试
3 OAuth与认证领取 共享state事务、实际用户核验、绑定代次、只返回access的独立DTO及领取认证 本次完成本地开发测试,显式broker模式启用
4 ECS权威解绑与消息任务关联 停发Token、失效事务/任务、连接和旧码联动,多实例/异常恢复 本次完成本地开发测试,broker模式生效
5 配置部署、迁移与旧接口退出 密钥挂载、产品权限配置、客户端对接、停用旧刷新/claim及代理、ARM64和真实平台验收 已交付现有部署准备/检查/构建/切换/回退工具;现机及客户端验收待执行

产品经理决定功能和Scope清单。阶段1不预设具体权限,不生成真实凭据、不读取现有设备、不调用平台。

阶段1:加密存储基础

新增relay/credential_store.py和测试,使用现有Store数据库连接,支持SQLite本地测试和PostgreSQL部署。只有显式构造CredentialStore时初始化新增表work_credentials_v2,当前connector不导入/启用该模块。

存储与加密

  • 主键为environment/app_id/principal_id。access token、refresh token、实际Scope、到期时间一起作为AES-256-GCM密文保存;数据库元数据只有身份、凭据版本、key_id和更新时间。
  • AAD绑定格式版本、身份三元组、凭据版本和key_id,防止跨用户/应用/环境调换密文。每次写入生成随机96位nonce。
  • 调用方提交expected_version:0仅允许首次创建;后续更新必须匹配数据库版本。冲突抛固定异常,不自动覆盖、重试或刷新上游。
  • keyring包含active_key_id及保留解密用的旧密钥。新写入采用当前密钥;旧记录必须先由有旧密钥的服务读取并以CAS重写后才可移除旧密钥。改active_key_id不表示全量密文已迁移。
  • 存储对象仅供ECS内部使用,包含refresh token,绝不能直接序列化为客户端响应。后续阶段必须用独立字段白名单DTO,客户端只收到access token。

密钥管理

CredentialKeyring.from_file(Path(...))读取JSON文件,格式为active_key_id和keys映射,每项keys值为32字节随机密钥的标准Base64编码。当前不提供默认密钥、环境配置或自动启动接线,不能只上线此提交就开始存生产凭据。

部署阶段需由运维将密钥文件放在Git、镜像、数据库和普通备份之外的受控位置,以最小OS权限挂载,仅凭据服务可读;Windows文件ACL和Linux权限由部署检查落实,模块不声称已校验ACL。密钥与加密数据库备份分开保护。不要把真实密钥作为命令行参数、日志、工单或文档示例。

兼容与未完成边界

现有设备/绑定、数据库旧表、OAuth路由、通知和客户端协议均未修改;原始快照目录保留。阶段1没有发Token接口、后台刷新、绑定代次或解绑联动;旧实现仍可能把refresh下发PC,不能把本提交视为已经满足最终凭据边界。

版本CAS用于避免陈旧写入覆盖,并不能实现跨平台刷新exactly-once。AEAD用于检测密文篡改,不保证数据库整体历史回滚检测。PostgreSQL真实环境、密钥轮换运维和加密备份恢复必须另行验收。

复核命令

在仓库根设置PYTHONPATH=deployable后执行:

python -m pytest deployable/tests/test_credential_store.py -q
python -m pytest deployable/tests deployment-source/tests -q

真实PostgreSQL用例只有在测试环境设置HN_TEST_DATABASE_URL时执行;它创建并清理独立随机schema,不把测试指向业务库。未提供时明确skipped,不冒充实机通过。

本阶段验证记录(2026-11-04)

  • Windows / Python 3.12.10,使用本机已有隔离测试依赖环境,PYTHONPATH=deployable。
  • 最后一轮完整本地回归:102 passed,2 skipped,15 warnings(42秒)。其中新增存储测试23项通过,新增真实PostgreSQL测试1项跳过;原有真实PostgreSQL测试也因未配置连接而跳过。
  • warnings为现有uvicorn/websockets旧接口弃用提示,没有新增测试失败。新增模块AST语法与git diff --check通过。
  • 覆盖密文/WAL不含测试Token、重开连接持久性、环境/应用/用户密文调换拒绝、AAD/认证标签篡改、错误密钥、旧密钥移除、轮换重写、陈旧CAS和双连接并发写入、异常输入与固定错误信息。
  • connector未引用新增模块,未新增公开路由,未生成真实密钥或初始化现有数据库。

测试只使用合成凭据、本地临时文件和平台桩,没有进行现网授权、刷新或消息推送。真实PostgreSQL、Docker/ARM64容器运行及现机业务验收尚未执行;不得将本地回归标为服务器上线完成。

阶段2:集中凭据Broker与刷新(2026-11-04)

本次改造

  • 新增内部CredentialBroker,按环境/应用/已核验owner读取加密凭据,保留原凭据实际剩余期限。AccessGrant只包含access token、到期时间、剩余秒数、版本和实际Scope,不含refresh token,repr也隐藏access token。
  • 按环境/应用/owner取Redis可续期租约,刷新与新授权共用同一锁;持锁重读当前凭据,只在access即将过期时刷新。锁等待有上限,慢请求超过等待预算时其他调用返回busy,不自动并发刷新。
  • 新增持久work_refresh_attempts_v2,按源凭据版本唯一。上游调用前记录started;超时、取消、响应缺字段、身份不符、失锁或数据库失败后标为unknown;即使标记失败留下started,也阻止重复使用同一旧refresh。
  • 新凭据经user_info核验实际用户后,以CAS原子保存access/refresh和版本,再返回access;后续领取不再触发同一版本刷新。重开数据库可保留刷新未知状态;重新授权写新版本后恢复。
  • 新授权与刷新共享互斥与版本检查,拒绝旧结果覆盖外部已写入的新凭据。刷新Scope缺失仅继承原已核验Scope,不扩权;显式返回缩减Scope时保存新凭据但拒绝缺失能力。新授权必须返回实际Scope。
  • platform.py增加独立的credential_exchange/credential_refresh适配,使用现有私有化v1 OIDC端点。严格检查HTTP状态、顶层业务码和必要字段;不改变旧exchange/refresh/normalize调用契约,不直接复制agent-hub默认v3接口。
  • 新增平台调用超时、Redis失败、租约失效、身份与Scope核验,错误采用固定消息,不输出平台原始凭据或错误正文。

调用边界与后续集成要求

截至阶段2,Broker仍是内部模块,未由connector实例化,没有新HTTP接口或后台调度。owner参数暂按应用范围内已核验的open_id使用,只能来自可信设备/授权事务映射;不得把此内部方法直接暴露给模型、客户端自选用户或无认证HTTP路由。阶段3的接线与边界见下节。

此阶段不改变旧OAuth向PC交付refresh的行为,也不读取旧PC凭据。部署阶段必须关闭旧刷新并避免双主,不能仅发布此模块就宣称refresh只在ECS。

当前get_access连有效Token读取也经过短租约,便于与新授权/刷新串行;客户端将缓存access以降低领取压力。阶段3需在发放前复核绑定和代次,阶段4实现解绑联动。数据库失效状态、已发Bearer残余有效、Scope审批和平台撤权均不由本阶段替代。

已有Redis租约和CAS仍无法消除“平台已轮换、服务端未可靠保存”的故障窗口:持续未知时需重新授权,不自动重试旧refresh。数据库记录可恢复到新版本时后续领取复用,不因调用方未收到响应而再次刷新。记录清理必须保留当前源版本的重试屏障,后续运维策略另行定义,不能简单按短TTL删除started/unknown。

测试环境及结果

测试extra改为fakeredis[lua],在本机隔离测试环境安装Lua支持,用FakeRedis实际执行锁的Lua脚本及续租,不将Python本地锁冒充Redis分布式锁。Lua支持仅为测试依赖,生产使用Redis自身脚本,不增加生产Lupa依赖。离线测试环境需事先准备对应测试extra依赖。

最后一轮完整回归:147 passed,2 skipped,15 warnings(29.57秒)。新增Broker/平台适配测试45项通过;真实PostgreSQL的2个用例因未配置HN_TEST_DATABASE_URL而跳过,扩充的PostgreSQL用例含刷新记录唯一性和状态更新但尚未实测。

本地覆盖:多Broker实例与独立Redis客户端/数据库连接并发只刷新一次、续租覆盖慢平台调用、失败续租不发布结果、实际剩余期限、access-only对象、身份错误、授权/刷新串行、陈旧CAS、Scope减少、异常字段、进程取消、调用超时、崩溃started记录重开保留、刷新状态写失败、新凭据提交后确认丢失、Redis不可用及旧接口回归。

首轮完整回归有一条原有PC测试遇到Windows临时文件replace拒绝访问(WinError 5);该用例单独重跑和最后完整回归均通过,未修改该客户端实现,具体系统原因未确定。warnings仍为uvicorn/websockets旧API弃用提示。

未进行真实Redis多进程/多节点压测、真实PostgreSQL、Docker/ARM64、现机部署或真实授权/刷新。FakeRedis共享实例测试证明本地协议并发行为,不外推为生产集群验收。

阶段3:OAuth落库与认证领取(2026-11-04)

接口细节见 集中凭据协议v2。

改造内容

  • Settings新增legacy/broker显式模式、服务端密钥文件和产品权限版本集合。默认legacy,不自动改变现有部署;broker缺少密钥/权限或平台OAuth未启用时拒绝启动。生产broker要求PostgreSQL。
  • 新增CredentialAPI:认证状态、发起授权、授权状态查询、access-token领取和新OAuth回调。所有设备接口验证证书/签名、环境/应用/协议版本、method/path、完整请求摘要、时间nonce、当前owner及绑定代次。
  • 加密存储共享授权state及请求关联;一次性原子认领,固定600秒有效,重复回调不再次换码;其他connector可处理同一持久事务。实际授权用户必须匹配绑定本人,授权完成直接加密保存ECS,不将refresh下发PC。
  • 授权稳定request_id幂等且不延长有效期;新授权意图使同用户旧waiting/exchanging事务superseded,旧授权提交前重查,避免较早权限意图覆盖较新的请求。数据库设备行写锁用于跨worker串行化创建/取代。
  • 设备表增加binding_generation,保留原数据与身份;bind/unbind/revoke推进版本。新绑定回执返回版本,已有客户端可通过设备认证status安全同步,不要求重新配对。
  • Broker增加同步绑定/事务guard:等待锁后、换码提交前和领取返回前核验当前状态;刷新已轮换时先保存最新凭据,再拒绝向已解绑设备发放,避免丢失服务端refresh。
  • 领取响应是显式字段白名单,只含access token和必要元数据;成功授权与发放写脱敏审计,不含code、state、Token或完整授权URL。
  • 共用旧设备证明函数抽取到device_auth.py,OAuth/通知与旧代理复用,不再要求保留work_api路由才能认证。
  • broker模式不注册旧/oauth/start、claim、pending、refresh及/work/api,防止同模式双主。新授权卡以事务ID引用服务器链接;文本/通知卡沿用本人发送边界。

兼容与未完成

legacy模式继续旧凭据协议;新字段/表是增量迁移,不删除旧设备和绑定。旧客户端与broker模式不兼容,阶段5需协调客户端版本、一次新授权和旧本地凭据清理;不能未经准备切换生产配置。

本次没有更新实际Compose参数/密钥挂载、安装包或服务器;公开接口仅在显式broker配置下注册。数据库绑定版本让新接口拒绝旧设备上下文,但完整连接断开补偿、持久任务/回包关联、旧绑定码失效和后台刷新暂停等仍为阶段4;不能宣称整体解绑闭环已完成。

事务在exchanging中崩溃时不自动重放code,超期需重新授权;授权scope不足时显式返回permission_update_required,不把刷新当扩权。平台刷新未知、已发Bearer残余有效、客户端最终缓存清理和用户Scope审批边界保持不变。

验证结果

Windows / Python 3.12.10,平台桩、临时证书/密钥、SQLite及带Lua的FakeRedis。本轮新增v2接口测试38项通过,另增1项真实PostgreSQL事务/绑定迁移用例因未配置连接而跳过。覆盖跨用户/跨应用环境签名、路径/正文篡改、nonce重放、错人授权、state过期/取消/重放、双connector单次换码、数据库重开、授权取代、部分Scope、旧入口关闭、代次失效和刷新中解绑不发Token。

最后完整回归:185 passed,3 skipped,15 warnings(49.77秒)。3个跳过项均需要真实PostgreSQL测试连接;warnings仍为原有uvicorn/websockets弃用提示。文档表格/围栏、relay模块AST及git diff --check通过。

真实PostgreSQL、真实Redis多进程、ARM64镜像、私有化平台及现机业务验收尚未执行;本地ASGI/FakeRedis结果不能作为线上多节点或生产部署结论。

阶段4:ECS权威解绑、连接准入与任务关联(2026-11-04)

细节见阶段4协议和边界。本次仅修改ECS项目,未修改或发布PC安装包,未部署现机。

改造内容

  • 新增BindingState及Store生命周期挂钩,在broker模式统一bind/unbind/revoke,数据库事务内更改绑定代次、作废未完成授权/任务/配对码epoch、记录审计和outbox。legacy路径保持原行为。
  • 新增认证设备解绑入口;机器人命令、管理员和设备解绑共用同一权威状态。旧配对码按owner epoch拒绝;新broker配对码只存摘要,和绑定一起一次性消费,不接受原legacy Redis码。
  • Redis失效动作失败时保留outbox供本节点/其他connector重试;删除在线presence有比较保护,断连消息包含代次,旧事件不误断新连接。接口published/pending不等于PC确认。
  • router新增独立内部准入Secret,和事件接入Secret分权;请求带nonce并验证connector签名的短期准入结果,不取得Token。握手/订阅后/任务上下行/周期均复核数据库绑定及任务;控制服务失败时拒绝转发。
  • 新v2设备握手绑定应用、环境、owner和generation;任务下行带签名routing及密文摘要。新模式旧PC握手会拒绝,不能宣称对现有安装透明兼容。
  • 持久任务记录关联原message/chat/conversation、设备、generation、session、worker及deadline;结果逆序仍按原任务交付,平台回复单次认领;迟到/解绑/死亡worker/超时不改变终态、不重放写任务。
  • worker使用30秒Redis存活租约和5秒维护;任务扫描轮转避免后续任务饥饿;无结果正文持久化,不承诺重启后恢复丢失的内存结果。
  • 通知增加broker必填generation并在等待平台凭据后复查,防止同用户重绑后旧通知继续发送;legacy原签名兼容。应用及用户refresh均不下发。

本地验证

新增阶段4专项28项:真实回环WebSocket而非纯函数桩,覆盖两用户/同用户多任务逆序、机器人解绑断连与旧回包拒绝、数据库提交/Redis失败补偿、事务回滚、另一connector重开补偿、旧码拒绝与一次消费、迟到kill不影响新连接、通知期间重绑不发、吊销与旧握手拒绝、控制面中断拒绝转发、周期查库发现解绑、死亡worker和reply_unknown不重放,以及DB/Redis清理失败仍释放内存连接/等待记录。扩展可选PostgreSQL用例覆盖owner epoch和outbox,但无连接时仍跳过。

专项测试不代表真实Hermes客户端的记忆隔离已经完成;本次测试用合成PC设备/平台桩和本地SQLite/FakeRedis,客户端可信TaskContext传入Agent/MCP仍需后续适配。默认旧模式、服务器配置和真实凭据均未切换。

最后完整回归:213 passed,3 skipped,30 warnings(45.87秒)。3个跳过项均需要真实PostgreSQL连接,warnings为既有uvicorn/websockets旧API弃用提示(新增真实回环连接增加提示次数);relay模块AST、文档和diff检查通过。

生产部署、真实Redis/PostgreSQL多实例、ARM64镜像、平台实际撤权/Scope/容量和客户端安装升级仍待阶段5及现场验收。平台已接收的请求不可靠解绑撤回,已发access仍可能有效到期。

阶段5工具交付:保留现有部署的迁移接线(2026-11-04)

用户提供现场Docker/Compose、7份配置路径、不同组件镜像ID及已生成备份,数据库dump目录解析通过,并建立4个原镜像回滚标签。该信息仅是当次现场证据,不等同真实恢复或新架构上线验收。

新增标准库工具scripts/broker_deploy.py与现有ECS操作指导:

  • preflight只读识别实际容器标签、Compose文件、项目与ARM64镜像,不写文件/密钥,不输出解析配置,不重启。
  • prepare创建运行目录外的新私有计划:保留全部原Compose、CA、数据库卷和异构镜像;生成独立keyring/准入Secret和仅影响connector/router的叠加,复制无凭据源代码快照。不修改现有.env或初始化数据库。
  • check拒绝配置/源码/密钥/镜像漂移,核对原挂载、网络、数据库卷及内部路径拒绝规则;密钥权限/UID要求明确。不打印展开后的Secret。
  • build复用确切现场ARM64运行镜像,以禁网/禁止拉取方式构建候选;不替换原镜像、不下载依赖。导入smoke与两角色配置/密钥读取检查通过后才标记候选就绪;配置通过stdin送入无网络临时容器,不放在命令行或日志。
  • activate需明确声明v2客户端就绪,重新检查候选及运行基线后仅up connector/router;缺标志时在发切换命令前拒绝。健康通过后仍需实际业务验收。
  • rollback有独立停用broker声明,按每组件原实际镜像回退connector/router,不恢复旧refresh或删除数据库。保持新密钥和凭据数据,避免覆盖平台已轮换状态。

默认部署配置不自动切换;本次工具通过本地模拟Docker编排测试,但开发机没有真实Docker/ARM64环境,不能宣称已构建或验证候选镜像。新客户端尚未适配,现机当前只应执行只读preflight或经产品权限确认的准备/构建,不能启用broker。

本地新增工具策略测试26项,覆盖7份配置保留、独立旧镜像、准备不启动服务、密钥不覆盖、路径/配置漂移、私有入口拒绝、产品权限格式、候选失败不标就绪、候选换标签拒绝、客户端就绪门槛、离线构建和仅重建两服务。最后完整回归:239 passed,3 skipped,30 warnings(46.94秒);跳过项需要真实PostgreSQL,warnings仍为旧依赖弃用提示。宿主脚本通过Python3.7语法兼容检查、CLI help及diff检查。

测试中Docker命令均为受控桩,不声称实际执行Compose合并、ARM64构建或密钥挂载。真实Compose/ARM64、PostgreSQL/Redis、多用户平台、客户端升级和密钥恢复仍待执行,因此阶段5总体尚未验收完成。

现机预检查兼容修订

用户已通过HTTP拉取da1b423,执行只读preflight返回unexpected Compose services;未创建密钥或重启。核对原导出compose.yaml发现longconn带profiles: [longconn],而首版脚本未指定profile,存在漏解析该服务的明确兼容缺口。

修订Compose命令统一显式指定--profile longconn,不启用未知profile;保留服务集合严格校验并在不符时仅输出missing/extra服务名。后续up仍限connector/router且带--no-deps。新增3项回归模拟被profile隐藏的服务及缺失/多出服务的安全诊断,本地工具测试29项通过;现机实际解析结果仍需更新后重跑确认,不将该推断当作已经现场复现的唯一原因。

修订后完整本地回归:242 passed,3 skipped,30 warnings(48.50秒)。跳过与warnings类型同上,宿主脚本Python3.7语法及diff检查通过。

准备阶段配置诊断兼容修订

现场prepare在platform/database配置检查处停止,未切换容器;原流程在最后验证前已生成私有plan/keyring,不得删除重建来绕过。核对旧初始化器默认environment=development,首版工具错误地要求字面production,可能误拒绝现有测试部署;同时数据库/开关条件合并导致现场无法辨别具体字段。

新版按现有Settings接受production/development/test,保持原身份命名空间和原.env,所有部署环境仍强制PostgreSQL、固定HTTPS平台/公开入口和WSS,不降低网络校验。布尔开关对齐Settings接受true/1/yes/on。错误只列字段,不回显数据库URL等敏感值;新增diagnose只读已有plan,无需重生成keyring。未来prepare在生成私有目录前先验证必要条件。

新增11项工具回归,覆盖合法环境保持、HTTPS/WSS/数据库失败在写密钥前拒绝、只读diagnose保留全部准备文件、错误不泄露数据库凭据;工具专项40项通过。实际现场哪项原始条件不符仍以更新后的diagnose输出为准,不将历史默认值当作当前配置证明。

修订后完整本地回归:253 passed,3 skipped,30 warnings(49.46秒);真实PostgreSQL仍未提供,warnings类型同上,Python3.7语法与diff检查通过。

部分切换故障与router公钥路径修复

现场activate只输出通用Docker失败,用户随后提供状态:connector已是broker候选并healthy,router同候选持续Restarting(1)。进一步只读确认router未配置HN_CONNECTOR_PUBLIC_KEY,实际日志FileNotFoundError指向默认runtime/pki/connector.pub。这是旧router此前不消费connector公钥,而新模式开始验证路由签名后,迁移叠加漏传原信任目录公钥路径;首次import/Settings探测未实际打开公钥,没提前发现。

修订新prepare识别现有只读信任挂载中的公钥并显式传HN_CONNECTOR_PUBLIC_KEY,runtime_check挂载并实际load_public。新增repair-router面向已知健康候选connector的部分切换,备份叠加/plan、保留keyring/原.env/其他镜像,只补router路径并重建router。原密钥或运行配置漂移时拒绝,不自动删除/重准备。

新增state只读查看停止/重启容器并对本地日志只提取固定错误类(包含Docker logs的stderr);run错误报告阶段/退出码而非原始配置。activate输出阶段,明确up失败可能部分切换。rollback的目标服务可为已停止的已知原/候选容器,不再因只查询运行容器而无法识别;未知镜像仍拒绝。

工具专项50项通过(新增state/部分回滚/错误脱敏4项、公钥修复5项、旧部分计划CLI回滚1项)。完整本地回归262 passed、3 skipped、30 warnings(49.76秒),之后追加的回滚入口检查再次通过工具50项;Python3.7语法与diff检查通过。真实PostgreSQL仍未提供。实际修复结果仍需现场执行并核验,不能把本地Docker桩通过当作router已恢复。

无Healthcheck容器导致修复前检查退出

现场repair-router未进入修改步骤即报docker-command失败,state能读connector/router/signer,却将longconn/edge显示为no unique。核对新版inspect模板使用.State.Health可选键,longconn/edge没有健康检查时Docker map模板会失败;state原先又把所有DeployError误归为容器数量问题。

改为with index .State "Health"安全读取,无字段记health=none;单独区分ServiceLookupError和容器inspect错误,命令失败阶段明确为container-inspect。新增2项回归模拟无健康检查的现有服务,覆盖state与整条部分切换repair流程以及错误分类,工具52项通过。未改配置、已生成keyring或运行容器;仍需现场更新并重跑修复核验。

最后完整本地回归:265 passed,3 skipped,30 warnings(63.22秒);真实PostgreSQL未配置,warnings类型同上,Python3.7语法及diff检查通过。