本文将会指导你如何搭建你自己的小可机器人。
搭建机器人需要计算机等相关知识有一定的了解，若在阅读或搭建过程中感到困惑，请善于使用搜索引擎。
使用每晚构建（Nightly Build）二进制文件搭建
请在 Github 上登录账户，然后在此处点击最新的（第一个）构建版本，然后下载对应你使用的平台的 Artifacts，然后解压即可。后续请按照下文的设置配置章节进行。
使用源代码搭建
安装 Python 环境
请前往 Python 官网 下载 Python 3.12 及以上版本，低于此版本将不再受到支持。
获取源代码
使用 Git 克隆
请在需要放置小可的文件目录下打开终端，并输入以下命令：
git clone https://github.com/Teahouse-studios/akari-bot.git
直接下载
请前往此处下载 Master 分支的源代码。由于无法保证 Release 版本的稳定性，我们不再提供 Release 版本的下载。
~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文件夹中，进行配置即可。）
当机器人检测到配置文件不存在时，将会弹出配置向导以生成配置文件。
使用源代码搭建
根据系统不同，用以下方法即可启动机器人：
- Windows
不推荐双击运行 start.bat 来启动机器人程序。
建议使用终端或 Powershell 运行：
- 在机器人根目录下，按下 Shift + 右键来打开右键菜单。
- 选择“在此处打开 Powershell 窗口”或“在此处打开命令窗口”。
- 在终端内输入
start.bat或在 Powershell 输入.\start.bat来启动机器人。
- Linux/MacOS
- 在终端内设置
start脚本的执行权限：chmod +x start - 启动脚本：
./start
进入 config 文件夹，然后开始配置所需的配置项。
当第一次启动后，命令行将会弹出如下提示：
Hello, it seems you are first time to run Akari-bot, 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 镜像搭建，请在此处下载配置文件模板，然后解压并进行配置。
在配置文件中填入必要的配置项后，请删除所有未使用的配置项，否则机器人无法正常运行。
使用每晚构建（Nightly Build）二进制文件搭建
根据系统不同，用以下方法即可启动机器人：
- Windows
不推荐双击运行 bot.exe 来启动机器人程序。
建议使用终端或 Powershell 运行：
- 在机器人根目录下，按下 Shift + 右键来打开右键菜单。
- 选择“在此处打开 Powershell 窗口”或“在此处打开命令窗口”。
- 在终端内输入
bot.exe或在 Powershell 输入.\bot.exe来启动机器人。 - 启动后可能会提示是否允许 launcher.exe 程序访问网络，请选择允许。
- Linux/MacOS
- 在终端内设置
bot.bin和launcher.bin的执行权限：chmod +x bot.bin launcher.bin - 启动二进制程序：
./bot.bin
配置项目
在 secret.toml 及以这个名字为后缀的文件储存的配置项为私有内容，例如 API 密钥等，当机器人发送的消息中存在这些内容时会被自动拦截，请将私密信息填写到此部分。
config.toml 内存储的一般是一些模块设定的常量等内容，同时请不要在这个文件里面填写私密内容，以防止内容意外泄露。
除此之外，还存在着若干以bot_为开头的文件，这些文件中包含了一些特定平台机器人的独有配置（如Discord 和 Telegram 机器人的 secret token 等），若需要配置相关机器人，请留意里面的内容。
关于配置项的详细信息，参见配置文件。
数据库
位于：config.toml
机器人需要一个数据库以用于存储用户数据。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 可能会遇到极少数的锁表问题，或在误删文件未备份时数据丢失。
内容安全
请填写在：secret.toml
机器人集成了阿里云内容安全服务，用于检查 QQ 和 KOOK 平台下的消息安全。
如有需求，请前往阿里云进行开通并获取 AccessKeyID 及 AccessKeySecret，并在配置文件中填写相关配置项。
check_access_key_id =- 填写获取的 AccessKeyID。check_access_key_secret =- 填写获取的 AccessKeySecret。
WebRender
请填写在：secret.toml
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 官方机器人（WIP）
QQ 官方现已开放机器人功能，可进入 QQ 开放平台进行申请。
目前，QQ 官方机器人已开放个人开发者使用权限，包括频道与群聊机器人。
QQ 官方机器人无需担心风控问题，但出于隐私考虑，QQ 官方对机器人能力有严格限制，包括但不限于：获取用户 QQ 号、昵称，非 @ 消息响应，URL 消息推送，主动消息推送等。
配置机器人
要通过 QQ 官方机器人在 QQ 平台连接机器人，你需要建立好一个机器人应用。
请前往 QQ 开放平台，实名注册后，按照要求创建一个机器人应用。
进入机器人管理后台，点击侧边栏“开发设置”，在“IP 白名单”栏中填写机器人所在服务器的公网 IP。
上滑可以得到机器人 ID 与密钥。将机器人 ID 复制后，填写到配置文件 bot_ntqq.toml 的 qq_bot_appid 配置项中。
随后点击机器人密钥后的“生成”，确认后点击“复制”复制 Token。将复制的 Token 填写到配置文件 bot_ntqq_secret.toml 的 qq_bot_secret 配置项中。
请在机器人配置文件 bot_ntqq.toml 和 bot_ntqq_secret.toml 填写以下配置项：
qq_bot_appid =- 机器人的 AppID。qq_bot_secret =- 机器人的 AppSecret。qq_bot_private = False- 设置机器人是否为私域机器人。
填写完毕后，请在 bot_ntqq.toml 配置文件中 将 enable 选项设置为 true 以启用机器人。
指令配置
点击侧边栏“发布设置”，点击“功能配置”目录右侧“配置”与“指令”选项卡。
点击“添加指令”或“重新配置”（如果之前已设置）按钮，点击“+”按钮可添加新的指令页。
进入对应的指令页，在“指令名”中填写模块名称，“指令介绍”中填写模块简介。在“使用场景”栏中可选中所有场景，具体可在沙箱场景中测试模块是否良好运行。
配置完成后，点击“保存配置”并确认即可。
机器人上线
点击侧边栏“使用范围与人员”，点击“编辑”按钮，将所有情况选择为“全部”后点击确认。
配置完成后，点击“发布设置”，按要求填写并上传“自测报告”与“隐私协议”。
点击“提交审核”按钮后，等待 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 填写到配置文件 bot_discord_secret.toml 的 discord_token 配置项中。
proxy 配置项中填写代理服务地址。如果你想把机器人邀请到服务器中，需要在侧边栏“Installation”选项卡中的“Authorization Methods”选项中勾选 Guild Install。
要申请用于邀请机器人到 Discord 服务器的链接，请前往侧边导航栏“OAuth2”下方的子目录“URL Generator”，在“Scopes”中选择 Bot 后在下方“Bot Permissions”中选择你希望机器人拥有的权限。完成后复制下方生成的 URL，复制到浏览器打开。
若你不确定具体应该添加哪些权限，可直接添加
Administrator（管理员）权限。填写完毕后，请在 bot_discord.toml 配置文件中 将 enable 选项设置为 true 以启用机器人。
Telegram
要在 Telegram 平台连接机器人，你需要建立好一个机器人账户。
请在 Telegram 私信 @BotFather，输入命令 /start 后使用 /newbot 按照要求创建一个机器人账号。
/newbot 命令下需完成两个步骤：
- 输入机器人的显示名称
- 输入机器人的账号名称（需以“bot”结尾）
完成后，@BotFather 会发送一条含有 Token 的消息。将复制的 Token 填写到配置文件 bot_telegram_secret.toml 的 telegram_token 配置项中。
proxy 配置项中填写代理服务地址。填写完毕后，请在 bot_telegram.toml 配置文件中 将 enable 选项设置为 true 以启用机器人。
KOOK
要在 KOOK（开黑啦）平台连接机器人，你需要建立好一个应用。
请前往并登录 KOOK 开发者平台，点击“创建应用”，按照要求填写应用名字并确认创建。
完成后，点击侧边导航栏“机器人”，在“Token”下找到 Token 并复制。将复制的 Token 填写到配置文件 bot_kook_secret.toml 的 kook_token 配置项中。
要申请用于邀请机器人到 KOOK 服务器的链接，请前往侧边导航栏“机器人”下方的子目录“邀请链接”，选择你希望机器人拥有的权限。完成后复制下方生成的 URL，复制到浏览器打开。
若你不确定具体应该添加哪些权限，可直接添加
管理员 权限。填写完毕后，请在 bot_kook.toml 配置文件中 将 enable 选项设置为 true 以启用机器人。
Matrix
要在 Matrix 平台连接机器人，你需要注册一个机器人账号。
请前往 Element，按照要求填写注册信息以建立一个账号。你可以自定义机器人账号托管的家服务器，建议使用官方的 https://matrix.org 家服务器。
若使用客户端获取会话 ID 和 Access Token：
点击头像，选择“Security & Privacy”，复制“Session ID”后的字符串。将复制的 ID 填写到配置文件 bot_matrix_secret.toml 的 matrix_device_id 配置项中。
选择“Help & About”，点击“Advanced”下的“Access Token”，复制展开的 Token，将复制的 Token 填写到配置文件 bot_matrix_secret.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 填写到配置文件 bot_matrix_secret.toml 的 matrix_device_id 配置项中，复制的 Token 填写到配置文件 bot_matrix_secret.toml 的 matrix_token 配置项中。
请在配置文件 bot_matrix.toml 填写以下其他配置项：
matrix_homeserver =- 机器人账号使用的 Matrix 家服务器 URL。matrix_user =- 机器人的完全限定用户 ID（包括@与:）。matrix_device_name =- 机器人的设备名称。（可选）
proxy 配置项中填写代理服务地址。填写完毕后，请在 bot_matrix.toml 配置文件中 将 enable 选项设置为 true 以启用机器人。
E2E 加密
目前，由于 libolm 在一些情况下需要手动配置，机器人默认没有启用端对端（E2E）加密支持。
若要启用 E2E 加密支持，请在终端执行以下命令：
- 使用 Poetry：
poetry run -- pip3 install matrix-nio[e2e]
- 使用 pip：
pip3 install matrix-nio[e2e]
请在配置文件 bot_matrix_secret.toml 填写以下配置项：
matrix_megolm_backup_passphrase =- 填写机器人的 megolm 备份密码短语。（可选）- 建议使用随机的长密码，不填写则不会导出 megolm 备份。
如果需要导入 megolm 备份，请将备份文件放置在 matrix_store/megolm_backup/restore.txt 下，并将密码短语写入 matrix_store/megolm_backup/restore-passphrase.txt。
控制台
控制台中包括了一个基础的运行环境，可以在控制台内使用命令进行基本的机器人交互。
- 在机器人根目录下打开终端。
- 在终端内使用
poetry shell切换 Poetry 的虚拟环境来调用先前安装的依赖。（可选） - 在终端内运行
python console.py以启动控制台。
Docker 镜像搭建
请在终端内运行以下命令启用机器人：
docker run \
> -d \
> -v /path/to/config:/akari-bot/config \ # 请将路径修改成对应的位置
> -p 11451:11451 \ # 反向 WebSocket 服务器端口，请根据配置文件更改
> -p 3306:3306 \ # 用于对接 MySQL 数据库（可选）
> --name akari-bot \ # 指定容器名称
> dorowolf/akari-bot
如果终端中返回了 long_tag 类型的容器 ID，证明容器已成功创建。
在终端内运行 docker logs akari-bot 可以查看机器人日志。此处的 akari-bot 为容器名，若你忘记定义容器名，可以替换为容器 ID。
| 技术性 | ||
|---|---|---|
| 部署 | ||
| 使用 | ||
| 开发 | ||