CoolQ HTTP API 插件配置详解

CoolQ HTTP API 插件配置详解

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

配置文件基础

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

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

配置文件加载顺序

插件启动时会按照以下顺序尝试加载配置文件，一旦成功加载就会停止后续尝试：

1. 优先加载 config.cfg，若不存在则尝试 config.ini
2. 尝试加载 config/general.cfg（或 .ini）和 config/<user_id>.cfg（或 .ini）组合
3. 尝试加载 config.json
4. 尝试加载 config/general.json 和 config/<user_id>.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格式）

通用配置文件 config/general.json：

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

账号特定配置文件 config/12345678.json：

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

核心配置项详解

网络通信配置

1. HTTP服务器配置：

   • host：监听IP，默认0.0.0.0表示监听所有网络接口
   • port：监听端口，默认5700
   • use_http：是否启用HTTP接口，默认为true

2. WebSocket服务器配置：

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

3. 反向WebSocket配置：

   • ws_reverse_api_url：反向WebSocket API地址
   • ws_reverse_event_url：反向WebSocket事件上报地址
   • use_ws_reverse：是否使用反向WebSocket，默认为false

安全相关配置

1. 访问控制：

   • access_token：API访问令牌，设置后需要在请求头中添加Authorization: Token xxxxxxxx
   • secret：上报数据签名密钥，用于HMAC SHA1签名验证

2. 消息上报：

   • post_url：消息和事件上报地址
   • post_timeout：HTTP上报超时时间（秒），0表示不设超时
   • post_message_format：消息格式，可选string或array

性能与日志配置

1. 线程池配置：

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

2. 日志配置：

   • log_level：日志级别，可选debug、info、warning、error、fatal
   • max_log_file_size：单个日志文件最大大小，默认6MB
   • max_log_files：日志文件备份数量，默认1

其他功能配置

1. 更新配置：

   • auto_check_update：是否自动检查更新
   • auto_perform_update：是否自动执行更新

2. 特殊功能：

   • convert_unicode_emoji：是否转换Unicode表情符号，默认true
   • event_filter：事件过滤规则文件路径
   • enable_backward_compatibility：是否启用旧版兼容性，默认false

配置建议

1. 生产环境建议：

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

2. 开发环境建议：

   • 可以启用show_log_console方便调试
   • 设置log_level为debug获取更详细的日志信息

3. 性能优化：

   • 对于处理大量消息的场景，可以考虑关闭convert_unicode_emoji
   • 根据实际负载调整线程池大小

通过合理配置CoolQ HTTP API插件，开发者可以构建出既安全又高效的机器人应用。希望本文能帮助您更好地理解和使用该插件的配置功能。