跳转至

管理员手册

概述

WxBot管理员手册提供了完整的系统管理、配置优化和故障排除指南，帮助管理员高效运维微信机器人系统。

管理员权限

权限等级

  • 超级管理员: 拥有所有权限，在config.yaml中配置
  • 群管理员: 群组邀请人，拥有群内管理权限
  • 普通管理员: 受限管理权限，可配置具体权限范围

权限配置

# config.yaml
superUsers:
  - "wxid_admin1"
  - "wxid_admin2"

groupAdmins:
  enabled: true
  permissions:
    - "plugin_control"
    - "user_management"
    - "group_settings"

核心管理功能

🔧 系统管理

  • 服务控制: 启动、停止、重启机器人服务
  • 配置管理: 在线修改配置文件
  • 插件管理: 启用、禁用、配置插件
  • 监控面板: 实时系统状态监控

👥 用户管理

  • 用户权限: 设置用户权限等级
  • 黑名单管理: 屏蔽违规用户
  • 积分管理: 调整用户积分数值
  • 使用统计: 查看用户使用情况

🏠 群组管理

  • 群组设置: 配置群组特定功能
  • 成员监控: 监控群成员变动
  • 消息管理: 消息过滤和审核
  • 邀请关系: 管理群组邀请关系

管理指令

系统控制指令

/status          # 查看系统状态
/restart         # 重启机器人（慎用）
/reload config   # 重载配置文件
/logs [行数]     # 查看系统日志
/health         # 健康检查

插件管理指令

/plugins list    # 列出所有插件
/plugin enable [插件名]   # 启用插件
/plugin disable [插件名]  # 禁用插件
/plugin config [插件名]   # 查看插件配置
/plugin stats [插件名]    # 插件使用统计

用户管理指令

/users list      # 用户列表
/user info @用户 # 用户详细信息
/user ban @用户  # 封禁用户
/user unban @用户 # 解封用户
/user score @用户 [分数] # 设置用户积分

群组管理指令

/groups list     # 群组列表
/group info      # 当前群组信息
/group config    # 群组配置设置
/group members   # 群成员统计
/group invite    # 邀请关系查询

监控系统

实时监控面板

访问地址：http://localhost:7601/monitor.html

监控指标

  • 系统资源: CPU、内存、协程使用情况
  • 业务指标: 消息处理量、错误率、响应时间
  • 插件状态: 各插件运行状态和性能数据
  • 网络状态: 框架连接状态、API调用成功率

告警系统

  • 自动告警: 系统异常自动触发告警
  • 告警级别: Critical、High、Medium、Low四个级别
  • 告警静默: 防止告警风暴的静默机制
  • 告警历史: 查看历史告警记录

配置管理

主配置文件 (config.yaml)

# 基础配置
framework:
  name: "StarBotPro"
  http:
    host: "127.0.0.1"
    port: 7600

# 管理员配置
superUsers:
  - "wxid_admin"

# 安全配置
security:
  rateLimit:
    enabled: true
    requests: 60
    window: 60

# 监控配置
monitoring:
  enabled: true
  port: 7601
  alerts:
    enabled: true
    levels: ["critical", "high", "medium"]

插件配置文件 (plugins.yaml)

# 插件导入列表
_ "github.com/Ruk1ng001/wxbot/plugins/chatgpt"
_ "github.com/Ruk1ng001/wxbot/plugins/weather"
_ "github.com/Ruk1ng001/wxbot/plugins/signin"
# ... 更多插件

环境变量配置

# API密钥
export OPENAI_API_KEY="your-api-key"
export WEATHER_API_KEY="your-weather-key"

# 代理设置
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

# 数据库配置
export DB_PATH="./data/wxbot.db"

安全管理

访问控制

  • IP白名单: 限制管理面板访问IP
  • 认证机制: 管理员身份认证
  • 权限隔离: 不同管理员不同权限
  • 审计日志: 记录所有管理操作

数据安全

  • 数据备份: 定期自动备份重要数据
  • 加密存储: 敏感信息加密存储
  • 传输安全: HTTPS传输加密
  • 访问日志: 详细的访问日志记录

内容审核

  • 敏感词过滤: 自动过滤不当内容
  • 消息审核: 可疑消息人工审核
  • 用户举报: 用户举报处理机制
  • 违规处理: 违规用户处理流程

故障排除

常见问题诊断

1. 机器人无响应

# 检查进程状态
ps aux | grep wxbot

# 查看日志
tail -f logs/wxbot.log

# 检查网络连接
curl -I http://localhost:7600/wxbot/health

2. 插件功能异常

# 查看插件状态
curl http://localhost:7601/wxbot/monitor/metrics | jq .plugins

# 重载插件配置
kill -HUP $(pidof wxbot)

# 查看插件日志
grep "plugin_name" logs/wxbot.log

3. 消息发送失败

  • 检查框架连接状态
  • 验证API调用权限
  • 确认消息格式正确
  • 检查网络连接状态

日志分析

日志级别

  • DEBUG: 调试信息，开发环境使用
  • INFO: 一般信息，正常操作记录
  • WARN: 警告信息，需要关注
  • ERROR: 错误信息，需要立即处理

日志格式

2025-01-29 10:30:45 [INFO] [plugin:chatgpt] 用户wxid_123请求AI对话
2025-01-29 10:30:46 [ERROR] [framework:starbot] API调用失败: timeout

性能优化

系统调优

# 性能配置
performance:
  maxGoroutines: 1000    # 最大协程数
  bufferSize: 1024       # 事件缓冲区大小
  timeoutSeconds: 30     # 请求超时时间
  cacheSize: 10000       # 缓存大小

数据库优化

-- 定期清理过期数据
DELETE FROM event_logs WHERE created_at < DATE('now', '-30 days');

-- 优化索引
CREATE INDEX idx_user_id_created ON messages (user_id, created_at);

-- 分析查询性能
EXPLAIN QUERY PLAN SELECT * FROM messages WHERE user_id = ?;

数据管理

数据备份

#!/bin/bash
# 自动备份脚本
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/wxbot"

# 备份数据库
cp ./data/wxbot.db "$BACKUP_DIR/wxbot_$DATE.db"

# 备份配置文件
cp config.yaml "$BACKUP_DIR/config_$DATE.yaml"

# 备份日志文件
tar -czf "$BACKUP_DIR/logs_$DATE.tar.gz" logs/

# 清理30天前的备份
find "$BACKUP_DIR" -type f -mtime +30 -delete

数据恢复

# 恢复数据库
cp /backup/wxbot/wxbot_20250129_100000.db ./data/wxbot.db

# 恢复配置
cp /backup/wxbot/config_20250129_100000.yaml config.yaml

# 重启服务
systemctl restart wxbot

数据清理

# 清理临时文件
find ./temp -type f -mtime +7 -delete

# 清理缓存文件
find ./data/cache -type f -mtime +1 -delete

# 清理日志文件
find ./logs -name "*.log" -mtime +30 -delete

运维最佳实践

部署建议

  1. 容器化部署: 使用Docker进行部署
  2. 负载均衡: 多实例负载均衡
  3. 健康检查: 配置健康检查机制
  4. 自动重启: 服务异常自动重启

监控建议

  1. 指标收集: 收集关键性能指标
  2. 告警设置: 设置合理的告警阈值
  3. 日志分析: 定期分析日志发现问题
  4. 性能分析: 定期进行性能分析

安全建议

  1. 定期更新: 定期更新系统和依赖
  2. 安全扫描: 定期进行安全漏洞扫描
  3. 访问控制: 严格控制管理权限
  4. 数据保护: 保护敏感数据安全

应急处理

紧急停机

# 立即停止服务
kill -9 $(pidof wxbot)

# 禁用自动重启
systemctl disable wxbot

# 备份关键数据
cp -r ./data /backup/emergency/

快速恢复

# 回滚到上一版本
docker run --name wxbot-backup -d wxbot:v1.0.0

# 恢复数据
cp /backup/emergency/wxbot.db ./data/

# 启动服务
systemctl start wxbot

问题上报

当遇到无法解决的问题时： 1. 收集错误日志 2. 记录重现步骤 3. 收集系统环境信息 4. 提交到项目Issues 5. 联系技术支持

相关文档