可爱的绪山真寻Bot部署教程
zhenxun_bot 相关导航
- 【zhenxun_bot】可爱的绪山真寻 Bot 部署教程⇦ 当前位置 🪂
封面图片 PID:81677882
阅前须知：本教程与此项目仅用于学习交流，不存在任何盈利目的，请勿用于非法或盈利用途！！！
目前已实现的功能
关于小真寻（绪山真寻）
更多更详细的介绍请移步:[使用文档]|[项目地址]
注意事项
- 保证系统的相同，环境的相同，是尽量减少麻烦的最有效的途径
- 遇到麻烦先不要慌，先看看你是不是漏看了亿步
- 实在解决不了，带上你的完整的报错，和自己所做过的行为去群里问问。QQ 群：「是真寻酱哒」或「真寻酱的技术群」
必要的准备
- 一定的基础，包括但不限于稍微熟悉 linux 或 windows cmd 命令行
- 一台还凑合的电脑或云服务器，推荐部署系统: Ubuntu20.04 LTS
- 一个可以用的脑子
- 善于百度谷歌的双手
简要说明
真寻 Bot 是基于
Nonebot2，以tortoise-orm作为ORM，支持Postgresql、MySQL、SQLite等数据库，使用以OneBot v11协议为准的框架的由HibiKier等人开发的非常可爱的 QQ Bot。
推荐的部署系统为Linux，可以使用Ubuntu等Linux发行版，Windows也可以获得很好的支持。本文就分别以Ubuntu 20.04 LTS和Windows 10 x64作为部署系统，简要介绍部署教程。
Windows 部署教程
此节主要参考自官方安装文档[2]zhenxun_bot安装文档参考资料
下文中提到的命令个人推荐使用PowerShell运行，当然你也可以使用cmd。
1 必要工具/环境安装
1.1 git 和 python
由于
zhenxun_bot的源码存储在GitHub上，后续安装 bot 本体时需要从GitHub上拉取源码，因此需要安装git。此外zhenxun_bot的运行也依赖python，因此也需要安装python。
| 工具/环境 | 版本要求 | 官方下载地址 | 快速下载地址 |
|---|---|---|---|
| git | 最新稳定版即可 | git - Git for Windows (git-scm.com) | Git-2.47.0-64-bit.exe |
| python | 要求 >= 3.10 | python - Official Download Page | python-3.11.6-amd64.exe |
1.2 数据库
zhenxun_bot原先仅支持PostgreSQL，近期重构后支持的数据库包括PostgreSQL、MySQL、SQLite，用户可依需选择数据库。
zhenxun_bot已内置SQLite数据库，开箱即用。若使用SQLite数据库，可直接跳过此步骤。
| 数据库 | 版本要求 | 官方下载地址 | 快速下载地址 |
|---|---|---|---|
| PostgreSQL | 大于9.x即可 |
PostgreSQL: Download the official PostgreSQL database | PostgreSQL 15.1 64-bit |
1 安装:
- 双击安装程序，点击
Next
- 选择安装路径（没有特殊情况一般默认即可），继续
Next 3. 去掉`Stack Builder`即可，不影响使用，`Next`  4. 数据存储路径（没有特殊情况一般默认即可），`Next`  5. 设置 postgres 用户的密码，例如: `zhenxun`  6. 默认端口，`Next`  7. 接下来一路`Next`直到进入安装进度条  8. ✨✨ 安装完成 ✨✨ 安装路径请不要出现中文！
2 配置连接:
- 找到安装的 pgAdmin，直接启动！
2. 新建连接 左侧栏右键点击`Servers`后选择`Register`，再点击`服务器`  3. 为服务器是英文界面？别急，已百度
随便起一个响亮的名字  4. 填写配置 填写`主机名称/地址`，如果是连接远程服务器的话对应的服务器 IP，本地的话可以直接填写`127.0.0.1` `端口`就是安装时配置的端口，没有修改的话默认`5432` `密码`就是安装时配置的密码  5. ✨✨ 点击保存 ✨✨ 左侧栏会出现一头 🐘 3 创建数据库:
- 展开 🐘🐘
右击数据库，选择创建后点击数据库
- ✨✨ 直接创建！ ✨✨
设置数据库名称后点击保存
- 展开 🐘🐘
- 找到安装的 pgAdmin，直接启动！
| 数据库 | 版本要求 | 官方下载地址 | 快速下载地址 |
|---|---|---|---|
| MySQL | 较新稳定版即可 | MySQL : Download MySQL Community Server | MySQL LTS 8.4.2-winx64.msi |
SQLite与PostgreSQL数据库。
1.3 无头 QQ 安装
无头 QQ 作为前端用于真寻 Bot 与 QQ 服务器之间的通信。无头 QQ 负责接收 QQ 消息并转发给真寻 Bot，真寻 Bot 处理消息后返回给无头 QQ，无头 QQ 再将消息发送给 QQ 用户。之前，旧版真寻 Bot 的默认前端是go-cqhttp，但
go-cqhttp的风险性实在较高，已基本宣告死亡，因此推荐使用NapCat, LLOneBot, Lagrange.Core等。这些前端均支持HTTP、WebSocket、TCP等多种协议，并且均支持OneBot协议，因此可以无缝对接真寻 Bot。
真寻默认使用反向ws协议连接，默认连接地址为ws://127.0.0.1:8080/onebot/v11/ws。
| 项目地址 | 平台 | 核心作者 | 文档 | 备注 |
|---|---|---|---|---|
| NapCat | NTQQ | NapNeko | 文档 | 部署简单，可以不使用GUI，方便内存较小不支持图形界面的服务器部署；可以与手机同时在线； |
请移步官方文档。
此处仅提供一个示例配置，具体配置请移步官方文档。host 为真寻本体所在服务器地址，port 为真寻本体所在服务器端口。若真寻本体与NapCat在同一台服务器上，则host为127.0.0.1或localhost，port为真寻本体所在端口，默认为8080。
1 | { |
| 项目地址 | 平台 | 核心作者 | 文档 | 备注 |
|---|---|---|---|---|
| Lagrange.Core | LagrangeDev/Linwenxuan04 | 文档 |
未使用过此前端，请自行查阅官方文档。
2 安装真寻 Bot
2.1 下载 Bot 文件并安装依赖
1.使用
git拉取真寻源码
1 | git clone https://github.com/HibiKier/zhenxun_bot.git # 拉取源码 |
2.安装依赖
真寻使用poetry管理依赖，在安装依赖之前，需要先安装poetry。当出现异常情况导致环境配置出错时，只需删除对应的poetry虚拟环境（真寻的依赖的虚拟环境路径为~/.cache/pypoetry/virtualenvs）重新安装即可，不需要回滚系统。
1 | cd zhenxun_bot # 进入项目目录 |
2.2 修改相关配置
1.设置超级用户，打开
~/zhenxun_bot/.env.dev，在SUPERUSERS和
1 | SUPERUSERS=["123456789"] # 将 123456789 替换为你的 QQ 号 |
2.设置数据库连接，打开
~/zhenxun_bot/.env.dev，在DB_URL中添加你的数据库连接地址。
建议的数据库，嫌麻烦请使用 SQLite。
1 | # 示例: "postgres://user:[email protected]:5432/database" |
Sqlite 可以放置在任何位置，sqlite:之后为存放路径，但建议在data文件夹下新建db文件夹后使用。
1 | # 示例: "sqlite:data/db/zhenxun.db" |
1 | # 示例: "mysql://user:[email protected]:3306/database" |
3.配置外网访问（可选）
1 | # 若无头QQ与真寻本体不在同一台服务器，需要配置外网访问 |
Bot第一次成功启动后会生成配置文件，配置文件保存在 ~/zhenxun_bot/data/config.yaml，所有真寻相关插件都在使用该配置文件，按需修改
2.3 启动真寻 Bot
真寻必须在
poetry环境下运行，启动真寻前请先进入poetry环境。
1 | # cd zhenxun_bot # 进入项目目录 |
在执行命令
1 | poetry shell |
时，可能会出现报错：The command "shell" does not exist
在 Github 上有个 issue，提供了一个解决方案，即安装poetry-plugin-shell解决
1 | pip install poetry-plugin-shell |
当你的控制台出现以下日志，说明你已经成功了 🎉🎉
1 | 08-14 23:18:44 [INFO] zhenxun | CMD[Web UI] API启动成功 |
启动成功后，请勿关闭终端窗口，否则 Bot 会停止运行。
3 插件安装
当前版本真寻本体与插件库分离，你可以在以下获取插件或其他相关，或通过与真寻的对话命令安装插件（插件商店）
| 项目名称 | 主要用途 | 仓库作者 | 备注 |
|---|---|---|---|
| 插件库 | 插件库 | zhenxun-org | 原 plugins 文件夹插件 |
| 插件索引库 | 插件 | zhenxun-org | 扩展插件索引库 |
| 真寻一键安装脚本 | 一键安装脚本 | soloxiaoye2022 | 第三方 |
| WbeUi | 管理面板 | HibiKier | 基于真寻 WebApi 的 webui 实现 |
| 安卓 app(WebUi) | 安卓 app | YuS1aN | 第三方 |
当前版本真寻有独立的插件目录，即
[~/zhenuxn_bot/zhenuxn/plugins]。除基础插件外，其余所有新安装的插件都在此目录下。因为真寻是基于Nonebot2开发的，所以理论上是兼容 OneBot 插件商店中的插件的，不过具体是否适配需要自行测试。现有两种安装方式，一个是手动安装，一个是使用nb-cil命令安装。下面以安装插件nonebot-plugin-oddtext为例，演示如何安装插件。
1 | # 从github拉取插件文件 |
1 | # 在使用 poetry install 时会自动安装 nb-cil等依赖 |
安装完毕后，真寻可能不会自动加载插件，需要手动添加。在[~/zhenuxn_bot/]目录下，找到bot.py文件，在 nonebot.load_plugins("zhenxun/plugins") 下添加 nonebot.load_plugin("nonebot_plugin_oddtext")，重启真寻即可。
1 | nonebot.load_plugins("zhenxun/builtin_plugins") |
如果插件还需要一些其他额外步骤，请参考插件仓库中的说明。若插件要求在
.env文件中填写相关配置，可将配置写入zhenxun_bot/.env.dev文件中。
Ubuntu 部署教程
本教程在Ubuntu环境下进行，其包管理器使用apt，不同的Linux发行版的包管理器可能不同，但具体步骤大差不差。
下文的命令若未指定环境，则默认均在Ubuntu的Terminal中执行。对于Ubuntu桌面版用户，可使用快捷键CTRL + ALT + T 打开Terminal。
1 必要工具/环境安装
在安装任何新软件之前，建议先更新软件包，确保一切都是最新的。打开终端并运行以下命令：
1 | sudo apt update && sudo apt upgrade -y |
1.1 git 和 python
由于
zhenxun_bot的源码存储在GitHub上，后续安装 bot 本体时需要从GitHub上拉取源码，因此需要安装git。此外zhenxun_bot的运行也依赖python，因此也需要安装python。
| 工具/环境 | 版本要求 |
|---|---|
| git | 最新稳定版即可 |
| python | 要求 >= 3.10 |
- 安装
git
1 | sudo apt install git -y |
- 安装
python[1]在 Ubuntu 20.04 上安装 Python 3.12：详细教程参考资料，此处安装python3.11，其他版本同理
步骤 1：添加Deadsnakes PPA由于Ubuntu默认存储库中可能没有最新版本的Python（如Python 3.12），我们需要添加第三方的Deadsnakes PPA，这个PPA提供多种版本的Python，包括最新版本。
1 | # 首先安装管理 PPA 的工具 |
步骤 2：安装
Python 3.11
1 | sudo apt install python3.11 |
步骤 3：验证安装
1 | python3.11 --version |
步骤 4：设置
Python 3.11为默认版本（可选）
1 | # 首先，列出系统上可用的 Python 版本 |
步骤 5：安装
pip
1 | # 使用如下命令检查是否已安装 `pip` |
1.2 数据库
zhenxun_bot原先仅支持PostgreSQL，近期重构后支持的数据库包括PostgreSQL、MySQL、SQLite，用户可依需选择数据库。
zhenxun_bot已内置SQLite数据库，开箱即用。若使用SQLite数据库，可直接跳过此步骤。
| 数据库 | 版本要求 |
|---|---|
| PostgreSQL | 大于9.x即可 |
1 安装:
1 | # 安装 PostgreSQL |
2 创建与配置数据库:
1 | # 首先切换到`postgres`用户 |
配置完成数据库后，连接接数据库链接为
1 | postgres://[username]:[password]@[host]:[port]/[database] |
| 数据库 | 版本要求 |
|---|---|
| MySQL | 较新稳定版即可 |
请自行寻找安装教程，建议使用SQLite与PostgreSQL数据库。
1.3 无头 QQ 安装
无头 QQ 作为前端用于真寻 Bot 与 QQ 服务器之间的通信。无头 QQ 负责接收 QQ 消息并转发给真寻 Bot，真寻 Bot 处理消息后返回给无头 QQ，无头 QQ 再将消息发送给 QQ 用户。之前，旧版真寻 Bot 的默认前端是go-cqhttp，但
go-cqhttp的风险性实在较高，已基本宣告死亡，因此推荐使用NapCat, LLOneBot, Lagrange.Core等。这些前端均支持HTTP、WebSocket、TCP等多种协议，并且均支持OneBot协议，因此可以无缝对接真寻 Bot。
真寻默认使用反向ws协议连接，默认连接地址为ws://127.0.0.1:8080/onebot/v11/ws。
| 项目地址 | 平台 | 核心作者 | 文档 | 备注 |
|---|---|---|---|---|
| NapCat | NTQQ | NapNeko | 文档 | 部署简单，可以不使用GUI，方便内存较小不支持图形界面的服务器部署；可以与手机同时在线； |
具体详细内容请移步官方文档。
-
安装
NapCatNapCat提供了非常方便的一键安装脚本，可以非常方便的安装NapCat，安装命令如下：1
curl -o napcat.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh && sudo bash napcat.sh
-
配置连接
此处仅提供一个示例，具体配置请移步官方文档。host 为真寻本体所在服务器地址，port 为真寻本体所在服务器端口。若真寻本体与NapCat在同一台服务器上，则host为127.0.0.1或localhost，port为真寻本体所在端口，默认为8080。
1 | { |
| 项目地址 | 平台 | 核心作者 | 文档 | 备注 |
|---|---|---|---|---|
| Lagrange.Core | LagrangeDev/Linwenxuan04 | 文档 |
未使用过此前端，请自行查阅官方文档。
2 安装真寻 Bot
2.1 下载 Bot 文件并安装依赖
1.使用
git拉取真寻源码
1 | git clone https://github.com/HibiKier/zhenxun_bot.git # 拉取源码 |
2.安装依赖
真寻使用poetry管理依赖，在安装依赖之前，需要先安装poetry。当出现异常情况导致环境配置出错时，只需删除对应的poetry虚拟环境（真寻的依赖的虚拟环境路径为~/.cache/pypoetry/virtualenvs）重新安装即可，不需要回滚系统。
1 | cd zhenxun_bot # 进入项目目录 |
2.2 修改相关配置
1.设置超级用户，打开
~/zhenxun_bot/.env.dev，在SUPERUSERS和
1 | SUPERUSERS=["123456789"] # 将 123456789 替换为你的 QQ 号 |
2.设置数据库连接，打开
~/zhenxun_bot/.env.dev，在DB_URL中添加你的数据库连接地址。
建议的数据库，嫌麻烦请使用 SQLite。
1 | # 示例: "postgres://user:[email protected]:5432/database" |
Sqlite 可以放置在任何位置，sqlite:之后为存放路径，但建议在data文件夹下新建db文件夹后使用。
1 | # 示例: "sqlite:data/db/zhenxun.db" |
1 | # 示例: "mysql://user:[email protected]:3306/database" |
3.配置外网访问（可选）
1 | # 若无头QQ与真寻本体不在同一台服务器，需要配置外网访问 |
Bot第一次成功启动后会生成配置文件，配置文件保存在 ~/zhenxun_bot/data/config.yaml，所有真寻相关插件都在使用该配置文件，按需修改
2.3 启动真寻 Bot
真寻必须在
poetry环境下运行，启动 Bot 前请先进入poetry环境。
1 | # cd zhenxun_bot # 进入项目目录 |
当你的控制台出现以下日志，说明你已经成功了 🎉🎉
1 | 08-14 23:18:44 [INFO] zhenxun | CMD[Web UI] API启动成功 |
启动成功后，请勿关闭终端窗口，否则 Bot 会停止运行。
2.4 使用 screen 持久化运行（可选）
如果你希望 Bot 在后台运行，可以使用
screen持久化运行。
1 | # 创建一个名为 zhenxun 的 screen 会话 |
3 插件安装
当前版本真寻本体与插件库分离，你可以在以下获取插件或其他相关，或通过与真寻的对话命令安装插件（插件商店）
| 项目名称 | 主要用途 | 仓库作者 | 备注 |
|---|---|---|---|
| 插件库 | 插件库 | zhenxun-org | 原 plugins 文件夹插件 |
| 插件索引库 | 插件 | zhenxun-org | 扩展插件索引库 |
| 真寻一键安装脚本 | 一键安装脚本 | soloxiaoye2022 | 第三方 |
| WbeUi | 管理面板 | HibiKier | 基于真寻 WebApi 的 webui 实现 |
| 安卓 app(WebUi) | 安卓 app | YuS1aN | 第三方 |
当前版本真寻有独立的插件目录，即
[~/zhenuxn_bot/zhenuxn/plugins]。除基础插件外，其余所有新安装的插件都在此目录下。因为真寻是基于Nonebot2开发的，所以理论上是兼容 OneBot 插件商店中的插件的，不过具体是否适配需要自行测试。现有两种安装方式，一个是手动安装，一个是使用nb-cil命令安装。下面以安装插件nonebot-plugin-oddtext为例，演示如何安装插件。
1 | # 从github拉取插件文件 |
1 | # 在使用 poetry install 时会自动安装 nb-cil等依赖 |
安装完毕后，真寻可能不会自动加载插件，需要手动添加。在[~/zhenuxn_bot/]目录下，找到bot.py文件，在 nonebot.load_plugins("zhenxun/plugins") 下添加 nonebot.load_plugin("nonebot_plugin_oddtext")，重启真寻即可。
1 | nonebot.load_plugins("zhenxun/builtin_plugins") |
如果插件还需要一些其他额外步骤，请参考插件仓库中的说明。若插件要求在
.env文件中填写相关配置，可将配置写入zhenxun_bot/.env.dev文件中。
