Lagrange.OneBot+NoneBot搭建QQ机器人详细指南

Lagrange.Core 是基于 NTQQ 协议的纯 C# 实现，可为 QQ 账号提供协议层支持；NoneBot 则是一款跨平台的 Python 异步聊天机器人框架，具备高扩展性和易用性。本文将详细介绍如何在 Debian 12 系统上部署一套基于 Lagrange.OneBot 协议的 NoneBot QQ 机器人。

前置准备

在开始前，请确保你的 Debian 12 服务器满足以下条件：

已安装基础工具：tar、vim、python3（3.9 及以上版本）、curl（可选，用于下载文件）；
服务器具备网络连接（需访问 GitHub 下载资源）；
拥有一个可正常登录的 QQ 账号（建议使用非主号，避免风控风险）。

第一步：部署 Lagrange.OneBot（协议层）

下载运行Lagrange.OneBot

Lagrange.OneBot 负责与 QQ 服务器通信，为 NoneBot 提供消息收发能力，需先完成部署与配置。

访问 Lagrange.Core 的 GitHub 发行页，下载符合我们需求的Lagrange.OneBot_linux-x64_net9.0_SelfContained.tar.gz。

上传到服务器，使用下面命令解压：

tar -xvzf ./Lagrange.OneBot_linux-x64_net9.0_SelfContained.tar.gz

将可执行文件移动到 Lagrange.OneBot 目录：

cd Lagrange.OneBot
mv ./bin/Release/net9.0/linux-x64/publish/Lagrange.OneBot ./Lagrange.OneBot

为可执行文件添加执行权限：

chmod +x ./Lagrange.OneBot

执行以下命令启动程序，首次运行需扫码登录 QQ：

./Lagrange.OneBot

启动成功后，终端会显示二维码链接或图片路径，使用手机 QQ 扫描二维码完成登录。登录成功后，终端会输出 “登录成功” 等提示信息。此时可先按Ctrl+C停止程序，后续配置为系统服务自动运行。

为 Lagrange 配置 systemd 服务

为避免手动启动的繁琐，将 Lagrange.OneBot 配置为 systemd 服务，实现开机自启和崩溃自动重启。

创建服务配置文件：

vim /lib/systemd/system/lagrange.service

写入以下内容（根据实际路径调整，写入前请删除注释）：

[Unit]
Description=Lagrange.OneBot Service
After=network.target  # 网络启动后再运行

[Service]
Type=simple
User=root  # 运行用户（根据需求修改，如非root需确保权限）
WorkingDirectory=/root/Lagrange.OneBot  # 程序所在目录
ExecStart=/root/Lagrange.OneBot/Lagrange.OneBot  # 程序完整路径
Restart=always  # 程序崩溃时自动重启
RestartSec=5  # 重启间隔（秒）

[Install]
WantedBy=multi-user.target  # 多用户模式下启动

保存并退出后，执行以下命令启动并设置开机自启：

systemctl daemon-reload   # 重新加载 systemd 配置
systemctl enable lagrange # 设置开机自启
systemctl start lagrange  # 启动服务
systemctl status lagrange # 查看服务状态

验证服务状态，若显示 “active (running)”，则 Lagrange 服务配置成功。

第二步：安装 NoneBot 脚手架（框架层）

安装 pipx

pipx可在独立环境中安装 Python 命令行工具，两种安装方式任选其一：

方式 1：通过 pip 安装（用户级，推荐，建议使用虚拟环境执行）

# 确保pip已更新
python3 -m pip install --upgrade pip
# 安装pipx
python3 -m pip install --user pipx
# 配置环境变量（使pipx命令生效）
python3 -m pipx ensurepath

注意：若输出 “请重启终端” 提示，需关闭当前终端并重新打开。

方式 2：通过 apt 安装（系统级，适合权限充足场景）

sudo apt update && sudo apt install -y pipx
pipx ensurepath  # 配置环境变量（需重启终端）

安装 NoneBot 脚手架

pipx install nb-cli

验证安装：

nb --version

若输出版本号，则脚手架安装成功。

第三步：创建 NoneBot 项目并连接 Lagrange

初始化 NoneBot 项目

执行以下命令启动项目创建向导：

nb create

按以下步骤完成配置（推荐选项已标注）：

选择项目模板：推荐simple（简洁模板，适合新手）

输入项目名称：例如chatbot（自定义，小写无空格）

选择适配器：按空格选中OneBot V11（必须选，用于连接 Lagrange），然后按 Enter 下一步

选择驱动器：默认FastAPI（NoneBot 推荐，性能稳定）

插件存储位置：推荐src（规范目录结构，便于管理插件）

安装依赖：输入y（自动安装项目所需依赖）

创建虚拟环境：

若已在独立虚拟环境中操作，输入n；
若直接在系统环境操作，输入y（避免依赖冲突）。

安装内置插件：推荐全选便于测试机器人基础功能

安装成功会出现下面提示：

启动 NoneBot 并验证连接

根据提示运行下面命令：

cd chatbot # 替换为你的项目名称
nb run --reload # 带热重载，修改代码后自动重启

出现类似下面命令且没有报错，证明 NoneBot 已经和 Lagrange 握手链

08-30 01:57:36 [SUCCESS] nonebot | NoneBot is initializing...
08-30 01:57:36 [INFO] nonebot | Current Env: dev
08-30 01:57:36 [DEBUG] nonebot | Loaded Config: {'driver': '~fastapi', 'host': IPv4Address('127.0.0.1'), 'port': 8080, 'log_level': 'DEBUG', 'api_timeout': 30.0, 'superusers': set(), 'nickname': set(), 'command_start': {'/'}, 'command_sep': {'.'}, 'session_expire_timeout': datetime.timedelta(seconds=120), 'environment': 'dev'}
08-30 01:57:36 [DEBUG] nonebot | Succeeded to load adapter "OneBot V11"
08-30 01:57:36 [SUCCESS] nonebot | Running NoneBot...
08-30 01:57:36 [SUCCESS] nonebot | Loaded adapters: OneBot V11
08-30 01:57:36 [INFO] uvicorn | Started server process [548469]
08-30 01:57:36 [INFO] uvicorn | Waiting for application startup.
08-30 01:57:36 [INFO] uvicorn | Application startup complete.
08-30 01:57:36 [INFO] uvicorn | Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
08-30 01:57:40 [INFO] uvicorn | 127.0.0.1:41046 - "WebSocket /onebot/v11/ws" [accepted]
08-30 01:57:40 [INFO] nonebot | OneBot V11 | Bot 2934575117 connected
08-30 01:57:40 [INFO] websockets | connection open

第四步：配置 NoneBot 后台运行

默认nb run在终端关闭后会停止，需配置后台运行方式。以下提供两种常用方案：

方案 1：nohup（简单临时方案）

适合短期测试，不支持开机自启，但配置简单：

# 后台运行并将日志输出到nonebot.log
nohup nb run > /root/nonebot.log 2>&1 &

查看实时日志：tail -f /root/nonebot.log
停止进程：先通过ps aux | grep nb找到 PID，再执行kill <PID>

方案 2：systemd（推荐，支持开机自启）

与 Lagrange 配置类似，创建 NoneBot 服务文件：

创建服务文件：
```
vim /lib/systemd/system/chatbot.service
```

粘贴以下内容（替换项目路径）：

[Unit]
Description=NoneBot Service (QQ Robot Framework)
After=network.target lagrange.service  # 确保Lagrange启动后再启动NoneBot

[Service]
Type=simple
User=root
WorkingDirectory=/root/chatbot  # 替换为你的项目目录
ExecStart=/root/.local/bin/nb run  # 替换为nb命令的绝对路径（可通过which nb查看）
Restart=always
RestartSec=5
StandardOutput=append:/var/log/nonebot.log

[Install]
WantedBy=multi-user.target

启动并启用服务：

systemctl daemon-reload
systemctl start chatbot
systemctl enable chatbot

第五步：测试机器人功能测试

如果想要测试机器人是否启动运行，可以在 src/plugins 目录下新建 test.py 文件写入以下内容：

from nonebot import on_regex
from nonebot.typing import T_State
from nonebot.adapters.onebot.v11 import GroupMessageEvent, Bot, Message

Test = on_regex(pattern=r'^测试$',priority=1)


@Test.handle()
async def Test_send(bot: Bot, event: GroupMessageEvent, state: T_State):
    msg = "测试成功"
    await Test.finish(message=Message(msg))

在群聊发送“测试”，如果看到机器人回复，则机器人正常运行：

此时恭喜你成功搭建了一个QQ聊天机器人。

第六步：修改通信端口（可选）

Lagrange默认使用8080端口，若该端口被占用（如其他服务使用），需同步修改Lagrange和NoneBot的端口配置。

1. 停止相关服务

systemctl stop lagrange chatbot

2. 修改Lagrange端口

进入Lagrange目录，编辑配置文件：

cd /root/Lagrange.OneBot
vim appsettings.json

找到Implementations下的Port字段，修改为空闲端口（如1145）：

"Implementations": [
    {
        "Type": "ReverseWebSocket",
        "Host": "127.0.0.1",
        "Port": 1145,  // 修改为空闲端口
        "Suffix": "/onebot/v11/ws",
        "ReconnectInterval": 5000,
        "HeartBeatInterval": 5000,
        "AccessToken": ""
    }
]

3. 修改NoneBot端口

进入NoneBot项目目录，编辑.env文件：
```
cd /root/chatbot
vim .env
```
添加或修改PORT字段，与Lagrange端口保持一致：
```
PORT=1145  # 必须与Lagrange的Port一致
```

4. 重启服务验证

systemctl start lagrange nonebot
# 验证端口是否被占用
netstat -tuln | grep 1145

若显示 127.0.0.1:1145 处于监听状态，则端口修改成功。

总结

通过以上步骤，你已成功在Debian 12上搭建了基于Lagrange.OneBot和NoneBot的QQ机器人。接下来可通过开发自定义插件扩展功能（如自动回复、天气查询、群管理等），具体可参考 NoneBot 官方文档和 Lagrange.Doc。也可以查看 Awesome NoneBot | NoneBot 相关资源汇总。

注意， QQ 账号可能触发风控，建议避免频繁发送广告或敏感内容。风控相关内容请查看 NoneBot 社区文档的相关部分。

菜单

分享