142 lines
8.4 KiB
Markdown
142 lines
8.4 KiB
Markdown
# 海诺中继服务部署项目
|
||
|
||
本目录用于新环境部署,源码对应 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 可调用。
|
||
- 自动注册没有逐台管理员审批;持包并能取得机器人配对码的范围由私有化应用可用范围控制。
|
||
- 不包含向量库、向量检索以及未经验证的新功能。
|