# 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
```

确保子模块已更新：

```bash
git submodule update --init --recursive
```

---

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

### 3.1 安装与构建

```bash
cd Yonexus.Server
npm install
npm run build
```

### 3.2 配置

示例配置（OpenClaw 配置中）：

```json
{
  "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 安装与构建

```bash
cd Yonexus.Client
npm install
npm run build
```

### 4.2 配置

```json
{
  "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 分钟内可看到心跳日志/状态更新