Import ECS deployed relay source and historical patches (2026-10-27)

This commit is contained in:
ex_tianzy
2026-10-27 17:26:58 +08:00
commit 011a7797ee
319 changed files with 34265 additions and 0 deletions
@@ -0,0 +1,211 @@
# Linux ARM64单机部署操作手册
## 1. 环境要求和目录
- Linux `aarch64/arm64`,推荐4核8GB、40GB可用盘起步做两人两机联调;不是50人容量保证。
- Docker Engine及Compose v2;能拉取镜像、访问Python依赖源。使用原生ARM64镜像,不强制amd64模拟。
- 默认容器基础是Debian bookworm/glibc。已下载核验Python3.12 ARM64 wheels;麒麟等宿主机仍须实际运行验证,尤其64KiB页内核。
- 安全组只开放业务需要的443;SSH限制管理来源。18081仅绑定服务器127.0.0.1,不开放到公网。
- PC能够出站访问ECS的443;平台事件源或ECS到平台的网络按所选接入方式打通。
将源码包解压到 `/opt/hainuo-relay`。以下命令均在该目录执行。
```bash
uname -m
getconf PAGESIZE
docker version
docker compose version
```
## 2. 初始化
```bash
bash scripts/bootstrap.sh relay.company.example
```
替换域名为你们实际提供的入口。脚本构建镜像并生成:
- `.env`:随机管理员凭据、内部调用凭据、Redis和PostgreSQL密码;不会回显。
- `runtime/connector/connector.key`:B1签名私钥,只挂载给B1。
- `runtime/trust/ca.pem`、`connector.pub`:设备CA与连接器信任公钥。
- `runtime/tls/server.pem`、`server.key`:30天测试自签TLS证书。
- `operator/ca.key`:设备CA私钥,仅供签发工作站使用,不挂载容器。初始化后移至离线签发工作站,并保留该工作站需要的ca.pem和connector.pub;不要放在公网业务目录或普通备份中。
初始化拒绝覆盖已有文件和密钥;失败后不要直接再次初始化覆盖半成品,先检查已生成内容。
配置前建议 `chmod 600 .env`。不要把 `.env` 或CA私钥发群聊。
## 3. TLS和域名
将入口DNS指向ECS实际可达地址,使用公司认可的服务器证书替换:
```text
runtime/tls/server.pem # 服务器证书及中间链
runtime/tls/server.key # 对应私钥
```
测试自签证书时,必须在PC上显式信任该测试证书或通过CLI的 `--tls-ca server.pem` 指定;不要禁用证书校验。
设备CA是设备身份用途,与浏览器HTTPS信任不是同一件事。不要以“PC设备证书已签发”代替“手机信任网页证书”。
## 4. 启动与检查
```bash
bash scripts/start.sh
bash scripts/verify_deployment.sh
docker compose ps
```
默认启动五个容器:edge、connector、router、postgres、redis。官方SDK长连接作为可选第六个容器。
```bash
# 不显示密钥,直接在B1容器内查看设备元数据。
docker compose exec connector python -m relay.cli status --url http://127.0.0.1:8000
```
`/health`证明进程活着;`/ready`还检查依赖和回复订阅线程。二者都不代表海能Work联调通过。
本机环境没有Docker,交付前只完成Compose结构检查与shell语法检查;目标ECS必须实际执行上面步骤。PostgreSQL适配器的真实验证命令:
```bash
docker compose -f compose.yaml -f compose.acceptance.yaml run --rm acceptance
```
该用例只在数据库中新建随机 `hn_test_*` schema,结束时删除该测试schema,不操作已有业务表。
## 5. 第一次不接平台,先接两台PC
PC安装Python3.12及本项目依赖,执行后续命令。每台PC必须生成自己的设备目录,禁止复制别人设备的私钥。
### 5.1 PC生成公钥申请
```powershell
python -m relay.cli device-request --directory D:\HainuoRelayDevice
```
得到 `device.key` 和 `request.json`。只将request.json交给签发工作站。
### 5.2 签发工作站签证书
签发工作站的项目目录需要保存 `operator/ca.key`、`runtime/trust/ca.pem`、`runtime/trust/connector.pub`。
```bash
python -m relay.cli issue-device --root . --request request.json --output issued-device-a
```
将输出的 `device.pem`、`ca.pem`、`connector.pub`、`device.json`交回原PC设备目录。设备私钥不经过服务器。
### 5.3 ECS登记证书
将 `registration.json`临时放到ECS,例如 `runtime/connector/registration-a.json`,然后:
```bash
docker compose exec connector python -m relay.cli register \
--registration /data/registration-a.json --url http://127.0.0.1:8000
```
该文件只有证书和设备ID,没有私钥。登记成功后可移出服务数据目录保管。
### 5.4 生成模拟账号绑定码
```bash
docker compose exec connector python -m relay.cli binding-code \
--owner ou_test_a --url http://127.0.0.1:8000
```
绑定码在受控管理终端显示,五分钟有效,一次使用。这是development/test专用;production环境不开放。
PC执行并在隐藏输入框输入绑定码:
```powershell
python -m relay.cli bind --directory D:\HainuoRelayDevice --url https://relay.company.example
# 若仍使用测试自签证书,上面命令额外加 --tls-ca D:\certs\server.pem。
```
### 5.5 启动桥接端
```powershell
python -m relay.cli device --directory D:\HainuoRelayDevice --url wss://relay.company.example/device/ws --test-root D:\HainuoRelayTestFiles
```
测试目录由你自己创建,先放一个无敏感内容的UTF-8文本文件。桥接端以当前普通用户运行;不要使用SYSTEM或管理员账号扩展文件权限。
另一台PC重复上述步骤,绑定 `ou_test_b`。
### 5.6 从ECS发起测试
```bash
docker compose exec connector python -m relay.cli dispatch \
--owner ou_test_a --text '/回显 A机链路通过' --turn-id test-a-001 --url http://127.0.0.1:8000
docker compose exec connector python -m relay.cli dispatch \
--owner ou_test_b --text '/主机名' --turn-id test-b-001 --url http://127.0.0.1:8000
```
重复同一turn-id应返回duplicate;断开PC应返回offline;超时返回unknown,表示结果不确定,不自动重新执行。
## 6. 接海能Work
编辑 `.env`:
```dotenv
HN_FEISHU_ENABLED=true
HN_FEISHU_API_BASE=https://实际私有化开放平台域名
HN_FEISHU_AUTHORIZE_URL=https://实际授权页完整路径
HN_FEISHU_APP_ID=实际应用ID
HN_FEISHU_APP_SECRET=单独渠道取得的密钥
HN_FEISHU_ENCRYPT_KEY=实际事件加密密钥
HN_FEISHU_VERIFICATION_TOKEN=实际校验Token
```
本版默认适配材料中的legacy OIDC接口:`auth/v3/app_access_token/internal`、`authen/v1/oidc/access_token`、`authen/v1/oidc/refresh_access_token`、`authen/v1/user_info`。机器人回复使用单独缓存的tenant_access_token,不把OAuth的app_access_token混用于消息API。实际私有化版本若不同,在 `relay/platform.py`中集中适配;不要直接改为公有云地址试错。
平台侧:
1. 创建/选择机器人应用,开通私聊消息接收和回复所需权限,发布版本并限制试点可见范围。
2. 用户文档授权权限与机器人权限分开核对;不能把“tenant权限全空”直接套到需要应用身份回复消息的机器人。
3. OAuth重定向地址配置为 `https://入口域名/oauth/cb`。
4. 在以下事件源中选择一个,不要同时启用后再依赖去重掩盖配置错误。
### 方式A:长连接(领导方案过渡态)
后台选择长连接,订阅 `im.message.receive_v1`:
```bash
docker compose up -d --force-recreate connector
docker compose --profile longconn up -d longconn
```
使用官方lark-oapi SDK支持的 `domain`参数,明确指向私有化平台;SDK日志关闭以防打印连接URL或正文。单Redis租约防止重复消费者。SDK实际建立连接、私有化平台消息格式和频控必须实测。
### 方式B:webhook
配置回调为 `https://入口域名/feishu/event`,要求请求签名、时间戳、校验Token及配置的加密参数一致。支持加密事件;校验失败拒绝,不开放绕过开关。
用户分别私聊机器人 `/绑定`,在自己PC输入绑定码,再发送 `/主机名`、`/回显 内容`。
## 7. 本地海诺Agent对接
默认桥接端不猜测1.065接口。若本地海诺适配层实现了[协议](PROTOCOL.md)中的只读HTTP接口,启动时增加:
```powershell
python -m relay.cli device --directory D:\HainuoRelayDevice --url wss://relay.company.example/device/ws --agent-url http://127.0.0.1:8765/relay/read-only
```
此时 `/助手 整理测试文件`才调用固定回环地址。Agent侧必须真实限制工具与文件权限;`read_only:true`字段本身不能阻止一个拥有写权限的Agent写文件。
## 8. 维护、备份、停用
```bash
docker compose logs --tail 100 connector router
# 不开access log/debug,不采集请求体、令牌或SDK明文事件。
docker compose exec connector python -m relay.cli revoke --host-id 实际32位host_id --url http://127.0.0.1:8000
docker compose exec -T postgres pg_dump -U hainuo -d hainuo -Fc > metadata-backup.dump
# 恢复演练使用独立测试数据库,核对设备数、绑定与吊销状态;不要覆盖现有数据库。
docker compose restart connector
```
Redis不落盘;重启后在线状态重建,B1从持久库恢复准入/吊销数据。若需要手动同步,运行 `reconcile`子命令。
B1密钥、数据库和CA分别制定备份策略;不能把整个runtime打包当普通日志发出。不能只用 `docker compose down`冒充备份;不要执行 `down -v`删除元数据卷。
切换 `HN_ENVIRONMENT=production`会禁用模拟绑定码和模拟派发API。切换前必须替换测试TLS证书、配置真实平台并完成两人两机验收;该开关不代表项目自动满足P0九关。