Files
ecs-relay-service/deployable/EXISTING_ECS_BROKER_DEPLOY.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

143 lines
11 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;不写密钥、不构建、不重启。
兼容修订:原部署将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拒绝,应先审阅差异,不用强制选项绕过。