QQBotHub 机器人框架：下载、安装、进程守护全教程

!! 归档：本教程对应 QQBotHub v0.0351，更新日志见文末。

[TOC]

## QQBotHub 是什么

QQBotHub 是一个跑在 Typecho 博客上的 **QQ 官方机器人框架**（插件形态）：
走 QQ 开放平台官方 WebSocket 通道，不需要逆向协议、不怕封号。
支持 AI 对话（多模型自由切换）、语音点歌、图片识别、整点报时电台、词库问答、群管、Markdown 卡片菜单等。

## 一、安装插件

1. 你需要一台装了宝塔面板的服务器 + 一个 Typecho 博客（没有博客的先装一个，PHP 8.0+ / MySQL 5.7+）
2. 把下载的 zip 上传到服务器，解压得到 `QQBotHub` 文件夹
3. 放到 Typecho 目录的 `usr/plugins/` 下，最终结构：`usr/plugins/QQBotHub/Plugin.php`
4. 整个目录给 www 用户权限：宝塔文件管理里右键 → 权限 → 应用到子目录，用户 `www`
5. 进 Typecho 后台 → 控制台 → 插件 → 找到 QQBotHub → 启用

## 二、申请机器人并对接

1. 打开 [QQ 开放平台](https://q.qq.com/) 注册开发者，创建一个「机器人」拿到 **AppID / AppSecret / 机器人openid**
2. Typecho 后台 → 机器人后台 → 机器人账号页，填入这三样并保存
3. 回调地址、事件订阅按后台「自检」页的提示在开放平台配好（WebSocket 模式不需要回调地址）
4. 点「运行自检」，全绿说明对接成功

## 三、添加常驻进程（关键一步）

机器人靠两个进程活着，用宝塔的「进程守护管理器」插件来挂：

**进程 1：WebSocket 守护（收发消息）**

- 名称：`qqbothub_ws`
- 启动用户：`www`
- 运行目录：`/你的博客路径/usr/plugins/QQBotHub`
- 启动命令：`/usr/bin/php src/cli/ws_daemon.php run`
- 进程数量：1

**进程 2：定时心跳（整点报时、电台、提醒下发）**

- 名称：`qqbothub_cron`
- 启动命令：`/usr/bin/php src/cli/cron_cli.php`
- 用「计划任务」也行：Shell 脚本 `php /你的博客路径/usr/plugins/QQBotHub/src/cli/cron_cli.php >> /tmp/qbh_cron.log 2>&1`，每 5 分钟一次

两个都显示「运行中」后，往群里 @机器人 说句话，能回就全通了。

## 四、常见问题

| 现象 | 处理 |
| --- | --- |
| 机器人不理人 | 先看守护进程是否在跑；再到后台「日志」页看错误 |
| 语音发不出 | 主动语音需要开放平台审核通过；先用文字模式 |
| 改了配置不生效 | 重启 `qqbothub_ws` 进程（配置是启动时加载的） |
| 403 / 未授权 | 检查 AppSecret 是否填对、机器人是否已上线 |

## 更新日志（v0.0351）

- **修复插件目录里多出来的 `uploads` 文件夹**：音乐缓存的路径少算了一级，之前会在 `usr/plugins/uploads/` 里另建一份；现已统一写入 `usr/uploads/`，旧数据已合并，不影响使用
- **签到改为普通签到**：去掉修为 / 灵根 / 境界 / 奇遇等修仙玩法，只留打卡；输出全新排版——今日积分、连续签到、累计签到、群内排名一目了然
- 连签里程碑保留：连签 7 / 30 / 100 天有额外积分奖励
- **删除全部修仙玩家存档**；后台「数据归档」与「功能使用统计」不再显示任何修仙条目
- 修复扫码绑定卡在「连接中」（服务器 IPv6 不通，已强制 IPv4）
- 修复机器人永远不在线（CLI 进程被静默退出）与扫码添加的机器人被覆盖丢失的问题
- 新增「进程守护」页面与「美化设置」页面，后台全面重排

## 更新日志（v0.0311）

- 修仙系统精简为纯签到（签到 + 排行），数据全保留
- AI 人设固定为 AstrBot 默认风格；机器人现在知道自己的框架和教程地址
- 后台大整合：AI / 机器人 / 词库 / 日志 四个主页面
- 模型选择全部换成卡片式，手机上不再弹系统菜单
- 修复多处配置保存被覆盖的问题

---