perf: onebot, satori docs improvement
This commit is contained in:
Soulter
@@ -87,13 +87,7 @@ export default defineConfig({
|
||||
},
|
||||
{
|
||||
text: "OneBot v11",
|
||||
base: "/platform/aiocqhttp",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: "NapCat", link: "/napcat" },
|
||||
{ text: "Lagrange", link: "/lagrange" },
|
||||
{ text: "其他端", link: "/others" },
|
||||
],
|
||||
link: "/aiocqhttp"
|
||||
},
|
||||
{ text: "企微应用", link: "/wecom" },
|
||||
{ text: "企微智能机器人", link: "/wecom_ai_bot" },
|
||||
@@ -111,7 +105,7 @@ export default defineConfig({
|
||||
base: "/platform/satori",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: "使用 LLOneBot", link: "/llonebot" },
|
||||
{ text: "接入 Satori", link: "/guide" },
|
||||
{ text: "使用 server-satori", link: "/server-satori" },
|
||||
],
|
||||
},
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# 接入 OneBot v11 协议实现
|
||||
|
||||
OneBot 是一个聊天机器人应用接口标准，旨在统一不同聊天平台上的机器人应用开发接口，使开发者只需编写一次业务逻辑代码即可应用到多种机器人平台。
|
||||
|
||||
AstrBot 支持接入所有适配了 OneBotv11 反向 Websockets（AstrBot 做服务器端）的机器人协议端。
|
||||
|
||||
下文给出一些常见的 OneBot v11 协议实现端项目。
|
||||
|
||||
- [NapCat](https://github.com/NapNeko/NapCatQQ)
|
||||
- [OneDisc](https://github.com/ITCraftDevelopmentTeam/OneDisc)
|
||||
- [Tele-KiraLink](https://github.com/Echomirix/Tele-KiraLink)
|
||||
|
||||
请参阅对应的协议实现端项目的部署文档。
|
||||
|
||||
## 1. 配置 OneBot v11
|
||||
|
||||
1. 进入 AstrBot 的 WebUI
|
||||
2. 点击左边栏 `机器人`
|
||||
3. 然后在右边的界面中，点击 `+ 创建机器人`
|
||||
4. 选择 `OneBot v11`
|
||||
|
||||
在出现的表单中，填写：
|
||||
|
||||
- ID(id)：随意填写，仅用于区分不同的消息平台实例。
|
||||
- 启用(enable): 勾选。
|
||||
- 反向 WebSocket 主机地址：请填写你的机器的 IP 地址，一般情况下请直接填写 `0.0.0.0`
|
||||
- 反向 WebSocket 端口：填写一个端口，默认为 `6199`。
|
||||
- 反向 Websocket Token：只有当 NapCat 网络配置中配置了 token 才需填写。
|
||||
|
||||
点击 `保存`。
|
||||
|
||||
## 2. 配置协议实现端
|
||||
|
||||
请参阅对应的协议实现端项目的部署文档。
|
||||
|
||||
一些注意点：
|
||||
|
||||
1. 协议实现端需要支持 `反向 WebSocket` 实现，及 AstrBot 端作为服务端，实现端作为客户端。
|
||||
2. `反向 WebSocket` 的 URL 为 `ws(s)://<your-host>:6199/ws`。
|
||||
|
||||
## 3. 验证
|
||||
|
||||
前往 AstrBot WebUI `控制台`，如果出现 ` aiocqhttp(OneBot v11) 适配器已连接。` 蓝色的日志，说明连接成功。如果没有，若干秒后出现` aiocqhttp 适配器已被关闭` 则为连接超时（失败），请检查配置是否正确。
|
||||
@@ -1,61 +0,0 @@
|
||||
# 接入 Lagrange
|
||||
|
||||
> [!TIP]
|
||||
>
|
||||
> - 请合理控制使用频率。过于频繁地发送消息可能会被判定为异常行为，增加触发风控机制的风险。
|
||||
> - 本项目严禁用于任何违反法律法规的用途。若您意图将 AstrBot 应用于非法产业或活动，我们**明确反对并拒绝**您使用本项目。
|
||||
> - 最新的部署方式请以 [Lagrange Doc](https://lagrangedev.github.io/Lagrange.Doc/Lagrange.OneBot/Config/#%E4%B8%8B%E8%BD%BD%E5%AE%89%E8%A3%85) 为准。
|
||||
|
||||
## 下载
|
||||
|
||||
从 [GitHub Release](https://github.com/LagrangeDev/Lagrange.Core/releases) 下载最新版的 `Lagrange.OneBot`。
|
||||
|
||||
对于 Windows 设备，请下载 `Lagrange.OneBot_win-x64_xxxx` 压缩包。
|
||||
|
||||
对于 X86 的 Linux 用户，下载 `Lagrange.OneBot_linux-x64_xxx` 压缩包。
|
||||
|
||||
对于 Arm 的 Linux 用户，下载 `Lagrange.OneBot_linux-arm64_xxx` 压缩包。
|
||||
|
||||
对于 M 芯片 Mac 用户，下载 `Lagrange.OneBot_osx-arm64_xxx` 压缩包。
|
||||
|
||||
对于 Intel 芯片 Mac 用户，下载 `Lagrange.OneBot_osx-x64_xxx` 压缩包。
|
||||
|
||||
## 部署
|
||||
|
||||
请参阅 [Lagrange Doc](https://lagrangedev.github.io/Lagrange.Doc/Lagrange.OneBot/Config/#%E8%BF%90%E8%A1%8C)。
|
||||
|
||||
运行完成后，请修改 [配置文件](https://lagrangedev.github.io/Lagrange.Doc/Lagrange.OneBot/Config/#%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6)，
|
||||
|
||||
在 `Implementations` 字段下添加：
|
||||
|
||||
```json
|
||||
{
|
||||
"Type": "ReverseWebSocket",
|
||||
"Host": "127.0.0.1",
|
||||
"Port": 6199,
|
||||
"Suffix": "/ws",
|
||||
"ReconnectInterval": 5000,
|
||||
"HeartBeatInterval": 5000,
|
||||
"AccessToken": ""
|
||||
}
|
||||
```
|
||||
|
||||
一定要保证 `Suffix` 为 `/ws`。
|
||||
|
||||
## 连接到 AstrBot
|
||||
|
||||
### 配置 aiocqhttp
|
||||
|
||||
1. 进入 AstrBot 的管理面板
|
||||
2. 点击左边栏 `机器人`
|
||||
3. 然后在右边的界面中，点击 `+ 创建机器人`
|
||||
4. 选择 `aiocqhttp(OneBotv11)`
|
||||
|
||||
弹出的配置项填写：
|
||||
|
||||
配置项填写：
|
||||
|
||||
- ID(id)：随意填写，用于区分不同的消息平台实例。
|
||||
- 启用(enable): 勾选。
|
||||
- 反向 WebSocket 主机地址：请填写你的机器的 IP 地址。一般情况下请直接填写 `0.0.0.0`
|
||||
- 反向 WebSocket 端口：填写一个端口，例如 `6199`。
|
||||
@@ -1,134 +0,0 @@
|
||||
# 使用 NapCat
|
||||
|
||||
> [!TIP]
|
||||
>
|
||||
> - 本项目严禁用于任何违反法律法规的用途。若您意图将 AstrBot 应用于非法产业或活动，我们**明确反对并拒绝**您使用本项目。
|
||||
> - AstrBot 通过 `aiocqhttp` 适配器接入 OneBot v11 协议。OneBot v11 协议是一个开放的通信协议，并不代表任何具体的软件或服务。
|
||||
|
||||
NapCat 的 GitHub 仓库：[NapCat](https://github.com/NapNeko/NapCatQQ)
|
||||
NapCat 的文档：[NapCat 文档](https://napcat.napneko.icu/)
|
||||
|
||||
NapCat 提供了大量的部署方式，包括 Docker、Windows 一键安装包等等。
|
||||
|
||||
## 通过一键脚本部署
|
||||
|
||||
推荐采用这种方式部署。
|
||||
|
||||
### Windows
|
||||
|
||||
看这篇文章：[NapCat.Shell - Win手动启动教程](https://napneko.github.io/guide/boot/Shell#napcat-shell-win%E6%89%8B%E5%8A%A8%E5%90%AF%E5%8A%A8%E6%95%99%E7%A8%8B)
|
||||
|
||||
### Linux
|
||||
|
||||
看这篇文章：[NapCat.Installer - Linux一键使用脚本(支持Ubuntu 20+/Debian 10+/Centos9)](https://napneko.github.io/guide/boot/Shell#napcat-installer-linux%E4%B8%80%E9%94%AE%E4%BD%BF%E7%94%A8%E8%84%9A%E6%9C%AC-%E6%94%AF%E6%8C%81ubuntu-20-debian-10-centos9)
|
||||
|
||||
> [!TIP]
|
||||
> **Napcat WebUI 在哪打开**：
|
||||
> 在 napcat 的日志里会显示 WebUI 链接。
|
||||
>
|
||||
> 如果是 linux 命令行一键部署的napcat：`docker log <账号>`。
|
||||
>
|
||||
> Docker部署的 NapCat：`docker logs napcat`。
|
||||
|
||||
## 通过 Docker Compose 部署
|
||||
|
||||
1. 下载或复制 [astrbot.yml](https://github.com/NapNeko/NapCat-Docker/blob/main/compose/astrbot.yml) 内容
|
||||
2. 将刚刚下载的文件重命名为 `astrbot.yml`
|
||||
3. 编辑 `astrbot.yml`，将 `# - "6199:6199"` 修改为 `- "6199:6199"`，移除开头的 `#`
|
||||
4. 在 `astrbot.yml` 文件所在目录执行:
|
||||
|
||||
```bash
|
||||
NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker compose -f ./astrbot.yml up -d
|
||||
```
|
||||
|
||||
## 通过 Docker 部署
|
||||
|
||||
此教程默认您安装了 Docker。
|
||||
|
||||
在终端执行以下命令即可一键部署。
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-e NAPCAT_GID=$(id -g) \
|
||||
-e NAPCAT_UID=$(id -u) \
|
||||
-p 3000:3000 \
|
||||
-p 3001:3001 \
|
||||
-p 6099:6099 \
|
||||
--name napcat \
|
||||
--restart=always \
|
||||
mlikiowa/napcat-docker:latest
|
||||
```
|
||||
|
||||
执行成功后，需要查看日志以得到登录二维码和管理面板的 URL。
|
||||
|
||||
```bash
|
||||
docker logs napcat
|
||||
```
|
||||
|
||||
请复制管理面板的 URL，然后在浏览器中打开备用。
|
||||
|
||||
然后使用你要登录的账号扫描出现的二维码，即可登录。
|
||||
|
||||
如果登录阶段没有出现问题，即成功部署。
|
||||
|
||||
## 连接到 AstrBot
|
||||
|
||||
## 在 AstrBot 配置 aiocqhttp
|
||||
|
||||
1. 进入 AstrBot 的管理面板
|
||||
2. 点击左边栏 `机器人`
|
||||
3. 然后在右边的界面中，点击 `+ 创建机器人`
|
||||
4. 选择 `OneBot v11`
|
||||
|
||||
弹出的配置项填写：
|
||||
- ID(id)：随意填写，仅用于区分不同的消息平台实例。
|
||||
- 启用(enable): 勾选。
|
||||
- 反向 WebSocket 主机地址：请填写你的机器的 IP 地址，一般情况下请直接填写 `0.0.0.0`
|
||||
- 反向 WebSocket 端口：填写一个端口，默认为 `6199`。
|
||||
- 反向 Websocket Token：只有当 NapCat 网络配置中配置了 token 才需填写。
|
||||
|
||||
图例：（最快只需要点击启用，然后保存即可）
|
||||
|
||||
<img width="818" height="799" alt="xinjianya" src="https://github.com/user-attachments/assets/813ac338-2fd7-4add-bde4-8b0f6d0bda95" />
|
||||
|
||||
|
||||
点击 `保存`。
|
||||
|
||||
### 配置管理员
|
||||
|
||||
填写完毕后，进入 `配置文件` 页，点击 `平台配置` 选项卡，找到 `管理员 ID`，填写你的账号（不是机器人的账号）。
|
||||
|
||||
切记点击右下角 `保存`，AstrBot 重启并会应用配置。
|
||||
|
||||
### 在 NapCat 中添加 WebSocket 客户端
|
||||
|
||||
切换回 NapCat 的管理面板，点击 `网络配置->新建->WebSockets客户端`。
|
||||
|
||||
<img width="649" height="751" alt="jiaochenXJY" src="https://github.com/user-attachments/assets/5044f96a-a81f-407a-a3b1-0c518499eda4" />
|
||||
|
||||
|
||||
在新弹出的窗口中：
|
||||
|
||||
- 勾选 `启用`。
|
||||
- `URL` 填写 `ws://宿主机IP:端口/ws`。如 `ws://localhost:6199/ws` 或 `ws://127.0.0.1:6199/ws`。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 1. 如果采用 Docker 部署并同时把 AstrBot 和 NapCat 两个容器接入了同一网络，`ws://astrbot:6199/ws`（参考本文档的 Docker 脚本）。
|
||||
> 2. 由于 Docker 网络隔离的原因，不在同一个网络时请使用内网 IP 地址或公网 IP 地址 ***（不安全）*** 进行连接，即 `ws://(内网/公网):6199/ws`。
|
||||
|
||||
- 消息格式：`Array`
|
||||
- 心跳间隔: `5000`
|
||||
- 重连间隔: `5000`
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> 1. 切记后面加一个 `/ws`!
|
||||
> 2. 这里的 IP 不能填为 `0.0.0.0`
|
||||
|
||||
点击 `保存`。
|
||||
|
||||
前往 AstrBot WebUI `控制台`，如果出现 ` aiocqhttp(OneBot v11) 适配器已连接。` 蓝色的日志，说明连接成功。如果没有，若干秒后出现` aiocqhttp 适配器已被关闭` 则为连接超时（失败），请检查配置是否正确。
|
||||
|
||||
## 🎉 大功告成
|
||||
|
||||
此时，你的 AstrBot 和 NapCat 应该已经连接成功！使用 `私聊` 的方式对机器人发送 `/help` 以检查是否连接成功。
|
||||
@@ -1 +0,0 @@
|
||||
支持接入所有适配了 OneBotv11 反向 Websockets（AstrBot 做服务器端） 的机器人协议端。
|
||||
@@ -0,0 +1,32 @@
|
||||
# 接入 Satori 协议
|
||||
|
||||
## Satori 协议简介
|
||||
|
||||
> 摘录自：https://satori.chat/zh-CN/introduction.html
|
||||
|
||||
Satori 是一个通用的聊天协议。Satori 协议希望能够抹平不同聊天平台之间的差异，让开发者以更低的成本开发出跨平台、可扩展、高性能的聊天应用。
|
||||
|
||||
Satori 的名称来源于游戏东方 Project 中的角色 [古明地觉 (Komeiji Satori)](https://zh.touhouwiki.net/wiki/%E5%8F%A4%E6%98%8E%E5%9C%B0%E8%A7%89)。古明地觉能够以心灵感应的方式与各种动物交流，取这个名字是希望 Satori 能够成为各个聊天平台之间的桥梁。
|
||||
|
||||
Satori 的开发团队长期从事聊天机器人开发，熟悉各种聊天平台的通信方式。经过长达 4 年的发展，Satori 有了健全的设计和完善的实现。目前，Satori 官方提供了超过 15 个聊天平台的适配器，完全覆盖了世界上主流的聊天平台，如 QQ、Discord、企业微信、KOOK 等等。
|
||||
|
||||
## 1. 配置协议实现端
|
||||
|
||||
请参阅对应的协议实现端项目的部署文档。
|
||||
|
||||
## 2. 配置 Satori 协议
|
||||
|
||||
1. 进入 AstrBot 的 WebUI
|
||||
2. 点击左边栏 `机器人`
|
||||
3. 然后在右边的界面中，点击 `+ 创建机器人`
|
||||
4. 选择 `Satori`
|
||||
|
||||
弹出的配置项填写：
|
||||
|
||||
- 机器人名称 (id): `satori` (随意)
|
||||
- 启用 (enable): 勾选
|
||||
- Satori API 终结点 (satori_api_base_url)：`http://localhost:5600/v1`（端口和上面配置的协议端端口一致）
|
||||
- Satori WebSocket 终结点 (satori_endpoint)：`ws://localhost:5600/v1/events`（端口和上面配置的协议端端口一致）
|
||||
- Satori 令牌 (satori_token)：根据协议端配置情况选择填写
|
||||
|
||||
点击 `保存`。
|
||||
@@ -1,78 +0,0 @@
|
||||
# 接入 LLTwoBot (Satori)
|
||||
|
||||
> [!TIP]
|
||||
> LLTwoBot 是一个基于 QQNT 的 Onebot v11、Satori 多协议实现端，可以让你在 QQ 平台使用 Satori 协议与 AstrBot 进行通信。
|
||||
|
||||
> [!TIP]
|
||||
>
|
||||
> - 请合理控制使用频率。过于频繁地发送消息可能会被判定为异常行为，增加触发风控机制的风险。
|
||||
> - 本项目严禁用于任何违反法律法规的用途。若您意图将 AstrBot 应用于非法产业或活动，我们**明确反对并拒绝**您使用本项目。
|
||||
|
||||
## 准备工作
|
||||
|
||||
请先参考 LLTwoBot 官方文档完成基础配置：
|
||||
[LLTwoBot 文档](https://llonebot.com/guide/getting-started)
|
||||
|
||||
完成文档中的步骤，确保你已经：
|
||||
|
||||
1. 下载并安装了 LLTwoBot
|
||||
2. 成功登录了 QQ 账号
|
||||
|
||||
## 配置 LLTwoBot 的 Satori 服务
|
||||
|
||||
在成功登录 QQ 后，先打开 LLTwoBot 的 WebUI 配置界面。
|
||||
> WebUI 默认地址为：<http://localhost:3080/>
|
||||
|
||||
---
|
||||
|
||||
在WebUI的配置界面侧边，选择【Satori】选项卡，进行如下配置：
|
||||
|
||||
1. 确认【启用 Satori 协议】配置项已开启
|
||||
2. 端口默认为 5600（如需修改请记住新端口）
|
||||
3. 如有必要，可填写【Satori Token】
|
||||
4. 点击右下角的【保存配置】
|
||||
|
||||
|
||||
|
||||
## 在 AstrBot 中配置 Satori 适配器
|
||||
|
||||
1. 进入 AstrBot 的管理面板
|
||||
2. 点击左边栏 `机器人`
|
||||
3. 然后在右边的界面中，点击 `+ 创建机器人`
|
||||
4. 选择 `satori`
|
||||
|
||||
弹出的配置项填写：
|
||||
|
||||
- 机器人名称 (id): `LLTwoBot`
|
||||
- 启用 (enable): 勾选
|
||||
- Satori API 终结点 (satori_api_base_url)：`http://localhost:5600/v1`
|
||||
- Satori WebSocket 终结点 (satori_endpoint)：`ws://localhost:5600/v1/events`
|
||||
- Satori 令牌 (satori_token)：根据 LLTwoBot 配置填写（如有设置）
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> - LLTwoBot 的 satori协议 默认在 `5600` 端口提供服务
|
||||
> - 因此完整的 URL 路径为 `http://localhost:5600/v1`
|
||||
>
|
||||
> 如果你的 satori协议运行在其他端口，请根据实际情况修改对应的配置！
|
||||
|
||||
|
||||
|
||||
点击右下角 `保存` 完成配置。
|
||||
|
||||
## 🎉 大功告成
|
||||
|
||||
此时，你的 AstrBot 应该已经通过 Satori 协议成功连接到 LLTwoBot。
|
||||
|
||||
在 QQ 中发送 `/help` 以检查是否连接成功。
|
||||
|
||||
如果成功回复，则配置成功。
|
||||
|
||||
## 常见问题
|
||||
|
||||
如果遇到连接问题，请检查：
|
||||
|
||||
1. LLTwoBot 是否正常运行
|
||||
2. Satori 服务是否已启用
|
||||
3. 端口配置是否正确
|
||||
4. Token 是否匹配（如设置了 Token）
|
||||
Reference in New Issue
Block a user