9.2 KiB
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。以下命令均在该目录执行。
uname -m
getconf PAGESIZE
docker version
docker compose version
2. 初始化
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实际可达地址,使用公司认可的服务器证书替换:
runtime/tls/server.pem # 服务器证书及中间链
runtime/tls/server.key # 对应私钥
测试自签证书时,必须在PC上显式信任该测试证书或通过CLI的 --tls-ca server.pem 指定;不要禁用证书校验。
设备CA是设备身份用途,与浏览器HTTPS信任不是同一件事。不要以“PC设备证书已签发”代替“手机信任网页证书”。
4. 启动与检查
bash scripts/start.sh
bash scripts/verify_deployment.sh
docker compose ps
默认启动五个容器:edge、connector、router、postgres、redis。官方SDK长连接作为可选第六个容器。
# 不显示密钥,直接在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适配器的真实验证命令:
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生成公钥申请
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。
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,然后:
docker compose exec connector python -m relay.cli register \
--registration /data/registration-a.json --url http://127.0.0.1:8000
该文件只有证书和设备ID,没有私钥。登记成功后可移出服务数据目录保管。
5.4 生成模拟账号绑定码
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执行并在隐藏输入框输入绑定码:
python -m relay.cli bind --directory D:\HainuoRelayDevice --url https://relay.company.example
# 若仍使用测试自签证书,上面命令额外加 --tls-ca D:\certs\server.pem。
5.5 启动桥接端
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发起测试
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:
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中集中适配;不要直接改为公有云地址试错。
平台侧:
- 创建/选择机器人应用,开通私聊消息接收和回复所需权限,发布版本并限制试点可见范围。
- 用户文档授权权限与机器人权限分开核对;不能把“tenant权限全空”直接套到需要应用身份回复消息的机器人。
- OAuth重定向地址配置为
https://入口域名/oauth/cb。 - 在以下事件源中选择一个,不要同时启用后再依赖去重掩盖配置错误。
方式A:长连接(领导方案过渡态)
后台选择长连接,订阅 im.message.receive_v1:
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接口。若本地海诺适配层实现了协议中的只读HTTP接口,启动时增加:
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. 维护、备份、停用
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九关。