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

shangxue · 2024 年12 月 23 日 16:10

由于 QQ 官方声明，WebSocket 协议将在2024年年底不再维护，

所以为各位开发者提供此教程——从选购服务器、配置服务到上线机器人的全流程教程帖~

shangxue · 2024 年12 月 23 日 16:11

在教程开始之前，你还需要准备几样东西哦：

一个域名
一个SSL

你需要确保可以通过

https://你的域名

访问得到内容

比如这样网页这样 → https://webhook.company/

（如果你已经完成此步/达到此要求，请向下移步至对应教程处）

当然如果你完全不知道该怎么做

我们接下来也会教你如何搭建这样一模一样的网站

~~

shangxue · 2024 年12 月 23 日 16:12

购买-搭建域名+SSL

建议购买境外服务器（可以免备案）

为了演示

我们此处示例使用比较平民向的雨云服务器

来演示

可以首先来到雨云官网 → https://app.rainyun.com/

在登录/注册账号后，我们前往购买一台服务器+域名+申请SSL证书

第一步 → 购买云服务器

我们前往 → 雨云 - 新一代云服务提供商

这里我选择的是香港的服务器

考虑到大部分看此教程的用户，我们此处电脑系统选择 Windows server 2025

当然，4G 内存就够我们使了，2G其实也行只是操作起来太卡了啦~

购买之后我们就可以在这里看到我们购买了的服务器了

→ 雨云 - 新一代云服务提供商

第二步 → 购买域名

来到域名注册的页面 → 雨云 - 新一代云服务提供商

我们可以搜索自己喜欢的英文单词作为域名

这里呢

我们演示的话就选一个叫 webhook 的吧

然后看看价格我们差不多选择这个吧 → webhook.company

由于我之前已经买过了所以这里显示的是暂不可用

然后我们就需要付款了捏

注意这里如果你是第一次买那么这里是需要填写【实名认证模板】的

请如实填写哦~

然后点击最下方的【付款】

买完域名之后我们需要把他与我们对应的服务器IPV4地址相对应解析

我们来到这个页面 → 雨云 - 新一代云服务提供商

选择你购买的对应的域名，然后点击【设置】按钮

我们需要先添加一个解析记录

然后按照我们这个来选即可

注意其中：

一定要选择对应的雨云产品ID（就是云服务器的产品ID）
主机名称要写 @ ，不是让你起名字。。。。
其他默认即可

image737×1089 28.6 KB

点击【添加】

在这之后的 2 到 24 小时之内这个就会生效啦~

你就可以通过域名访问了呢

为了成为安全的网站

我们还必须要有证书呢！

第三步 → 申请 SSL 证书

我们可以在雨云免费申请SSL证书

→ 雨云 - 新一代云服务提供商

我们刚才购买的是

webhook.company

所以在这里我们需要这样填写哦

我们点击【立即验证】之后就会有一个这个申请记录啦

我们点击右侧的【小眼睛】

我们需要先分别记录一下这两个内容

然后我们来到【域名解析设置】这里 → 雨云 - 新一代云服务提供商

填入之后呢

应该就会有这样的两个记录啦

然后这个时候我们再回到 SSL证书这里点击【立即验证】

如果你出现了

那请你再仔细检查检查是不是弄错了什么

如果你出现了

那你需要再等待一会

毕竟上面说啦嘛 2 到 24 小时生效

你也可以在这里验证SSL的有效性 → SSL Server Test (Powered by Qualys SSL Labs)

最终我们可以得到这样的结果

然后我们来下载一下证书

下载得到一个压缩包

这个压缩包里有我们需要的证书啦

你需要解压后放到一个文件夹里

接下来我们需要配置 Nginx 啦

shangxue · 2024 年12 月 23 日 16:14

配置 Nginx

我们登录到云服务器

这里如果你的 Windows 连接 Windows

我们可以使用 RDP 来远程桌面连接

我们在这里找到服务器的公网IP 用户名密码

填入到对应的地方然后就可以连接啦

注意用户名不要写错哦

然后我们来到了服务器上，

需要先去几个地方下载/安装一些软件

我这里列出本教程需要下载的软件哦

这些软件的安装就不在此赘述了

好的假设你现在已经安装好了 koishi 和一个编辑器可以编辑文件、nginx配置文件

那现在我们就可以继续了

配置 nginx

我们找到 nginx 所在位置

找到配置文件 nginx.conf

我们可以使用VScode打开，
并且编辑

我们需要修改内容哦

你可以参考我的呢~

worker_processes  1;

events {
    worker_connections  1024;
}

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

    # 重定向所有 HTTP 请求到 HTTPS
    server {
        listen 80;
        server_name localhost webhook.company;  # 你的域名名称
        return 301 https://$host$request_uri;
    }

    # HTTPS 服务器（443端口）
    server {
        listen 443 ssl;
        server_name webhook.company;  # 你的域名名称

        ssl_certificate      C:/server/nginx/ssl/cert.pem;  # 你的证书路径
        ssl_certificate_key  C:/server/nginx/ssl/cert.key;  # 你的私钥路径

        # 处理 /qq 路径的反向代理
        # 反向代理到 koishi 地址（这是之后 koishi 需要使用的地址，请修改为实际的koishi地址）
        location /qq {
            proxy_pass http://127.0.0.1:5140/qq;

            # 支持 WebSocket 的必要头字段
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";

            # 传递客户端的真实 IP 地址等信息
            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;
        }

    }
}

注意！！！

这里的

        ssl_certificate      C:/server/nginx/ssl/cert.pem;  # 你的证书路径
        ssl_certificate_key  C:/server/nginx/ssl/cert.key;  # 你的私钥路径

必须换成你的自己服务器的真实路径

这两个文件就是你的证书文件，这在上一步的最后我们下载的压缩包里有哦
你需要把他放到服务器上，并且填的是服务器上的证书的绝对路径

然后保存这个文件

我们在 nginx.exe 所在文件夹的地址栏输入

cmd

然后回车

就会弹出一个黑框框

然后我们让 nginx 检查一下我们的配置文件对不对，
我们输入

nginx -t

如果输出有【successful】字眼，即代表正确

C:\server\nginx>nginx -t
nginx: the configuration file C:\server\nginx/conf/nginx.conf syntax is ok
nginx: configuration file C:\server\nginx/conf/nginx.conf test is successful

C:\server\nginx>

然后我们就可以双击 nginx 让他启动服务

要确保他在运行哦

到这里

你的网页应该就是和我一样了！

尝试使用 https 和你的域名访问看看吧！

shangxue · 2024 年12 月 23 日 16:32

配置 KOISHI — adapter-qq

第一步安装koishi

前往 → https://koishi.chat/ 选择你的安装方式

这里教程使用 项目模板 的安装方式，使用方式基本一致啦~

打开 koishi 的 webUI 之后，先进行小火箭更新，确保使用的是最新的依赖

第二步配置adapter-qq

请先根据官方机器人连接配置指南

了解如何连接对应的QQ官方机器人

回到教程

本教程演示的为全域的机器人，也贴一下配置内容吧

请注意，其中的 `protocol` 要选择 `webhook`

此时虽然右下角状态显示为绿灯，但是由于webhook 的连接特性，并不代表可以接收到消息

第三步确认koishi地址

将鼠标放到左侧活动栏处，可以看到对应的koishi地址

我们需要注意其中的koishi端口是否为预期的端口

如果与上面步骤中 nginx 配置文件所使用的地址不一致，那么请根据实际情况修改

教程此处图中端口就是 15140 端口
那么 nginx 配置文件 里写的地址就应该是  http://127.0.0.1:15140/

itzdrli · 2024 年12 月 23 日 16:38

~~雨云给了你多少钱，我出双倍~~

shangxue · 2024 年12 月 23 日 16:41

通过网址访问webUI

在上文中我们已经配置好了 nginx 和 koishi

并且已经把 koishi 的地址反代到了 433 端口

那么这个时候我们已经可以尝试通过 https://域名 来访问koishi的UI了！

访问起来，可能像这样~

如果你已经实现了这一步，那么恭喜你，你已经里完成不远啦~

配置回调地址

前往 → QQ机器人管理端

首先

配置请求地址

在这里我们填入 域名/qq，鼠标点击一下其他空白处，即可看到是否校验成功

如果没有红色的【校验失败】的提示，那就代表地址可用

为什么是 `域名/qq`？

这由于在 adapter-qq 的配置项处，所填路径默认为 /qq

在这一步，可能会有校验延迟，可以多尝试几次，延迟可能在十几分钟（指配置完 域名/qq 到可以校验成功）

然后我们

选择要添加的事件

这里我是都选了啦，

注意千万不要少选什么的，就配置完成，

会造成有一段时间收不到消息的

建议还是与本教程一样全选吧

shangxue · 2024 年12 月 23 日 16:59

测试机器人

此时你就可以对着机器人测试他有没有响应啦

由于 QQ官方平台的要求，机器人必须可以响应以 / 开头的前缀指令，

所以你需要在koishi的全局设置里进行配置

为了初测上线机器人，我们就先整些，简单的小功能吧

比如我们先安装个表情包功能来进行测试测试呢

安装完成后，我们需要在【插件配置】页面来添加这个插件

然后我们点击【开启插件】

如果没有出现指令的话，可以重新关开一下 commands 插件

然后再回到 emojihub 的插件配置页面就可以看到很多指令了

接下来，我们可以测试机器人是否响应指令

在 QQ聊头平台内，发送消息内容（请替换为你实际拥有的指令）

@机器人 /ba表情包

可以看到是有响应的呢~

那么到这里就是完成了官方机器人的 webhook 连接~

Halvanhelev · 2024 年12 月 24 日 06:45

感谢教程

araea · 2025 年1 月 2 日 14:38

谢谢上学大人的贴心教程，好人一生平安安~