Yonexus/DEPLOYMENT.md

Yonexus 部署指南 (v1)

本指南面向 单主多从 拓扑：

• 主节点：运行 Yonexus.Server
• 从节点：运行 Yonexus.Client

说明：Yonexus 采用三仓库/子模块结构（Umbrella + Server + Client + Protocol）。

---

1. 拓扑与前置条件

• 主节点需要可被从节点访问的稳定地址（域名或固定 IP）
• 从节点只需能 outbound 访问主节点 WebSocket
• 需要一个 Discord Bot Token，用于向管理员 DM 配对码
• 需要管理员的 Discord User ID

---

2. 仓库结构与同步

在 umbrella 仓库内：

Yonexus/
├── Yonexus.Server
├── Yonexus.Client
├── Yonexus.Protocol

确保子模块已更新：

git submodule update --init --recursive

---

3. 主节点部署（Yonexus.Server）

3.1 安装与构建

cd Yonexus.Server
npm install
npm run build

3.2 配置

示例配置（OpenClaw 配置中）：

{
  "followerIdentifiers": ["client-a", "client-b"],
  "notifyBotToken": "<discord-bot-token>",
  "adminUserId": "123456789012345678",
  "listenHost": "0.0.0.0",
  "listenPort": 8787,
  "publicWsUrl": "wss://example.com/yonexus"
}

3.3 启动

• 将 Yonexus.Server 安装为 OpenClaw 插件
• 启动 OpenClaw Gateway 后，Server 会自动启动 WebSocket 服务

---

4. 从节点部署（Yonexus.Client）

4.1 安装与构建

cd Yonexus.Client
npm install
npm run build

4.2 配置

{
  "mainHost": "wss://example.com/yonexus",
  "identifier": "client-a",
  "notifyBotToken": "<discord-bot-token>",
  "adminUserId": "123456789012345678"
}

4.3 启动

• 将 Yonexus.Client 安装为 OpenClaw 插件
• 启动 OpenClaw Gateway 后，Client 会自动连接 Server

---

5. 首次配对流程

1. Client 连接后发送 hello
2. Server 检测未配对，生成配对码
3. Server 通过 Discord DM 将配对码发送给管理员
4. 管理员将配对码转交给 Client 操作员
5. Client 提交 pair_confirm 完成配对
6. Server 返回 pair_success 并下发 secret
7. Client 进入认证流程并开始心跳

---

6. 版本与兼容性

• 协议版本：1
• 需要确保 Yonexus.Protocol 子模块与 Server/Client 使用的协议一致

---

7. 快速验证建议

• 主节点启动后确认 WebSocket 监听端口可达
• 从节点能建立连接且收到 hello_ack
• 配对完成后收到 auth_success
• 5 分钟内可看到心跳日志/状态更新