Linux安装QQ机器人，环境依赖怎么配？

99ANYc3cd6 机器人 2025-12-04 7

目前最主流、最稳定、功能最强大的框架是 NoneBot，它基于 Python 开发，支持多种协议（包括 OneBot v11，这是最常用的 QQ 协议）。

（图片来源网络，侵删）

这篇教程将手把手教你如何使用 go-cqhttp 作为协议适配器，结合 NoneBot2 框架来搭建一个功能强大的 QQ 机器人。

核心概念理解

在开始之前,你需要了解几个关键角色：

协议适配器：负责与 QQ 服务器通信，登录账号，收发消息等，它就像一个“翻译官”，把机器人的指令翻译成 QQ 服务器能懂的语言。go-cqhttp 是目前最流行、最稳定的协议适配器。
机器人框架：负责处理逻辑，当收到‘天气’指令时，查询天气并回复”。NoneBot2 是一个非常灵活且强大的 Python 框架。
机器人插件：实现具体功能的小程序，复读机”、“定时提醒”、“搜图”等，你可以自己写,也可以使用社区开发的丰富插件。

我们的工作流程是：go-cqhttp 监听 QQ 消息 -> 将消息格式化为 OneBot v11 标准数据 -> 发送给 NoneBot2 框架 -> NoneBot2 根据插件逻辑处理数据 -> 将处理结果返回给 go-cqhttp -> go-cqhttp 发送消息回 QQ。

准备工作

一台 Linux 服务器/虚拟机：推荐使用 Ubuntu 20.04/22.04 或 CentOS 7/8，本教程以 Ubuntu 为例。
一个可用的 QQ 号码：
- 非常重要：建议使用小号作为机器人，因为使用第三方协议存在被腾讯风控（封禁）的风险。
- 确保该QQ号开启了设备锁，并准备好扫码验证的环境。
基本 Linux 操作能力：会使用 ssh 连接服务器,执行基本命令。
Python 3.8+ 环境：NoneBot2 需要 Python 3.8 或更高版本。

第一步：安装 Python 3 和 pip

如果你的系统没有 Python 3，或者版本过低,需要先安装。

（图片来源网络，侵删）

对于 Ubuntu/Debian:

# 更新软件包列表
sudo apt update
# 安装 Python 3, pip, 和虚拟环境工具
sudo apt install python3 python3-pip python3-venv -y

对于 CentOS/RHEL:

# 安装 EPEL 仓库
sudo yum install epel-release -y
# 安装 Python 3, pip, 和虚拟环境工具
sudo yum install python3 python3-pip python3-venv -y

第二步：创建项目目录和虚拟环境

使用虚拟环境可以隔离项目依赖，避免与系统 Python 包冲突。

# 创建一个项目文件夹，my-qq-bot
mkdir my-qq-bot && cd my-qq-bot
# 创建一个名为 venv 的虚拟环境
python3 -m venv venv
# 激活虚拟环境
source venv/bin/activate
# 激活后，你的命令行提示符前面会出现 (venv)
# 从现在开始，所有操作都在这个虚拟环境中进行

第三步：安装和配置 go-cqhttp

go-cqhttp 是一个独立的二进制程序,直接下载解压即可。

# 创建一个文件夹来存放 go-cqhttp
mkdir go-cqhttp && cd go-cqhttp
# 下载对应你系统架构的 go-cqhttp (以 Linux x64 为例)
# 访问 https://github.com/Mrs4s/go-cqhttp/releases 获取最新版本
wget https://github.com/Mrs4s/go-cqhttp/releases/download/v1.2.1/go-cqhttp-v1.2.1-linux-amd64.tar.gz
# 解压
tar -xvf go-cqhttp-v1.2.1-linux-amd64.tar.gz
# 删除压缩包
rm go-cqhttp-v1.2.1-linux-amd64.tar.gz

首次运行生成配置文件：

# 在 go-cqhttp 目录下执行
./go-cqhttp

首次运行会生成一个 config.yml 配置文件，并提示你扫码登录,你需要：

用手机QQ扫描终端中显示的二维码。
在手机上确认登录授权。
登录成功后，go-cqhttp 会自动退出。

配置 go-cqhttp (可选但推荐):

编辑 config.yml 文件,进行一些基本配置。

nano config.yml

主要关注以下几个配置项：

# account.yml 文件中配置的账号
uin: 12345678 # 你的QQ号
password: ''  # 密码留空，使用扫码登录
# 是否开启服务器模式
servers:
  - # 访问地址
    host: 0.0.0.0
    # 访问端口
    port: 8080
    # 反向 HTTP 服务的认证密钥 (可选)
    # access-token: "your-access-token"
    # 反向 HTTP 服务的地址 (用于公网访问)
    # reverse-host: example.com
    # 反向 HTTP 服务的端口
    # reverse-port: 443
    # 反向 HTTP 服务的协议 (http 或 https)
    # reverse-http-protocol: http

uin: 填写你的机器人QQ号。
servers: 这里我们配置 go-cqhttp 以 HTTP Server 模式 运行，监听在 0.0.0:8080。NoneBot2 将通过这个地址与它通信。

第四步：安装和配置 NoneBot2

现在我们回到项目根目录，安装 NoneBot2。

# 回到项目根目录
cd ..
# 使用 pip 安装 nonebot2
pip install nonebot2
# (可选) 安装命令行界面工具，方便后续管理
pip install nb-cli

使用 nb-cli 初始化项目：

nb-cli 是 NoneBot 官方的命令行工具,可以快速创建项目骨架。

# 在项目根目录下执行
nb-cli create mybot

它会引导你进行一些选择：

Project Name: 输入你的项目名，mybot。
Project Path: 默认即可,回车。
Adapter: 选择 OneBot V11。
Platform: 选择 QQ。
Reverse WS: 选择 Yes。
Reverse Host: 输入 0.0.1 (因为 go-cqhttp 和 NoneBot2 在同一台机器上)。
Reverse Port: 输入 8080 (与 go-cqhttp 的配置端口一致)。
Reverse Access Token: 回车（留空）。

等待安装完成,你的项目结构看起来会是这样：

my-qq-bot/
├── go-cqhttp/          # go-cqhttp 程序和配置
│   ├── config.yml
│   └── go-cqhttp
├── mybot/              # NoneBot2 项目
│   ├── .env            # 环境变量配置文件
│   ├── bot.py          # 机器人入口文件
│   ├── pyproject.toml  # 项目依赖配置
│   └── src/
│       └── plugins/    # 插件目录
└── venv/               # Python 虚拟环境

第五步：安装一个示例插件

一个没有插件机器人是“哑巴”，我们安装一个官方的示例插件 echo（复读机）来测试。

# 进入 mybot 目录
cd mybot
# 使用 nb-cli 安装插件
nb-plugin install nonebot-plugin-echo

第六步：启动和测试机器人

万事俱备,现在启动机器人！

启动 go-cqhttp:
```
# 在 go-cqhttp 目录下
cd ../go-cqhttp
# 让它在后台运行
nohup ./go-cqhttp > go-cqhttp.log 2>&1 &
```
- nohup: 让程序在用户退出登录后继续运行。
- > go-cqhttp.log 2>&1: 将程序的输出（包括错误）重定向到 go-cqhttp.log 文件中,方便排查问题。
启动 NoneBot2:
```
# 回到 mybot 目录
cd ../mybot
# 启动机器人
nb run
```
如果看到类似 INFO: Uvicorn running on http://127.0.0.1:8080 的日志，说明 NoneBot2 启动成功了。
测试:
- 用你的个人QQ号,去添加机器人QQ号为好友。
- 在聊天中给机器人发送任意消息。
- 如果一切正常，机器人应该会复读你刚才发送的消息。

第七步：使用 Systemd 守护进程 (推荐)

为了让机器人能在服务器重启后自动启动，并且方便管理，我们使用 systemd 来创建一个服务。

创建服务文件:

sudo nano /etc/systemd/system/go-cqhttp.service

粘贴以下内容，并修改 User 和 WorkingDirectory 为你的实际路径：

[Unit]
Description=go-cqhttp Service
After=network.target
[Service]
# 替换为你的 Linux 用户名
User=your_linux_username
# 替换为你的 go-cqhttp 所在目录的绝对路径
WorkingDirectory=/home/your_linux_username/my-qq-bot/go-cqhttp
ExecStart=/home/your_linux_username/my-qq-bot/go-cqhttp/go-cqhttp
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target

创建 NoneBot2 服务文件:

sudo nano /etc/systemd/system/nonebot.service

粘贴以下内容，并修改 User 和 WorkingDirectory：

[Unit]
Description=NoneBot2 Service
After=network.target
[Service]
# 替换为你的 Linux 用户名
User=your_linux_username
# 替换为你的 mybot 所在目录的绝对路径
WorkingDirectory=/home/your_linux_username/my-qq-bot/mybot
# 注意这里要使用虚拟环境中的 nb
ExecStart=/home/your_linux_username/my-qq-bot/venv/bin/nb run
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target

启用并启动服务:

# 重载 systemd 配置
sudo systemctl daemon-reload
# 启用并启动 go-cqhttp
sudo systemctl enable go-cqhttp
sudo systemctl start go-cqhttp
# 启用并启动 nonebot
sudo systemctl enable nonebot
sudo systemctl start nonebot

检查服务状态:

# 查看 go-cqhttp 状态
sudo systemctl status go-cqhttp
# 查看 nonebot 状态
sudo systemctl status nonebot

如果显示 active (running),说明服务正常运行。

常见问题与进阶

机器人没反应怎么办？
1. 检查是否是好友,或者是否在群聊中。
2. 检查防火墙是否开放了 8080 端口（如果需要公网访问 go-cqhttp 的话）。
3. 查看日志：tail -f go-cqhttp/go-cqhttp.log 和 tail -f mybot/nb.log。
4. 确认 config.yml 和 .env 文件中的配置（特别是端口和地址）是否正确。
如何安装更多插件？ 访问 NoneBot 插件市场，找到你喜欢的插件，然后使用 nb-plugin install <插件名> 来安装。
如何开发自己的插件？ 参考 NoneBot2 开发文档,学习如何编写插件。
关于风控 再次强调，使用第三方协议存在账号被封禁的风险，请务必使用小号，并遵守腾讯的用户协议，不要频繁发送消息,不要进行恶意操作。