水缸机器人

Appearance

Webhook 模式（HTTP 回调） ​

与 WebSocket 网关二选一（bot.mode）。mode: webhook 时机器人不建立出站长连接，改为在本机启动回调服务，由 QQ 开放平台把事件 POST 推送到回调地址。

适合无法维持出站长连接的场景。回调地址需公网可达，开放平台通过 HTTPS 访问它（HTTPS 的提供方式见 部署要求，框架本身不强制任何方案）。

工作流程 ​

开放平台 ──POST 回调地址（HTTPS）──> HTTPS 入口 ──> Bngeuit 回调服务（host:port/path）
                                        │（反向代理 / 内网穿透 / 直接监听，均可选）
                                        ├─ 回调地址验证 → 返回签名，完成验证
                                        └─ 事件推送     → 分发到插件，回包 ACK

事件结构与 WebSocket 模式完全一致，分发到插件的方式也相同——插件无需感知接入方式差异。

配置 ​

yaml
bot:
  mode: webhook              # 切换为 webhook 接入
  webhook:
    host: "0.0.0.0"          # 回调监听地址
    port: 8080               # 回调监听端口（官方限定 80/443/8080/8443）
    path: "/"                # 回调路径（必须以 / 开头）
    verifySignature: true    # 校验事件请求签名（默认 true）
    backlog: 128             # TCP accept 队列长度（1-4096）
    callbackThreads: 4       # 回调处理线程数（1-32）

webhook.* 下的配置只在 mode: webhook 时生效并校验。

部署要求 ​

  • 端口：官方限定 80 / 443 / 8080 / 8443
  • HTTPS 必选：开放平台要求回调地址为 HTTPS。框架不关心 TLS 在哪一层终止——常用方式：
    • 反向代理（nginx / Caddy 等）把公网 HTTPS 转发到本机监听端口
    • 内网穿透（frp / cloudflared 等）把公网域名映射到本机
    • 直接让 Bngeuit 监听公网端口并提供证书（如监听 443）
  • 回调地址：开放平台填写的回调地址 = https://<公网域名或IP><path>，与 webhook.path 必须一致；配置一次即固定，重启无需重配
  • 安全建议：前面有本地反向代理/穿透时，host 可锁 127.0.0.1 只让本机入口访问；直接暴露公网端口时保持 0.0.0.0，依靠签名校验（verifySignature: true）防止伪造请求

回调地址验证与签名 ​

  • 配置回调地址时：开放平台会发起验证请求，机器人需按官方规则返回签名，框架自动处理，无需干预。
  • 接收事件时：默认校验请求签名，校验失败的请求直接拒绝（HTTP 401），不会进入插件。
  • webhook.verifySignature: false 可关闭校验，仅调试用，生产必须开启。

与 WebSocket 模式的差异 ​

维度WebSocketWebhook
连接方向出站长连接（主动连网关）入站 HTTP 回调（被动收推送）
分片（shard）支持多分片无分片（单一回调地址）
断线重连框架自动重连（补拉断线期间的事件）平台侧负责推送重试
就绪事件网关真实 READY 触发 ReadyEvent回调服务启动后触发 WebhookReadyEvent
接入鉴权access_tokenappSecret 派生签名
回复消息走 API（需 access_token）同左——回复消息仍需 access_token

就绪信号（WebhookReadyEvent / onActive） ​

READY / RESUMED 是 QQ 开放平台 WebSocket 网关专属的系统事件，Webhook 模式没有网关连接、平台也不会推送这两个事件。框架不会伪造 ReadyEvent，而是：

  • 事件形式：回调服务启动完成后分发一次 WebhookReadyEvent，事件监听器 / 脚本可用 @SubscribeEvent / bngeuit.on('WebhookReadyEvent', ...) 监听
  • 插件推荐方式：实现 Plugin.onActive() —— 该生命周期在两种接入模式统一触发一次（WS 全部分片就绪 / Webhook 回调服务就绪），做「机器人已上线」初始化无需关心接入方式
java
// 插件：两种模式通用的「机器人上线」时机
@Override
public void onActive() {
    startScheduledTasks(); // 启动定时推送等
}