跳转至

最后更新: 2026-08-04

配置系统快速参考

顶层配置总览

config.yaml 共有 9 个顶层配置节(完整字段与热更新标注见 config.example.yaml):

顶层键 Go 结构体 用途 热更新
bot config.BotConfig 各平台适配器(qq/onebot/discord/satori/milky/telegram/wechat) 增删平台、换 Token 可热替换;换端口需重启
log logger.Config 日志级别/格式/输出目标 级别即时生效,格式重建 logger
retry config.RetryConfig 发送失败自动重试 即时生效
middleware config.MiddlewareConfig 内置中间件(限流/去重/降级/慢处理器等) 多数开关即时生效
dead_letter config.DeadLetterConfig 失败事件持久化(file/kafka/webhook) 需重启
engine config.EngineConfig 引擎内部参数(临时匹配器清理、批量删除等) 需重启
tracing tracing.Config OpenTelemetry 分布式追踪 多数需重启;自适应采样率支持热更
pprof config.PprofConfig pprof 性能分析服务器 服务器开关/地址需重启,采样参数运行时生效
api config.APIConfig 管理 API(配置 reload、插件管理等) 需重启

另有 plugins: 扩展节点:任意插件的自定义键值配置,插件侧通过 cfg.PluginString / PluginInt / PluginBool 读取,无需为每个插件定义顶层结构体。

如何使用新增的配置项

1. 基础使用

package main

import (
    "github.com/KomeiDiSanXian/remilia/config"
    "github.com/KomeiDiSanXian/remilia/infra/logger"
)

func main() {
    // 加载配置
    cfg, err := config.LoadDefault()
    if err != nil {
        logger.Fatalf("Failed to load config: %v", err)
    }

    // 访问配置
    logger.Infof("Webhook workers: %d", cfg.Webhook.WorkerCount)
    logger.Infof("Event buffer: %d", cfg.Webhook.EventBuffer)
    logger.Infof("Token retry delay: %s", cfg.Token.RetryDelay)
}

2. 性能关键配置

Webhook 并发配置

webhook:
  # 并发处理器数量(0 = CPU 核心数)
  # 测试数据:8 并发可达 6127 msg/s
  worker_count: 8

  # 事件缓冲区大小
  # 推荐:高流量场景 1000-5000
  event_buffer: 2000
// 代码中访问
workers := cfg.Webhook.WorkerCount
if workers == 0 {
    workers = runtime.NumCPU()
}
buffer := cfg.Webhook.EventBuffer
if buffer <= 0 {
    buffer = 100 // 默认值
}

Token 管理配置

token:
  retry_delay: "10s"        # 获取失败重试延迟
  refresh_advance: "30s"    # 提前刷新时间
  min_refresh_ratio: 0.5    # 最小刷新比例
import "time"

// 解析配置
retryDelay, _ := time.ParseDuration(cfg.Token.RetryDelay)
refreshAdvance, _ := time.ParseDuration(cfg.Token.RefreshAdvance)

Engine 配置

engine:
  temp_matcher_cleanup_interval: "5m"    # 默认 1m
  pending_delete_buffer_size: 1000       # 默认 1000
  pending_delete_process_interval: "100ms"
  pending_delete_batch_size: 1000
  matcher_pool_capacity: 16              # 默认 16
// 使用配置创建 Engine
eng := engine.NewEngine(
    engine.WithCleanupInterval(cleanupInterval),          // 默认 1m
    engine.WithPendingDeleteBufferSize(1000),              // 默认 1000
    engine.WithMaxMatchers(5000),                          // 默认 0(不限制)
    engine.WithConfig(cfg.Engine),                         // 从配置文件一次性应用所有值
)

WithMaxMatchers: 设置 Matcher 注册上限。 达到上限后新注册的 Matcher 返回 noop(链式调用安全,但不执行)。 默认值 0 表示不限制。

正则缓存调优

// 在首次调用 OnRegex/OnRegexSafe 之前设置(程序启动时)
// 默认值:1000(适合大多数 Bot)
context.SetRegexCacheSize(200)   // 小型 Bot,节省内存
context.SetRegexCacheSize(5000)  // 大型 Bot,避免频繁淘汰

3. 中间件配置

限流配置

middleware:
  rate_limit: true
  rate_limit_rate: 100
  rate_limit_burst: 200
  rate_limit_bucket_ttl: "10m"
  rate_limit_cleanup_interval: "5m"
// 简单全局限流(每秒最多 N 个事件)
engine.Use(middleware.SimpleRateLimit(10))

// 按用户限流(每用户每秒 2 次)
engine.Use(middleware.RateLimitTokenBucket(2, 4, func(ctx *context.Context) string {
    return ctx.GetSenderInfo().ID
}))

去重配置

middleware:
  dedup_enable: true
  dedup_max_size: 10000           # 默认 10000
  dedup_default_ttl: "5m"         # 默认 5m
  dedup_cleanup_interval: "1m"

慢处理器配置

middleware:
  slow_handler_enable: true
  slow_handler_threshold: "1s"  # 超过 1 秒记录警告

自适应降级热更新阈值

middleware:
  # 新增:通过 hotreload.Bridge.WatchDegradation 推送给 AdaptiveDegradation
  degradation_cpu_threshold: 80.0       # CPU 超过此值触发降级(0-100)
  degradation_memory_threshold: 85.0    # 内存超过此值触发降级(0-100)
// 在程序启动时建立热更新桥接
bridge := hotreload.NewBridge()
bridge.WatchDegradation(adaptiveDeg)   // 降级阈值热更新
bridge.WatchDedup(dedupFilter)          // 去重 TTL/MaxSize 热更新
token := bridge.Subscribe()             // 注册到 config.Watcher
defer token.Cancel()

4. 高级功能:自适应降级

middleware:
  degradation:                  # 注意:位于 middleware 节下
    enable: true
    cpu_threshold: 80.0         # CPU 超过 80% 开始降级
    memory_threshold: 85.0      # 内存超过 85% 开始降级
    latency_threshold: "500ms"  # 延迟超过 500ms 开始降级
    monitor_interval: "5s"      # 每 5 秒检查一次
    recovery_interval: "10s"    # 恢复检查间隔
    delay_queue_size: 1000      # delay 策略的延迟队列容量
    goroutine_threshold: 10000  # 协程数阈值(>0 时参与降级判定)
    strategy: "drop"            # 降级策略:drop/delay/simplify

cmd/bot 在 enable: true 时自动装配:创建控制器、绑定 Bot 生命周期启动监控、 注册中间件,并接入配置热更新(阈值改动下一监控周期生效)。库使用者自己装配时参考:

dc := cfg.Middleware.Degradation
deg := degradation.NewAdaptiveDegradation(degradation.DegradationConfig{
    CPUThreshold:       dc.CPUThreshold,
    MemoryThreshold:    dc.MemoryThreshold,
    LatencyThreshold:   parseDuration(dc.LatencyThreshold, 500*time.Millisecond),
    Strategy:           degradation.DegradationDrop,
    EnableGoroutineLimit: dc.GoroutineThreshold > 0,
    GoroutineThreshold: dc.GoroutineThreshold,
})
deg.StartMonitor(bot.Context())
engine.Use(deg.Middleware())
bridge.WatchDegradation(deg)   // 阈值热更新

平台与运维配置

Bot 平台配置(bot)

所有平台适配器的凭证与网络配置。每个平台均为指针字段 + omitempty,未使用的平台不出现在 YAML 中:

bot:
  qq:
    mode: "webhook"               # webhook(默认,官方回调)| ws(官方 WebSocket 网关)
    # intents: 33554432           # 仅 ws 模式:事件订阅位掩码,0/缺省 = 全部
    app_id: 123456789
    bot_id: 987654321
    token: "your_qq_bot_token"
    secret: "your_qq_bot_secret"
    webhook:                      # 仅 mode: webhook 生效
      host: "0.0.0.0"
      port: 8080
  # onebot 三种接入方式(mode 留空时按字段推断):
  #   forward_ws(默认)— 适配器主动连接实现端,需要 url
  #   reverse_ws        — 适配器监听,由实现端连入,需要 listen_addr
  #   http_post         — 实现端 POST 事件到 listen_addr,API 调用走 url
  # onebot:
  #   mode: "reverse_ws"
  #   listen_addr: ":8080"
  #   url: "http://127.0.0.1:5700"

  # discord 两种接入方式(mode 留空时按是否配置 interactions 块推断):
  #   gateway(默认)— 常驻 WebSocket,收全量事件
  #   interactions    — 只收斜杠命令/按钮/表单交互(端点须为 HTTPS)
  # discord:
  #   mode: "interactions"
  #   token: "your_discord_bot_token"
  #   interactions:
  #     listen_addr: ":8080"
  #     public_key: "YOUR_APP_PUBLIC_KEY"

  # satori 两种接入方式(mode 留空时按是否配置 webhook 块推断):
  #   ws(默认)— 常驻 WebSocket 订阅;webhook — SDK 把事件 POST 到本端
  # 注意 platform / user_id 是适配器必填项。
  # satori:
  #   mode: "webhook"
  #   server_url: "http://localhost:5140"
  #   platform: "chronocat"
  #   user_id: "1234567890"
  #   webhook:
  #     listen_addr: ":5140"

  # telegram 两种接入方式(mode 留空时按是否配置 webhook 块推断):
  #   polling(默认)— getUpdates 长轮询,无需公网地址
  #   webhook         — Telegram 把更新 POST 到本端,public_url 必须是 https
  # telegram:
  #   mode: "webhook"
  #   token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
  #   webhook:
  #     public_url: "https://your.domain/telegram"
  #     port: 8443
  #     secret_token: "your_secret_token"

  # 企业微信智能机器人(两种接入方式共用一份配置,凭证互不通用):
  #   ws(默认)— 连企业微信长连接,无需公网地址,支持主动推送与素材上传
  #   webhook    — 企业微信把加密回调 POST 到本端,回复走一次性 response_url
  # wechat:
  #   mode: "ws"
  #   bot_id: "YOUR_AIBOT_ID"
  #   secret: "your_long_connection_secret"
  #   # token: "your_callback_token"
  #   # encoding_aes_key: "43 位密钥"
  #   # webhook:
  #   #   listen_addr: ":8080"

  # milky: 同理
cfg, _ := config.Get()
if cfg.Bot.QQ != nil {
    logger.Infof("QQ AppID: %d", cfg.Bot.QQ.AppID)
}

自 v1.14.1 起支持平台热替换(SyncPlatforms):增删平台、更换 Token/URL 零停机; 更换 webhook 监听端口等网络层变更仍需重启。

死信队列(dead_letter)

处理失败的事件写入死信队列,避免静默丢失。由 infra/dlq 消费,所有变更需重启:

dead_letter:
  enable: true
  target: "file"                      # file / kafka / webhook
  file_path: "./dead_letters.log"     # target=file 时使用
  kafka_brokers: ["localhost:9092"]   # target=kafka 时使用
  kafka_topic: "bot-dead-letters"
  webhook_url: "https://..."          # target=webhook 时使用

分布式追踪(tracing)

Config.Tracing 直接复用 infra/tracing 的 tracing.Config:

tracing:
  enable: false                       # [R] 需重建 TracerProvider
  service_name: "remilia-bot"
  exporter: "otlp"                    # 需部署 Tempo/Zipkin 等后端
  endpoint: "http://localhost:4318"
  sampling_rate: 1.0                  # 生产环境建议 < 1.0
  use_adaptive_sampling: false        # 启用后 sampling_rate 支持运行时更新
  include_event_detail: false         # [H] 运行时开关

pprof 性能分析(pprof)

pprof:
  enabled: false                      # [R] HTTP 服务器开关
  addr: ":9001"                       # [R]
  auto_profile: false                 # [H] 周期性自动采样
  profile_interval: "1h"              # [H]
  profile_duration: "30s"             # [H]
  output_dir: "data/profiles"         # [R] 仅创建时读取
  enable_mutex: false                 # [H] mutex profile 开关
  enable_block: false                 # [H] block profile 开关

崩溃核心转储(coredump)

coredump:
  enable: false                       # [R] 仅启动时生效
  dir: "data/coredumps"               # [R] 留空用默认 coredumps
  # diagnose_on_enable: true          # [R] 启用时输出一次环境诊断

启用后进程崩溃时由操作系统生成 core(Linux/macOS)或 MiniDump(Windows), 并把 Go 运行时的崩溃报告写入 dir 下的 crash-*.log(与转储互补, Windows 上 MiniDump 不含异常上下文,寄存器快照只能从这里看)。 容器环境需额外放开 --ulimit core=-1 与 SYS_PTRACE,否则转储静默失败; 启用失败只告警,不影响 Bot 启动。

管理 API(api)

提供 POST /api/v1/config/reload 等运维端点,用于触发 [R] 级配置重载、插件与权限管理:

api:
  enabled: true
  addr: ":9002"
  api_key: ""

认证方式为 Bearer Token(Authorization: Bearer <api_key>,常数时间比较)。 api_key 留空时仅允许本机回环地址访问——管理 API 能启停 Bot、改写配置、增删插件, 远程访问必须配置 api_key。

配置优先级

  1. 显式配置文件 (config.yaml)
  2. 环境变量 (BOT_APP_ID, BOT_TOKEN 等)
  3. 默认值 (代码中定义)

配置验证

所有配置在加载时都会进行验证:

cfg, err := config.Load("config.yaml")
if err != nil {
    // 配置无效,err 包含详细错误信息
    logger.Fatalf("Invalid config: %v", err)
}
// 配置有效,可以安全使用

常见配置场景

场景 1:低流量场景(个人 Bot)

webhook:
  event_buffer: 100
  worker_count: 2

engine:
  pending_delete_buffer_size: 100
  matcher_pool_capacity: 8

场景 2:中等流量场景(小型企业 Bot)

webhook:
  event_buffer: 1000
  worker_count: 4

engine:
  pending_delete_buffer_size: 1000
  matcher_pool_capacity: 16

场景 3:高流量场景(大型企业 Bot)

webhook:
  event_buffer: 5000
  worker_count: 16

engine:
  pending_delete_buffer_size: 10000
  matcher_pool_capacity: 64
  matcher_pool_max_capacity: 4096

degradation:
  enable: true
  cpu_threshold: 75.0
  memory_threshold: 80.0

场景 4:极限性能场景

webhook:
  event_buffer: 10000
  worker_count: 32  # 或使用 0 自动使用 CPU 核心数
  dedup_enable: false  # 为了性能可以禁用去重

engine:
  temp_matcher_cleanup_interval: "10m"  # 减少清理频率
  pending_delete_buffer_size: 50000
  pending_delete_process_interval: "50ms"  # 更频繁地批量删除

middleware:
  logging: false  # 禁用日志以提升性能

配置调优建议

1. Worker Count 调优

场景 推荐值 说明
CPU 密集型 CPU 核心数 worker_count: 0 (自动)
IO 密集型 CPU 核心数 × 2 worker_count: 16 (8核)
混合场景 CPU 核心数 × 1.5 worker_count: 12 (8核)

2. Buffer Size 调优

流量级别 推荐值 说明
< 100 msg/s 100-500 小缓冲即可
100-1000 msg/s 1000-2000 中等缓冲
> 1000 msg/s 5000-10000 大缓冲,防止丢失

3. Engine 调优

# 高频创建临时 Matcher
engine:
  temp_matcher_cleanup_interval: "2m"  # 更频繁清理
  pending_delete_buffer_size: 5000     # 更大的删除缓冲

# 低频创建临时 Matcher
engine:
  temp_matcher_cleanup_interval: "10m" # 减少清理开销
  pending_delete_buffer_size: 500      # 小缓冲节省内存

故障排查

问题 1:消息丢失

现象:日志显示 "Event channel is full, dropping payload"

解决方案:

webhook:
  event_buffer: 5000  # 增大缓冲区
  worker_count: 16    # 增加并发处理

问题 2:内存占用过高

现象:内存持续增长

解决方案:

engine:
  temp_matcher_cleanup_interval: "2m"  # 更频繁清理
  matcher_pool_max_capacity: 512       # 限制池大小

webhook:
  dedup_hard_max_size: 50  # 减小去重缓存

问题 3:CPU 占用过高

现象:CPU 持续 100%

解决方案:

webhook:
  worker_count: 4  # 减少并发数

middleware:
  logging: false  # 禁用日志中间件

degradation:
  enable: true    # 启用自适应降级
  cpu_threshold: 70.0

问题 4:Token 频繁失效

现象:API 调用频繁失败

解决方案:

token:
  refresh_advance: "60s"  # 提前更多时间刷新
  retry_delay: "5s"       # 减少重试延迟

环境变量覆盖

所有配置都可以通过环境变量覆盖:

# Bot 配置
export BOT_APP_ID=123456789
export BOT_BOT_ID=987654321
export BOT_TOKEN="your_token"
export BOT_SECRET="your_secret"

# 服务器配置
export SERVER_HOST="0.0.0.0"
export SERVER_PORT=8080

# 日志配置
export LOG_LEVEL="debug"
export LOG_FORMAT="json"

配置热重载

某些配置支持热重载(无需重启):

import "github.com/KomeiDiSanXian/remilia/config"

// 监听配置变化
watcher, err := config.NewWatcher("config.yaml")
if err != nil {
    panic(err)
}

watcher.OnReload(func(oldCfg, newCfg *config.Config) error {
    // 配置已更新,可以在这里更新运行时配置
    logger.Infof("Config reloaded: workers %d -> %d", 
        oldCfg.Webhook.WorkerCount, 
        newCfg.Webhook.WorkerCount)
    return nil
})

// 启动监听
if err := watcher.Start(); err != nil {
    panic(err)
}

相关文档

  • 配置示例文件(含每个字段的热更新标注:[H] 即时 / [H⚠] 有条件 / [R] 需重启)