自搭建指南

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

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

使用每晚构建（Nightly Build）二进制文件搭建

提示

此方式仅适用于想要进行快速体验的用户使用。我们仅在此处提供 x64 平台的构建文件，编译后的文件无法进行代码调试，且部分功能可能存在问题或被禁用（clac、update等），如需完整的功能体验，请使用源代码进行搭建。

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

使用源代码搭建

安装 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 镜像支持的架构为 amd64 和 arm64。

在终端内运行以下命令：

docker pull dorowolf/akari-bot:latest

设置配置

进入 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:////<绝对路径>/<数据库文件名>.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 官方机器人（WIP）

QQ 官方现已开放机器人功能，可进入 QQ 开放平台进行申请。

目前，QQ 官方机器人已开放个人开发者使用权限，包括频道与群聊机器人。

QQ 官方机器人无需担心风控问题，但出于隐私考虑，QQ 官方对机器人能力有严格限制，包括但不限于：获取用户 QQ 号、昵称，非 @ 消息响应，URL 消息推送，主动消息推送等。

配置机器人

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

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

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

注意

家庭网络的 IP 通常是不固定的，运营商可能会随时更换你的 IP。假如你在家庭网络中运行机器人，在遇到连接问题时，请先检查你的网络 IP 是否变动。

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

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

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

qq_bot_appid = - 机器人的 AppID。

qq_bot_secret = - 机器人的 AppSecret。

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

指令配置

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

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

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

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

机器人上线

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

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

提示

以下是 QQ 官方提供的“自测协议”与“隐私报告”模板：

• 机器人自测报告.xlsx
• 第三方机器人隐私保护指引.docx

请按照机器人实际情况填写，这将直接导致你的机器人是否能被 QQ 官方人员审核通过。

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

注意

目前的 QQ 审核主要是测试机器人在所提供的场景下，是否能正常回应指令列表中的指令。
在提交审核前，请善用沙箱场景，测试在自测报告中填写的指令是否能正常工作。如果填写的指令需要特殊参数（例如模块子命令、选项与参数等），请务必在自测报告的“特殊说明”栏中填写补充说明。
假如审核未通过，可点击右上角的“通知”按钮查看原因，解决后再次提交。

第三方

要使用第三方软件在 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。

启动

使用每晚构建（Nightly Build）二进制文件搭建

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

Windows

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

建议使用终端或 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

使用源代码搭建

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

Windows

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

建议使用终端或 Powershell 运行：

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

Linux/MacOS

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

控制台

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

1. 在机器人根目录下打开终端。
2. 在终端内使用 poetry shell 切换 Poetry 的虚拟环境来调用先前安装的依赖。（可选）
3. 在终端内运行 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。