CoolQ HTTP API 插件配置详解

CoolQ HTTP API 插件配置详解

配置文件基础

CoolQ HTTP API 插件使用标准的 INI 格式配置文件进行各项参数的设置。INI 文件采用分节(section)的方式组织配置项，每个配置项以键值对的形式存在。

配置文件的基本结构包含一个必须的 [general] 节和可选的 QQ 号专用节：

[general]
host=0.0.0.0
port=5700

[12345678]
post_url=http://192.168.0.11:8888
access_token=Mgep4rV49rM8Jf

配置项详解

网络监听配置

1. host (默认值: 0.0.0.0)

   • 作用：指定 HTTP 服务器监听的 IP 地址
   • 说明：设置为 0.0.0.0 表示监听所有可用网络接口

2. port (默认值: 5700)

   • 作用：指定 HTTP 服务器监听的端口号
   • 建议：避免使用 80、443 等常用端口

通信协议配置

1. use_http (默认值: yes)

   • 作用：是否启用 HTTP 接口
   • 说明：启用后可以通过 HTTP 请求调用 API

2. use_ws (默认值: no)

   • 作用：是否启用 WebSocket 服务器
   • 说明：启用后可以通过 WebSocket 连接调用 API 和接收事件

3. use_ws_reverse (默认值: no)

   • 作用：是否启用反向 WebSocket
   • 说明：启用后插件会主动连接指定的 WebSocket 服务器

安全配置

1. access_token (默认值: 空)

   • 作用：API 访问令牌
   • 说明：设置后需要在请求头中添加 Authorization: Token xxxxxxxx

2. secret (默认值: 空)

   • 作用：上报数据签名密钥
   • 说明：设置后会使用 HMAC SHA1 算法对上报数据进行签名

消息上报配置

1. post_url (默认值: 空)

   • 作用：消息和事件的上报地址
   • 说明：插件会以 POST 方式向该地址发送 JSON 格式的数据

2. post_message_format (默认值: string)

   • 可选值：string 或 array
   • 说明：控制上报消息的格式，数组格式更适合程序处理

高级配置

1. thread_pool_size (默认值: 4)

   • 作用：工作线程池大小
   • 建议：根据服务器性能调整，0 表示自动计算

2. server_thread_pool_size (默认值: 1)

   • 作用：API 服务器线程池大小
   • 说明：影响并发处理能力

多账号配置技巧

当需要管理多个 QQ 账号时，可以为每个账号创建独立的配置节：

[general]
host=0.0.0.0

[12345678]
port=5700
post_url=http://192.168.0.11:8888

[23456789]
port=5701
post_url=http://192.168.0.11:8889

这种配置方式允许每个账号拥有独立的监听端口和上报地址，非常适合多账号管理场景。

编码注意事项

重要提示：如果配置文件中需要使用中文或其他非 ASCII 字符，必须确保文件以 UTF-8 without BOM 编码保存，否则可能导致解析错误。

性能优化建议

1. 对于高并发场景，适当增加 thread_pool_size 和 server_thread_pool_size 的值
2. 如果主要使用反向 WebSocket，可以关闭 HTTP 和正向 WebSocket 以减少资源占用
3. 对于国内服务器，可以考虑修改 update_source 为国内镜像源以加快更新速度

常见问题解答

Q: 为什么修改配置后没有生效？ A: 请确保配置文件保存为 UTF-8 without BOM 格式，并检查配置项拼写是否正确。

Q: 如何测试配置是否正确？ A: 可以通过访问 http://host:port/ 来测试 HTTP 接口是否正常工作。

Q: 反向 WebSocket 和正向 WebSocket 有什么区别？ A: 正向 WebSocket 是插件作为服务器等待连接，反向 WebSocket 是插件作为客户端主动连接指定服务器。