自搭建指南

本文将会指导你如何搭建你自己的小可机器人。

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

直接搭建

安装 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

Docker 镜像搭建

拉取镜像

请确保你的计算机已安装 Docker，且 Docker Daemon 正常运行。

在终端内运行以下命令：

docker pull dorowolf/akari-bot:latest

提示

目前机器人的 Docker 镜像支持的架构为 amd64 和 arm64。

设置配置

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

如果使用 Docker 镜像搭建，请前往机器人储存库或在此处下载 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_render 与 web_render_local 配置项填写访问地址。

格式：

web_render = - Webrender 的地址（IP 或域名）及端口。

web_render_local = - 本地 Webrender 的地址，同时填写时将优先使用此地址。

示例：web_render = "http://127.0.0.1:15551"

连接平台

QQ

要在 QQ 平台连接机器人，请见自搭建指南/QQ。

危险

如果出现 QQ 账号被冻结等情况，我们无力解决此类问题，也不会为相应后果负责。

Discord

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

请前往并登录 Discord 开发者平台，点击“New application”，按照要求填写应用名字并确认创建。点击侧边导航栏“bot”，启用“Privileged Gateway Intents”下全部三个开关：Presence Intent、Server Members Intent、Message 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 家服务器。

使用客户端获取会话 ID 和 Access Token：

点击头像，选择“Security & Privacy”，复制“Session ID”后的字符串。将复制的 ID 填写到配置文件的 matrix_device_id 配置项中。

选择“Help & About”，点击“Advanced”下的“Access Token”，复制展开的 Token，将复制的 Token 填写到配置文件的 matrix_token 配置项中。

警告

如果使用客户端获取会话 ID 和 Access Token，不要使用客户端的退出登录功能，推荐通过浏览器隐私模式登录来获取会话 ID 与 Token。

使用 Matrix API 获取会话 ID 和 Access Token：

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

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

若响应成功，响应体将包含名为 access_token 和 device_id 的字段，复制其中的 Token 和 ID。

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

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

matrix_homeserver = - 机器人账号使用的 Matrix 家服务器 URL。

matrix_user = - 机器人的完全限定用户 ID（包括 @ 与 :）。

matrix_device_name = - 机器人的设备名称。（可选）

提示

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

E2E 加密

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

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

• 使用 Poetry：

poetry run -- pip3 install matrix-nio[e2e]

• 使用 pip：

pip3 install matrix-nio[e2e]

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

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

控制台

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

运行控制台：

在机器人根目录下打开终端。

在终端内使用 poetry shell 切换 Poetry 的虚拟环境来调用先前安装的依赖。（可选）

在终端内运行 python console.py 以启动控制台。

Docker 镜像搭建

请在终端内运行以下命令启用机器人：

docker run \
> -d \
> -v /path/to/config.toml:/akari-bot/config/config.toml \ # 请将路径修改成对应的位置
> -p 11451:11451  \ # 反向 WebSocket 服务器端口，请根据配置文件更改
> -p 3306:3306  \ # 用于对接 MySQL 数据库（可选）
> --name akari-bot  \ # 指定容器名称
> dorowolf/akari-bot

如果终端中返回了 long_tag 类型的容器 ID，证明容器已成功创建。

在终端内运行 docker logs akari-bot 可以查看机器人日志。此处的 akari-bot 为容器名，若你忘记定义容器名，可以替换为容器 ID。