2023 版 QQ 机器人运行部署文档

1.前置说明

1. 该部署文档会按照先在 Windows 上部署运行再在 Linux 服务器上部署运行的步骤讲解，每一步操作都会比较详细，提供保姆级教程，因此可以放心食用。

2. 你在 Windows 上部署运行需要有的环境：

   • JDK8 及以上版本；
   • 集成开发环境 IDEA；
   • Maven（IDEA 会自带，也可以额外下载）。

3. 如果你想让你的机器人持续运行，监听消息，你需要购买一个 Linux 服务器，同时将服务器防火墙所有端口开放。

   

4. 当然，你还需要准备一个 QQ 号作为我们的机器人，等级不要太低，群聊容易被封，私聊应该没什么问题。

5. 我们等会需要从 Github 上下载一些东西，如果你受到了网速的影响无法下载，可以从我的网盘中直接获取：https://pan.baidu.com/s/17s2usSxazCoV0FtqOGajTQ?pwd=1314

   需要下载的东西包括了：

   • pbbot-rq-v0.1.14-win-x86_64.exe
   • static.zip
   • Spring-Mirai-Server-master.zip
   • socksdroid-1.0.3.apk
   • pbbot-rq-v0.1.14-linux-x86_64

2.机器人框架的下载与运行

这里我们选用基于 ricq-高性能 QQ 协议 的机器人框架 pbbot-rq。

2.1 下载机器人框架

框架版本地址：https://github.com/ProtobufBot/pbrq/releases

由于先在 Windows 上进行演示，这里我们选择下载当前最新 0.0.14 windows 版本。

在硬盘任意位置创建一个文件夹，这里取名为 pbrq，将下载好的 pbbot-rq-v0.1.14-win-x86_64.exe 放到 pbrq 文件夹下。

为了 方便/简化 后续命令的执行，我们在这里将 pbbot-rq-v0.1.14-win-x86_64.exe 重命名为 pbbot-rq.exe：

2.2 下载可操作框架的静态页面

静态页面版本地址：https://github.com/lz1998/ricq-react-ui/releases

这里我们下载当前最新的 v0.1.7 版本。

将下载好的 static.zip 解压后也放到 pbrq 文件夹下。

2.3 运行机器人框架

在 pbrq 文件夹下打开 cmd 窗口：

执行命令：

pbbot-rq --bind-addr 0.0.0.0:9000 --static-dir static

3.登录QQ机器人

⚠️ 如果你下定决心尝试实现 QQ 机器人，请不要半途而废，最好找到比较充裕的时间把该文档的过程一次性走完。因为如果频繁的下线又登录QQ机器人存在账号被封的风险。当然这是我遇到的情况，虽然解封非常简单，只需要扫脸认证一下是本人即可。但还是最好不要这么做。

3.1 前提说明

为了保证 QQ 登录的可靠性，我们需要先对作为机器人登录的 QQ 做以下处理：

• 在手机上登录 QQ，找到 设置 -> 账号安全 -> 登录设备管理，把除了当前本机之外的其他设备管理全删除，效果如图：

  

• 将你的手机与使用的电脑处于同一网络中，有两种可选方式：

  1. 手机关闭 wifi，使用流量，同时开启手机热点，让电脑连上手机热点；
  2. 手机和电脑使用同一 wifi 信号，例如 校园网。

  ⚠️ 记得如果在手机和电脑上启动了代理设备（软件），记得关闭下。

3.2 扫码登录

访问本地网页：http://localhost:9000

点击“创建账号”，切换到“QRCode”扫码登录方式，将 QQ 号 作为“Seed”，将 Watch 作为“Protocol”。

配置信息完毕，点击“Login”，就会弹出一个二维码，直接使用手机进行扫码。

扫码后，手机上会弹出“登录确认”提醒：

点击“登录”，再次查看网页界面，切换到“正在运行”界面，就可以看到我们正在运行的 QQ 了：

运行成功后，建议不要频繁关闭又运行 pbbot-cq 机器人框架程序，因为一旦关闭了 cmd 就意味着 QQ 下线了，频繁登录可能导致被封。

这时候查看我们的 cmd 控制台，发现一直在发出警告：

这是正常的，因为该 pbbot-rq 框架一直在尝试与本机的 8081 端口建立连接。也就是我们可以编写后端程序来处理这些消息了，例如存储或者回复消息。

当然，如果你尝试使用其它 QQ 账号向该 QQ 发送消息，pbbot-rq 是可以收到消息的，会在 cmd 控制台上显示出来：

3.3 注意事项

如果遇到如下图所示登陆失败的情况：当前设备网络不稳定或处于夏杂网络环境，为了你的帐号安全，建议将两个设备连接同一网络或将被扫描设备连接你的手机热点后，重新扫码登录。

那么你在电脑上登录校验时，注意以下几点：

• 设备种子统一使用 QQ 号；
• 电脑要连接你手机的热点或使用同一 wifi，且保证代理软件已关闭；
• QQ中 设置 --> 账号安全 --> 登录设备管理 --> 删除所有除了你登录在当前手机的设备，相当于只留下了一个当前登录 QQ 的本地手机设备。

4.后端程序处理消息

我们使用一个后端程序来与 pbbot-rq 建立连接，可以接收到消息并做出处理后交给 pbbot-rq 进一步处理。

关于这个后端程序，pbbot-rq 的作者已经为我们提供了一个快速开发的 spring boot stateer，我们只需要在此基础上进一步修改代码做自定义处理即可。

4.1 下载 stater

仓库地址：https://github.com/ProtobufBot/Spring-Mirai-Server

4.2 stater 基本说明

下载完成后解压缩，使用 IDEA 打开该项目。

Plugin 包下有四个插件类，是对消息进行处理的插件，允许执行的插件以及插件的执行顺序在 application.yml 中进行配置：

spring:
  bot:
    plugin-list: # 配置插件列表（有序），如果插件返回0，继续执行剩余插件，如果插件返回1，终止剩余插件执行
      - net.lz1998.pbbot.plugin.LogPlugin # 日志插件
      - net.lz1998.pbbot.plugin.DemoPlugin # 测试插件
      - net.lz1998.pbbot.plugin.ImagePlugin # 动态生成图片插件
      - net.lz1998.pbbot.plugin.HelloPlugin # 测试插件

server:
  port: 8081 # 不要去动这个端口，因为 pbbot-rq 在尝试向本机的 8081 端口建立连接。

4.3 运行后端程序

为了方便测试与便于理解，我们先将 ImagePlugin 和 HelloPlugin 的配置注释掉：

spring:
  bot:
    plugin-list: # 配置插件列表（有序），如果插件返回0，继续执行剩余插件，如果插件返回1，终止剩余插件执行
      - net.lz1998.pbbot.plugin.LogPlugin # 日志插件
      - net.lz1998.pbbot.plugin.DemoPlugin # 测试插件
#      - net.lz1998.pbbot.plugin.ImagePlugin # 动态生成图片插件
#      - net.lz1998.pbbot.plugin.HelloPlugin # 测试插件

server:
  port: 8081

再将 DemoPlugin 修改为以下内容：

@Component
public class DemoPlugin extends BotPlugin {

    /**
     * 对私聊消息进行处理，这里我们实现一个QQ机器人复读机效果
     */
    @Override
    public int onPrivateMessage(@NotNull Bot bot, @NotNull OnebotEvent.PrivateMessageEvent event) {
        // 拿到发送给 QQ 机器人消息的发送者的 QQ 号
        long userId = event.getUserId();
        // 拿到发送者的发送消息内容
        String eventRawMessage = event.getRawMessage();
        // 构建准备回复的消息，将发送者消息作为 QQ 机器人的回复
        Msg msg = Msg.builder().text(eventRawMessage);
        // 发送消息
        bot.sendPrivateMsg(userId, msg, false);
        // 表示不继续执行下一个插件
        return MESSAGE_BLOCK;
    }
}

将 MyAspect 类的 @Component 注解注释掉：

找到 SpringMiraiServerApplication 启动类，启动项目。

可以看到新的连接已经建立了，其实是与 pbbot-rq 建立了连接。我们再观察 cmd 控制台，发现也不报警告了：

4.4 测试消息处理

我们在上一步修改了 DemoPlugin 的代码，对发送给 QQ 机器人私有消息进行了处理，即会回复重复的消息，我们就此进行测试。

拿其它 QQ 账号向 QQ 机器人发送消息，发现 QQ 机器人进行了回复：

查看 cmd 控制台：

查看后端应用程序控制台：

4.5 关于扩展消息处理

你可以自定义插件类去对消息做更多处理，作者提供的四个插件类已经做了一些示例来处理来自“私聊”和“群聊”的消息。

当然，了解更多的功能，你可以参考作者的博客：lz1998’s blog

⚠️ 在对群聊消息进行处理回复时，你需要注意 QQ 机器人的等级不要太低。我目前的 QQ 机器人等级是 3 个月亮，在十几个人的群聊里进行 QQ 机器人的消息回复没有任何问题，但当加入了一百多个人的大群进行消息回复一段时间后，就会被腾讯禁用无法发送消息到群聊（隔 24 个小时后又恢复了，如此往复几天后不再会被禁用），但私聊还是被允许的。

5.Linux 服务器持续运行 QQ 机器人

上述已经演示了如何在 Windows 上运行，为了让 QQ 机器人持续运行提供服务，我们需要把 QQ 机器人放到 Linux 服务器上。

5.1 安装 docker

基于centos的安装

1. 安装yum-utils

   sudo yum install -y yum-utils
   

2. 从国内服务器上下载docker

   sudo yum-config-manager \
       --add-repo \
       http://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
   

3. 安装docker

   sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   

4. 验证是否成功

   sudo docker --version
   

基于ubuntu

1. 安装需要的包

   sudo apt-get update
   

2. 安装依赖包

   sudo apt-get install \
      apt-transport-https \
      ca-certificates \
      curl \
      gnupg-agent \
      software-properties-common
   

3. 添加 阿里 GPG 密钥

   sudo curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo apt-key add -
   

4. 设置远程仓库

   sudo add-apt-repository \
      "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
     $(lsb_release -cs) \
     stable"
   

5. 安装 Docker-CE

   sudo apt-get update
   

   # 会让你输入 y/n，选择输入 y
   sudo apt-get install docker-ce docker-ce-cli containerd.io
   

6. 验证是否成功

   sudo docker --version
   

   

5.2 配置阿里云加速器

国内镜像中心常用的为阿里云与网易云，选择其中一个加速器进行配置即可。在本地 Docker 中指定要使用的国内加速器地址后，就可以直接从国内镜像中心下载镜像了。这里我们配置阿里云加速器。

找到相应页面

若要配置阿里云加速器，必须首先要有阿里云的账号。

登录阿里云后，打开阿里云的容器镜像服务 (aliyun.com)。

然后找到如下页面，可以查看到你的 registry-mirrors：

创建 docker 目录

sudo mkdir -p /etc/docker

创建 daemon.json 文件

注意，该 json 数据中的 URL 地址是与阿里云用户登录账号绑定的，不同的阿里云用户所生成的地址是不同的。

sudo vim /etc/docker/daemon.json

将以下内容放入 daemon.json 中，registry-mirrors 的值需要查看你的阿里云用户的加速器地址。

{
  "registry-mirrors": ["https://*******.mirror.aliyuncs.com"]
}

重新加载服务配置文件

sudo systemctl daemon-reload

重启 docker 引擎

sudo systemctl restart docker

5.3 将手机与服务器处于同一网络：socks5

在 Windows 上登录 QQ 机器人时，我们说明了需要让手机和电脑处于同一网络，这里我们需要同样进行处理，让手机和 Linux 服务器也处于同一网络。

什么是 SOCKS5

SOCKS5 是一个代理协议，它在使用 TCP/IP 协议通讯的前端机器和服务器机器之间扮演一个中介角色，使得内部网中的前端机器变得能够访问 Internet 网中的服务器，或者使通讯更加安全。

socks5 类似于梯子，可以通过 socks5 协议，将自己的设备“伪装”成对应的服务器（socks5 属于明文代理，不能用来做一些特殊的事），可以使用 socks5 来做跳板机等常用的运维工具。

设置数据卷

# 创建目录
sudo mkdir -p /app/socks5-docker

# 编辑配置信息
sudo vim /app/socks5-docker/sockd.passwd

将以下内容写入到 sockd.passwd 中：

sockd:xJY9EJy0Bk//U

运行容器

sudo docker run \
--name sockd \
--publish 2020:2020 \
--volume /app/socks5-docker/sockd.passwd:/home/danted/conf/sockd.passwd \
-d lozyme/sockd

创建用户

这里我将用户的用户名设置为 testu，密码设置为 testp。

sudo docker exec sockd script/pam add testu testp

验证

sudo curl https://ifconfig.co --socks5 127.0.0.1:2020 --proxy-user testu:testp
#此处显示为你的服务器 ip，则为成功

下载连接工具

这个工具是在手机上进行安装使用的。

下载地址：Releases · bndeff/socksdroid (github.com)

下载完成后，将安装包发送给手机，然后手机上安装。

手机与服务器建立连接

进行如下配置：

• Server IP：你的服务器的 IP 地址；
• Server Port：2020；
• Username：用户名，使用我们之前配置的 testu；
• Password：密码，使用我们之前配置的 testp。

设置完成后，点击右上角的“开关”，即可开启代理。

5.4 将所有启动文件放到 Linux

下载并上传 Linux 版的 pbbot-rq.exe

Releases · ProtobufBot/pbrq (github.com)

在 Linux 服务器上新建 qqrobot 文件夹，添加权限，并进入到该目录下：

# 在根目录下创建 qqrobot 文件夹
sudo rmdir /qqrobot

# 添加权限，方便文件上传
sudo chmod 777 /qqrobot

# 进入 qqrobot 文件夹
cd qqrobot

将从 Github 下载好的 pbbot-rq-v0.1.14-linux-x86_64 上传到 qqrobott 文件夹下：

# 将 pbbot-rq-v0.1.14-linux-x86_64 重命名为 pbbot-rq
sudo mv pbbot-rq-v0.1.14-linux-x86_64 pbbot-rq

# 添加权限
sudo chmod 777 pbbot-rq

上传静态页面

我们只需要将之前下载的 static.zip 重新解压一份上传到 Linux 服务器的 qqrobot 文件夹下即可。

打包并上传后端程序

使用 IDEA 打开我们在本文第四节使用的 Spring-Mirai-Serve，该项目我们已经实现了私聊时的复读机功能。

现在我们把这个项目打包成 jar，放到 Linux 服务器上去运行。

打包后在 target 文件夹下就可以看到了：

我们将 spring-mirai-server-0.0.1-SNAPSHOT.jar 同样上传到 Linux 服务器的 qqrobot 文件夹下：

Linux 安装 JDK 环境

• centos

  sudo yum install java-1.8.0-openjdk
  

• ubuntu

  # 会让你输入 y/n，选择输入 y
  sudo apt install openjdk-8-jre-headless
  

登录 QQ 机器人

前提说明

这里与之前在 Windows 上登录 QQ 机器人同样的要求：

• 保证登录设备只存在手机本机一个；
• 服务器和手机处于同一网络，这个问题我们已经使用 socks 解决了，登录成功后就可以关闭 socks 了。

启动 pbbot-rq

# 在 qqrobot 文件夹下执行该命令，采用的后台运行模式
sudo nohup ./pbbot-rq --bind-addr 0.0.0.0:9000 --static-dir static >pbrq.log 2>&1 &

在自己电脑上访问：http://【服务器IP】:9000

扫码登录

点击“Login”，就会显示登录二维码。

使用手机扫码后，就能登录成功了。

登陆成功后，就可以关闭 socks 了，在 Linux 上的操作：

# 关闭 socks
sudo docker stop sockd

# 启动 socks
sudo docker start sockd

启动后端程序

# 在 qqrobot 文件夹下执行该命令，采用的后台运行模式
sudo nohup java -jar spring-mirai-server-0.0.1-SNAPSHOT.jar >qqrobot.log 2>&1 &

测试

使用其它账号尝试向 QQ 机器人发送消息：

停止运行

停止后端程序运行

如果你是想让 QQ 机器人停止对消息的处理而不是退出登录，则只需要停止后端程序的运行。当然也推荐这么做，避免重复登录。

# 查看后端程序运行的 pid
sudo ps -ef | grep java

# 格式：sudo kill 
sudo kill 22016

停止 pbbot-rq 框架运行

这意味着 QQ 机器人下线。

# 查看框架运行的 pid
sudo ps -ef | grep pbbot-rq

# 格式：sudo kill 
sudo kill 21915

6.总结

以上就是全部说明，每一步都是我的实际操作。

最后，如果你在运行 QQ 机器人一段时间后遇到了如下问题被迫下线：

你只需要点击“去处理”，认证是本人登录即可，非常简单。初次使用 QQ 机器人时可能会遇到这个问题，运行久了就不会出现了。