# 现有ARM64 ECS:集中凭据模式部署指导 日期:2026-11-04。适用已运行的`hainuo-relay`七服务项目。使用新脚本`deployable/scripts/broker_deploy.py`,不重新执行init,不复制新Compose替换旧部署,也不操作其他项目。 ## 1. 已取得的现场基线 - 部署目录:`/home/cnooc/hainuo-offline-arm64/hainuo-relay`。 - Docker Engine 29.9.0 / Linux ARM64,Compose v2.40.3;cnooc账号操作Docker需要sudo。 - 当前运行Compose由容器标签记载的7份配置叠加。脚本动态读取并保留全套文件,不要求人工少选几份。 - 备份:`/home/cnooc/hainuo-relay-backups/20261104-115742`,数据库dump已完成`pg_restore --list`解析;这不等于真实恢复演练。 - 已保留`rollback-connector-20261104`、`rollback-router-20261104`、`rollback-longconn-20261104`、`rollback-signer-20261104`;connector实际镜像与router/longconn不同,回退必须分别保留。 这是用户提供的当次运行信息,后续有变化时以预检查为准。不要提交/上传备份、.env、密钥或实际Token。 ## 2. 现在可以执行:下载代码并只读预检查 如果目标暂存目录尚不存在: ```bash cd /home/cnooc git clone --branch master git@git.yssing.cloud:ex_tianzy/ecs----.git ecs-relay-service-staging cd /home/cnooc/ecs-relay-service-staging git log -1 --oneline sudo python3 deployable/scripts/broker_deploy.py preflight \ --deployment-root /home/cnooc/hainuo-offline-arm64/hainuo-relay ``` 如果之前已经clone,先在该暂存仓库执行`git status --short --branch`确认没有个人改动,再使用`git pull --ff-only`更新;clone或pull失败时停止,不在运行目录内强制reset。仓库当前SSH地址沿用已核验的remote,页面显示名与历史路径不同不影响这一路由,若服务器提示不存在则回报错误,不在命令行粘贴访问Token。 脚本只依赖Python标准库(Python≥3.7)及现有Docker/Compose,不要求服务器安装本机开发venv、pytest或cryptography。`preflight`读取容器/镜像/Compose,仅输出项目、文件数量、实际镜像及模式,不打印解析后的配置、Secret或Token;不写密钥、不构建、不重启。 兼容修订:原部署将longconn声明在`longconn` profile。脚本显式携带`--profile longconn`解析完整现有服务集合,而不是默认省略它;不使用`--profile '*'`开放未知服务。预检查仍只读;后续up仍只指定connector/router并使用`--no-deps`,不会因此启动第二个longconn。服务集合不符时报告缺失/多出服务名并停止,不打印环境配置。 **当前客户端尚未适配v2,执行到这里即可。** 后续prepare/check/build同样不启用新模式,但需要产品权限集合;activate必须等新客户端和测试计划就绪,不能因为代码测试通过就切换现网。 ## 3. 产品权限与准备阶段 客户端产品经理确认功能范围、读写边界和集中授权体验,开发映射API/Scope、管理员确认发布生效后,将批准的权限profile映射保存为本机JSON文件。格式为对象:产品权限版本名映射到Scope字符串数组。不要用本方案中的任意示例权限替代产品决定,不用每接口单独授权。 假定批准文件已放到`/home/cnooc/work-product-profiles.json`,选择一个**尚不存在、位于运行目录之外**的准备目录: ```bash cd /home/cnooc/ecs-relay-service-staging sudo python3 deployable/scripts/broker_deploy.py prepare \ --deployment-root /home/cnooc/hainuo-offline-arm64/hainuo-relay \ --profiles /home/cnooc/work-product-profiles.json \ --output /home/cnooc/hainuo-broker-prepared-20261104 ``` prepare生成独立的root私有目录、随机AES密钥keyring、独立router准入Secret、broker Compose叠加配置、精确镜像回滚叠加、基线和源码快照。密钥文件600且归属服务UID10001;目录700。**不改运行.env、CA、connector签名密钥、绑定、数据库卷,也不初始化数据库或服务。** 输出目录已存在时拒绝覆盖,不自动重新生成密钥。 这份目录包含真实密钥,不能上传聊天/Git,不能与普通源码归档一起公开分发。数据库备份和密钥需要分开保护;首次prepare产生的密钥还不在之前现场备份中,启用前必须落实单独密钥备份与恢复。丢失密钥会使集中凭据无法解密。 ## 4. 检查与离线构建:仍不切换 如果旧版prepare返回`broker production platform/database configuration incomplete`,不要删除目录或重跑prepare。旧初始化器曾使用`HN_ENVIRONMENT=development`,首版工具把production写死,且把多个条件合并成同一错误。新版保留经过校验的原environment命名空间(production/development/test),所有模式仍要求PostgreSQL及HTTPS/WSS;不会为通过检查修改运行.env或将凭据换一个身份空间。 先更新暂存仓库,再对已经生成的计划执行只读诊断: ```bash sudo python3 deployable/scripts/broker_deploy.py diagnose \ --plan /home/cnooc/hainuo-broker-prepared-20261104 ``` 只显示environment合法枚举、数据库类型及开关状态,不显示URL、账号密码、Secret或Token。通过后原地继续check,沿用原keyring和配置;若仍有错误按字段处理,不关闭HTTPS校验、不改用SQLite。新prepare在生成密钥前检查这些条件;旧目录因原检查失败留下的密钥不会被自动覆盖。 ```bash cd /home/cnooc/ecs-relay-service-staging sudo python3 deployable/scripts/broker_deploy.py check \ --plan /home/cnooc/hainuo-broker-prepared-20261104 sudo python3 deployable/scripts/broker_deploy.py build \ --plan /home/cnooc/hainuo-broker-prepared-20261104 ``` check确认旧.env/7份Compose/准备配置/密钥/源码快照无漂移,各服务实际镜像仍匹配,数据库卷/网络/原挂载保持,router不持有管理员/事件/App Secret,edge有已审阅的内部接口拒绝规则。只在内存解析Compose,不把展开后的Secret打印出来。未识别配置时停止,不自动“修复”现网。 build基于**当前connector的确切ARM64运行镜像**创建候选,复制新版relay代码;`--network none --pull=false`,不下载Python包或基础镜像,不覆盖原`hainuo-relay:0.1.0`。构建阶段验证新模块可导入,完成后记录候选镜像ID;不使用依赖不明的新基础镜像,不替换正在运行的应用。 这种方式复用现场已有运行依赖,因此必须在ECS执行并验证候选构建/导入。开发机的Docker命令桩只能证明命令编排,不能代替ARM64镜像构建、真实PostgreSQL、真实Redis或业务联调。 ## 5. 启用前门槛与切换 必须已经具备:新PC的集中凭据领取/v2握手与任务上下文、产品Scope生效、准确HTTPS回调白名单、候选镜像真实构建通过、数据库及密钥备份、两用户测试资源、升级与回滚窗口。客户端access只内存缓存,refresh仅在ECS;平台已发Bearer是否即时撤销仍需实测。 在上述条件满足后,才允许: ```bash cd /home/cnooc/ecs-relay-service-staging sudo python3 deployable/scripts/broker_deploy.py activate \ --plan /home/cnooc/hainuo-broker-prepared-20261104 \ --client-v2-ready ``` 该标志是操作方对就绪状态的明确声明,不是脚本自动验收客户端。没有该标志,脚本在发任何切换Docker命令前拒绝执行。 只重建connector/router容器,保留原数据库、Redis、edge、longconn、签发服务和其他知识库项目;不创建第二个机器人长连接接收器。旧有longconn继续内部事件协议,不需要持有router准入密钥。broker切换将关闭旧refresh/claim/业务代理,旧PC会不兼容;切换前完成客户端安排,使用一次新授权建立集中凭据。 健康检查通过只代表容器就绪,随后必须验证:本人OAuth和实际user_info、access-only领取、集中刷新、PC直连业务、原消息回复、通知、解绑/旧码/旧回包和两用户ACL。没有结果不能宣称上线验收完成。 启用后继续使用该plan和叠加配置管理connector/router;直接运行原7份Compose的up可能撤销broker配置。不要删除准备目录或重跑init来恢复连接。长期维护入口统一化与运行配置纳管需在正式发布交接中明确。 ## 6. 应急容器回退 ### 已部分切换且router缺少公钥参数 现场已确认一种旧配置兼容遗漏:connector候选健康,router不断重启,日志报`FileNotFoundError: runtime/pki/connector.pub`;router原环境仅有`HN_CA_CERT=/trust/ca.pem`,没有`HN_CONNECTOR_PUBLIC_KEY`。不要修改公钥内容、重新生成CA或keyring,不要重复activate。 更新暂存仓库后可先只读查看包含停止/重启中容器的状态和固定错误类型: ```bash sudo python3 deployable/scripts/broker_deploy.py state \ --plan /home/cnooc/hainuo-broker-prepared-20261104 ``` 仅在已知候选connector运行且healthy时执行: ```bash sudo python3 deployable/scripts/broker_deploy.py repair-router \ --plan /home/cnooc/hainuo-broker-prepared-20261104 ``` 该操作先验证原配置/密钥/准备目录完整性及已知候选镜像,从router已有只读信任挂载识别实际公钥位置(该现场为`/trust/connector.pub`),备份原叠加和plan后只增加router公钥参数并同步计划校验。不会重生成任何密钥、修改原.env、重建connector或其他服务。重跑隔离配置/公钥实际读取检查后,只up router;重复执行不会覆盖备份或改密钥。 新prepare已包含此参数;build/activate的隔离容器现在会实际加载挂载的router公钥,不能只验证Settings字段就标记候选就绪。`state`不打印原始日志或环境,只报告原/候选镜像类别、容器状态/健康/退出码和固定错误类。已部分切换时rollback可识别停止或重启中的已知候选容器,但拒绝未知镜像;原有回滚限制仍适用。 兼容修订:没有HEALTHCHECK的longconn/edge不包含State.Health,旧查询模板会因此在修复开始前失败。新模板使用可选map键读取并将其健康状态记为none;容器inspect失败与确实查不到唯一容器分别报告。更新后对原计划再次执行repair-router即可,不需重新prepare、删除备份或生成密钥。 ### 完整回退 若切换失败,先停止broker客户端继续使用,按记录的每服务镜像回退: ```bash cd /home/cnooc/ecs-relay-service-staging sudo python3 deployable/scripts/broker_deploy.py rollback \ --plan /home/cnooc/hainuo-broker-prepared-20261104 \ --stop-broker-use ``` 回退仅对connector/router执行up,不操作数据库卷或恢复陈旧refresh。脚本验证原配置和非目标服务未漂移后使用实际旧镜像;原longconn/签发镜像单独保留。**容器回退不等于用户授权无损回退**:服务端已轮换的refresh不能交回旧PC继续刷新,旧客户端需要协调模式/重新授权。保留集中凭据数据库及密钥,不用旧数据库备份覆盖新的平台轮换状态。 activate失败不会自动猜测执行回滚,停止后按此流程处置;如果配置、密钥或运行版本漂移导致check拒绝,应先审阅差异,不用强制选项绕过。 ## 已运行broker的权限配置更新 用于飞书开发者后台完成权限开通/版本发布后,同步ECS实际申请的用户scope。不是重新部署代码,不重建镜像,不生成密钥,不更换客户端模式。 先准备产品确认的JSON,保留原profile名称和已有scope。示例只展示新增云盘、wiki、任务读写;其他用户业务权限按开发者后台实际开通的内容加入。 ```json {"current-config-v1":["calendar:calendar","calendar:calendar:readonly","drive:drive","wiki:wiki","task:task:write"]} ``` 对现场最新已激活的计划操作,先预览: ```bash cd /home/cnooc/ecs-relay-service-staging-http git pull --ff-only sudo python3 deployable/scripts/broker_deploy.py update-permissions \ --plan /home/cnooc/hainuo-broker-update-20261105-recovery \ --profiles /home/cnooc/work-product-profiles.expanded.json ``` 核对预览只列出已开通的scope后,用相同命令加`--apply`。脚本校验活动容器、计划完整性、已有scope不被移除,备份overlay和plan并同步校验记录,只recreate connector;相同配置重跑不重启。镜像、router、长连接、数据库卷、密钥和绑定保持,connector重建期间请求可能短暂中断;失败恢复原配置并尝试重建旧connector,失败状态明确报告。不输出解析后的环境或密钥。 完成后必须发起**新的授权事务**:旧授权页面/已创建事务的scope不会随环境变更自动扩展。确认授权URL的scope已包含新增项、实际token返回granted_scopes包含目标范围,再以真实业务code和数据验收。不要手改授权URL绕过ECS产品权限Profile。新权限要求可能使旧凭据暂时需要重新授权,使用测试用户完成验证。 ### 私有化平台授权目录核对修订(2026-11-06) 扩展profile原先误将token返回的auth:user.id:read作为显式可申请scope。登录实际开发者后台后发现该值不在524项应用权限目录中;不能把token的granted_scopes直接复制成authorize请求清单。当前示例已移除此项。 已有运行配置含该项时,先核对开发者后台其余23项均已开通且发布,再执行: ```bash git pull --ff-only sudo python3 deployable/scripts/broker_deploy.py update-permissions \ --plan /home/cnooc/hainuo-broker-update-20261105-recovery \ --profiles deployable/examples/work-product-profiles.expanded.json \ --allow-remove-scope auth:user.id:read ``` 默认仍只预览。核对移除项仅为auth:user.id:read后,同命令加--apply。仅显式列出的scope可以移除;不删除已有凭据、绑定或应用权限。此为授权请求清单修正,不是撤销用户在平台上的权限。 实际后台还发现contact:department.base:readonly、contact:department.organize:readonly、task:tasklist:write三项未开通(后台status=0,其余对应已开通项status=5)。开通/发布这三项,或由产品决定移出首版申请清单后,必须创建新的授权事务,旧事务仍绑定旧scopes_json。本次没有自动替用户开通后台权限。