CoolQ HTTP API 插件配置详解

CoolQ HTTP API 插件配置详解

CoolQ HTTP API 是一款功能强大的机器人插件，它通过 HTTP 和 WebSocket 协议为开发者提供了丰富的 API 接口。本文将详细介绍该插件的配置方式，帮助开发者快速上手并优化配置。

配置文件基础

CoolQ HTTP API 支持两种配置文件格式：INI 和 JSON。开发者可以根据个人偏好选择适合的格式。配置文件支持两种组织方式：

1. 单文件多账号配置：所有账号配置集中在一个文件中
2. 多文件单账号配置：每个账号有独立的配置文件，配合通用配置文件使用

配置文件加载顺序

插件启动时会按以下顺序尝试加载配置文件：

1. config.(cfg|ini) - 优先加载.cfg文件
2. config\general.(cfg|ini) + config\<user_id>.(cfg|ini) - 通用配置+账号特定配置
3. config.json - JSON格式的集中配置
4. config\general.json + config\<user_id>.json - JSON格式的分开配置

重要提示：如果配置文件中需要使用中文或其他非ASCII字符，必须使用UTF-8 without BOM编码保存文件。

典型配置示例

INI格式多账号配置示例

[general]
host = 0.0.0.0
post_url = http://192.168.0.11:8888

[12345678]
access_token = Mgep4rV49rM8Jf
port = 5700

[87654321]
port = 5701

JSON格式多账号配置示例

{
    "general": {
        "host": "0.0.0.0",
        "post_url": "http://127.0.0.1:8080"
    },
    "12345678": {
        "access_token": "Mgep4rV49rM8Jf",
        "port": 5700
    },
    "87654321": {
        "port": 5701
    }
}

JSON格式分账号配置示例

通用配置文件 general.json:

{
    "host": "0.0.0.0",
    "post_url": "http://127.0.0.1:8080"
}

账号特定配置文件 12345678.json:

{
    "access_token": "Mgep4rV49rM8Jf",
    "port": 5700
}

核心配置项详解

网络通信配置

1. HTTP服务器配置：

   • host：监听IP，默认为IPv6地址[::]（4.6.2版本后）
   • port：监听端口，默认5700
   • use_http：是否启用HTTP接口，默认为true

2. WebSocket服务器配置：

   • ws_host：监听IP，默认为IPv6地址[::]
   • ws_port：监听端口，默认6700
   • use_ws：是否启用WebSocket服务器，默认为false

3. 反向WebSocket配置：

   • ws_reverse_url：反向WebSocket共用地址
   • use_ws_reverse：是否使用反向WebSocket，默认为false

安全配置

1. 访问控制：

   • access_token：API访问令牌，用于验证请求合法性
   • secret：上报数据签名密钥，用于HMAC SHA1签名验证

2. 消息格式：

   • post_message_format：消息格式，可选string(字符串)或array(数组)

性能优化配置

1. 线程池配置：

   • thread_pool_size：工作线程池大小，默认为4
   • server_thread_pool_size：API服务器线程池大小，默认为4

2. 日志配置：

   • log_level：日志级别，可选debug/info/warning/error/fatal
   • max_log_file_size：最大日志文件大小，默认6MB

高级功能配置

1. 事件过滤：

   • event_filter：指定事件过滤规则文件路径

2. 扩展机制：

   • use_extension：是否启用扩展机制

3. 心跳机制：

   • enable_heartbeat：是否启用心跳
   • heartbeat_interval：心跳间隔，默认15000毫秒

配置建议

1. 生产环境建议：

   • 启用access_token和secret增强安全性
   • 根据服务器性能调整线程池大小
   • 合理设置日志级别和文件大小

2. 性能优化建议：

   • 对于高并发场景，适当增加线程池大小
   • 关闭不必要的功能如convert_unicode_emoji可提升性能
   • 考虑使用反向WebSocket减少连接开销

3. 开发环境建议：

   • 启用show_log_console方便调试
   • 设置log_level为debug获取详细日志
   • 启用auto_check_update保持最新版本

通过合理配置CoolQ HTTP API插件，开发者可以构建出稳定、安全且高性能的机器人应用。建议根据实际需求仔细调整各项配置参数，以达到最佳运行效果。