114 lines
2.4 KiB
Markdown
114 lines
2.4 KiB
Markdown
# 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 / 配对码明文
|
||
- 建议在生产环境开启结构化日志并保留最小必要字段
|