基于NapCat+NoneBot2的QQ机器人相关介绍和部署

自己捣鼓QQ野生机器人也快一年多了，起初只是自己创建的鸣潮群群友聊起来这个，没想到一弄就是快一年，期间换了好几次服务器，也部署了不少次。

本篇文章将会介绍我使用过的协议端NapCat，两个机器人框架——NoneBot2和AmiyaBot，以及拓展插件框架GsCore，了解这些便可搭建一个基本的QQBot。

wwuid作者写的常用协议端 + 机器人框架 + GsCore补充文档：https://wiki.wavesuid.top/

QQBot基本结构

一个QQBot应该有至少三个基础部分，机器人框架、协议端和QQ客户端。简单来说，协议端是一个连接另外两者的桥梁，他可以模拟QQ客户端的通信行为，如LLOneBot、以及本篇会介绍的Napcat。协议端连接上可以处理消息事件的机器人框架（常见如NoneBot2、Koishi、YunzaiBot），框架接收到协议端传来的消息后按照写好的逻辑做出相应反应，协议端再将事件注入QQ客户端，此时就可以看到机器人在QQ的回应了。

举个例子，协议端是Bot的耳朵和嘴，负责接收和发送消息，而机器人框架就是大脑，用于处理信息。

机器人协议

常见的协议有oneBot v11 /v12 /Telegram / Discord / QQ频道等。本篇文章使用的是oneBot v11。
协议规定了机器人的底层消息格式，方便框架和协议端之间的适配。

部署前通用准备

如果你使用的是服务器/虚拟机，推荐至少是2c2g的配置，确保有一个公网IP，能让你在自己的设备上访问各种服务的WebUI。
确保Python版本>=3.9（如果要使用GsCore，则推荐>=3.12，但不建议3.13），环境内安装了git、pip。
确保你有root权限，如果系统提示你不是root，安装了pip但无法使用，可以尝试创建虚拟环境再部署。

shell

# 检查Python
python -V
python --version
python3 -V
python3 --version

# 检查git
# 如果没有，Windows进入Git官网下载，Linux输入sudo apt-get install git
git -v
git --version

# 检查pip
pip -V
pip --version

协议端——NapCat

NapCat官方文档

NapCat（简称nc）是基于NTQQ的Bot协议端，易上手且在持续更新。nc有两种版本，Shell和Framework。前者在命令行运行，占用较低适合服务器持续运行，后者则是启动完整的NTQQ客户端，通过liteLoaderQQ加载nc插件的方式实现，方便主人窥屏和夺舍bot。但由于QQ官方对于第三方插件的限制和制裁，新版QQ使用liteLoaderQQ容易出现直接闪退的情况，因此建议选择Shell版本，下文也仅介绍此版本使用方式。

indows推荐食用方式仅限win的nc可视化管理界面——GitHub项目

确保已经安装最新版NTQQ客户端（nc也有提供无需用户安装QQ客户端的一键包，但是实践后发现此版本有可能不稳定）
在nc的release页面下载最新版NapCat.Shell.zip并解压
双击目录下launcher.bat启动

Linux推荐食用方式
可选择一键使用脚本(支持Ubuntu 20+/Debian 10+/Centos9)

bash

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

# 安装完成启动
napcat

连接网页控制台

管理nc账户、配置连接服务、查看日志等均可在网页控制台进行。
nc默认的webui地址为0.0.0.0（或者主机IP），接口为6099。Token请查看启动日志。
连接Bot框架相关我将在后续介绍对应框架的部分说明。

Bot框架——NoneBot2

NoneBot2官方文档

NoneBot2（简称nb）
推荐进入虚拟环境部署 ~~（能规避很多问题）~~。

安装

shell

python -m pip install --user pipx
python -m pipx ensurepath # 如果无法执行ensurepath需要手动把pipx所在地址添加到系统环境变量Path中

# 新开一个终端
pipx install nb-cli

创建Bot项目

shell

# 在当前目录创建
nb create

shell

 # 选择bootstrap模板
[?] Select a template to use: (Use ↑ and ↓ to choose, Enter to submit)
> bootstrap (for beginner or user)

# 填写Bot项目名，也是Bot文件夹名
[?] Project Name: 

# 选择OneBot V11协议
[?] Which adapter(s) would you like to use? 
○ OneBot V11 (OneBot V11 协议)

# 选择驱动器FastAPI + HTTPX + websockets
[?] Which driver(s) would you like to use? 
○ FastAPI (FastAPI 驱动器)
○ HTTPX (HTTPX 驱动器)
○ websockets (websockets 驱动器)

# 输入Y安装依赖，创建虚拟环境
[?] Install dependencies now? (Y/n)
[?] Create virtual environment? (Y/n)

# 选择默认插件是否安装
[?] Which builtin plugin(s) would you like to use?
○ echo
○ single_session

一切准备就绪，输入以下命令即可启动bot

shell

cd <Bot文件夹>
nb run --reload

.env.prod基础配置

.env.prod在Bot目录下，包括了Bot本体和插件相关配置。

dotenv

# NoneBot2 运行所使用的驱动器，文件默认一般只有这一行
# 见 https://nonebot.dev/docs/next/advanced/driver
DRIVER=~fastapi+~httpx+~websockets

# 重定向 localstore 插件的存储路径，便于后续迁移 Bot
LOCALSTORE_CACHE_DIR=data/nonebot/cache
LOCALSTORE_CONFIG_DIR=data/nonebot/config
LOCALSTORE_DATA_DIR=data/nonebot/data

# LogPile 日志文件保存路径
# LOGPILE_PATH=./log

# LogPile 日志输出等级，可以为列表
LOGPILE_LEVEL=INFO

# LogPile 日志保留天数
# LOGPILE_RETENTION=14

### NoneBot 配置项 ###

# 机器人超级用户
# 超级用户拥有对 Bot 的最高权限
SUPERUSERS=[""]

# 机器人的昵称
# 消息以机器人昵称开头可以代替艾特
NICKNAME=[""]

# 命令起始字符
# 一般只有 on_command 匹配规则适用
# 如果有一个指令为 查询，当该配置项为 ["/"] 时使用 /查询 才能够触发
COMMAND_START=["", "/", "#"]

# 命令分割字符
# 一般用于二级指令（不常见）
COMMAND_SEP=[".", " "]

# NoneBot2 监听的 IP 或 主机名
# 如果要对公网开放，请改成 0.0.0.0
HOST=127.0.0.1
# NoneBot2 监听的端口
# 请保证该端口号与连接端配置相同 或与端口映射配置相关
PORT=8080

# NoneBot2 日志输出等级
LOG_LEVEL=INFO

### OneBot 适配器配置 ###

# OneBot Access Token 配置
# ONEBOT_ACCESS_TOKEN=你的访问令牌

# OneBot V11 Secret 配置
# ONEBOT_SECRET=你的签名

# OneBot V11 正向 Universal WebSocket 配置
# 参考 https://onebot.adapters.nonebot.dev/docs/guide/setup#%E6%AD%A3%E5%90%91-websocket-%E8%BF%9E%E6%8E%A5
# 请确保你的 NoneBot 使用的是 ForwardDriver，否则无法使用此连接方式。
# ONEBOT_WS_URLS=["ws://127.0.0.1:5700"]

# OneBot V11 HTTP POST 配置
# 参考 https://onebot.adapters.nonebot.dev/docs/guide/setup#http-post
# 请确保你的 NoneBot 使用的是 ForwardDriver 和 ReverseDriver，否则无法使用此连接方式。
# ONEBOT_API_ROOTS={"Bot QQ号": "http://127.0.0.1:5700/"}

# OneBot V12 正向 WebSocket 配置
# 参考 https://onebot.adapters.nonebot.dev/docs/guide/setup#%E6%AD%A3%E5%90%91-websocket-%E8%BF%9E%E6%8E%A5-1
# 请确保你的 NoneBot 使用的是 ForwardDriver，否则无法使用此连接方式。
# ONEBOT_V12_WS_URLS=["ws://127.0.0.1:5700"]

# OneBot V12 HTTP Webhook 配置
# 参考 https://onebot.adapters.nonebot.dev/docs/guide/setup#http-webhook
# 请确保你的 NoneBot 使用的是 ForwardDriver 和 ReverseDriver，否则无法使用此连接方式。
# ONEBOT_V12_API_ROOTS={"Bot QQ号": "http://127.0.0.1:5700/"}

使用插件

NoneBot2插件商店

在插件商店中寻找需要的插件，展开插件详情——复制安装命令，在Bot项目目录下执行，然后重启nb。部分插件需要在.env.prod进行额外配置，具体请查看每个插件的文档说明。

shell

nb plugin install <插件包名>

# 删除插件
nb plugin uninstall <插件包名>

连接nc

nb默认启用反向WS。确保.env.prod文件中已配置：

dotenv

HOST=0.0.0.0
PORT=8080

在NapCat中配置WS客户端，此处仅展示webui配置，用nc cli也是大差不差，选择配置-对应账号-ws客户端即可。然后再nb的.env.prod中添加：

dotenv

ONEBOT_ACCESS_TOKEN=你在 NapCat 中配置的 token

如果nb和nc不在一个主机，将127.0.0.1改成nb所在主机IP，并且开放对应端口。

Bot框架——AmiyaBot

AmiyaBot官方文档

插件多为明日方舟相关。

推荐通过代码部署，详见官方指南

连接控制台

AmiyaBot的管理、日志查看、插件安装均可通过网页控制台进行。默认访问地址为127.0.0.1，端口为8088，没有密钥。
如果需要暴露在公网，需配置文件AmiyaBot路径/config/server.yaml，并新增入站规则，开放端口8088（或者你自定义的端口）。

yaml

host: 0.0.0.0
port: 8088 # 也可以改成别的端口
authKey: # 暴露在公网时务必填写authKey

创建实例和连接nc

详见AmiyaBot官方说明，可选正向HTTP或正向WS连接。如果Bot和nc不在一个主机，nc配置处填写IP0.0.0.0，amiya配置处填写nc所在主机IP，并确保nc所在主机开放对应端口。

拓展插件框架GsCore

GsCore官方文档

GsCore（早柚核心）不是独立的机器人框架，需要连接上游Bot框架，提供一系列以二游为主的角色信息查询插件（插件列表）。可以对接 NoneBot2、HoshinoBot、YunZai-Bot、Koishi等框架使用。

本文强烈推荐也仅介绍通过uv安装依赖。

shell

# 检查uv是否存在
uv -V

# 安装方式
pip install uv

开始安装

shell

# 克隆项目
git clone https://github.com/Genshin-bots/gsuid_core.git --depth=1 --single-branch

# 进入gscore文件夹 
cd gsuid_core

# 使用uv安装依赖
uv sync
uv run python -m ensurepip

# 基本安装步骤已完成，先启动一次core生成config.json和插件文件夹
uv run core

基础配置

config.json位于gsuid_core/data/config.json，启动一次core后自动生成。一般仅需配置开头几行：

json

    "HOST": "localhost", //如果需从别处访问网页控制台（即挂在公网），改成0.0.0.0，并开放8765端口
    "PORT": "8765",
    "ENABLE_HTTP": true,
    "masters": ["Bot主人QQ号"], //注意双引号

保存并重启core。

网页控制台

管理core、插件、各种设置、数据统计均可在网页控制台进行。默认地址为localhost:8765/genshinuid，如果在挂在公网，可以通过主机IP:8765/genshinuid访问。初始账密均为root，初次访问后请立刻更改密码。

连接上游Bot框架（NoneBot2）

本文仅介绍连接nb的方式，其他框架请查看官方说明。
cd到nb项目文件夹内

shell

nb plugin install nonebot-plugin-genshinuid

重启nb，nb在连接nc时，将同时尝试连接core。

使用插件

插件列表

插件有两种安装方式

访问网页控制台，左侧栏选择插件管理-插件管理，即可安装/更新插件
cd到gsuid_core/gsuid_core/plugins，执行克隆命令然后重启core

shell

git clone <插件仓库地址>

一些小技巧

Screen：在Linux多开进程，后台运行。比如可以执行screen -S gs创建一个新会话，执行uv run core，然后再执行Ctrl + A + D让会话在后台运行。同理新开一个会话执行nb run。

bash

# screen基础命令
# 创建会话
screen
# 创建带名字的会话
screen -S <name>
# 离开会话：Ctrl + A + D
# 进入后台运行的会话
screen -r <name>
# 关闭会话
screen -S <name> -X quit
# 在会话中关闭会话
quit
# 或者Ctrl + D
# 查看会话列表
screen -ls

一般来说考虑到方便管理，把协议端、框架（或者加上拓展框架）放在一个服务器。博主因为用的Azure for Students订阅，可免费使用的虚拟机只有两台2C1G。因此在内存不够的情况下，可以把框架和协议端分别部署在两台主机上，然后通过公网连接（在上文有说明）。
有什么内容想到再加吧。。。

QQBot基本结构 ​

机器人协议 ​

部署前通用准备 ​

协议端——NapCat ​

连接网页控制台 ​

Bot框架——NoneBot2 ​

安装 ​

创建Bot项目 ​

.env.prod基础配置 ​

使用插件 ​

连接nc ​

Bot框架——AmiyaBot ​

连接控制台 ​

创建实例和连接nc ​

拓展插件框架GsCore ​

开始安装 ​

基础配置 ​

网页控制台 ​

连接上游Bot框架（NoneBot2） ​

使用插件 ​

一些小技巧 ​

QQBot基本结构

机器人协议

部署前通用准备

协议端——NapCat

连接网页控制台

Bot框架——NoneBot2

安装

创建Bot项目

.env.prod基础配置

使用插件

连接nc

Bot框架——AmiyaBot

连接控制台

创建实例和连接nc

拓展插件框架GsCore

开始安装

基础配置

网页控制台

连接上游Bot框架（NoneBot2）

使用插件

一些小技巧