🚀 框架部署教程

从零开始部署陌城qqbot框架,大约 10 分钟即可完成

📌 部署架构概览

陌城qqbot框架基于 Python + OneBot v11 协议 构建,部署需要两部分:

🤖
QQ 协议端
OneBot 实现(如 NapCat / Lagrange),负责与 QQ 服务器通信
⇄
⚙️
陌城qqbot框架
Python 程序,处理消息逻辑、插件、WebUI 管理后台
💡 简单理解: 协议端负责"收发 QQ 消息",框架负责"处理消息逻辑",两者通过 WebSocket 通信。

🔌 适配器类型

陌城qqbot框架支持两种适配器接入方式,可在 WebUI「适配器管理」页面同时配置多个:

🤖
OneBot v11 适配器
通过 NapCat/Lagrange 等第三方协议端连接个人 QQ 号,
功能完整(群管/禁言/踢人等),但有封号风险
🛡️
QQ 官方机器人适配器
直接对接腾讯官方机器人 API,合规无封号风险,
功能受限(被动回复为主,主动消息有配额)
💡 选择建议: 需要完整群管功能选 OneBot v11;需要合规运营选 QQ 官方;两者可同时使用,互不影响。
1

环境准备

部署前请确保服务器/电脑满足以下环境要求:

🐍
Python 3.8+
推荐 Python 3.10 或 3.11,安装时勾选 "Add Python to PATH"
📦
Node.js 18+(可选)
仅当需要自行构建 WebUI 时安装。正式版压缩包已预构建,可跳过
🌐
OneBot 协议端
NapCat / Lagrange / go-cqhttp 等(任选其一)
💻
操作系统
Windows / Linux / macOS 均可,推荐 Windows Server 或 Linux
2

下载框架

从下载页获取最新版本压缩包 (推荐下载正式版,已包含预构建的 WebUI,无需额外安装 Node.js)。

将压缩包解压到任意目录,例如:

# Windows
D:\qqbot\

# Linux
/opt/qqbot/
💡 路径提示: 框架支持任意路径部署,但建议路径中不要包含中文,以避免部分依赖库的编码问题。
3

启动框架

🪟 Windows 系统

双击目录中的 start.bat 文件即可,脚本会自动完成以下操作:

  • ✅ 检测 Python 环境
  • ✅ 创建虚拟环境(venv)
  • ✅ 安装依赖库(使用清华源加速)
  • ✅ 检查 / 构建 WebUI(若已预构建则跳过)
  • ✅ 启动框架

🐧 Linux / macOS 系统

赋予执行权限后运行启动脚本:

cd /opt/qqbot
chmod +x start.sh
./start.sh

🔧 手动启动(高级)

若脚本启动失败,可手动执行:

cd /opt/qqbot
python -m venv venv

# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

pip install -r requirements.txt
python main.py
💡 首次启动: 框架会在 config/ 目录自动生成默认配置文件 (config.json 和 .env),无需手动创建。
4

部署 OneBot 协议端

框架本身无法直接登录 QQ,需要一个 OneBot 协议端来收发消息。推荐以下几种实现:

NapCat
基于 QQNT 的 OneBot 实现,推荐使用
GitHub →
Lagrange
跨平台 OneBot 实现,支持 Linux/Windows
GitHub →
go-cqhttp
老牌 OneBot 实现,功能稳定
GitHub →

配置协议端连接

框架默认使用 WebSocket 客户端模式(框架主动连接协议端)。需在协议端开启 正向 WebSocket 服务,然后在框架的 WebUI 中填写连接地址。

💡 默认连接地址: ws://127.0.0.1:3001 (若协议端与框架部署在同一服务器)。若部署在不同服务器,请填写协议端服务器的 IP 和端口。
5

QQ 官方机器人适配器(可选)

如果你想使用腾讯官方机器人接口(合规无封号风险),请按以下步骤操作。此步骤可选,框架支持同时配置 OneBot 和官方两种适配器。

📝 注册 QQ 开放平台账号

  1. 访问 QQ 开放平台,使用 QQ 号登录
  2. 完成开发者认证(个人或企业)
  3. 点击「创建机器人」,填写机器人信息并提交审核
  4. 审核通过后,在机器人管理后台获取以下凭据:
    • AppID:机器人应用 ID
    • AppSecret:机器人应用密钥
    • Token:WebSocket 鉴权 Token(可选)

⚙️ 配置机器人权限

在机器人管理后台的「权限管理」页面,开启以下权限:

  • ✅ 群@机器人消息(GROUP_AT_MESSAGE_CREATE)
  • ✅ C2C 消息(C2C_MESSAGE_CREATE)
  • ✅ 发送群消息
  • ✅ 发送 C2C 消息
⚠️ 注意: 官方接口功能受限,不支持群管操作(禁言/踢人/撤回等)。如需完整群管功能,请同时配置 OneBot v11 适配器。

🔌 在框架中添加适配器

框架启动后,打开 WebUI 管理后台,进入「连接配置 → 适配器管理」页面:

  1. 点击「新增适配器」按钮
  2. 填写名称(如「官方机器人」)
  3. 类型选择「QQ 官方机器人」
  4. 填写 AppID、AppSecret、Token
  5. 点击「确定」保存
  6. 点击「测试」按钮验证连接是否正常
💡 提示: 适配器保存后,框架会自动启动连接。鉴权 token(access_token)由框架自动管理,有效期 120 分钟,过期自动刷新。
6

配置框架

框架启动后,打开浏览器访问 WebUI 管理后台: 

http://127.0.0.1:8081

在 WebUI 中完成以下配置:

  1. OneBot 连接配置 - 填写协议端的 WebSocket 地址和 Access Token
  2. 机器人配置 - 设置超级用户(QQ 号)、昵称、命令前缀
  3. 群设置 - 配置每个群的开关、插件启用状态
  4. 菜单管理 - 自定义菜单标题、触发词、分类
💡 超级用户: 在 config.json 的 bot.superusers 数组中添加你的 QQ 号, 即可拥有最高管理权限。
7

连接测试

完成配置后,按以下步骤验证部署是否成功:

  • ✅ 控制台输出 WebSocket 已连接 - 协议端连接成功
  • ✅ 控制台输出 Bot 已登录: xxxxxxx - QQ 账号登录成功
  • ✅ WebUI 首页显示 在线 状态 - 框架运行正常
  • ✅ 在 QQ 群中发送 菜单 - 机器人回复菜单 - 功能完全可用
⚠️ 若连接失败: 请检查协议端是否已启动、WebSocket 地址/端口是否正确、 Access Token 是否一致、防火墙是否放行端口。
📋

端口说明

服务
默认端口
说明
Bot WebSocket
8080
框架主服务端口
WebUI 管理后台
8081
浏览器访问的可视化管理界面
OneBot 协议端
3001
协议端的正向 WebSocket 服务端口(在协议端配置)
💡 端口冲突: 若端口被占用,可在 WebUI 的「服务器配置」中修改框架端口,或在协议端配置中修改其端口。
🔄

后台常驻运行(Linux)

Linux 服务器推荐使用 systemd 或 screen 让框架在后台持续运行:

方案一:screen(简单)

# 创建后台会话
screen -S qqbot

# 启动框架
cd /opt/qqbot && ./start.sh

# 按 Ctrl+A 然后按 D 脱离会话(框架继续运行)

# 重新连接会话
screen -r qqbot

方案二:systemd(推荐生产环境)

创建服务文件 /etc/systemd/system/qqbot.service:

[Unit]
Description=MoCheng QQBot Framework
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/qqbot
ExecStart=/opt/qqbot/venv/bin/python /opt/qqbot/main.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启动并设置开机自启:

systemctl daemon-reload
systemctl start qqbot
systemctl enable qqbot

# 查看运行状态
systemctl status qqbot

# 查看日志
journalctl -u qqbot -f
📁

目录结构

qqbot/
├── main.py                 # 主入口
├── start.bat               # Windows 一键启动
├── start.sh                # Linux/macOS 启动脚本
├── requirements.txt        # Python 依赖
├── config_manager.py       # 配置管理
├── log_manager.py          # 日志管理
├── core/                   # 核心代码
│   ├── app.py              # 应用主类
│   ├── version.py          # 版本号
│   ├── plugin_loader.py    # 插件加载器
│   ├── menu_registry.py    # 菜单注册
│   ├── permission.py       # 权限管理
│   └── onebot/             # OneBot 协议实现
├── plugins/                # 插件目录
│   ├── group_admin.py      # 群管理
│   ├── group_ai_chat.py    # AI 对话
│   ├── group_checkin.py    # 签到
│   ├── group_points.py     # 积分
│   └── ...                 # 更多插件
├── webui/                  # WebUI 管理后台
│   ├── app.py              # WebUI 服务
│   └── frontend/dist/      # 前端构建产物
├── config/                 # 配置文件
│   ├── config.json         # 主配置
│   ├── .env                # 环境变量
│   └── data/               # 数据存储
└── venv/                   # 虚拟环境(自动创建)
?

常见问题

Q: 启动时提示"未找到 Python"?
请安装 Python 3.8 以上版本,安装时务必勾选 Add Python to PATH。下载地址:python.org
Q: 依赖安装失败?
可能是网络问题,启动脚本已配置清华镜像源加速。若仍失败,可手动执行:python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
Q: WebUI 打不开?
检查 8081 端口是否被占用或被防火墙拦截。正式版压缩包已预构建 WebUI,无需安装 Node.js。若使用测试版且未构建前端,需安装 Node.js 18+ 后重新运行 start.bat。
Q: 机器人无法连接协议端?
1) 确认协议端已启动并登录 QQ;2) 确认协议端开启了正向 WebSocket 服务;3) 确认 WebUI 中填写的地址端口正确(默认 ws://127.0.0.1:3001);4) 确认 Access Token 一致(若未设置则留空)。
Q: 路径包含中文导致启动失败?
部分 Python 依赖库对中文路径支持不佳,建议将框架部署到纯英文路径下,如 D:\qqbot\ 或 /opt/qqbot/。
Q: 如何升级框架到新版本?
下载新版本压缩包,解压后覆盖旧目录(建议先备份 config/ 目录)。数据文件位于 config/data/,覆盖时保留即可,不会丢失配置。
Q: 如何添加超级用户?
在 WebUI「机器人配置」中添加,或直接编辑 config/config.json,在 bot.superusers 数组中添加 QQ 号:"superusers": ["123456789"]
Q: 如何开发自己的插件?
将插件 Python 文件放入 plugins/ 目录,框架启动时会自动加载。插件需继承基础插件类并注册命令处理器,参考 plugins/group_admin.py 的实现。
⬇️ 立即下载 查看更新日志 返回首页