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.
海诺中继服务部署项目
集中凭据改造按阶段交付,见 改造与阶段记录。阶段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 天自签证书,客户端仍须显式信任该测试证书。不能作为正式证书交付。
私有化应用后台需配置:
- 机器人可用范围及消息接收事件
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 可调用。
- 自动注册没有逐台管理员审批;持包并能取得机器人配对码的范围由私有化应用可用范围控制。
- 不包含向量库、向量检索以及未经验证的新功能。