• 欢迎来到小可 · Wiki,人人可编辑的,多平台聊天机器人“小可”的官方文档资源。
  • 小可很可爱,请给我们打钱
  • 原 MkDocs 已迁入本站。若发现 404 属正常现象,请点击左上角搜索您想要的模块。

自搭建指南

来自小可 · Wiki,人人可编辑的,QQ机器人“小可”的官方文档资源
Dorowolf讨论 | 贡献2024年7月7日 (日) 14:43的版本 →‎直接下载

本文将会指导你如何搭建与部署小可。

搭建机器人需要计算机等相关知识有一定的了解,若在阅读过程中感到困惑,请善于使用搜索引擎。

安装 Python 环境

请前往 Python 官网 下载 Python 3.12 及以上版本,低于此版本将不再受到支持。

获取源代码

使用 Git 克隆

请在需要放置小可的文件目录下打开终端,并输入以下命令:

git clone https://github.com/Teahouse-studios/akari-bot.git

直接下载

请前往此处下载 Master 分支的源代码。由于无法保证 Release 版本的稳定性,我们不再提供 Release 版本的下载。

提示
不建议通过直接下载的方式进行部署,因为这样将无法使用 Git 或 ~update 命令更新机器人源代码。

安装依赖

使用 Poetry

Poetry 是一个现代化的依赖管理工具,它能够帮助你管理项目的依赖和虚拟环境。要使用 Poetry 安装依赖,首先需请确保已经安装了 Poetry。

Windows

打开终端或 PowerShell,执行以下命令:

(Invoke-WebRequest -Uri "https://install.python-poetry.org" -UseBasicParsing).Content | py -
Linux

打开终端并运行以下命令:

curl -sSL https://install.python-poetry.org | python -

安装 Poetry 完成后,请执行以下命令安装依赖:

poetry install

使用 pip

pip 是 Python 自带的官方包管理工具。

如果你不想使用 Poetry,请执行以下命令安装依赖:

pip install -r requirements.txt

设置配置

进入 config 文件夹,将配置文件 config.toml.example 重命名为 config.toml,然后开始配置所需的内容。

提示
当前配置文件使用 toml 格式。如果你使用的是旧版 cfg 文件,机器人会自动将其转换为 toml 格式。
在配置文件中填入必要的字段后,请删除所有未使用的字段,否则程序可能无法正常运行。

在表 secret 储存的配置项为私有内容,例如 API 密钥等,当机器人发送的消息中存在这些内容时会被自动拦截。表 config 中大多数配置项的默认值与程序内设定一致。如果你觉得冗余,可以直接将其删除。

关于配置项的详细信息,请查看配置文件

配置数据库

机器人需要一个数据库以用于存储用户数据。db_path 配置项需要填写一个可被 sqlalchemy 支持的数据库链接。

如果使用 MySQL 作为数据库:

格式:db_path = "mysql+pymysql://<数据库用户名>:<数据库用户密码>@<数据库地址>"
示例:db_path = "mysql+pymysql://bot:123456@example.com/bot_prod"

如果使用 SQLite 作为数据库:

格式:db_path = "sqlite:///<相对路径>/<数据库文件名>.db"
示例:db_path = "sqlite:///database/save.db"

此示例将会在 database 文件夹内创建 save.db 来存储用户数据。

提示
如果你希望避免复杂的数据库安装或购买服务,建议使用 SQLite。注意,SQLite 可能会遇到极少数的锁表问题,或在误删文件未备份时数据丢失。

内容安全

机器人集成了阿里云内容安全服务,用于检查 QQ 和 KOOK 平台下的消息安全。

如有需求,请前往阿里云进行开通并获取 AccessKeyID 及 AccessKeySecret,并在配置文件中填写相关配置项。

check_access_key_id = - 填写获取的 AccessKeyID。
check_access_key_secret = - 填写获取的 AccessKeySecret。
提示
由于阿里云政策限制,内容安全服务不面向个人开发者,必须完成阿里云企业认证才能使用。

Webrender

Webrender 为机器人的外置服务,主要用于处理 Wiki infobox 图片渲染、 html 渲染以及部分功能的访问代理。

Webrender 的部署相关内容请见 Webrender#部署。亦可使用云服务产商的 Serverless 来部署本服务。

请在配置文件中 web_renderweb_render_local 配置项填写访问地址。

格式:
web_render = - Webrender 的地址(IP 或域名)及端口。
web_render_local = - 本地 Webrender 的地址,同时填写时将优先使用此地址。
示例:web_render = "http://127.0.0.1:15551"

连接平台

QQ

要在 QQ 平台连接机器人,请见自搭建/QQ

Discord

要在 Discord 平台连接机器人,你需要建立好一个应用。

请前往并登录 Discord 开发者平台,点击“New application”,按照要求填写应用名字并确认创建。完成后,点击侧边导航栏“bot”,打开“Privileged Gateway Intents”目录下全部三个开关:Presence IntentServer Members IntentMessage Content Intent。完成后点击“Save Changes”。

建立好应用后上滑,点击“Reset Token”,确认后点击“Copy”复制 Token。将复制的 Token 填写到配置文件的 discord_token 配置项中。

提示
如果你的机器人所处的位置直接访问 Discord 有困难,请在配置文件的 proxy 配置项中填写代理服务地址。

如果你想把机器人邀请到服务器中,需要在侧边栏“Installation”选项卡中的“Authorization Methods”选项中勾选 Guild Install

要申请用于邀请机器人到 Discord 服务器的链接,请前往侧边导航栏“OAuth2”下方的子目录“URL Generator”,在“Scopes”中选择 Bot 后在下方“Bot Permissions”中选择你希望机器人拥有的权限。完成后复制下方生成的 URL,复制到浏览器打开。

提示
如果给予的权限不充分,可能会导致无法发送消息或图片。
若你不确定具体应该添加哪些权限,可直接添加 Administrator(管理员)权限。

Telegram

要在 Telegram 平台连接机器人,你需要建立好一个机器人账户。

请在 Telegram 私信 @BotFather,输入命令 /start 后使用 /newbot 按照要求创建一个机器人账号。

提示
/newbot 命令下需完成两个步骤:
  1. 输入机器人的显示名称
  2. 输入机器人的账号名称(需以“bot”结尾)

完成后,@BotFather 会发送一条含有 Token 的消息。将复制的 Token 填写到配置文件的 telegram_token 配置项中。

提示
如果你的机器人所处的位置直接访问 Telegram 有困难,请在配置文件的 proxy 配置项中填写代理服务地址。

KOOK

要在 KOOK(开黑啦)平台连接机器人,你需要建立好一个应用。

请前往并登录 KOOK 开发者平台,点击“创建应用”,按照要求填写应用名字并确认创建。

完成后,点击侧边导航栏“机器人”,在“Token”下找到 Token 并复制。将复制的 Token 填写到配置文件的 kook_token 配置项中。

要申请用于邀请机器人到 KOOK 服务器的链接,请前往侧边导航栏“机器人”下方的子目录“邀请链接”,选择你希望机器人拥有的权限。完成后复制下方生成的 URL,复制到浏览器打开。

提示
如果给予的权限不充分,可能会导致无法发送消息或图片。
若你不确定具体应该添加哪些权限,可直接添加管理员权限。

Matrix

要在 Matrix 平台连接机器人,你需要注册一个机器人账号。

请前往 Element,按照要求填写注册信息以建立一个账号。你可以自定义机器人账号托管的家服务器,建议使用官方的 https://matrix.org 家服务器。

注册好账号后点击头像,选择“Security & Privacy”,复制“Session ID”后的字符串。将复制的会话 ID 填写到配置文件的 matrix_device_id 配置项中。

使用客户端获取 Access Token(不推荐):

点击头像,选择选择“Help & About”,点击“Advanced”下的“Access Token”,复制展开的 Token。

警告
如果使用客户端获取 Access Token,不要使用客户端的退出登录功能,推荐通过浏览器隐私模式登录并获取 Token。

使用 Matrix API 获取 Access Token:

打开终端并运行以下命令:

curl -X POST -d '{"type":"m.login.password", "user":"<用户名>", "password":"<密码>"}' https://matrix.org/_matrix/client/r0/login

若响应成功,响应体将包含一个名为 access_token 的字段,复制其中的值。

将复制的 Token 填写到配置文件的 matrix_token 配置项中。

请在配置文件填写以下其他配置项:

matrix_homeserver = - 机器人账号使用的 Matrix 家服务器 URL。
matrix_user = - 机器人的完全限定用户 ID(包括 @:)。
matrix_device_name = - 机器人的设备名称。(可选)
提示
如果你的机器人所处的位置直接访问 Matrix 有困难,请在配置文件的 proxy 配置项中填写代理服务地址。

E2E 加密

目前,由于 libolm 在一些情况下需要手动配置,机器人默认没有启用端对端(E2E)加密支持。

若要启用 E2E 加密支持,请在终端执行以下命令:

poetry run -- pip3 install matrix-nio[e2e] ; Poetry
pip3 install matrix-nio[e2e] ; PIP

请在配置文件填写以下配置项:

matrix_megolm_backup_passphrase = - 填写机器人的 megolm 备份密码短语。(可选)
建议使用随机的长密码,不填写则不会导出 megolm 备份。

如果需要导入 megolm 备份,请将备份文件放置在 matrix_store/megolm_backup/restore.txt 下,并将密码短语写入 matrix_store/megolm_backup/restore-passphrase.txt

启动

根据系统不同,用以下方法即可启动机器人:

Windows

不推荐双击运行 start.bat 来启动机器人程序。

建议使用终端或 Powershell 运行:

  1. 在机器人根目录下,按下 Shift + 右键来打开右键菜单。
  2. 选择“在此处打开 Powershell 窗口”或“在此处打开命令窗口”。
  3. 在终端内输入 start.bat 或在 Powershell 输入 .\start.bat 来启动机器人。
Linux
  1. 在终端内设置 start 脚本的执行权限:chmod +x start
  2. 启动脚本:./start

控制台

控制台中包括了一个基础的运行环境,可以在控制台内使用命令进行基本的机器人交互。

运行控制台:

  1. 在机器人根目录下打开终端。
  2. 在终端内使用 poetry shell 切换 Poetry 的虚拟环境来调用先前安装的依赖。(可选)
  3. 在终端内运行 python console.py 以启动控制台。
Cookie帮助我们提供我们的服务。通过使用我们的服务,您同意我们使用cookie。