Unify broker-mode binding changes in database transactions: advance device generation, invalidate pending authorizations/tasks and prior pairing-code epochs, and persist audit plus invalidation outbox. Add authenticated device unbind alongside robot/admin paths. Pairing codes are hashed, generation- fenced and consumed atomically with binding. Replay Redis invalidation effects without undoing committed unbind. Guard online cleanup and delayed kill events by generation. Introduce a separate router admission credential with no platform-event injection authority. Router verifies signed nonce-bound internal admission on handshake, task traffic and periodic checks; reject stale sessions and control-plane outages. Persist task owner/device/generation/session/worker and original message mapping. Sign routing metadata, verify late results, claim replies once and mark ambiguous/crashed tasks unknown instead of replaying writes. Fence notifications across same-user rebind. Release in-memory slots/waiters even when database or Redis cleanup fails. Validation: 213 passed, 3 skipped (real PostgreSQL not configured), 30 existing uvicorn/websockets deprecation warnings. New lifecycle coverage: 28 tests, including real loopback WebSocket isolation, reverse completion, missed kill, periodic unbind checks, outbox recovery, transaction rollback and cleanup failures. Syntax, docs and staged diff checks pass. Default legacy mode remains unchanged. Broker mode now requires coordinated router admission configuration and a v2 client handshake. No production ECS configuration, real credentials or client installer was changed. PostgreSQL, real Redis multi-node, ARM64 and actual Work/client rollout remain stage 5.
9.1 KiB
海诺中继服务部署项目
集中凭据改造按阶段交付,见 改造与阶段记录。阶段1/2已提供存储与刷新,阶段3新增显式broker模式的OAuth及认证领取接口,默认仍为legacy;v2接口契约包含签名、配置和兼容边界。尚未部署或发布新客户端,不能据此判断现网已切换。
阶段4新增权威解绑、连接准入和任务生命周期,broker模式要求router独立准入凭据及PC v2握手。默认legacy不变;部署接线和客户端适配未完成前不要直接切换生产模式。
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 天自签证书,客户端仍须显式信任该测试证书。不能作为正式证书交付。
私有化应用后台需配置:
- 机器人可用范围及消息接收事件
im.message.receive_v1,事件接收方式为 SDK 长连接。 - OAuth 回调为
${HN_PUBLIC_URL}/oauth/cb,例如https://relay.company.example/oauth/cb。 - 按实际业务启用日历、用户搜索、文档、知识库等权限;
.env.example的 scope 只是请求范围,不等于平台已经授予。 - 按平台规则让应用配置对测试用户生效,再由各用户完成本人授权。新增权限后可能需要重新授权。
配对码仍由用户在机器人中获取,再输入其 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。备份时会话及在途任务不作恢复保证,建议业务空闲时执行。
恢复必须在维护窗口进行:
- 校验备份
SHA256SUMS,保留当前数据的独立备份;确认镜像版本兼容。 - 停止本项目服务,向新的空目录恢复同版本源码,解压配置和密钥,按原样保留 UID 10001 权限;不要运行 init。
- 为隔离恢复测试设置新的 Compose 项目名、公开地址和端口;正式原机恢复保留原值。
- 启动 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。 - 再执行
check、start和业务验收。不要把 dump 直接灌入有业务数据的库;非空库覆盖恢复需要专门的维护方案。
备份脚本通过不代表恢复成功;当前恢复流程未在真实数据库上验收。
已知边界
- 新环境是新的设备 CA 与绑定数据库,已有 PC 不能默认沿用旧服务身份。迁移旧环境必须协调原 CA、连接器密钥、数据库及客户端地址,不能用首次初始化替代迁移。
- H5 是测试入口,尚未成为正式移动端产品。
- 用户 token 由本人授权获得;不把 tenant token 当用户 token,也不随代码交付。
- 文档/日历/联系人能力受应用权限、个人授权、平台版本及现有业务白名单限制,不保证任意平台 API 可调用。
- 自动注册没有逐台管理员审批;持包并能取得机器人配对码的范围由私有化应用可用范围控制。
- 不包含向量库、向量检索以及未经验证的新功能。