部署你的第一个通用机器人框架--QQ篇

前言

本文所有操作基于 Ubuntu server 24.04 系统进行部署，全程需要在Shell环境下操作，无图形交互界面（WebUI除外），使用 Napcat + NoneBot框架 架构部署，请自行准备好相关环境

优先选择阅读官方文档，本文中部分文本节选自官方文档

起步

1.安装Napcat & 登录机器人QQ号

Napcat 官方文档中提供了较为完整的且适用于各个操作系统的安装说明，在Linux平台上，Napcat提供了三种安装方式：

1.NapCat.Linux.Launcher - 新式非入侵式启动器 | 2.NapCat.AppImage | 3.NapCat.Docker - Linux容器化部署

本文基于第一种方式进行部署，读者注意根据自身管理方式选择最佳安装方式，此部分可直接使用官方文档中的安装命令

curl -o napcat.sh https://raw.githubusercontent.com/NapNeko/napcat-linux-installer/refs/heads/main/install.sh && bash napcat.sh

官方脚本可以完美的一键安装在当前目录中，我们看到如下提示代表一切就绪

[2026-02-01 02:12:52]: 启动步骤: 
[2026-02-01 02:12:52]: 输入 Xvfb :1 -screen 0 1x1x8 +extension GLX +render > /dev/null 2>&1 & 
[2026-02-01 02:12:52]: 输入 export DISPLAY=:1 
[2026-02-01 02:12:52]: 输入 sudo su 
[2026-02-01 02:12:52]: 输入 LD_PRELOAD=./libnapcat_launcher.so qq --no-sandbox 
[2026-02-01 02:12:52]: 或直接运行 sudo bash ./launcher.sh 启动 NapCat Shell

此时，在安装目录下会包含有napcat插件、脚本以及QQ程序本体等文件，我们根据目录找到 安装目录/napcat/config 文件夹下，创建一个名为 onebot11_机器人QQ.json 的文件，注意此文件名字中的 “机器人QQ” 部分要替换成你所登录的QQ号，一串仅由数字构成的字符串

向文件中写入以下内容

{
  "network": {
    "httpServers": [],
    "httpClients": [],
    "websocketServers": [],
    "websocketClients": [
      {
        "name": "WsClient",
        "enable": true,
        "url": "ws://localhost:8080/onebot/v11/ws",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "reconnectInterval": 5000,
        "token": "napcat",	
        "debug": false,
        "heartInterval": 30000
      }
    ]
  },
  "musicSignUrl": "",
  "enableLocalFile2Url": false,
  "parseMultMsg": false
}

按照自己的个性化设定，注意更改其中的token值，以及nonebot对应的正确url，安装完成后在安装目录中执行启动命令

sudo bash ./launcher.sh

Napcat会自行引导QQ启动并弹出登录二维码，使用手机QQ登录对应的账号即可

至此 Napcat 框架搭建完成

对于拓展机器人数量，按照上述过程创建不同的onebot11配置文件即可，但不建议在同一台设备上登录过多QQ账户

另外，Napcat本身自带一个暴露在6099端口的WebUI服务，可以直观的管理napcat的各项配置以及占用状况，本文基于Shell环境，故此部分不展开，只需通过对应公网地址与端口即可访问这个页面

2.部署Nonebot

NoneBot2 是一个现代、跨平台、可扩展的 Python 聊天机器人框架（下称 NoneBot），它基于 Python 的类型注解和异步优先特性（兼容同步），能够为你的需求实现提供便捷灵活的支持。同时，NoneBot 拥有大量的开发者为其开发插件，用户无需编写任何代码，仅需完成环境配置及插件安装，就可以正常使用 NoneBot。

需要注意的是，NoneBot 仅支持 Python 3.9 以上版本

基于Ubuntu 24.04版本，系统出厂已包含Python 3.12，故不再需要安装Python，只需安装所需额外支持库，并修改pip安装源来加快国内下载速度(以清华源为例)

apt install python3-pip python3-venv
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

便于集中管理，在安装目录下新建一个 nonebot 文件夹，使用Python3-venv库创建一个虚拟环境并激活虚拟环境，此时目录下会多出一个名为nonebot-venv的文件夹，不必打开它，它是我们使用虚拟环境时，pip安装的软件包的存储路径。看到shell命令行的前缀出现了(环境名)即代表成功

python3 -m venv nonebot-venv
#Nonebot框架相关操作全程都需在虚拟环境中进行
source nonebot-venv/bin/activate
(nonebot-venv) root@test-env:/opt/QQ/nonebot #

此时按照Nonebot官方文档给出的安装命令进行安装即可

python -m pip install pipx
python -m pipx ensurepath
#如果在此步骤的输出中出现了“open a new terminal”或者“re-login”字样，那么请关闭当前终端并重新打开一个新的终端。
pipx install nb-cli
#创建项目
nb create

过程中会让我们自行选择附带安装的模板，对于QQ以及Napcat来说，按照如下安装选择参考

[?] 选择一个要使用的模板: bootstrap (初学者或用户)
[?] 项目名称: awesome-bot
[?] 要使用哪些适配器? OneBot V11 (OneBot V11 协议)
[?] 要使用哪些驱动器? FastAPI (FastAPI 驱动器), websockets (websockets 驱动器)
[?] 要使用什么本地存储策略? Current project (suitable for multiple/portable instances)
[?] 立即安装依赖? (Y/n) Y
[?] 创建虚拟环境? (Y/n) n
[?] 要使用哪些内置插件? single_session
[?] Which official plugins would you like to use? 本地数据存储 (存储插件数据至本地文件)

安装完成后在机器人目录下编辑机器人配置文件 nano .env.prod

DRIVER=~fastapi+~websockets
PORT=8080
NICKNAME=["bot"]
COMMAND_START=["/", ""]
COMMAND_SEP=[".", " "]
LOCALSTORE_USE_CWD=true
SUPERUSERS=[""]
ONEBOT_ACCESS_TOKEN="napcat"

SUPERUSERS为超级管理员的QQ号，设置为自己的，最下面的TOKEN要和前文与napcat配置的一致，这是建立通信的关键。在机器人目录下执行 nb run --reload 一切无误

02-01 02:50:14 [INFO] uvicorn | Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

至此Nonebot框架安装完成

3.安装个性化插件

Nonebot框架拥有十分丰富的插件社区插件商店 | Nonebot ，找到自己想要安装的插件并复制安装命令在机器人目录下安装即可，例如

nb plugin install nonebot-plugin-abcdefg

安装命令会自动启用此插件，使用者仅需前往插件项目页面查询可配置的内容，并在 .env.prod 文件中添加相关变量

注意：使用以及编辑Nonebot框架与机器人项目的过程中，务必全程在前文提到的虚拟环境中操作