# 海诺中继服务部署项目 集中凭据改造按阶段交付,见 [改造与阶段记录](CREDENTIAL_MIGRATION.md)。阶段1已提供加密存储基础,阶段2已提供内部Broker与集中刷新;尚未接入公开OAuth/领取路由或改变当前客户端协议,不能据此判断现网已切换。 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 可调用。 - 自动注册没有逐台管理员审批;持包并能取得机器人配对码的范围由私有化应用可用范围控制。 - 不包含向量库、向量检索以及未经验证的新功能。