docs: add deployment and operations guides
This commit is contained in:
123
DEPLOYMENT.md
Normal file
123
DEPLOYMENT.md
Normal file
@@ -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 分钟内可看到心跳日志/状态更新
|
||||||
113
OPERATIONS.md
Normal file
113
OPERATIONS.md
Normal file
@@ -0,0 +1,113 @@
|
|||||||
|
# Yonexus 运维与排障指南 (v1)
|
||||||
|
|
||||||
|
本指南覆盖常见运行状态、错误码与恢复步骤。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 运行状态速览
|
||||||
|
|
||||||
|
### Client 侧状态
|
||||||
|
- `connecting`：正在连接
|
||||||
|
- `pairing_required`：需要配对
|
||||||
|
- `waiting_pair_confirm`：等待提交配对码
|
||||||
|
- `authenticating`：认证中
|
||||||
|
- `authenticated`：已认证，心跳中
|
||||||
|
|
||||||
|
### Server 侧状态
|
||||||
|
- `online`：已认证且心跳正常
|
||||||
|
- `unstable`：7 分钟未收到心跳
|
||||||
|
- `offline`：11 分钟未收到心跳，已断开连接
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 常见问题与处理
|
||||||
|
|
||||||
|
### 2.1 Client 无法连接 Server
|
||||||
|
**可能原因**
|
||||||
|
- `mainHost` 配置错误
|
||||||
|
- Server 未启动或端口不可达
|
||||||
|
|
||||||
|
**处理**
|
||||||
|
- 检查 `mainHost` 是否为 `ws://` 或 `wss://`
|
||||||
|
- 验证 Server 监听端口是否对外开放
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.2 Client 一直停在 `pairing_required`
|
||||||
|
**可能原因**
|
||||||
|
- Server 未能发送 Discord DM
|
||||||
|
- `notifyBotToken` 或 `adminUserId` 配置错误
|
||||||
|
|
||||||
|
**处理**
|
||||||
|
- 检查 Server 日志是否出现 `admin_notification_failed`
|
||||||
|
- 确认 Bot 有向目标用户发送 DM 的权限
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.3 配对码无效 / 过期
|
||||||
|
**可能原因**
|
||||||
|
- 输入错误
|
||||||
|
- 配对码超过 TTL
|
||||||
|
|
||||||
|
**处理**
|
||||||
|
- 重新触发配对流程（断线后重连）
|
||||||
|
- 确保管理员转发的配对码最新
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.4 认证失败 (`auth_failed`)
|
||||||
|
**可能原因**
|
||||||
|
- Secret 不匹配
|
||||||
|
- 时间漂移过大
|
||||||
|
- Nonce 重放或格式错误
|
||||||
|
|
||||||
|
**处理**
|
||||||
|
- 检查系统时间是否正确
|
||||||
|
- 清除 Client 本地 secret，触发重新配对
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.5 频繁触发 `re_pair_required`
|
||||||
|
**可能原因**
|
||||||
|
- 非法重放或高频认证尝试
|
||||||
|
- Client 有并发连接/重连异常
|
||||||
|
|
||||||
|
**处理**
|
||||||
|
- 确认同一 `identifier` 只存在一个活跃 Client
|
||||||
|
- 检查 Client 是否重复启动多个实例
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 错误码参考
|
||||||
|
|
||||||
|
常见协议错误码：
|
||||||
|
- `MALFORMED_MESSAGE`
|
||||||
|
- `UNSUPPORTED_PROTOCOL_VERSION`
|
||||||
|
- `IDENTIFIER_NOT_ALLOWED`
|
||||||
|
- `PAIRING_REQUIRED`
|
||||||
|
- `PAIRING_EXPIRED`
|
||||||
|
- `ADMIN_NOTIFICATION_FAILED`
|
||||||
|
- `AUTH_FAILED`
|
||||||
|
- `NONCE_COLLISION`
|
||||||
|
- `RATE_LIMITED`
|
||||||
|
- `RE_PAIR_REQUIRED`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 恢复步骤建议
|
||||||
|
|
||||||
|
**场景：Client 无法恢复认证**
|
||||||
|
1. 停止 Client
|
||||||
|
2. 删除本地 state 中的 secret
|
||||||
|
3. 重启 Client 触发重新配对
|
||||||
|
|
||||||
|
**场景：Server 端状态异常**
|
||||||
|
1. 检查持久化 store 文件是否损坏
|
||||||
|
2. 必要时备份后清理 store 文件（会导致所有 Client 重新配对）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 日志建议
|
||||||
|
|
||||||
|
- Server 日志中应避免输出 secret / 配对码明文
|
||||||
|
- 建议在生产环境开启结构化日志并保留最小必要字段
|
||||||
12
TASKLIST.md
12
TASKLIST.md
@@ -1065,13 +1065,25 @@
|
|||||||
- 已明确当前限制项（测试、配对输入 UX、生命周期集成等），方便后续交接和联调
|
- 已明确当前限制项（测试、配对输入 UX、生命周期集成等），方便后续交接和联调
|
||||||
|
|
||||||
### YNX-1203 输出部署文档
|
### YNX-1203 输出部署文档
|
||||||
|
**状态**
|
||||||
|
- [x] 已完成（2026-04-08）
|
||||||
|
|
||||||
**目标**
|
**目标**
|
||||||
- 写清楚单主多从部署方式、配置示例、配对流程
|
- 写清楚单主多从部署方式、配置示例、配对流程
|
||||||
|
|
||||||
|
**已完成内容**
|
||||||
|
- 新增 `DEPLOYMENT.md`，覆盖拓扑、子模块同步、Server/Client 安装、配置示例与配对流程
|
||||||
|
|
||||||
### YNX-1204 输出运维排障文档
|
### YNX-1204 输出运维排障文档
|
||||||
|
**状态**
|
||||||
|
- [x] 已完成（2026-04-08）
|
||||||
|
|
||||||
**目标**
|
**目标**
|
||||||
- 写清楚常见报错、状态含义、恢复步骤
|
- 写清楚常见报错、状态含义、恢复步骤
|
||||||
|
|
||||||
|
**已完成内容**
|
||||||
|
- 新增 `OPERATIONS.md`，覆盖状态说明、常见错误与恢复建议
|
||||||
|
|
||||||
### YNX-1205 输出协议测试与验收清单
|
### YNX-1205 输出协议测试与验收清单
|
||||||
**状态**
|
**状态**
|
||||||
- [x] 已完成（2026-04-08）
|
- [x] 已完成（2026-04-08）
|
||||||
|
|||||||
Reference in New Issue
Block a user