本文将会指导你如何搭建你自己的小可机器人。
搭建机器人需要计算机等相关知识有一定的了解，若在阅读或搭建过程中感到困惑，请善于使用搜索引擎。
使用每晚构建（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 文件夹，然后开始配置所需的配置项。
在第一次启动时，命令行将会弹出如下提示：
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 镜像搭建，请在此处下载配置文件模板，然后解压并进行配置。
在配置文件中填入必要的配置项后，请删除所有未使用的配置项，否则机器人无法正常运行。
使用每晚构建（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
配置项目
config.toml 内存储了机器人所有的配置项。其中在 secret 表中储存的配置项为私有内容，例如 API 密钥等，当机器人发送的消息中存在这些内容时会被自动拦截，请将私密内容填写到此部分。在 config 表中一般是一些模块设定的常量等内容，请不要在这个文件里面填写私密信息，防止意外泄露。
除此之外，还存在着若干以bot_为开头的文件，这些文件中包含了一些平台端的独有配置，若需要配置相关平台，请留意里面的内容。
数据库
机器人需要一个数据库以用于存储用户数据。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 可能会遇到极少数的锁表问题，或在误删文件未备份时数据丢失。
内容安全
机器人集成了阿里云内容安全服务，用于检查 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 官方机器人无需担心风控问题，但出于隐私考虑，QQ 官方对机器人能力有严格限制，包括但不限于：获取用户 QQ 号、昵称，非 @ 消息响应，URL 消息推送，主动消息推送等。
配置机器人
要通过 QQ 官方机器人在 QQ 平台连接机器人，你需要建立好一个机器人应用。
请前往 QQ 开放平台，实名注册后，按照要求创建一个机器人应用。
进入机器人管理后台，点击侧边栏“开发设置”，在“IP 白名单”栏中填写机器人所在服务器的公网 IP。
上滑可以得到机器人 ID 与密钥。将机器人 ID 复制后，填写到配置文件 bot_qqbot.toml 的 qq_bot_appid 配置项中。
随后点击机器人密钥后的“生成”，确认后点击“复制”复制 Token。将复制的 Token 填写到配置文件 bot_qqbot.toml 的 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 平台连接机器人，你需要建立好一个应用。
请前往并登录 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 配置项中。
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_aiogram.toml 的 telegram_token 配置项中。
proxy 配置项中填写代理服务地址。填写完毕后，请在 bot_aiogram.toml 配置文件中的 enable 选项设置为 true 以启用此平台端。
KOOK
要在 KOOK（开黑啦）平台连接机器人，你需要建立好一个应用。
请前往并登录 KOOK 开发者平台，点击“创建应用”，按照要求填写应用名字并确认创建。
完成后，点击侧边导航栏“机器人”，在“Token”下找到 Token 并复制。将复制的 Token 填写到配置文件 bot_kook.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.toml 的 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 填写到配置文件 bot_matrix.toml 的 matrix_device_id 配置项中，复制的 Token 填写到配置文件 bot_matrix.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.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。
| 技术性 | ||
|---|---|---|
| 部署 | ||
| 使用 | ||
| 开发 | ||