Yonexus/OPERATIONS.md

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