wxauto_api/doc/wxauto_center/TROUBLESHOOTING.md

WXAuto Center 常见问题与解决方案

概述

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

---

1. 服务启动问题

1.1 端口被占用

问题描述：

Error: [Errno 48] Address already in use

可能原因：

• 另一个进程正在使用 8080 端口
• 上一次启动的服务未正常关闭

解决方案：

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

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

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

1.2 依赖库安装失败

问题描述：

ModuleNotFoundError: No module named 'fastapi'

解决方案：

# 确保使用 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 格式：

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

# 或使用在线 JSON 验证工具

---

2. API 认证问题

2.1 API Key 无效

问题描述：

{
    "detail": "Invalid API Key"
}

可能原因：

• 请求时未提供 X-API-Key Header
• 提供的 API Key 与配置不匹配

解决方案：

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

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

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

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

2.2 CORS 跨域问题

问题描述：

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

解决方案：

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

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

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

---

3. 节点管理问题

3.1 节点添加失败

问题描述：

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

解决方案：

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

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

3.2 节点连接失败

问题描述：

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

可能原因：

• 节点服务未启动
• API URL 配置错误
• 网络不通
• API Key 不正确

解决方案：

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

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

2. 检查节点配置：

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

3. 测试节点 API 连通性：

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

3.3 节点健康检测失败

问题描述：

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

可能原因：

• 微信窗口未打开或已关闭
• 微信版本不兼容
• WXAuto-HTTP-API 服务异常

解决方案：

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

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

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

3. 重启节点服务

---

4. 消息发送问题

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

问题描述：

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

HTTP 状态码：503

解决方案：

1. 先检查节点状态：

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

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

3. 手动初始化微信：

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

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

问题描述：

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

解决方案：

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

# 获取好友列表
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 消息类型不支持

问题描述：

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

解决方案：

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

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

---

5. Webhook 问题

5.1 Webhook 通知发送失败

问题描述：

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

可能原因：

• Webhook URL 配置错误
• 网络不通
• Webhook 服务不可用
• 消息格式不被接受

解决方案：

1. 检查 Webhook 配置：

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

2. 测试 Webhook URL 是否可用：

# 测试企业微信 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 事件类型配置：

{
    "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. 检查监控配置：

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

2. 确保 enabled 为 true

3. 检查监控状态：

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

6.2 监控检测间隔过长

问题描述：

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

解决方案：

调整 check_interval 配置：

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. 实现断线重连机制：

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 插件未注册

问题描述：

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

解决方案：

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

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

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

8.2 插件执行失败

问题描述：

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

解决方案：

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

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. 配置防火墙规则

---

诊断命令汇总

# 检查服务健康状态
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 使用正确
5. 查看 ARCHITECTURE.md 了解系统架构