docs: add deployment and operations guides

DEPLOYMENT.md

@@ -0,0 +1,123 @@
+# 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 分钟内可看到心跳日志/状态更新