跳转至

⚙️ WxBot Enhanced 配置参考手册

![Configuration](../images/configuration-banner.png) **完整的配置文件参考和最佳实践指南**

📋 配置文件概览

WxBot Enhanced 使用两个主要配置文件：

文件名 用途 必需性
config.yaml 主配置文件 ✅ 必需
plugins.yaml 插件配置 ✅ 必需

🔧 config.yaml 详细配置

基础配置

# 🤖 机器人基础信息
botWxId: ""                    # 机器人微信ID（必填）
botNickname: "WxBot Enhanced"  # 机器人昵称
botAvatar: ""                  # 机器人头像URL（可选）

# 👑 超级管理员配置
superUsers:                    # 超级管理员微信ID列表
  - "wxid_example1"           # 替换为真实的微信ID
  - "wxid_example2"           # 可配置多个管理员

# 💬 命令前缀配置
commandPrefix: "/"             # 管理命令前缀（如 /插件列表）

框架连接配置

framework:
  name: "StarBotPro"           # 框架类型：StarBotPro/DeanDLL/VLW
  apiUrl: "http://localhost:8080"  # 框架API地址
  apiToken: ""                 # API访问令牌（如果需要）
  proxyUrl: ""                 # HTTP代理URL（可选）

  # 🚀 Enhanced版本扩展配置
  enhanced:
    timeout: 30s               # 请求超时时间
    retry:
      maxRetries: 4            # 最大重试次数
      baseDelay: 1s            # 基础延迟时间
      maxDelay: 4s             # 最大延迟时间
      backoffFactor: 2.0       # 退避因子

    # 🔒 安全配置
    security:
      validateInput: true      # 启用输入验证
      maxMessageLength: 10000  # 消息最大长度
      rateLimitEnabled: true   # 启用限流
      rateLimitRPS: 10         # 每秒请求数限制

服务器配置

# 🌐 HTTP服务配置
server:
  port: 7601                   # Enhanced版本默认端口
  host: "0.0.0.0"             # 绑定地址（0.0.0.0表示所有接口）
  readTimeout: 30s             # 读取超时
  writeTimeout: 30s            # 写入超时
  idleTimeout: 60s             # 空闲超时

  # 🔐 TLS配置（可选）
  tls:
    enabled: false             # 是否启用HTTPS
    certFile: ""               # SSL证书文件路径
    keyFile: ""                # SSL私钥文件路径

  # 🛡️ 安全头配置
  security:
    cors:
      enabled: true            # 启用CORS
      allowOrigins: ["*"]      # 允许的来源
      allowMethods: ["GET", "POST"]  # 允许的方法
      allowHeaders: ["*"]      # 允许的请求头

Enhanced特性配置

enhanced:
  # 📊 监控系统配置
  monitoring:
    enabled: true              # 启用监控系统
    webDashboard: true         # 启用Web仪表板
    metricsInterval: 30s       # 指标收集间隔

    # ⚠️ 告警配置
    alerting:
      enabled: true            # 启用告警
      channels:                # 告警通知渠道
        - type: "webhook"      # Webhook通知
          url: "https://example.com/webhook"
          enabled: false
        - type: "email"        # 邮件通知
          enabled: false
          smtp:
            host: "smtp.gmail.com"
            port: 587
            username: "your-email@gmail.com"
            password: "your-app-password"
            to: ["admin@example.com"]

      # 📋 告警规则
      rules:
        highErrorRate:
          threshold: 0.05      # 错误率阈值（5%）
          enabled: true
        highMemoryUsage:
          threshold: 1073741824  # 内存阈值（1GB）
          enabled: true
        connectionLost:
          enabled: true

  # 💾 数据库配置
  database:
    # 主数据库
    main:
      path: "data/wxbot.db"    # 数据库文件路径
      maxOpenConns: 25         # 最大连接数
      maxIdleConns: 5          # 最大空闲连接数
      connMaxLifetime: 300s    # 连接最大生存时间

    # 🔄 备份配置
    backup:
      enabled: true            # 启用自动备份
      interval: 24h            # 备份间隔
      retention: 168h          # 备份保留时间（7天）
      path: "data/backups"     # 备份目录
      compress: true           # 压缩备份文件

    # 🧹 清理配置  
    cleanup:
      enabled: true            # 启用自动清理
      oldDataDays: 30          # 清理30天前的数据
      tempFileHours: 24        # 清理24小时前的临时文件

  # 📝 日志配置
  logging:
    level: "info"              # 日志级别：debug/info/warn/error
    format: "json"             # 日志格式：json/text
    output: "file"             # 输出方式：console/file/both

    # 📄 文件日志配置
    file:
      path: "logs/wxbot.log"   # 日志文件路径
      maxSize: 100             # 单文件最大大小（MB）
      maxBackups: 7            # 保留文件数量
      maxAge: 30               # 文件保留天数
      compress: true           # 压缩旧文件

    # 🔍 结构化日志字段
    structured:
      includeTimestamp: true   # 包含时间戳
      includeLevel: true       # 包含日志级别
      includeCaller: true      # 包含调用者信息
      includeStacktrace: false # 包含堆栈跟踪（error级别）

事件处理配置

# ⚡ 事件处理系统配置
eventSystem:
  bufferLen: 4096              # 事件缓冲区大小
  latency: 1s                  # 处理延迟
  maxProcessTime: 180s         # 最大处理时间
  workerCount: 10              # 工作协程数量

  # 🔄 重试配置
  retry:
    maxRetries: 3              # 事件处理最大重试次数
    backoffDuration: 1s        # 重试间隔

  # ⚠️ 超时处理
  timeout:
    enabled: true              # 启用超时处理
    duration: 30s              # 超时时间
    action: "skip"             # 超时动作：skip/retry/fail

插件系统配置

# 🔌 插件系统配置
plugins:
  # 🔄 热加载配置
  hotReload:
    enabled: false             # 启用插件热加载（实验性功能）
    watchDir: "plugins"        # 监听目录
    debounceTime: 1s           # 防抖时间

  # 🛡️ 安全配置
  security:
    sandboxMode: false         # 插件沙箱模式（实验性）
    maxMemoryUsage: 100MB      # 单插件最大内存使用
    maxExecutionTime: 30s      # 单次执行最大时间

  # 📊 统计配置
  statistics:
    enabled: true              # 启用插件统计
    detailLevel: "full"        # 统计详细程度：basic/full
    retentionDays: 90          # 统计数据保留天数

🎮 plugins.yaml 配置

基础插件配置

# 🎮 Enhanced游戏插件（强烈推荐）
- "github.com/ruk1ng001/wxbot/plugins/caichengyu"      # 猜成语Enhanced
- "github.com/ruk1ng001/wxbot/plugins/chengyujielong"  # 成语接龙Enhanced
- "github.com/ruk1ng001/wxbot/plugins/music"           # 音乐猜题Enhanced
- "github.com/ruk1ng001/wxbot/plugins/xiehouyu"        # 歇后语Enhanced
- "github.com/ruk1ng001/wxbot/plugins/signin"          # 签到系统Enhanced

# 🤖 AI智能插件
- "github.com/ruk1ng001/wxbot/plugins/chatgpt"         # ChatGPT聊天

# 🔧 实用工具插件
- "github.com/ruk1ng001/wxbot/plugins/weather"         # 天气查询
- "github.com/ruk1ng001/wxbot/plugins/zaobao"          # 每日早报
- "github.com/ruk1ng001/wxbot/plugins/movies"          # 影片搜索
- "github.com/ruk1ng001/wxbot/plugins/crazykfc"        # KFC疯狂星期四
- "github.com/ruk1ng001/wxbot/plugins/plmm"            # 美女图片

# 🤝 社交管理插件
- "github.com/ruk1ng001/wxbot/plugins/friendadd"       # 自动加好友
- "github.com/ruk1ng001/wxbot/plugins/groupmanager"    # 群管理
- "github.com/ruk1ng001/wxbot/plugins/spywithdraw"     # 撤回监听
- "github.com/ruk1ng001/wxbot/plugins/confirmpayment"  # 自动收款

# 🛠️ 系统管理插件
- "github.com/ruk1ng001/wxbot/plugins/manager"         # 系统管理
- "github.com/ruk1ng001/wxbot/plugins/score"           # 积分系统
- "github.com/ruk1ng001/wxbot/plugins/invitemanager"   # 邀请关系管理

插件启用/禁用说明

# ✅ 启用插件：保留该行
- "github.com/ruk1ng001/wxbot/plugins/weather"

# ❌ 禁用插件：注释掉该行
# - "github.com/ruk1ng001/wxbot/plugins/weather"

# 🔄 修改插件配置后，需要重新生成：
# make plugins
# 或者: go generate -tags plugins ./engine/plugins && go mod tidy

🌍 环境变量配置

常用环境变量

# 🔧 基础配置
export WXBOT_CONFIG_PATH="./config.yaml"      # 配置文件路径
export WXBOT_DATA_DIR="./data"                # 数据目录路径
export WXBOT_LOG_LEVEL="info"                 # 日志级别
export WXBOT_SERVER_PORT="7601"               # 服务端口

# 🔗 框架连接
export WXBOT_FRAMEWORK_NAME="StarBotPro"      # 框架名称
export WXBOT_FRAMEWORK_URL="http://localhost:8080"  # 框架地址
export WXBOT_FRAMEWORK_TOKEN="your-token"     # 框架令牌
export WXBOT_FRAMEWORK_PROXY=""               # 代理地址

# 📊 Enhanced配置
export WXBOT_MONITORING_ENABLED="true"        # 启用监控
export WXBOT_ALERTING_ENABLED="true"          # 启用告警
export WXBOT_DATABASE_PATH="data/wxbot.db"    # 数据库路径

# 🛡️ 安全配置
export WXBOT_RATE_LIMIT_RPS="10"              # 请求频率限制
export WXBOT_MAX_MESSAGE_LENGTH="10000"       # 最大消息长度
export WXBOT_ENABLE_INPUT_VALIDATION="true"   # 启用输入验证

# 🔍 调试配置
export DEBUG="true"                           # 启用调试模式
export DEBUG_LOG="true"                       # 启用调试日志

环境变量优先级

配置加载优先级（从高到低）：

  1. 命令行参数 - 最高优先级
  2. 环境变量 - 高优先级
  3. 配置文件 - 中优先级
  4. 默认值 - 最低优先级
# 示例：使用环境变量覆盖配置文件
export WXBOT_SERVER_PORT=8080
./wxbot  # 将使用端口8080，而不是config.yaml中配置的7601

🏗️ 不同环境配置示例

开发环境配置

# config-development.yaml
enhanced:
  monitoring:
    enabled: true
    webDashboard: true
    metricsInterval: 10s      # 更频繁的指标收集

  logging:
    level: "debug"            # 详细的调试日志
    format: "text"            # 便于阅读的文本格式
    output: "console"         # 输出到控制台

  database:
    backup:
      enabled: false          # 开发环境不需要备份

framework:
  enhanced:
    timeout: 10s              # 较短的超时时间，便于调试
    retry:
      maxRetries: 2           # 较少的重试次数

生产环境配置

# config-production.yaml
enhanced:
  monitoring:
    enabled: true
    webDashboard: true
    metricsInterval: 60s      # 适中的指标收集频率
    alerting:
      enabled: true           # 生产环境必须启用告警

  logging:
    level: "warn"             # 只记录警告和错误
    format: "json"            # 结构化日志便于分析
    output: "file"            # 输出到文件
    file:
      maxSize: 500            # 更大的日志文件
      maxBackups: 30          # 保留更多备份

  database:
    backup:
      enabled: true           # 必须启用备份
      interval: 12h           # 每12小时备份一次
      retention: 720h         # 保留30天备份

framework:
  enhanced:
    timeout: 30s              # 更长的超时时间
    retry:
      maxRetries: 4           # 更多的重试次数

server:
  readTimeout: 60s            # 更长的读取超时
  writeTimeout: 60s           # 更长的写入超时

测试环境配置

# config-testing.yaml
enhanced:
  monitoring:
    enabled: true
    webDashboard: false       # 测试环境不需要Web界面
    metricsInterval: 30s

  logging:
    level: "info"
    format: "json"
    output: "both"            # 同时输出到控制台和文件

  database:
    backup:
      enabled: false          # 测试环境不需要备份
    cleanup:
      enabled: true
      oldDataDays: 7          # 测试数据保留7天即可

eventSystem:
  bufferLen: 1024             # 较小的缓冲区
  maxProcessTime: 30s         # 较短的处理时间

🔒 安全配置最佳实践

基础安全配置

enhanced:
  security:
    # 🛡️ 输入验证
    inputValidation:
      enabled: true
      maxMessageLength: 10000
      blockPatterns:           # 阻止的模式
        - "script.*>"          # 阻止脚本标签
        - "<.*javascript.*>"   # 阻止JavaScript
        - "sql.*injection"     # 阻止SQL注入模式

    # 🚦 限流配置
    rateLimit:
      enabled: true
      global:
        rps: 100              # 全局每秒请求数
        burst: 200            # 突发请求数
      perUser:
        rps: 10               # 单用户每秒请求数
        burst: 20             # 单用户突发请求数
      perPlugin:
        rps: 50               # 单插件每秒请求数
        burst: 100            # 单插件突发请求数

    # 🔐 访问控制
    accessControl:
      ipWhitelist: []         # IP白名单（空则不限制）
      ipBlacklist: []         # IP黑名单
      userBlacklist: []       # 用户黑名单

server:
  security:
    # 🔒 安全头
    headers:
      enableXSSProtection: true
      enableFrameGuard: true
      enableContentTypeNoSniff: true
      enableReferrerPolicy: true
      enableCSP: true
      cspDirectives:
        defaultSrc: ["'self'"]
        scriptSrc: ["'self'", "'unsafe-inline'"]
        styleSrc: ["'self'", "'unsafe-inline'"]

HTTPS配置

server:
  tls:
    enabled: true
    certFile: "/path/to/certificate.crt"
    keyFile: "/path/to/private.key"
    # 或者使用自动证书
    autoTLS:
      enabled: true
      domain: "yourdomain.com"
      email: "admin@yourdomain.com"
      provider: "letsencrypt"  # 使用Let's Encrypt

📊 性能调优配置

高性能配置

# 🚀 高性能配置示例
eventSystem:
  bufferLen: 8192             # 更大的缓冲区
  workerCount: 20             # 更多的工作协程
  latency: 500ms              # 更短的延迟

enhanced:
  database:
    main:
      maxOpenConns: 50        # 更多的数据库连接
      maxIdleConns: 10        # 更多的空闲连接
      connMaxLifetime: 600s   # 更长的连接生存时间

plugins:
  statistics:
    enabled: true
    detailLevel: "basic"      # 基础统计减少开销

server:
  readTimeout: 15s            # 更短的超时提高响应
  writeTimeout: 15s
  idleTimeout: 30s

内存优化配置

# 💾 内存优化配置
enhanced:
  monitoring:
    metricsInterval: 120s     # 降低指标收集频率

  database:
    cleanup:
      enabled: true
      oldDataDays: 15         # 更短的数据保留期
      tempFileHours: 2        # 更频繁清理临时文件

plugins:
  security:
    maxMemoryUsage: 50MB      # 限制单插件内存使用

eventSystem:
  bufferLen: 2048             # 适中的缓冲区大小
  maxProcessTime: 60s         # 防止长时间处理占用内存

🔧 配置验证和测试

配置文件验证

# 验证配置文件语法
./wxbot --config-check

# 测试框架连接
./wxbot --test-framework

# 验证插件配置
./wxbot --test-plugins

# 完整配置测试
./wxbot --dry-run

配置备份和版本控制

# 备份配置文件
cp config.yaml config.yaml.backup.$(date +%Y%m%d)

# 版本控制（排除敏感信息）
git add config.yaml.template
git add plugins.yaml
# 不要提交包含真实密钥的config.yaml

🆘 配置问题排查

常见配置错误

  1. YAML语法错误 

    # 使用工具验证YAML语法
yamllint config.yaml

  2. 端口冲突 

    # 检查端口占用
netstat -an | grep 7601
lsof -i :7601

  3. 权限问题 

    # 检查文件权限
ls -la config.yaml
chmod 600 config.yaml  # 设置安全权限

  4. 路径错误 

    # 检查路径是否存在
ls -la data/
mkdir -p data/plugins  # 创建必要目录

配置调试技巧

# 在配置文件中添加调试配置
enhanced:
  logging:
    level: "debug"            # 启用详细日志

  debugging:
    enabled: true             # 启用调试模式
    configDump: true          # 启动时输出配置信息
    profileEnabled: true      # 启用性能分析
    profilePort: 6060         # pprof端口

📚 配置参考资源

配置模板

相关文档

**⚙️ 良好的配置是系统稳定运行的基础！** **根据你的环境和需求选择合适的配置，让WxBot Enhanced发挥最佳性能！**