Files
ecs-relay-service/deployable/README.md
T
ex_tianzy 02d433250f feat(credentials): add stage 2 centralized broker and refresh fencing
Add an internal CredentialBroker that serializes refresh and authorization
by environment/app/user using renewable Redis leases. Re-read credentials
under the lease and persist rotated pairs with expected-version CAS before
returning an explicit access-only grant. Verify the actual platform user,
remaining lifetime and scopes; never return refresh tokens from the broker.

Persist source-version refresh attempts before platform calls. Timeouts,
cancellation, lease loss, malformed responses and ambiguous database errors
fence reuse of the old rotating refresh token, including after restart.
A new authorization can establish a new version without stale overwrite.

Add a strict, separate private Work v1 OIDC adapter while preserving legacy
OAuth method behavior. Enable fakeredis Lua test support for Redis lease
renewal tests. Document stage boundaries, recovery limitations and testing.

Validation: 147 passed, 2 skipped (real PostgreSQL not configured), with
15 existing uvicorn/websockets deprecation warnings. New broker/adapter
coverage: 45 tests. AST, runtime opt-in boundary and diff checks pass.
An earlier Windows temp-file replace failure in a legacy client test passed
both isolated rerun and the final full suite; no client code was changed.

No public credential/OAuth routes are wired, no production database/key is
initialized, and no real Work authorization, refresh or ECS deployment was
performed. Authenticated access-token issuance, state transactions, binding
checks and unbind integration remain subsequent stages.
2026-11-04 10:30:27 +08:00

146 lines
8.8 KiB
Markdown
Raw 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.
# 海诺中继服务部署项目
集中凭据改造按阶段交付,见 [改造与阶段记录](CREDENTIAL_MIGRATION.md)。阶段1已提供加密存储基础,阶段2已提供内部Broker与集中刷新;尚未接入公开OAuth/领取路由或改变当前客户端协议,不能据此判断现网已切换。
2026-10-28 新增[客户端主动消息与授权卡片](NOTIFICATIONS.md),本地代码已实现,现网部署和卡片验收待完成。
本目录用于新环境部署,源码对应 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` 中平台地址是当前私有化环境默认值,其他单位必须替换。代理仅在本项目应用容器内禁用,不改宿主机代理。
## 一、取得代码和依赖
联网部署:
```bash
git clone git@git.yssing.cloud:ex_tianzy/ecs----.git
cd ecs----/deployable
bash scripts/relayctl.sh build online
```
内网部署:使用另行交付的完整离线包(含本目录最新代码、`images/`、`wheelhouse/` 和校验文件),而不是旧版 0.1.0 离线包中的旧源码。
```bash
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`,任何下载或版本失败会停止,不自动替换版本。
## 二、填写平台和网关配置
```bash
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` 一致。
将组织认可的网关证书链和对应私钥放入:
```text
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。
## 三、首次初始化及启动
```bash
# 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](ACCEPTANCE.md)。当前本地 Windows 没有 Docker Engine,尚未完成此目录的干净 ARM64 主机部署验收;本地检查结果见 [VALIDATION_REPORT.md](VALIDATION_REPORT.md)。
## 五、日常维护
```bash
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
bash scripts/relayctl.sh update offline
```
脚本先备份,再给当前应用镜像打 `hainuo-relay:rollback-时间` 标签,然后构建和启动。失败会停下,旧镜像标签已打印;日志和备份保留,不自动猜测修复。离线升级不替换数据库/Redis基础镜像;如基础镜像更新,应单独安排维护。
```bash
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 可调用。
- 自动注册没有逐台管理员审批;持包并能取得机器人配对码的范围由私有化应用可用范围控制。
- 不包含向量库、向量检索以及未经验证的新功能。