Files
ecs-relay-service/deployable/EXISTING_ECS_BROKER_DEPLOY.md
T
ex_tianzy da1b4230b9 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.
2026-11-04 12:18:43 +08:00

104 lines
7.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 现有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拒绝,应先审阅差异,不用强制选项绕过。