Files
ecs-relay-service/deployable
ex_tianzy db116284b1 fix(deploy): keep broker credentials active during update rollback
Preserve broker environment and the active keyring mount when rolling application images back. Guard with update staging tests: 54 passed. No runtime services changed.
2026-11-04 18:16:53 +08:00
..

海诺中继服务部署项目

集中凭据改造按阶段交付,见 改造与阶段记录。阶段1/2已提供存储与刷新,阶段3新增显式broker模式的OAuth及认证领取接口,默认仍为legacy;v2接口契约包含签名、配置和兼容边界。尚未部署或发布新客户端,不能据此判断现网已切换。

阶段4新增权威解绑、连接准入和任务生命周期,broker模式要求router独立准入凭据及PC v2握手。默认legacy不变;部署接线和客户端适配未完成前不要直接切换生产模式。

已有ECS升级请使用保留现有部署的broker迁移指导,先运行只读preflight;工具可生成独立密钥和Compose叠加,构建候选但不自动启用。新客户端未就绪时不要使用activate,也不要重新init已有CA/数据库。

2026-10-28 新增客户端主动消息与授权卡片,本地代码已实现,现网部署和卡片验收待完成。

本目录用于新环境部署,源码对应 2026-10-27 ECS connector/router/longconn 导出版本。协议和业务源码保持原样。仓库其他快照目录用于追溯,不需要手工合并。

环境要求

  • Linux ARM64 是当前内网目标;Docker Engine、Compose 插件 v2.20+(支持 up --wait)。Docker 需由可信管理员操作。
  • 预留 443/TCP,客户端能访问该地址;服务器能直连私有化 Work HTTPS 和其返回的 WebSocket 地址。
  • PostgreSQL、Redis、自动签发服务只在 Docker 网络内开放;管理员接口仅绑定服务器回环地址 127.0.0.1:18081。
  • Docker 和 Compose 本身不包含在离线依赖包内。默认未设 platform,在线 AMD64 构建理论可用,但没有实际部署验收。
  • .env.example 中平台地址是当前私有化环境默认值,其他单位必须替换。代理仅在本项目应用容器内禁用,不改宿主机代理。

一、取得代码和依赖

联网部署:

git clone git@git.yssing.cloud:ex_tianzy/ecs----.git
cd ecs----/deployable
bash scripts/relayctl.sh build online

内网部署:使用另行交付的完整离线包(含本目录最新代码、images/、wheelhouse/ 和校验文件),而不是旧版 0.1.0 离线包中的旧源码。

tar -xzf hainuo-relay-deployable-arm64-20261027.tar.gz
cd hainuo-relay-deployable
bash scripts/load-offline.sh
bash scripts/relayctl.sh build offline

如需自行准备离线依赖,在联网的 Linux ARM64/Python 3.12 环境运行 bash scripts/prepare-offline.sh,任何下载或版本失败会停止,不自动替换版本。

二、填写平台和网关配置

umask 077
cp .env.example settings.env
chmod 600 settings.env
vi settings.env
mkdir -p runtime/tls
chmod 700 runtime/tls

必须填写 HN_PUBLIC_URL、平台 API/授权地址、App ID、App Secret。公网 URL 示例是占位符,初始化会拒绝。IP 地址可以使用,证书必须包含该 IP 的 SAN。非 443 时公开 URL 中的端口必须与 HN_HTTPS_PORT 一致。

将组织认可的网关证书链和对应私钥放入:

runtime/tls/server.pem
runtime/tls/server.key

证书必须匹配 HN_PUBLIC_URL 的主机名/IP,且在有效期内。初始化检查证书与私钥匹配、SAN、有效期;客户端信任链仍须按组织规范配置。不要关闭 TLS 校验。设备 CA 与 HTTPS 网关证书是两套用途不同的证书。

只做隔离测试时可使用后文 --test-cert;它生成 30 天自签证书,客户端仍须显式信任该测试证书。不能作为正式证书交付。

私有化应用后台需配置:

  1. 机器人可用范围及消息接收事件 im.message.receive_v1,事件接收方式为 SDK 长连接。
  2. OAuth 回调为 ${HN_PUBLIC_URL}/oauth/cb,例如 https://relay.company.example/oauth/cb。
  3. 按实际业务启用日历、用户搜索、文档、知识库等权限;.env.example 的 scope 只是请求范围,不等于平台已经授予。
  4. 按平台规则让应用配置对测试用户生效,再由各用户完成本人授权。新增权限后可能需要重新授权。

配对码仍由用户在机器人中获取,再输入其 Windows Work 连接组件;Windows 安装包单独交付,本目录不会安装桌面 Agent。

三、首次初始化及启动

# offline 换成 online 即联网模式;不需要联网下载时必须用 offline。
bash scripts/relayctl.sh init offline
bash scripts/relayctl.sh check offline
bash scripts/relayctl.sh start offline
bash scripts/relayctl.sh status offline
bash scripts/relayctl.sh logs offline longconn connector

仅测试且未提供证书时:bash scripts/relayctl.sh init offline --test-cert。

初始化容器以 root 运行一次,为服务 UID 10001 设置私钥权限;常驻应用以 UID 10001 运行。生成新密码、设备 CA、连接器签名密钥和 .env,不输出凭据。自动签发 CA 私钥仅挂载到内部签发服务,connector/router 无法读取。不要重复初始化;已有 .env 或连接器私钥时拒绝覆盖。中途失败需先检查部分生成文件,不要在已有业务的目录中删除密钥后重新初始化。

默认镜像名 hainuo-relay:deploy-20261027。自定义镜像名时首次构建及初始化命令设置相同 HN_BUILD_IMAGE,并在 settings.env 中设置相同 HN_IMAGE;后续构建读取 .env 中的 HN_IMAGE。

start 的成功表示容器健康检查通过,不代表机器人和 PC 业务成功。日志应出现 platform_connected,然后必须完成验收清单。

四、验收

参见 ACCEPTANCE.md。当前本地 Windows 没有 Docker Engine,尚未完成此目录的干净 ARM64 主机部署验收;本地检查结果见 VALIDATION_REPORT.md。

五、日常维护

bash scripts/relayctl.sh status offline
bash scripts/relayctl.sh logs offline longconn connector router
bash scripts/relayctl.sh stop offline
bash scripts/relayctl.sh start offline
bash scripts/relayctl.sh backup offline

停止不会删除数据库卷。不要执行 docker compose down -v,这会删除元数据卷。无需重复传递多份历史 Compose override,统一配置在本目录 compose.yaml。

配置修改:保留 .env 备份,在服务器修改 .env 后重新 check、start。settings.env 只在首次初始化读取,修改它不会更新已有 .env。不得修改已有数据库密码而不同时修改 PostgreSQL 中的角色密码;不得重新生成 CA 或连接器密钥来处理普通配置问题。

六、升级与回滚

保留 .env、runtime/、backups/ 和数据库卷,将新源码与匹配依赖放入当前部署目录后执行:

bash scripts/relayctl.sh update offline

脚本先备份,再给当前应用镜像打 hainuo-relay:rollback-时间 标签,然后构建和启动。失败会停下,旧镜像标签已打印;日志和备份保留,不自动猜测修复。离线升级不替换数据库/Redis基础镜像;如基础镜像更新,应单独安排维护。

bash scripts/relayctl.sh rollback offline hainuo-relay:rollback-实际时间

回滚后按提示把 .env 的 HN_IMAGE 改成旧镜像标签,再检查业务。此操作只回滚应用镜像,不回滚配置、数据库结构或已有数据;涉及数据库变更时需遵循版本迁移说明和恢复流程,不能直接承诺镜像回滚兼容。

七、备份和恢复

backup 使用 PostgreSQL 自洽逻辑转储,并归档 .env 与 runtime/,保存到 backups/时间/。这些备份含真实密钥及 App Secret,权限 700/600,必须加密保管;不要上传 Git。备份时会话及在途任务不作恢复保证,建议业务空闲时执行。

恢复必须在维护窗口进行:

  1. 校验备份 SHA256SUMS,保留当前数据的独立备份;确认镜像版本兼容。
  2. 停止本项目服务,向新的空目录恢复同版本源码,解压配置和密钥,按原样保留 UID 10001 权限;不要运行 init。
  3. 为隔离恢复测试设置新的 Compose 项目名、公开地址和端口;正式原机恢复保留原值。
  4. 启动 PostgreSQL:docker compose -f compose.yaml -f compose.offline.yaml up -d postgres;等待健康后向空数据库恢复:docker compose -f compose.yaml -f compose.offline.yaml exec -T postgres pg_restore -U hainuo -d hainuo --no-owner --exit-on-error < backups/实际时间/metadata.dump。
  5. 再执行 check、start 和业务验收。不要把 dump 直接灌入有业务数据的库;非空库覆盖恢复需要专门的维护方案。

备份脚本通过不代表恢复成功;当前恢复流程未在真实数据库上验收。

已知边界

  • 新环境是新的设备 CA 与绑定数据库,已有 PC 不能默认沿用旧服务身份。迁移旧环境必须协调原 CA、连接器密钥、数据库及客户端地址,不能用首次初始化替代迁移。
  • H5 是测试入口,尚未成为正式移动端产品。
  • 用户 token 由本人授权获得;不把 tenant token 当用户 token,也不随代码交付。
  • 文档/日历/联系人能力受应用权限、个人授权、平台版本及现有业务白名单限制,不保证任意平台 API 可调用。
  • 自动注册没有逐台管理员审批;持包并能取得机器人配对码的范围由私有化应用可用范围控制。
  • 不包含向量库、向量检索以及未经验证的新功能。