CoolQ HTTP API 插件配置详解

CoolQ HTTP API 插件配置详解

配置文件概述

CoolQ HTTP API 插件提供了灵活的配置方式，支持 INI 和 JSON 两种格式，并允许开发者根据实际需求选择集中式或分散式的配置管理方式。本文将详细介绍插件的配置机制、典型配置方案以及各项配置参数的含义。

配置文件加载机制

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

1. 单文件集中配置模式

   • config.cfg 或 config.ini 文件
   • config.json 文件

2. 多文件分散配置模式

   • config/general.cfg 或 config/general.ini + config/<user_id>.cfg 或 config/<user_id>.ini
   • 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格式集中配置

同样适用于集中管理，但使用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/ws_port：WebSocket服务监听地址
   • use_ws：是否启用WebSocket服务，默认false

3. 反向WebSocket配置

   • ws_reverse_api_url/ws_reverse_event_url：反向连接地址
   • use_ws_reverse：是否启用反向WebSocket，默认false

安全配置

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

消息处理配置

1. post_message_format：消息上报格式，可选string(字符串)或array(数组)
2. convert_unicode_emoji：是否转换Unicode表情符号，默认true

系统配置

1. 日志配置

   • show_log_console：是否显示日志控制台
   • log_level：日志级别，可选debug/info/warning/error/fatal

2. 更新配置

   • update_channel：更新通道(stable/beta/alpha)
   • auto_check_update：是否自动检查更新

3. 性能配置

   • thread_pool_size：工作线程池大小
   • server_thread_pool_size：API服务器线程池大小

最佳实践建议

1. 生产环境建议启用access_token和secret确保通信安全
2. 多账号管理推荐使用分散配置方案，便于维护
3. 性能敏感场景可适当调整线程池大小，但需考虑服务器实际负载能力
4. 日志级别建议根据环境调整，生产环境可使用info或warning

通过合理配置CoolQ HTTP API插件，开发者可以构建稳定、安全且高效的机器人应用，满足各种业务场景需求。