本文将会指导你如何搭建你自己的小可机器人。
搭建机器人需要计算机等相关知识有一定的了解,若在阅读或搭建过程中感到困惑,请善于使用搜索引擎。
使用每晚构建(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
文件夹,将配置文件 config.toml.example
重命名为 config.toml
,然后开始配置所需的配置项。
如果使用 Docker 镜像搭建,请前往机器人储存库或在此处下载 config.toml.example
配置文件,并将其重命名为 config.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 可能会遇到极少数的锁表问题,或在误删文件未备份时数据丢失。
内容安全
机器人集成了阿里云内容安全服务,用于检查 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。
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
配置项中。
proxy
配置项中填写代理服务地址。如果你想把机器人邀请到服务器中,需要在侧边栏“Installation”选项卡中的“Authorization Methods”选项中勾选 Guild Install
。
要申请用于邀请机器人到 Discord 服务器的链接,请前往侧边导航栏“OAuth2”下方的子目录“URL Generator”,在“Scopes”中选择 Bot
后在下方“Bot Permissions”中选择你希望机器人拥有的权限。完成后复制下方生成的 URL,复制到浏览器打开。
若你不确定具体应该添加哪些权限,可直接添加
Administrator
(管理员)权限。Telegram
要在 Telegram 平台连接机器人,你需要建立好一个机器人账户。
请在 Telegram 私信 @BotFather,输入命令 /start
后使用 /newbot
按照要求创建一个机器人账号。
/newbot
命令下需完成两个步骤:
- 输入机器人的显示名称
- 输入机器人的账号名称(需以“bot”结尾)
完成后,@BotFather 会发送一条含有 Token 的消息。将复制的 Token 填写到配置文件的 telegram_token
配置项中。
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
配置项中。
若使用 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 =
- 机器人的设备名称。(可选)
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 运行:
- 在机器人根目录下,按下 Shift + 右键来打开右键菜单。
- 选择“在此处打开 Powershell 窗口”或“在此处打开命令窗口”。
- 在终端内输入
bot.exe
或在 Powershell 输入.\bot.exe
来启动机器人。 - 启动后可能会提示是否允许 launcher.exe 程序访问网络,请选择允许。
- Linux/MacOS
- 在终端内设置
bot.bin
和launcher.bin
的执行权限:chmod +x bot.bin launcher.bin
- 启动二进制程序:
./bot.bin
使用源代码搭建
根据系统不同,用以下方法即可启动机器人:
- Windows
不推荐双击运行 start.bat
来启动机器人程序。
建议使用终端或 Powershell 运行:
- 在机器人根目录下,按下 Shift + 右键来打开右键菜单。
- 选择“在此处打开 Powershell 窗口”或“在此处打开命令窗口”。
- 在终端内输入
start.bat
或在 Powershell 输入.\start.bat
来启动机器人。
- Linux
- 在终端内设置
start
脚本的执行权限:chmod +x start
- 启动脚本:
./start
控制台
控制台中包括了一个基础的运行环境,可以在控制台内使用命令进行基本的机器人交互。
运行控制台:
在机器人根目录下打开终端。
在终端内使用 poetry shell
切换 Poetry 的虚拟环境来调用先前安装的依赖。(可选)
在终端内运行 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。
开发 | ||
---|---|---|
部署 | ||
使用 | ||
技术性 |