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