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

150 lines
9.4 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.
# 海诺中继服务部署项目
集中凭据改造按阶段交付,见 [改造与阶段记录](CREDENTIAL_MIGRATION.md)。阶段1/2已提供存储与刷新,阶段3新增显式broker模式的OAuth及认证领取接口,默认仍为legacy;[v2接口契约](CREDENTIAL_PROTOCOL_V2.md)包含签名、配置和兼容边界。尚未部署或发布新客户端,不能据此判断现网已切换。
阶段4新增[权威解绑、连接准入和任务生命周期](BINDING_TASK_LIFECYCLE.md),broker模式要求router独立准入凭据及PC v2握手。默认legacy不变;部署接线和客户端适配未完成前不要直接切换生产模式。
已有ECS升级请使用[保留现有部署的broker迁移指导](EXISTING_ECS_BROKER_DEPLOY.md),先运行只读preflight;工具可生成独立密钥和Compose叠加,构建候选但不自动启用。新客户端未就绪时不要使用activate,也不要重新init已有CA/数据库。
2026-10-28 新增[客户端主动消息与授权卡片](NOTIFICATIONS.md),本地代码已实现,现网部署和卡片验收待完成。
本目录用于新环境部署,源码对应 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` 中平台地址是当前私有化环境默认值,其他单位必须替换。代理仅在本项目应用容器内禁用,不改宿主机代理。
## 一、取得代码和依赖
联网部署:
```bash
git clone git@git.yssing.cloud:ex_tianzy/ecs----.git
cd ecs----/deployable
bash scripts/relayctl.sh build online
```
内网部署:使用另行交付的完整离线包(含本目录最新代码、`images/`、`wheelhouse/` 和校验文件),而不是旧版 0.1.0 离线包中的旧源码。
```bash
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`,任何下载或版本失败会停止,不自动替换版本。
## 二、填写平台和网关配置
```bash
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` 一致。
将组织认可的网关证书链和对应私钥放入:
```text
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。
## 三、首次初始化及启动
```bash
# 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](ACCEPTANCE.md)。当前本地 Windows 没有 Docker Engine,尚未完成此目录的干净 ARM64 主机部署验收;本地检查结果见 [VALIDATION_REPORT.md](VALIDATION_REPORT.md)。
## 五、日常维护
```bash
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
bash scripts/relayctl.sh update offline
```
脚本先备份,再给当前应用镜像打 `hainuo-relay:rollback-时间` 标签,然后构建和启动。失败会停下,旧镜像标签已打印;日志和备份保留,不自动猜测修复。离线升级不替换数据库/Redis基础镜像;如基础镜像更新,应单独安排维护。
```bash
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 可调用。
- 自动注册没有逐台管理员审批;持包并能取得机器人配对码的范围由私有化应用可用范围控制。
- 不包含向量库、向量检索以及未经验证的新功能。