查看“自搭建指南”的源代码

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

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

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

请在 [https://github.com/ Github] 上登录账户，然后在[https://github.com/Teahouse-Studios/akari-bot/actions/workflows/build.yml 此处]点击最新的（第一个）构建版本，然后下载对应你使用的平台的 Artifacts，然后解压即可。后续请按照下文的[[自搭建指南#设置配置|设置配置]]章节进行。

== 使用源代码搭建 ==
=== 安装 Python 环境 ===
请前往 [https://www.python.org/ Python 官网] 下载 Python 3.12 及以上版本，低于此版本将不再受到支持。

=== 获取源代码 ===
==== 使用 Git 克隆 ====
请在需要放置小可的文件目录下打开终端，并输入以下命令：
<syntaxhighlight lang="sh">
git clone https://github.com/Teahouse-studios/akari-bot.git
</syntaxhighlight>

==== 直接下载 ====
请前往[https://github.com/Teahouse-Studios/akari-bot/archive/refs/heads/master.zip 此处]下载 Master 分支的源代码。由于无法保证 Release 版本的稳定性，我们不再提供 Release 版本的下载。
{{Mbox
| text = 不建议通过直接下载的方式进行搭建，因为这样将无法使用 Git 或 <code>~[[update]]</code> 命令更新机器人源代码。
| type = note
}}

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

: '''Windows''' 
打开终端或 PowerShell，执行以下命令：
<syntaxhighlight lang="powershell">
(Invoke-WebRequest -Uri "https://install.python-poetry.org" -UseBasicParsing).Content | py -
</syntaxhighlight>

: '''Linux''' 
打开终端并运行以下命令：
<syntaxhighlight lang="sh">
curl -sSL https://install.python-poetry.org | python -
</syntaxhighlight>

安装 Poetry 完成后，请执行以下命令安装依赖：
<syntaxhighlight lang="sh">
poetry install
</syntaxhighlight>

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

如果你不想使用 Poetry，请执行以下命令安装依赖：
<syntaxhighlight lang="sh">
pip install -r requirements.txt
</syntaxhighlight>

== Docker 镜像搭建 ==
=== 拉取镜像 ===
请确保你的计算机已安装 Docker，且 Docker Daemon 正常运行。

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

在终端内运行以下命令：
<syntaxhighlight lang="sh">
docker pull dorowolf/akari-bot:latest
</syntaxhighlight>

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

如果使用 Docker 镜像搭建，请前往机器人储存库或在[https://raw.githubusercontent.com/Teahouse-Studios/akari-bot/master/config/config.toml.example 此处]下载 <code>config.toml.example</code> 配置文件，并将其重命名为 <code>config.toml</code>。
{{Mbox
| text = 当前配置文件使用 toml 格式。如果你使用的是旧版 cfg 文件，机器人会自动将其转换为 toml 格式。<br>在配置文件中填入必要的配置项后，请删除所有未使用的配置项，否则机器人无法正常运行。
| type = important
}}

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

关于配置项的详细信息，参见[[配置文件]]。

=== 数据库 ===
机器人需要一个数据库以用于存储用户数据。<code>db_path</code> 配置项需要填写一个可被 sqlalchemy 支持的数据库连接串。

如果使用 MySQL 作为数据库：
: 格式：<code>db_path = "mysql+pymysql://<数据库用户名>:<数据库用户密码>@<数据库地址>"</code>
: 示例：<code>db_path = "mysql+pymysql://bot:123456@example.com/bot_prod"</code>

如果使用 SQLite 作为数据库：
: 格式：
* <code>db_path = "sqlite:///<相对路径>/<数据库文件名>.db"</code>
* <code>db_path = "sqlite:////<绝对路径>/<数据库文件名>.db"</code>
: 示例：<code>db_path = "sqlite:///database/save.db"</code>
此示例将会在 <code>database</code> 文件夹内创建 <code>save.db</code> 来存储用户数据。
{{Mbox
| text = 如果你希望避免复杂的数据库安装或购买服务，建议使用 SQLite。<br>SQLite 可能会遇到极少数的锁表问题，或在误删文件未备份时数据丢失。
| type = note
}}

=== 内容安全 ===
机器人集成了[https://www.aliyun.com/product/lvwang 阿里云内容安全服务]，用于检查 QQ 和 KOOK 平台下的消息安全。

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

: <code>check_access_key_id =</code> - 填写获取的 AccessKeyID。
: <code>check_access_key_secret =</code> - 填写获取的 AccessKeySecret。
{{Mbox
| text = 由于阿里云政策限制，内容安全服务'''不面向个人开发者'''，必须完成阿里云企业认证才能使用，敬请谅解。
| type = important
}}

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

WebRender 的搭建相关内容请见 [[WebRender#搭建]]。亦可使用云服务产商的 Serverless 来搭建本服务。

请在配置文件中 <code>web_render</code> 与 <code>web_render_local</code> 配置项填写访问地址。

: 格式：
:: <code>web_render =</code> - WebRender 的地址（IP 或域名）及端口。
:: <code>web_render_local =</code> - 本地 Webrender 的地址，同时填写时将优先使用此地址。
: 示例：<code>web_render = "<nowiki>http://127.0.0.1:15551</nowiki>"</code>

== 连接平台 ==
=== QQ ===
要在 QQ 平台连接机器人，请见[[自搭建指南/QQ]]。
{{Mbox
| text = 目前在 QQ 平台连接机器人的方法均不受官方支持，如果出现 QQ 账号被冻结等情况，我们无力解决此类问题，也不会为相应后果负责。
| type = danger
}}

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

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

建立好应用后上滑，点击“Reset Token”，确认后点击“Copy”复制 Token。将复制的 Token 填写到配置文件的 <code>discord_token</code> 配置项中。
{{Mbox
| text = 如果你的机器人所处的位置直接访问 Discord 有困难，请在配置文件的 <code>proxy</code> 配置项中填写代理服务地址。
| type = note
}}

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

要申请用于邀请机器人到 Discord 服务器的链接，请前往侧边导航栏“OAuth2”下方的子目录“URL Generator”，在“Scopes”中选择 <code>Bot</code> 后在下方“Bot Permissions”中选择你希望机器人拥有的权限。完成后复制下方生成的 URL，复制到浏览器打开。
{{Mbox
| text = 如果给予的权限不充分，可能会导致无法发送消息或图片。<br>若你不确定具体应该添加哪些权限，可直接添加 <code>Administrator</code>（管理员）权限。
| type = important
}}

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

请在 Telegram 私信 [https://t.me/BotFather @BotFather]，输入命令 <code>/start</code> 后使用 <code>/newbot</code> 按照要求创建一个机器人账号。
{{Mbox
| text = <code>/newbot</code> 命令下需完成两个步骤：
# 输入机器人的显示名称
# 输入机器人的账号名称（需以“bot”结尾）
| type = important
}}
完成后，@BotFather 会发送一条含有 Token 的消息。将复制的 Token 填写到配置文件的 <code>telegram_token</code> 配置项中。
{{Mbox
| text = 如果你的机器人所处的位置直接访问 Telegram 有困难，请在配置文件的 <code>proxy</code> 配置项中填写代理服务地址。
| type = note
}}

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

请前往并登录 [https://developer.kookapp.cn/app/index KOOK 开发者平台]，点击“创建应用”，按照要求填写应用名字并确认创建。

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

要申请用于邀请机器人到 KOOK 服务器的链接，请前往侧边导航栏“机器人”下方的子目录“邀请链接”，选择你希望机器人拥有的权限。完成后复制下方生成的 URL，复制到浏览器打开。
{{Mbox
| text = 如果给予的权限不充分，可能会导致无法发送消息或图片。<br>若你不确定具体应该添加哪些权限，可直接添加 <code>管理员</code> 权限。
| type = important
}}

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

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

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

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

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

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

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

打开终端并运行以下命令：
<syntaxhighlight lang="sh">
curl -X POST -d '{"type":"m.login.password", "user":"<用户名>", "password":"<密码>"}' https://matrix.org/_matrix/client/r0/login
</syntaxhighlight>

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

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

请在配置文件填写以下其他配置项：
:<code>matrix_homeserver =</code> - 机器人账号使用的 Matrix 家服务器 URL。
:<code>matrix_user =</code> - 机器人的[https://spec.matrix.org/v1.9/appendices/#user-identifiers 完全限定用户 ID]（包括 <code>@</code> 与 <code>:</code>）。
:<code>matrix_device_name =</code> - 机器人的设备名称。（可选）

{{Mbox
| text = 如果你的机器人所处的位置直接访问 Matrix 有困难，请在配置文件的 <code>proxy</code> 配置项中填写代理服务地址。
| type = note
}}

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

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

* 使用 Poetry：
<syntaxhighlight lang="sh">
poetry run -- pip3 install matrix-nio[e2e]
</syntaxhighlight>
* 使用 pip：
<syntaxhighlight lang="sh">
pip3 install matrix-nio[e2e]
</syntaxhighlight>

请在配置文件填写以下配置项：
: <code>matrix_megolm_backup_passphrase =</code> - 填写机器人的 megolm 备份密码短语。（可选）
: 建议使用随机的长密码，不填写则不会导出 megolm 备份。

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

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

: '''Windows'''
不推荐双击运行 <code>bot.exe</code> 来启动机器人程序。

建议使用终端或 Powershell 运行：
# 在机器人根目录下，按下 <kbd>Shift</kbd> + 右键来打开右键菜单。
# 选择“在此处打开 Powershell 窗口”或“在此处打开命令窗口”。
# 在终端内输入 <code>bot.exe</code> 或在 Powershell 输入 <code>.\bot.exe</code> 来启动机器人。
# 启动后可能会提示是否允许 launcher.exe 程序访问网络，请选择允许。

: '''Linux/MacOS'''
# 在终端内设置 <code>bot.bin</code> 和 <code>launcher.bin</code> 的执行权限：<code>chmod +x bot.bin launcher.bin</code>
# 启动二进制程序：<code>./bot.bin</code>

=== 使用源代码搭建 ===
根据系统不同，用以下方法即可启动机器人：

: '''Windows'''
不推荐双击运行 <code>start.bat</code> 来启动机器人程序。

建议使用终端或 Powershell 运行：
# 在机器人根目录下，按下 <kbd>Shift</kbd> + 右键来打开右键菜单。
# 选择“在此处打开 Powershell 窗口”或“在此处打开命令窗口”。
# 在终端内输入 <code>start.bat</code> 或在 Powershell 输入 <code>.\start.bat</code> 来启动机器人。

: '''Linux'''
# 在终端内设置 <code>start</code> 脚本的执行权限：<code>chmod +x start</code>
# 启动脚本：<code>./start</code>

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

运行控制台：

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

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

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

=== Docker 镜像搭建 ===
请在终端内运行以下命令启用机器人：
<syntaxhighlight lang="sh">
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
</syntaxhighlight>

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

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

{{Navbox dev}}