# WXAuto Center 常见问题与解决方案

## 概述

本文档收集了 WXAuto Center 使用过程中可能遇到的常见问题及其解决方案。

---

## 1. 服务启动问题

### 1.1 端口被占用

**问题描述**：

```
Error: [Errno 48] Address already in use
```

**可能原因**：
- 另一个进程正在使用 8080 端口
- 上一次启动的服务未正常关闭

**解决方案**：

```bash
# 查找占用端口的进程
lsof -i :8080  # macOS
# 或
netstat -tlnp | grep 8080  # Linux

# 终止占用进程
kill -9 <PID>

# 或使用其他端口启动
# 修改 config.json 中 port 为其他值，如 8081
```

### 1.2 依赖库安装失败

**问题描述**：

```
ModuleNotFoundError: No module named 'fastapi'
```

**解决方案**：

```bash
# 确保使用 Python 3.8+
python --version

# 升级 pip
pip install --upgrade pip

# 重新安装依赖
pip install -r requirements.txt

# 或使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 1.3 配置文件格式错误

**问题描述**：

```
JSONDecodeError: Expecting property name enclosed in double quotes
```

**解决方案**：

检查 `config.json` 文件是否为有效的 JSON 格式：

```bash
# 验证 JSON 格式
python -c "import json; json.load(open('config.json'))"

# 或使用在线 JSON 验证工具
```

---

## 2. API 认证问题

### 2.1 API Key 无效

**问题描述**：

```json
{
    "detail": "Invalid API Key"
}
```

**可能原因**：
- 请求时未提供 `X-API-Key` Header
- 提供的 API Key 与配置不匹配

**解决方案**：

1. 确认在请求头中添加了正确的 Header：

```bash
curl -H "X-API-Key: your-external-api-key" http://localhost:8080/api/v1/nodes
```

2. 检查 `config.json` 或 `.env` 中的 `external_api_key` 配置：

```json
{
    "external_api_key": "your-external-api-key"
}
```

### 2.2 CORS 跨域问题

**问题描述**：

```
Access-Control-Allow-Origin' header is present on the requested resource
```

**解决方案**：

1. 在 `config.json` 中配置允许的来源：

```json
{
    "cors_origins": ["http://localhost:3000", "https://your-domain.com"]
}
```

2. 或设置 `cors_origins": ["*"]`（仅开发环境）

---

## 3. 节点管理问题

### 3.1 节点添加失败

**问题描述**：

```json
{
    "success": false,
    "error": "Node 'xxx' already exists"
}
```

**解决方案**：

- 节点名称具有唯一性，不能重复
- 使用不同的名称添加节点
- 或先删除已有节点后再添加

```bash
# 删除节点
curl -X DELETE http://localhost:8080/api/v1/nodes/node1 \
  -H "X-API-Key: your-api-key"
```

### 3.2 节点连接失败

**问题描述**：

```json
{
    "data": {
        "is_healthy": false,
        "health_message": "API status: error"
    }
}
```

**可能原因**：
- 节点服务未启动
- API URL 配置错误
- 网络不通
- API Key 不正确

**解决方案**：

1. 确认节点服务正在运行：

```bash
# 在节点服务器上检查
curl http://节点IP:5000/health
```

2. 检查节点配置：

```bash
# 获取节点信息
curl http://localhost:8080/api/v1/nodes/node1 \
  -H "X-API-Key: your-api-key"
```

3. 测试节点 API 连通性：

```bash
# 直接测试节点 API
curl -X POST http://节点IP:5000/api/wechat/initialize \
  -H "X-API-Key: 节点API密钥"
```

### 3.3 节点健康检测失败

**问题描述**：

```json
{
    "health_message": "WeChat error: 无效"
}
```

**可能原因**：
- 微信窗口未打开或已关闭
- 微信版本不兼容
- WXAuto-HTTP-API 服务异常

**解决方案**：

1. 在对应节点上手动初始化微信：

```bash
curl -X POST http://localhost:8080/api/v1/nodes/node1/wechat/initialize \
  -H "X-API-Key: your-api-key"
```

2. 检查节点服务器的微信客户端是否正常运行

3. 重启节点服务

---

## 4. 消息发送问题

### 4.1 消息发送失败 - 节点不健康

**问题描述**：

```json
{
    "detail": "Node 'node1' is not healthy: WeChat check failed. Message sending failed."
}
```

**HTTP 状态码**：503

**解决方案**：

1. 先检查节点状态：

```bash
curl http://localhost:8080/api/v1/nodes/node1/status \
  -H "X-API-Key: your-api-key"
```

2. 确保微信客户端在节点机器上正常运行

3. 手动初始化微信：

```bash
curl -X POST http://localhost:8080/api/v1/nodes/node1/wechat/initialize \
  -H "X-API-Key: your-api-key"
```

### 4.2 消息发送失败 - 接收者不存在

**问题描述**：

```json
{
    "data": {
        "code": 1,
        "message": "receiver not found"
    }
}
```

**解决方案**：

1. 确认接收者的 wxid 或群ID 是否正确
2. 获取好友/群列表确认：

```bash
# 获取好友列表
curl http://localhost:8080/api/v1/nodes/node1/friends \
  -H "X-API-Key: your-api-key"

# 获取群列表
curl http://localhost:8080/api/v1/nodes/node1/groups \
  -H "X-API-Key: your-api-key"
```

### 4.3 消息类型不支持

**问题描述**：

```json
{
    "data": {
        "code": 1,
        "message": "unsupported message type"
    }
}
```

**解决方案**：

目前系统仅支持 `text` 类型消息，消息发送时指定 `msg_type`：

```json
{
    "node_id": "wx1",
    "who": "wxid_friend",
    "msg": "Hello!",
    "msg_type": "text"
}
```

---

## 5. Webhook 问题

### 5.1 Webhook 通知发送失败

**问题描述**：

日志中出现 `Webhook通知发送失败` 相关信息。

**可能原因**：
- Webhook URL 配置错误
- 网络不通
- Webhook 服务不可用
- 消息格式不被接受

**解决方案**：

1. 检查 Webhook 配置：

```bash
curl http://localhost:8080/api/v1/config/webhook \
  -H "X-API-Key: your-api-key"
```

2. 测试 Webhook URL 是否可用：

```bash
# 测试企业微信 Webhook
curl -X POST "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your-key" \
  -H "Content-Type: application/json" \
  -d '{"msgtype": "text", "text": {"content": "test"}}'
```

3. 检查 Webhook 事件类型配置：

```json
{
    "event_types": ["api_error", "wechat_offline", "wechat_online", "node_offline", "node_online"]
}
```

### 5.2 Bark 通知格式问题

**问题描述**：

Bark 格式的 Webhook 发送失败。

**解决方案**：

确保 Webhook URL 正确，格式为：`https://api.day.app/your-bark-id`

---

## 6. 监控服务问题

### 6.1 监控服务未启动

**问题描述**：

日志中没有看到监控服务的输出，状态变化不触发 Webhook。

**解决方案**：

1. 检查监控配置：

```bash
curl http://localhost:8080/api/v1/config/monitor \
  -H "X-API-Key: your-api-key"
```

2. 确保 `enabled` 为 `true`

3. 检查监控状态：

```bash
curl http://localhost:8080/api/v1/monitor/status \
  -H "X-API-Key: your-api-key"
```

### 6.2 监控检测间隔过长

**问题描述**：

状态变化后很久才收到 Webhook 通知。

**解决方案**：

调整 `check_interval` 配置：

```bash
curl -X POST http://localhost:8080/api/v1/config/monitor \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "check_interval": 30
  }'
```

---

## 7. 日志问题

### 7.1 SSE 日志流断开

**问题描述**：

前端日志流连接经常断开。

**可能原因**：
- 网络问题
- 服务器负载过高
- 客户端处理不及时

**解决方案**：

1. 检查网络连接
2. 实现断线重连机制：

```javascript
function connectLogStream() {
    const eventSource = new EventSource('/api/v1/logs/stream');

    eventSource.onmessage = (event) => {
        const log = JSON.parse(event.data);
        // 处理日志
    };

    eventSource.onerror = () => {
        console.log('Connection lost, reconnecting...');
        setTimeout(connectLogStream, 3000);
    };

    return eventSource;
}
```

### 7.2 日志丢失

**问题描述**：

日志数量超过 500 条后，早期的日志被清除。

**解决方案**：

这是系统设计行为，`LogService` 默认只保留最近 500 条日志。如需更多日志存储，可以：

1. 修改 `log_service.py` 中的 `max_logs` 参数
2. 实现日志持久化存储（写入文件或数据库）

---

## 8. 插件问题

### 8.1 插件未注册

**问题描述**：

```json
{
    "detail": "Plugin 'xxx' not found"
}
```

**解决方案**：

1. 检查插件是否已注册：

```bash
curl http://localhost:8080/api/v1/plugins \
  -H "X-API-Key: your-api-key"
```

2. 确认内置插件是否在启动时正确注册（检查 `builtin.py`）

### 8.2 插件执行失败

**问题描述**：

```json
{
    "success": false,
    "error": "Plugin execution failed"
}
```

**解决方案**：

1. 检查插件配置是否正确
2. 查看系统日志获取详细错误信息
3. 测试插件 API：

```bash
curl -X POST http://localhost:8080/api/v1/external/plugin/execute \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "plugin_name": "plugin_name",
    "action": "execute",
    "params": {}
  }'
```

---

## 9. 性能问题

### 9.1 高并发下响应慢

**可能原因**：
- 节点数量过多
- 网络延迟
- 同步阻塞操作

**解决方案**：

1. 增加监控检测间隔
2. 使用异步调用优化
3. 部署多实例负载均衡

### 9.2 内存占用过高

**可能原因**：
- 日志队列过大
- 订阅者过多
- 节点对象未及时释放

**解决方案**：

1. 减少 `LogService` 的 `max_logs` 参数
2. 及时关闭不需要的 SSE 连接
3. 定期重启服务清理内存

---

## 10. 安全问题

### 10.1 API Key 泄露

**风险**：外部系统可能非法访问 API

**解决方案**：

1. 立即更换 API Key
2. 限制 CORS 来源
3. 使用 HTTPS 传输
4. 定期轮换 API Key

### 10.2 生产环境安全建议

1. 修改默认的 `secret_key`
2. 设置 `debug: false`
3. 配置正确的 `cors_origins`
4. 使用强密码的 API Key
5. 启用 HTTPS
6. 配置防火墙规则

---

## 诊断命令汇总

```bash
# 检查服务健康状态
curl http://localhost:8080/health

# 检查监控状态
curl http://localhost:8080/api/v1/monitor/status \
  -H "X-API-Key: your-key"

# 检查节点状态
curl http://localhost:8080/api/v1/nodes \
  -H "X-API-Key: your-key"

# 检查 Webhook 配置
curl http://localhost:8080/api/v1/config/webhook \
  -H "X-API-Key: your-key"

# 检查最近日志
curl "http://localhost:8080/api/v1/logs/recent?count=20" \
  -H "X-API-Key: your-key"

# 检查插件列表
curl http://localhost:8080/api/v1/plugins \
  -H "X-API-Key: your-key"
```

---

## 获取帮助

如果以上方案无法解决您的问题，请：

1. 查看详细日志输出
2. 检查系统环境配置
3. 确认网络连通性
4. 查看 [API.md](./API.md) 确认 API 使用正确
5. 查看 [ARCHITECTURE.md](./ARCHITECTURE.md) 了解系统架构