自搭建指南 - Teahouse-Studios/akari-bot GitHub Wiki

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

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

请在 Github 上登录账户，然后在此处点击最新的（第一个）构建版本，然后下载对应你使用的平台的 Artifacts，然后解压即可。后续请按照下文的设置配置章节进行。

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

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

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

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

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

Windows

打开终端或 PowerShell，执行以下命令：

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

Linux

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

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

安装 Poetry 完成后，请执行以下命令安装依赖：

poetry install

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

如果你不想使用 Poetry，你可以使用 pip 来安装依赖：

pip install -r requirements.txt

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

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

在终端内运行以下命令：

docker pull dorowolf/akari-bot:latest

当安装好依赖后，你需要生成默认的配置文件并设置内容。

为了生成配置，我们需要先启动一次机器人程序。（使用每晚构建时，已默认将配置文件生成在 config 文件夹中，进行配置即可。）

当机器人检测到配置文件不存在时，将会弹出配置向导以生成配置文件。

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

Windows

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

建议使用终端或 Powershell 运行：

1. 在机器人根目录下，按下 Shift + 右键来打开右键菜单。
2. 选择“在此处打开 Powershell 窗口”或“在此处打开命令窗口”。
3. 在终端内输入 .\start.bat 或在 Powershell 输入 start.bat 来启动机器人。

Linux/MacOS

1. 在终端内设置 start 脚本的执行权限：chmod +x start
2. 启动脚本：./start

进入 config 文件夹，然后开始配置所需的配置项。

在第一次启动时，命令行将会弹出如下提示：

Hi, it seems you are first time to run AkariBot, what language do you want to use by default?
1. 简体中文
2. 繁體中文
3. English
Please input the number of the language you want to use: 

输入你想要使用的默认对话语言环境的开头编号并回车，机器人将会尝试自动生成文件，然后请根据下文进行配置具体的内容。

如果使用 Docker 镜像搭建，请在此处下载配置文件模板，然后解压并进行配置。

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

Windows

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

建议使用终端或 Powershell 运行：

1. 在机器人根目录下，按下 Shift + 右键来打开右键菜单。
2. 选择“在此处打开 Powershell 窗口”或“在此处打开命令窗口”。
3. 在终端内输入 .\bot.exe 或在 Powershell 输入 .\bot.exe 来启动机器人。
4. 启动后可能会提示是否允许 launcher.exe 程序访问网络，请选择允许。

Linux/MacOS

1. 在终端内设置 bot.bin 和 launcher.bin 的执行权限：chmod +x bot.bin launcher.bin
2. 启动二进制程序：./bot.bin

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

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

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

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

config.toml 内存储了机器人所有的配置项。其中在 secret 表中储存的配置项为私有内容，例如 API 密钥等，当机器人发送的消息中存在这些内容时会被自动拦截，请将私密内容填写到此部分。在 config 表中一般是一些模块设定的常量等内容，请不要在这个文件里面填写私密信息，防止意外泄露。

除此之外，还存在着若干以 bot_ 为开头的文件，这些文件中包含了一些平台端的独有配置，若需要配置相关平台，请留意里面的内容。

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

如果使用 MySQL 作为数据库：

格式：db_path = "mysql://<数据库用户名>:<数据库用户密码>@<数据库地址>"

示例：db_path = "mysql://bot:[email protected]/bot_prod"

如果使用 SQLite 作为数据库：

格式：

• db_path = "sqlite://<相对路径>/<数据库文件名>.db"
• db_path = "sqlite:///<绝对路径>/<数据库文件名>.db"

示例：db_path = "sqlite://database/save.db"

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

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

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

check_access_key_id = - 填写获取的 AccessKeyID。

check_access_key_secret = - 填写获取的 AccessKeySecret。

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

此服务使用 JavaScript 编写，并由 Puppeteer 驱动，因此需要安装 Node.js 环境，以及安装 Chromium 内核浏览器。

亦可使用云服务产商的 Serverless 来搭建本服务。

请前往此处下载源文件，并在终端内安装依赖。

npm install

前往此处下载任意版本 Chromium，或前往 Chromium 官方网站下载。

于 package.json 同级目录中新建 .env 文件，并填写以下字段：

CHROMIUM_PATH = # Chromium 可执行文件位置
FC_SERVER_PORT = 15551 # API 监听端口

使用 node 运行 ./src/index.js 来开启服务。

node ./src/index.js

API 监听端口默认位于 15551，可自行选择自定义端口。

请在配置文件 cnnfig.toml 中 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 官方机器人无需担心风控问题，但出于隐私考虑，QQ 官方对机器人能力有严格限制，包括但不限于：获取用户 QQ 号、昵称，非 @ 消息响应，URL 消息推送，主动消息推送等。

要通过 QQ 官方机器人在 QQ 平台连接机器人，你需要建立好一个机器人应用。

请前往 QQ 开放平台，实名注册后，按照要求创建一个机器人应用。

进入机器人管理后台，点击侧边栏“开发设置”，在“IP 白名单”栏中填写机器人所在服务器的公网 IP。

上滑可以得到机器人 ID 与密钥。将机器人 ID 复制后，填写到配置文件的 qq_bot_appid 配置项中。

随后点击机器人密钥后的“生成”，确认后点击“复制”复制 Token。将复制的 Token 填写到配置文件的 qq_bot_secret 配置项中。

请在机器人配置文件 bot_qqbot.toml 填写以下配置项：

qq_bot_appid = - 机器人的 AppID。

qq_bot_secret = - 机器人的 AppSecret。

qq_bot_private = False - 设置机器人是否为私域机器人。

填写完毕后，请在 bot_qqbot.toml 配置文件中的 enable 选项设置为 true 以启用此平台端。

点击侧边栏“发布设置”，点击“功能配置”目录右侧“配置”与“指令”选项卡。

点击“添加指令”或“重新配置”（如果之前已设置）按钮，点击“+”按钮可添加新的指令页。

进入对应的指令页，在“指令名”中填写模块名称，“指令介绍”中填写模块简介。在“使用场景”栏中可选中所有场景，具体可在沙箱场景中测试模块是否良好运行。

配置完成后，点击“保存配置”并确认即可。

点击侧边栏“使用范围与人员”，点击“编辑”按钮，将所有情况选择为“全部”后点击确认。

配置完成后，点击“发布设置”，按要求填写并上传“自测报告”与“隐私协议”。

点击“提交审核”按钮后，等待 QQ 官方人员测试并审核。审核通过后，在“发布设置”页面中点击“上线机器人”按钮。

要使用第三方软件在 QQ 平台连接机器人，请见自搭建指南：QQ。

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

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

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

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

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

填写完毕后，请在 bot_discord.toml 配置文件中的 enable 选项设置为 true 以启用此平台端。

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

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

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

填写完毕后，请在 bot_telegram.toml 配置文件中的 enable 选项设置为 true 以启用此平台端。

要在 KOOK（开黑啦）平台连接机器人，你需要建立好一个应用。

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

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

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

填写完毕后，请在 bot_kook.toml 配置文件中的 enable 选项设置为 true 以启用此平台端。

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

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

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

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

选择“Help & About”，点击“Advanced”下的“Access Token”，复制展开的 Token，将复制的 Token 填写到配置文件 bot_matrix.toml 的 matrix_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 = - 机器人的设备名称。（可选）

填写完毕后，请在 bot_matrix.toml 配置文件中的 enable 选项设置为 true 以启用此平台端。

目前，由于 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。

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

控制台在 Docker 镜像与二进制文件中不可用。

在控制台中的操作者默认拥有超级用户权限。

控制台中仅支持回复文本消息和图片，其它消息元素将被忽略或转换为文本或图片显示。

你可能需要使用 poetry env create 切换 poetry 的虚拟环境来调用先前安装的依赖。

1. 在机器人根目录下打开终端。
2. 在终端内使用 poetry env create 切换 Poetry 的虚拟环境来调用先前安装的依赖。（可选）
3. 在终端内运行 python console.py 以启动控制台。