# 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九关。