docs: add deployment and operations guides

OPERATIONS.md

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