如何部署一个QQ机器人？（小白版教程，中登也可以看看，大佬勿喷）

声明

本文章内容仅供交流学习之用，请勿用于非法用途
本文章纯属科普技术类文章，不存在任何呼吁、引导行为
本文章如有侵权，请通过首页联系作者删除

引言

相信不少兄弟姐妹们都看到过QQ机器人的存在，不论是官方的还是非官方的，不论是群聊的还是私聊的，每个感觉都很有意思，所以这篇文章我会带大家了解QQ机器人的技术，想要体验的可以直接选择加入社群体验机器人。首先，你必须要了解基础概念的相关部分（小白不看的话可能会有一丢丢问题，这里的小白指的是完全没有计算机或者IT相关知识的人），中登可以看一下详细教程，里面的各个参数甚至是重要方法我都会提及，小白直接看速通教程！

基础知识

一.客户端，服务端，协议端，第三方服务端

1.1. 定义

客户端：指的就是用户使用的平台，比如QQ本身就是一个典型的客户端，用于响应各种业务处理，比如你发送消息，接收消息，就是响应业务的表现
服务端：指的是后端处理数据的部分，接着上面的例子，你在发送消息和接收消息的时候，会产生数据交换的过程，而处理这些数据的平台或者位置就被成为服务端
协议端：从狭隘的角度来说，就QQ机器人这一项业务的理解范围来看，它的作用类似于服务端，是机器人项目中约定俗成的名称，功能也更侧重于”服务“，它的作用是代替用户桥接客户端与服务端进行通信，即发送消息。相当于模拟用户发出消息和调用客户端的功能（比如群聊，私聊，点赞等行为），第三方服务端会负责和协议端进行交接
第三方服务端（bot端）：这是我为了方便你们理解做出的新名词，方便你们更好理解，第三方服务端其实就是处理”接收消息“的地方，并将要发送的消息以协议端规定的格式传输，最后协议端根据第三方服务端传入的参数发送处理好的数据。

名称	功能	重要性
客户端	本地响应服务端或者用户数据	一般
服务端	处理客户端的响应数据	一般
协议端	代替用户执行各种消息的发送	重要
bot端	截获好友，群友等发送的消息，将处理结果发送给协议端处理	重要

所以QQ机器人的核心之一，就是协议端，客户端和服务端的概念不需要了解太清楚，重点掌握协议端和bot端。

1.2. 协议端的应用和主流框架

1.2.1 如何使用协议端？

大多数情况下，协议端会拉取一个兼容本协议端的QQ版本，（甚至许多协议端还能兼容其他社交平台应用），当然，这些都会自动完成。

首先，当你拉取相关协议端框架或者应用后，必须先登陆机器人账号，这样才能保证协议端能够正常发送消息。

接着，你需要规定不同服务运行的端口和网络协议类型（http,反向http,ws,反向ws），大多数情况下，一个端口只能运行一个服务。你并不需要了解这些网络协议的底层实现，大多数情况下，bot端的使用文档会给出你默认需要协议端运行的端口，或者你可以通过直接修改.env或者config.toml文件来修改需要连接的协议端开放的端口，协议端再开放对应的端口。

而不同的协议端可能采用不同的协议，不同协议的原理和数据格式要求可能也不同。

总的来说，协议端是负责转发bot端响应数据的载体，相当于模拟用户发送指定消息

1.2.2 主流协议端介绍和应用推荐

协议端名称	采用协议	特点	是否推荐
napcat	onebotv11	图形化页面（webui可视化操作）加命令行页面双支持；支持一号部署多个机器人，也支持多号部署多个机器人，灵活性强；onebot协议兼容目前大多数平台的机器人项目，扩展性强	十分推荐，我自己就用这个协议端适配了三个机器人
llonebot	onebotv11/satori	原生支持onebot协议，适合追求稳定的玩家,同时也兼容了不同的协议框架	推荐
icqq	tea协议	目前仍然有一部分机器人（如yunzai）默认使用icqq,需要签名才能正常使用,新版icqq的特性尚不可知，可以自行了解	不太推荐
mirai -console	mirai协议	java编写，性能可能更强，也需要额外签名等步骤，感兴趣的可以试一下	不太推荐

二.bot端

前文已经提到过了，大多数bot所需要连接到的协议端的地址都是反向ws，你可能需要在bot端的配置文件填写或者修改你在协议端设置的反向ws的监听地址，以及一些额外的机器人配置（比如机器人的自称等配置），这些配置文件的位置在开源项目的文档都会给出来，没有给出来的话，也可以通过查找.env,.nev.prod,.env.dev,config.yaml,config.toml等文件中查找，在这里给出我目前正在使用的机器人列表：

名称	特点	是否推荐
zhenxun_bot	基于nonebot开发，拥有丰富的后台网页呈现，方便进行管理和配置，并且插件商店支持60＋插件，均可通过指令下载，对新手十分友好	非常推荐新手尝试部署这个项目
nonebot2	支持上百个插件，并且能兼容部分真寻的插件，日常维护社区活跃，对功能丰富度要求比较高的可以考虑，但全程都是命令行操作，新手理解起来可能有一点难度	比较推荐
yunzai	有多个yunzai版本（yunzai,imao-yunzai,trss-yunzai），推荐使用trss-yunzai,通过docker部署，稳定性极高，能够兼容miao-yunzai ,其原始功能主要是提供米家游戏的查询，也提供了较为丰富的插件，但比真寻的插件要少一点	推荐

三.云服务器

众所周知，不论是什么程序，都需要一个运行载体，而我们所需要的就是-云服务器，大多数情况下，云服务器会给你分发一个公网IP,以及提供会话管理，文件管理，防火墙配置等功能。并且，云服务器支持预装不同的主流系统或者应用，比如Linux系服务器ubuntu,debian或者win系列的win-server服务。

2.1 云服务器配置

一般情况下，云服务器最主要的配置有内存，核心，存储，流量，CPU,显卡等主要配置，机器人属于极小型的项目，一般情况下，只需要关注其内存，核心，存储这三项信息，购买页面的提示大概是，2核2G 40SSD之类的提示，这三项对应的分别就是上述的三条信息，也可以简称为2h2g 40 SSD.

2.2 云服务器推荐

目前国内比较出名的云服务器厂商有阿里云，腾讯云，华为云，甚至还有抖音云服务器，我自己选用的腾讯云服务器。关于详细的配置的话，如果是只有一个机器人且处理的消息不多，那么2核2G的linux云服务器足够满足你的需求，不推荐win-server是因为win系统的图形占用忒高了，而linux比较轻量。

如果你部署了三个及以上的机器人，那么你至少需要2核4G的配置，4G的内存才能应对这种数据频繁的场景。

2.3 云服务器必须执行的命令（以ubuntu为例，首次进入终端后需要执行的命令）

包更新：sudo apt update && sudo apt upgrade

docker容器的依赖：sudo apt install docker

python的相关依赖：sudo apt install python3 && python --version

poetry相关的依赖：pip install poetry

四.linux运维常见问题

问题	解释	解决方法
permission denied	权限不足，需要用chmod赋权或者直接加上sudo(超级用户)	在执行命令的前面加上sudo
no such file or dictory	没有目标文件夹或者文件（mkdir创建文件夹，touch创建指定后缀名的文件）	mkdir /path/to/dictory touch example.txt
address has been used	指定端口被其他程序占用，需要先通过netstat找出其PID,再通过sudo kill -9 PID,结束占用这个端口的进程	以8080端口被占用为例： netstat -tuln \| grep 8080 (假设显示出了PID为666666) sudo kill -9 666666
其他的需要补充的常见错误会根据其他人遇到的问题来进行更新

速通教程（以zhenxun bot为例）

一.打开云服务器(请安装22.04版本的ubuntu-server)，创建如图的会话（mihomo为魔法，如果不需要使用国外模型，或者你额外设置代理，则不需要mihomo这个东西，这里你可以选择不创建,meme-gene是一些比较那种的表情包创建方法，不需要的也可以忽略）,会话可以保证你在离开云服务器后，程序能一直保持运行

二.安装napcat:打开napcat的会话，你需要运行以下命令

curl -o \
napcat.sh \
https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh \
&& sudo bash napcat.sh

在运行命令的过程中，只需要按照其默认的Y/N提示来输入后回车安装即可，强烈建议选择安装GUI图形化页面。

在完成安装后，napcat会自动启动，你的操作如下：启动napcat-配置新账号-填写账号-等待登陆-获取二维码，尝试用QQ扫描，如果成功了忽略下面的两步-解码URL-复制那一段网址-前往二维码在线生码网站（如草料二维码，将网址粘贴过去生成二维码再用QQ扫描）-配置账号-设置类型为反向ws-设置ws地址为ws://127.0.0.1:8081/onebot/v11/ws-选择保存-回到最初页面-选择你添加的机器人账号-选择查看日志

三.安装并配置zhenxun_bot

打开zhenxun的会话，运行以下内容

su - ubuntu
pip install nb-cli
nb self install nb-cli-plugin-zhenxun
nb zx

然后，选择安装小真寻，推荐用git安装，然后选择国内类型，等待完成下载后，填写以下三项信息，超级用户QQ号指的是机器人的主人账号，数据库连接地址留空即可，然后选择Y,安装完成后，依次运行以下代码

cd zhenxun_bot
chmod +x /*
sudo apt install sqlite3 -y
poetry run python bot.py

等到它显示运行地址的时候（类似于127.0.0.1时），程序可能会停止加载，此时选择用CTRL+C结束运行，然后在终端输入 nano .env.dev,找到port,将8080改为8081,接着CTRL+X,CTRL+Y,CTRL+M,保存并退出，同样的套路，在终端输入nano data/config.yaml,可以填写其他的配置，用相同的方法保存并退出。

再次输入poetry run python bot.py,看到初始化bot成功，就证明机器人已经成功部署了,可以通过对机器人发送菜单获取详细帮助，也可以在此处查看官方文档

四.其他注意事项: 在完成机器人部署后，私聊发送检查更新 main,更新真寻版本

4.1 关于AI模块

我用的BYM_AI，通过发送插件商店，再发送添加插件44即可获取，向zhenxun发送重启，等待机器人重新连接后，配置就载入成功了，此时添加终端上方的加号新建一个新的临时终端（不是会话！）

然后通过输入nano data/config.yaml，找到BYM_AI的配置项,将URL设为：https://api-proxy.me/gemini/v1beta/chat/completions

然后填入你gemini申请的免费的key或者说是token（必须是按列表形式填写，填写两个以上）,你就可以使用gemini的AI了，模型按照我的填就对了，比如：

BYM_AI_CHAT_TOKEN:
  - AItestkey1
  - AItestkey2
  BYM_AI_CHAT_MODEL: gemini-2.5-flash-lite-preview-06-17
  BYM_AI_TOOL_MODEL: gemini-2.5-flash-lite-preview-06-17

然后老样子保存，接着对机器人再发送重启，就可以载入配置了