Files
ecs-relay-service/deployable/EXISTING_ECS_BROKER_DEPLOY.md
T
ex_tianzy 2657146334 fix(deploy): preserve legacy environment and diagnose prepared plans safely
The old initializer defaults HN_ENVIRONMENT to development, while migration
validation required the literal production and combined database/platform
prerequisites into one opaque error. Preserve supported environment identity
namespaces without editing the live .env; still require PostgreSQL and fixed
HTTPS/WSS endpoints for every existing-server migration. Match supported
boolean spellings and report failing field names without credential values.

Add read-only diagnose for an existing prepared plan so an earlier failed
prepare can be reviewed without deleting or regenerating its keyring. Move
future prerequisite validation before private directory/key generation.

Validation: 253 passed, 3 skipped (real PostgreSQL unavailable), 30 existing
warnings; 40 deployment-tool tests including 11 new compatibility/redaction
cases. Python 3.7 syntax and staged diff checks pass. Actual ECS diagnosis
must still confirm the current failing field; no live config or key changed.
2026-11-04 13:59:22 +08:00

9.2 KiB
Raw Blame History

现有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. 现在可以执行:下载代码并只读预检查

如果目标暂存目录尚不存在:

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,选择一个尚不存在、位于运行目录之外的准备目录:

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或将凭据换一个身份空间。

先更新暂存仓库,再对已经生成的计划执行只读诊断:

sudo python3 deployable/scripts/broker_deploy.py diagnose \
  --plan /home/cnooc/hainuo-broker-prepared-20261104

只显示environment合法枚举、数据库类型及开关状态,不显示URL、账号密码、Secret或Token。通过后原地继续check,沿用原keyring和配置;若仍有错误按字段处理,不关闭HTTPS校验、不改用SQLite。新prepare在生成密钥前检查这些条件;旧目录因原检查失败留下的密钥不会被自动覆盖。

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是否即时撤销仍需实测。

在上述条件满足后,才允许:

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. 应急容器回退

若切换失败,先停止broker客户端继续使用,按记录的每服务镜像回退:

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拒绝,应先审阅差异,不用强制选项绕过。