Files
ecs-relay-service/deployable
ex_tianzy 71b9678d22 feat(credentials): add stage 1 encrypted server-side credential storage
Introduce an opt-in AES-256-GCM credential store keyed by environment,
application and principal. Bind ciphertext to identity, version and key ID
with authenticated data; support retained decryption keys and active-key
rotation. Use expected-version CAS to reject duplicate or stale writers.

Keep token values and scopes encrypted at rest, hide token fields from
object repr, and use fixed errors without credential contents. Add tests
for identity substitution, authenticated tampering, wrong keys, rotation,
persistence, concurrent writers and malformed inputs. Include an opt-in
PostgreSQL test using an isolated schema.

Validation: 102 passed, 2 skipped (no real PostgreSQL URL), 15 existing
uvicorn/websockets deprecation warnings. Python AST and diff checks pass.

This is stage 1 only: no public routes or existing OAuth/refresh behavior
are changed, no production key/database is initialized, and no ECS
runtime deployment or real platform requests were performed. Broker,
centralized refresh, access-token-only issuance and unbind lifecycle
integration remain subsequent stages. See deployable/CREDENTIAL_MIGRATION.md.
2026-11-04 10:04:42 +08:00
..

海诺中继服务部署项目

集中凭据改造按阶段交付,见 改造与阶段记录。阶段1仅提供独立加密存储基础,未启用Token集中管理或更改当前客户端协议;不能据此判断现网已切换。

2026-10-28 新增客户端主动消息与授权卡片,本地代码已实现,现网部署和卡片验收待完成。

本目录用于新环境部署,源码对应 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 中平台地址是当前私有化环境默认值,其他单位必须替换。代理仅在本项目应用容器内禁用,不改宿主机代理。

一、取得代码和依赖

联网部署:

git clone git@git.yssing.cloud:ex_tianzy/ecs----.git
cd ecs----/deployable
bash scripts/relayctl.sh build online

内网部署:使用另行交付的完整离线包(含本目录最新代码、images/、wheelhouse/ 和校验文件),而不是旧版 0.1.0 离线包中的旧源码。

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,任何下载或版本失败会停止,不自动替换版本。

二、填写平台和网关配置

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 一致。

将组织认可的网关证书链和对应私钥放入:

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。

三、首次初始化及启动

# 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。当前本地 Windows 没有 Docker Engine,尚未完成此目录的干净 ARM64 主机部署验收;本地检查结果见 VALIDATION_REPORT.md。

五、日常维护

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 scripts/relayctl.sh update offline

脚本先备份,再给当前应用镜像打 hainuo-relay:rollback-时间 标签,然后构建和启动。失败会停下,旧镜像标签已打印;日志和备份保留,不自动猜测修复。离线升级不替换数据库/Redis基础镜像;如基础镜像更新,应单独安排维护。

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 可调用。
  • 自动注册没有逐台管理员审批;持包并能取得机器人配对码的范围由私有化应用可用范围控制。
  • 不包含向量库、向量检索以及未经验证的新功能。