Files
ecs-relay-service/deployment-source/docs/DEPLOY_LINUX_ARM64.md

212 lines
9.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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九关。