基于NoneBot2与go-cqhttp的QQ机器人从零搭建与插件开发实战

之前想给社群或频道增加一个能自动回复、管理群聊、查询信息的智能助手尝试过不少方案要么配置复杂要么功能单一。直到接触了基于 NoneBot2 和 go-cqhttp 的 QQ 机器人方案才发现其强大的可扩展性和活跃的社区生态。本文将手把手带你从零开始在一台云服务器上搭建一个功能丰富的“云崽”QQ机器人涵盖环境部署、核心框架配置、插件安装以及安全运维的全流程。无论你是想学习机器人开发还是希望为社群提供一个实用的自动化工具这篇教程都能提供完整的、可复现的解决方案。1. 项目背景与核心概念在开始搭建之前我们首先需要理解整个技术栈的构成和各部分的作用。一个完整的 QQ 机器人系统通常不是单一程序而是一个协同工作的技术组合。1.1 什么是 QQ 机器人QQ 机器人是一种运行在服务器上的程序它通过模拟 QQ 客户端的行为实现自动登录 QQ 号、接收和发送群聊/私聊消息、处理加好友请求、执行管理命令等功能。它本质上是一个“自动化”的 QQ 账号可以 7x24 小时在线根据预设的规则或智能逻辑响应用户的交互。常见应用场景包括社群管理自动欢迎新人、定时发送公告、关键词禁言、聊天内容监控。信息查询查询天气、翻译文本、搜索百科、查询游戏战绩、生成二维码。娱乐互动抽签、占卜、成语接龙、点歌、讲笑话、AI 聊天。实用工具定时提醒、代码执行、网络状态检测、服务器状态监控。自定义服务对接企业内部系统、查询数据库、触发自动化工作流。1.2 技术栈组成NoneBot2 与 go-cqhttp我们采用的方案是NoneBot2 go-cqhttp这是目前社区最活跃、生态最成熟的 QQ 机器人开发框架之一。go-cqhttp (GOCQ):角色协议端 / 客户端模拟器。它是一个用 Go 语言编写的程序负责处理与 QQ 服务器的底层通信。它模拟 QQ 客户端的行为登录你的机器人 QQ 号接收来自腾讯服务器的原始事件如消息、通知并将这些事件转换成一个标准格式如 HTTP、WebSocket、反向 WebSocket转发给上层的机器人框架。同时它也接收来自框架的指令转换成 QQ 协议并发送出去。简单说它是机器人的“手”和“耳朵”。NoneBot2:角色机器人框架 / 大脑。它是一个基于 Python 的异步机器人框架负责处理业务逻辑。它接收来自 go-cqhttp 的事件根据开发者编写的“插件”Plugin中的规则进行匹配和处理然后生成回复指令再发回给 go-cqhttp。NoneBot2 提供了强大的插件系统、事件过滤器、依赖注入等机制让开发者可以专注于功能实现而无需关心底层协议细节。两者关系图解用户 机器人 - QQ 服务器 - go-cqhttp (接收、转换) - NoneBot2 (处理、生成回复) - go-cqhttp (转换、发送) - QQ 服务器 - 用户收到回复为什么选择这个组合生态丰富NoneBot2 拥有海量的社区插件几乎可以“开箱即用”实现大部分常见功能。开发友好使用 Python 语言学习成本低易于二次开发和自定义插件。协议稳定go-cqhttp 作为协议实现更新维护积极相对稳定。架构清晰前后端分离框架与协议解耦便于维护和升级。1.3 “云崽”机器人是什么“云崽”并非一个特定的官方机器人它更像是一个基于 NoneBot2 生态的、功能集成度很高的机器人项目模板或插件集合的流行称呼。通常一个被称为“云崽”的机器人会预装大量实用插件如签到、抽卡、游戏查询、管理工具等并拥有一个相对完善的管理系统。在本文的语境下我们搭建的就是一个以 NoneBot2 为框架集成丰富社区插件功能类似“云崽”的个性化 QQ 机器人。我们会从最基础的框架搭建开始逐步添加你需要的功能。2. 环境准备与服务器选择在开始写代码之前我们需要准备好运行环境。一台稳定、有公网 IP 的服务器是必需品。2.1 服务器选择与配置机器人需要长期在线因此不建议使用个人电脑关机即下线。推荐使用云服务器。推荐配置最低要求CPU1 核内存1 GB硬盘20 GB系统Ubuntu 20.04/22.04 LTS 或 CentOS 7/8本文以Ubuntu 22.04为例网络需要公网 IPv4 地址。这是 go-cqhttp 能够接收到 QQ 服务器消息的关键。云服务商选择国内外主流云服务商均可根据自身需求和预算选择。确保其服务条款允许运行此类自动化程序。购买后请记下服务器的公网 IP 地址、登录密码或密钥。安全组/防火墙配置在云服务器的控制台配置安全组或防火墙规则开放必要的端口。至少需要SSH (22):用于远程连接和管理。go-cqhttp 端口 (默认 5700):用于 NoneBot2 连接 go-cqhttp如果是反向 WebSocket 则不需要额外开放因为是机器人主动连接。NoneBot2 端口 (默认 8080):如果你需要提供 HTTP 服务如某些插件需要则需要开放。初期可以不开。2.2 本地与服务器基础环境搭建我们通过 SSH 连接到服务器进行操作。连接服务器ssh root你的服务器公网IP # 输入密码或使用密钥认证更新系统包apt update apt upgrade -y # Ubuntu/Debian # 如果是 CentOS: yum update -y安装 Python 和 pipNoneBot2 需要 Python 3.7.3 版本。Ubuntu 22.04 通常自带 Python 3.10。# 检查 Python 版本 python3 --version # 安装 pip 和 venv虚拟环境工具 apt install python3-pip python3-venv -y安装 Git用于拉取代码和插件apt install git -y3. 部署 go-cqhttp 协议端go-cqhttp 是我们的机器人与 QQ 网络通信的桥梁。3.1 下载与运行 go-cqhttp访问发布页面在服务器上我们通过wget从 GitHub 下载最新版本的 go-cqhttp。打开浏览器访问https://github.com/Mrs4s/go-cqhttp/releases/latest找到适合你服务器系统的版本。对于 Linux 64位通常是go-cqhttp_linux_amd64.tar.gz或go-cqhttp_linux_amd64。复制其下载链接。在服务器上下载并解压# 创建一个专门的工作目录 mkdir ~/qqbot cd ~/qqbot # 下载请将URL替换为实际的最新版链接 wget https://github.com/Mrs4s/go-cqhttp/releases/download/v1.0.0-rc4/go-cqhttp_linux_amd64.tar.gz # 解压 tar -zxvf go-cqhttp_linux_amd64.tar.gz # 授予执行权限 chmod x go-cqhttp首次运行生成配置文件./go-cqhttp首次运行会提示选择通信方式并生成config.yml配置文件。此时程序会退出。3.2 配置 go-cqhttp编辑生成的config.yml文件这是核心配置。nano config.yml你需要关注并修改以下几个关键部分# 账号配置 account: uin: 123456789 # 你的机器人QQ号 password: # 密码为空时使用扫码登录。建议留空使用扫码更安全。 encrypt: false # 是否开启密码加密需要配套签名服务新手不建议开 status: 0 # 在线状态 0-正常 1-隐身 relogin: delay: 3 # 重连延迟 interval: 0 # 重连间隔 max-times: 0 # 最大重连次数0为无限制 # 心跳配置 heartbeat: interval: 5 # 心跳频率单位秒 # 消息配置 message: post-format: string # 消息格式string 或 array ignore-invalid-cqcode: false # 是否忽略无效CQ码 force-fragment: false # 是否强制分片发送长消息 fix-url: false # 是否自动转换URL # 网络服务配置重点 servers: # 添加一个 HTTP 通信方式NoneBot2 使用 - http: host: 127.0.0.1 # 监听地址本地环回 port: 5700 # 监听端口 timeout: 5 # 请求超时 long-polling: enabled: false # 是否开启长轮询 middlewares: : *default # 引用默认中间件 post: # 上报地址NoneBot2 接收事件的地方 - url: http://127.0.0.1:8080/onebot/v11/http # 假设NoneBot2运行在本机8080端口 secret: # 密钥与NoneBot2配置一致用于校验 # 更推荐使用 反向WebSocket (Reverse WebSocket) - ws-reverse: universal: ws://127.0.0.1:8080/onebot/v11/ws/ # NoneBot2 的 WebSocket 地址 api: ws://127.0.0.1:8080/onebot/v11/ # 反向WS API地址 event: ws://127.0.0.1:8080/onebot/v11/ # 反向WS事件地址 reconnect-interval: 5000 # 重连间隔 middlewares: : *default关键配置解释uin: 填写你准备用作机器人的 QQ 号。强烈建议使用一个全新的、不重要的“小号”避免主号风险。password: 留空。首次运行时会使用扫码登录之后会保存 session 令牌实现免密登录。servers: 定义了 go-cqhttp 如何与 NoneBot2 通信。HTTP:需要配置post.url指向 NoneBot2 的 HTTP 上报地址。NoneBot2 作为服务端。ws-reverse (反向WebSocket):更推荐此方式。go-cqhttp 作为客户端主动去连接 NoneBot2 的 WebSocket 服务。配置更简单稳定性通常更好。我们后续的 NoneBot2 配置将基于此方式。保存并退出编辑器 (CtrlX, 然后Y, 然后Enter)。3.3 运行与登录 go-cqhttp再次运行 go-cqhttp./go-cqhttp扫码登录程序运行后会在控制台输出一个二维码图片用字符画显示。使用你的机器人QQ号对应的手机 QQ 扫描此二维码进行登录。如果服务器是纯命令行环境二维码可能显示异常。此时程序会在同级目录生成qrcode.png图片文件。你可以使用scp命令将其下载到本地查看# 在本地终端执行 scp root你的服务器公网IP:~/qqbot/qrcode.png .然后打开本地的qrcode.png扫码。登录成功扫码确认后控制台会显示登录成功的信息并开始输出心跳日志。此时go-cqhttp 已在后台运行并保持在线。后台运行可选但重要为了在断开 SSH 连接后程序依然运行我们需要使用screen或systemd将其放入后台。使用 screen# 安装 screen apt install screen -y # 新建一个 screen 会话 screen -S gocq # 在 screen 会话中启动 go-cqhttp ./go-cqhttp # 按 CtrlA然后按 D 键将会话放到后台 # 恢复会话screen -r gocq使用 systemd (更规范)创建服务文件/etc/systemd/system/gocq.service[Unit] DescriptionGo-CQHttp Service Afternetwork.target [Service] Typesimple Userroot WorkingDirectory/root/qqbot ExecStart/root/qqbot/go-cqhttp Restarton-failure RestartSec5 [Install] WantedBymulti-user.target然后启用并启动服务systemctl daemon-reload systemctl enable gocq systemctl start gocq systemctl status gocq # 查看状态至此协议端已部署完毕并保持在线。接下来部署大脑——NoneBot2。4. 部署 NoneBot2 机器人框架NoneBot2 是我们的机器人逻辑核心。4.1 创建项目与虚拟环境创建项目目录并进入cd ~ mkdir nonebot_bot cd nonebot_bot创建 Python 虚拟环境虚拟环境可以隔离项目依赖避免污染系统 Python 环境。python3 -m venv venv激活虚拟环境source venv/bin/activate激活后命令行提示符前会出现(venv)标识。4.2 安装 NoneBot2 及相关依赖使用国内镜像加速安装pip install nb-cli nonebot2[fastapi] nonebot-adapter-onebot -i https://pypi.tuna.tsinghua.edu.cn/simplenb-cli: NoneBot2 的命令行工具用于快速创建和管理项目。nonebot2[fastapi]: NoneBot2 框架本体并安装 FastAPI 驱动。nonebot-adapter-onebot: OneBot v11 协议适配器用于连接 go-cqhttp。使用脚手架快速初始化项目推荐nb create按提示进行选择Project name: 输入项目名如my_qq_bot。Runtime environment: 选择FastAPI。Template: 选择bootstrap(初学者模板)。Load builtin plugin?: 选择n(我们先不加载内置插件后续手动安装)。 完成后会生成一个项目目录如my_qq_bot进入该目录。cd my_qq_bot4.3 配置 NoneBot2项目的主要配置文件是.env和bot.py。配置环境变量 (.env 或 .env.prod)nano .env.prod写入以下配置# 驱动配置 DRIVER~fastapi # 监听地址和端口 (供 go-cqhttp 的 ws-reverse 连接) HOST127.0.0.1 PORT8080 # OneBot 协议适配器的配置 # 如果你在 go-cqhttp 中配置了 secret这里也需要填一样的 # SECRET # 超级用户列表你的QQ号用于执行管理员命令 SUPERUSERS[你的管理员QQ号] # 命令起始符例如 / 或 . COMMAND_START[/, ] COMMAND_SEP[.]HOST和PORT必须与 go-cqhttp 配置中ws-reverse的地址 (ws://127.0.0.1:8080/...) 一致。SUPERUSERS填写你自己的 QQ 号不是机器人号这样你就能在群里对机器人发送管理员指令。检查 bot.py脚手架生成的bot.py通常无需修改。它负责加载适配器和插件。# bot.py import nonebot from nonebot.adapters.onebot.v11 import Adapter as OneBotV11Adapter # 初始化 NoneBot nonebot.init() # 注册适配器 driver nonebot.get_driver() driver.register_adapter(OneBotV11Adapter) # 加载插件内置插件和自定义插件 nonebot.load_builtin_plugins() nonebot.load_plugins(src/plugins) # 加载 src/plugins 目录下的插件 if __name__ __main__: nonebot.run()4.4 运行与测试 NoneBot2在虚拟环境中运行 NoneBot2# 确保在项目根目录 (my_qq_bot) 下且虚拟环境已激活 python bot.py如果看到类似Uvicorn running on http://127.0.0.1:8080的日志说明 NoneBot2 启动成功正在监听 8080 端口。验证连接确保 go-cqhttp 也在运行。观察 go-cqhttp 和 NoneBot2 的日志。go-cqhttp 日志应显示成功连接到 WebSocket 服务器 ([INFO]: 正在尝试连接到反向WebSocket服务器 ws://127.0.0.1:8080/...)。NoneBot2 日志应显示适配器连接成功。 此时基础的通信链路已经打通。发送测试消息用你的个人 QQ 号向机器人 QQ 号或它所在的群发送一条消息。在 NoneBot2 的控制台日志中你应该能看到收到消息的事件记录。目前机器人还没有任何插件所以不会回复。后台运行 NoneBot2同样我们需要让 NoneBot2 在后台持续运行。使用screen或systemd。使用 systemd创建服务文件/etc/systemd/system/nonebot.service[Unit] DescriptionNoneBot2 QQ Robot Service Afternetwork.target gocq.service # 可以设置依赖确保 gocq 先启动 Wantsgocq.service [Service] Typesimple Userroot WorkingDirectory/root/nonebot_bot/my_qq_bot EnvironmentPATH/root/nonebot_bot/venv/bin ExecStart/root/nonebot_bot/venv/bin/python bot.py Restarton-failure RestartSec5 [Install] WantedBymulti-user.target启用并启动systemctl daemon-reload systemctl enable nonebot systemctl start nonebot systemctl status nonebot5. 安装与配置插件打造“云崽”功能NoneBot2 的强大之处在于其插件生态。我们可以通过安装社区插件快速赋予机器人各种能力。5.1 插件安装方式插件通常以 Python 包的形式发布在 PyPI 或 GitHub 上。使用 pip 安装推荐# 激活虚拟环境 source ~/nonebot_bot/venv/bin/activate cd ~/nonebot_bot/my_qq_bot # 安装插件包例如一个简单的复读机插件假设包名为 nonebot-plugin-repeater pip install nonebot-plugin-repeater -i https://pypi.tuna.tsinghua.edu.cn/simple通过 nb-cli 安装nb plugin install nonebot-plugin-repeater从 GitHub 安装适用于未发布到 PyPI 的插件pip install githttps://github.com/作者名/仓库名.git5.2 加载与配置插件安装插件后需要在 NoneBot2 的配置文件pyproject.toml或bot.py中加载它。使用pyproject.toml配置推荐脚手架生成的项目已有此文件编辑pyproject.toml文件[tool.nonebot] plugins [] # 在 plugins 列表中添加插件模块名 plugin_dirs [src/plugins] # 在 tool.nonebot.plugins 下添加插件配置 [tool.nonebot.plugins.插件模块名] # 插件特定的配置项每个插件不同需查阅插件文档 # 例如 # [tool.nonebot.plugins.nonebot_plugin_repeater] # enable true # priority 10更简单的方式是直接在bot.py中加载# 在 bot.py 的 nonebot.load_plugins 之前或之后 nonebot.load_plugin(nonebot_plugin_repeater) # 加载已安装的插件寻找“云崽”风格插件集“云崽”本身不是一个单一插件。你需要根据功能需求寻找对应的插件。以下是一些常见功能对应的插件方向插件名可能随时间变化请以社区商店为准基础娱乐签到 (nonebot-plugin-sign)、抽卡/扭蛋 (nonebot-plugin-gacha)、骰子 (nonebot-plugin-dice)、成语接龙。实用工具天气查询 (nonebot-plugin-weather)、翻译 (nonebot-plugin-translator)、二维码生成、短链接生成、密码生成。信息查询哔哩哔哩视频解析、知乎热榜、搜索引擎、星座运势。群管理入群欢迎、关键词回复、定时消息、禁言提醒、消息记录。AI对话接入大型语言模型的插件需自行配置 API Key。如何寻找插件访问 NoneBot2 官方商店https://v2.nonebot.dev/store在 GitHub 搜索nonebot-plugin-*关注相关社区和论坛安装示例插件包例如我们安装一个经典的nonebot-plugin-chessai下棋和nonebot-plugin-wordcloud生成词云来体验一下。pip install nonebot-plugin-chessai nonebot-plugin-wordcloud然后在bot.py中加载它们并重启 NoneBot2 服务。systemctl restart nonebot现在在群里发送/chess或生成词云等指令具体指令需查看插件文档机器人就应该能响应了。5.3 编写自定义插件进阶当社区插件无法满足需求时你可以自己编写插件。创建插件目录在src/plugins下新建一个文件夹例如my_custom_plugin。创建__init__.py文件这是插件的入口文件。# src/plugins/my_custom_plugin/__init__.py from nonebot.plugin import PluginMetadata from .hello import * __plugin_meta__ PluginMetadata( name我的自定义插件, description一个简单的打招呼插件, usage发送 /hello 试试看, typeapplication, homepagehttps://github.com/your_name/your_repo, configNone, extra{}, )编写功能模块# src/plugins/my_custom_plugin/hello.py from nonebot import on_command from nonebot.adapters.onebot.v11 import MessageEvent, MessageSegment from nonebot.rule import to_me hello_cmd on_command(hello, ruleto_me(), aliases{你好, 嗨}, priority5, blockTrue) hello_cmd.handle() async def handle_hello(event: MessageEvent): user_id event.get_user_id() # 发送一条文本回复 await hello_cmd.finish(MessageSegment.text(f你好呀用户 {user_id}))重启 NoneBot2 后对机器人说 “/hello” 即可测试。6. 常见问题与排查思路在搭建和使用过程中你可能会遇到以下问题问题现象可能原因排查步骤与解决方案go-cqhttp 扫码登录失败1. 二维码过期。2. 网络问题。3. 账号被风控。1. 重新运行./go-cqhttp生成新二维码。2. 检查服务器网络尝试更换服务器地区。3. 使用账号密码登录有风险或更换 QQ 号。go-cqhttp 无法连接 NoneBot21. NoneBot2 未启动或端口不对。2.config.yml中ws-reverse地址配置错误。3. 防火墙/安全组未开放端口。1. 检查 NoneBot2 进程状态和日志 (systemctl status nonebot)。2. 核对config.yml中的universal地址与 NoneBot2 的HOST:PORT是否完全一致。3. 检查服务器本地防火墙 (ufw status) 和云服务商安全组规则。机器人收不到消息/不回复1. 通信链路中断。2. 插件未正确加载。3. 消息不符合插件触发规则。1. 分别查看 go-cqhttp 和 NoneBot2 的日志确认消息上报和接收事件。2. 在 NoneBot2 日志中查看插件加载信息。3. 检查插件所需的命令前缀 (COMMAND_START) 和关键词。插件安装后报ModuleNotFoundError1. 插件依赖未安装。2. 虚拟环境未激活或不对。3. 插件名称错误。1. 根据插件文档安装其依赖 (pip install -r requirements.txt)。2. 确保在正确的虚拟环境中操作并重启 NoneBot2。3. 确认 pip 安装的包名与load_plugin中引用的模块名一致。账号被冻结或限制行为被腾讯判定为异常。1.最重要使用小号不要用主号2. 降低消息发送频率避免刷屏。3. 避免发送广告、敏感、违规内容。4. 如果被冻结尝试通过 QQ 安全中心解冻并暂停使用一段时间。服务器资源占用过高1. 插件存在内存泄漏或死循环。2. 并发处理消息过多。1. 使用htop或top命令监控进程。2. 禁用或优化有问题的插件。3. 考虑升级服务器配置。7. 最佳实践与运维建议为了让你的机器人稳定、安全、长久地运行请遵循以下建议账号安全第一务必使用专用小号。主号被封禁后果严重。go-cqhttp 配置中优先使用扫码登录而非密码登录。定期检查session.token文件权限避免泄露。配置管理将config.yml和.env等配置文件纳入版本控制 (如 Git)但务必通过.gitignore排除包含敏感信息如 token的文件。为生产环境和开发环境使用不同的配置文件如.env.prod,.env.dev。进程守护强烈推荐使用systemd来管理 go-cqhttp 和 NoneBot2 进程。它提供自动重启、日志管理、开机自启等功能比screen更可靠。配置合理的Restart策略如on-failure。日志与监控配置 systemd 服务使用journalctl -u gocq -f和journalctl -u nonebot -f来实时查看和追踪日志。将日志导出到文件便于后期排查问题。可以编写简单的监控脚本检查进程是否存活并通过其他渠道如邮件、Server酱告警。插件管理在安装社区插件前先阅读其文档了解其功能、配置和潜在风险。定期更新插件和框架版本以获取新功能和安全修复。使用pip freeze requirements.txt记录所有依赖方便在新环境部署。性能与规范避免编写或使用会频繁调用外部 API、进行大量循环或阻塞操作的插件以免拖慢机器人响应速度或导致风控。在群聊中合理设置机器人的响应频率和触发条件避免刷屏打扰用户。尊重用户隐私不要设计和部署用于记录、分析用户私人聊天内容的插件。遵守平台规则明确了解并遵守腾讯 QQ 平台的相关服务条款。自动化工具的使用存在一定风险。机器人行为应积极健康不用于传播恶意信息、骚扰用户或进行其他违规操作。通过以上步骤你已经成功搭建了一个功能可扩展的 QQ 机器人基础框架。从协议连接、框架部署到插件生态你已经掌握了核心的搭建和配置流程。接下来就是根据你的具体需求去探索和安装丰富的社区插件或者动手开发独一无二的自定义功能打造一个真正属于你自己的“云崽”机器人。