feat(deploy): add guarded existing-ECS broker migration tooling

Discover the current Compose project and all override files from container
labels. Add read-only preflight plus prepare/check/build/activate/rollback
commands without editing the running .env, CA, database volumes or unrelated
services. Preserve heterogeneous application image identities for rollback.

Prepare a private keyring, independent router credential, pinned source
snapshot and additive connector/router overlay. Refuse key overwrite and
configuration/image drift. Build offline from the exact existing ARM64
runtime, smoke import and validate role settings through stdin-only inputs.
Require explicit v2 client readiness before activation and recreate only
connector/router with --no-deps. Document actual backup/image evidence,
current client limitation and token-lifecycle rollback boundaries.

Validation: 239 passed, 3 skipped (real PostgreSQL absent), 30 existing
dependency deprecation warnings. Add 26 mocked Docker policy tests; host
script parses as Python 3.7, CLI help/docs/diff checks pass. Docker policy
mocks are not actual Compose or ARM64 build validation.

No remote files, keys, credentials, containers or live configuration were
changed. Stage 5 operational acceptance remains pending actual ECS build,
real databases/platform, v2 client, key recovery and controlled rollout.
This commit is contained in:
ex_tianzy
2026-11-04 12:18:43 +08:00
parent d1ab834ecb
commit da1b4230b9
6 changed files with 778 additions and 1 deletions
+103
View File
@@ -0,0 +1,103 @@
# 现有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;不写密钥、不构建、不重启。
**当前客户端尚未适配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. 检查与离线构建:仍不切换
```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. 应急容器回退
若切换失败,先停止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拒绝,应先审阅差异,不用强制选项绕过。