QQ官方机器人webhook搭建/迁移指南 --- 从选购服务器、配置服务到机器人响应的全流程教程帖~

技术分享
23

自建服务器可能的确备案困难

但是腾讯其实不要求你的域名是备案的。

显然不能。

服务器到期了，意味着公网IP、域名、SSL将无法使用，这会导致你的webhook地址不再能接受消息，导致机器人直接接收不到消息，形成掉线。

切换到webhook之后是不能再切换回websocket的

我建议你能用websocket就先websocket，

如果非要webhook不可，那我建议你只用国外服务器，配置域名、SSL、nginx之后，做FRP服务器，把你nas穿透到服务器

这样可以让服务器所需的开销最小。

1 个赞
24

正如我上面说的 腾讯并不要求你的域名是备案的

并且按照目前的情况来看，webhook连接方式 在启用 沙盒模式 的时候，是不需要IP白名单的，并且可以接收到沙盒之外的消息。

换言之，你可以用你本地的nas运行机器人，但是需要绑定域名和SSL，公网IP使用 沙盒模式 连接解决。

不过注意，如果套cf之类的一定要注意延迟不要太高。腾讯似乎对webhook地址校验有延迟要求。

1 个赞
25

是443吧

2 个赞
26

好麻烦呀。现在qq机器人还是测试中，没有发布。不过不影响自己个人使用。
我看websocket腾讯那边不维护了，这个是否会影响qq机器人的后续发布呢？
后续一直用websocket有没有什么影响？

1 个赞
27

目前没有

1 个赞
28

下面就有nginx配置

1 个赞
30

大佬您好，我在配置时遇到一些问题
我按照教程来，到最后一步设置回调时，开放平台提示

图片
图片737×356 32.3 KB

我没有公网环境，使用的是cloudflare tunnel穿透本地nginx
这是我的nginx配置文件
`
worker_processes 1;

events {
worker_connections 1024;
}

http {
include mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;

# 映射表用于 WebSocket
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

# 定义变量来识别 Cloudflare Tunnel 流量
# 使用 X-Forwarded-For 头是否存在来判断
map $http_x_forwarded_for $is_cf_tunnel {
    default 0;
    "~*" 1; # 如果 X-Forwarded-For 头存在，则认为是 Tunnel 流量
}

# HTTP 服务器块 (端口 80)
server {
    listen 80;
    server_name webhook.*****.top 192.168.0.107;

    # Cloudflare Tunnel 流量 - 直接代理
    location / {
        # 通用的代理头设置
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # 根据流量类型决定代理目标或重定向
        if ($is_cf_tunnel) {
            # 来自 Cloudflare Tunnel 的流量，直接代理到后端
            proxy_pass http://localhost:5140;
            break;
        }
        
        # 非 Tunnel 流量（直接访问 HTTP），重定向到 HTTPS
        return 301 https://$server_name$request_uri;
    }

    # 单独处理静态资源，避免 if 指令的问题
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        proxy_pass http://localhost:5140;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

# HTTPS 服务器块 (端口 443) - 用于直接访问
server {
    listen 443 ssl;
    server_name webhook.*****.top 192.168.0.107;

    ssl_certificate /www/ssl/cert.pem;
    ssl_certificate_key /www/ssl/cert.key;

    # SSL 配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;

    # 根路径代理
    location / {
        proxy_pass http://localhost:5140;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }

    # 处理 /qq 路径
    location /qq {
        proxy_pass http://localhost:5140/qq;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }

    # 静态资源处理
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        proxy_pass http://localhost:5140;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
}

`昨天的时候，我尝试配置，通过了地址校验，koishi日志输出

[W] qq GET /users/@me response: { message: ‘固定Token已禁用，请使用AccessToken鉴权…’, code: 11245, … }

但在保存时开放平台提示endpoint error
在这以后，就没有通过过地址校验

请问大佬我该如何解决这个问题，谢谢

2 个赞
31

其他部分都是和教程一样的

2 个赞
32

这里是因为你的adapter-qq的验证方式配置项，应该选择为bear

图片
图片998×123 2.5 KB

解决验证方式问题之后，

确保adapter-qq的配置项的协议使用的是webhook协议

在最下面的配置项

确保你可以通过域名访问你的koishi控制台

不出意外的话 是可以验证成功的

另外

QQ开放平台要求配置IP白名单的

你没有公网IP的话，就不方便配置IP白名单。会导致无法接收到消息。

即使没有IP白名单，需要注意的是，使用 cloudflare tunnel 可能会导致访问你的控制台的延迟增加。

在开放平台验证webhook地址的时候，对响应时间似乎也有一定的要求。

1 个赞
33

验证方式一直是bear,且这个报错

只出现了一次，后面在开放平台配置依然会出现校验签名失败，把koishi日志等级开到debug都看不见任何反应，大概是cloudflare 在国内的延迟问题吧
大佬，我该如何继续操作，谢谢

2 个赞
34

应该只是历史日志，不是实时报错。不需要在意。

只有这个配置webhook地址的校验这里对延迟比较严格。配置完成之后 对延迟似乎就没有什么要求了。

不太确定是不是延迟导致的，因为腾讯没有说明有延迟要求。但是实际配置的时候，有不少 cloudflare 代理的地址校验失败的。感觉是有延迟要求。

如果是延迟问题，你可以试试租一个很小的服务器，用他的公网 来代理腾讯的服务器，把adapter-qq的配置项的服务器地址改成这个地址。配置webhook到这个小服务器，小服务器下发事件到你的本地。

也就是这个服务器用来代理和解决腾讯那边的请求和事件。

顺便说一句唔，webhook还没有强制推行，换到webhook之后会比websocket麻烦不少(域名、证书等都需要维护)，相比之下 webhook却只是响应快了几百毫秒。

所以还是建议你保持在目前的websocket协议。

你在QQ开放平台后台，有没有配置IP白名单呢？如果有对应IP白名单可配置，但是没配置IP白名单的话，会导致收不到消息

1 个赞
35

配置了ip白名单，在找办法去掉白名单

1 个赞
36

八嘎，去不掉哦

只可以删掉已经配置的IP白名单和加入新的IP

只有在已经配置的IP白名单里才能连上机器人和收到事件

IP白名单是QQ开放平台的硬性要求，如果有这个配置项，那就必须要配置。

如果没有这个配置项可填，那就对IP没有限制

1 个赞
37

那太可怕了，tunnel的ip起码得有几百个

2 个赞
38

对

所以我才只推荐你这样

1 个赞
39

不过那你现在是怎么接收到websocket消息的？

IP白名单对websocket也生效的呀

你现在websocket连接的机器人可以响应消息吗

1 个赞
40

websocket是可以正常使用的，不管有几层nat,我上网总不能没有公网ip吧

2 个赞
41

咦，但是你的公网IP是会变动的呀，难道你IP白名单配置的都是动态IPV4吗

1 个赞
42

不清楚，只配置了一个，两个星期都能用，到时候再改吧

2 个赞
43

唔，好吧

那我建议你还是使用websocket协议

不要折腾webhook了

除非你有一个固定IPV4的服务器，不然十分不方便

1 个赞