From 414f98fb5e83d221fee8fa0dff16028456ca3f0b Mon Sep 17 00:00:00 2001 From: Soulter <905617992@qq.com> Date: Mon, 16 Mar 2026 11:41:25 +0800 Subject: [PATCH] perf: onebot, satori docs improvement --- docs/.vitepress/config.mjs | 10 +- docs/zh/platform/aiocqhttp.md | 43 ++++++++ docs/zh/platform/aiocqhttp/lagrange.md | 61 ----------- docs/zh/platform/aiocqhttp/napcat.md | 134 ------------------------- docs/zh/platform/aiocqhttp/others.md | 1 - docs/zh/platform/satori/guide.md | 32 ++++++ docs/zh/platform/satori/llonebot.md | 78 -------------- 7 files changed, 77 insertions(+), 282 deletions(-) create mode 100644 docs/zh/platform/aiocqhttp.md delete mode 100644 docs/zh/platform/aiocqhttp/lagrange.md delete mode 100644 docs/zh/platform/aiocqhttp/napcat.md delete mode 100644 docs/zh/platform/aiocqhttp/others.md create mode 100644 docs/zh/platform/satori/guide.md delete mode 100644 docs/zh/platform/satori/llonebot.md diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index aad7a7027..ea96183ea 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -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" }, ], }, diff --git a/docs/zh/platform/aiocqhttp.md b/docs/zh/platform/aiocqhttp.md new file mode 100644 index 000000000..a13fc4a89 --- /dev/null +++ b/docs/zh/platform/aiocqhttp.md @@ -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)://:6199/ws`。 + +## 3. 验证 + +前往 AstrBot WebUI `控制台`，如果出现 ` aiocqhttp(OneBot v11) 适配器已连接。` 蓝色的日志，说明连接成功。如果没有，若干秒后出现` aiocqhttp 适配器已被关闭` 则为连接超时（失败），请检查配置是否正确。 \ No newline at end of file diff --git a/docs/zh/platform/aiocqhttp/lagrange.md b/docs/zh/platform/aiocqhttp/lagrange.md deleted file mode 100644 index bf2ddc286..000000000 --- a/docs/zh/platform/aiocqhttp/lagrange.md +++ /dev/null @@ -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`。 diff --git a/docs/zh/platform/aiocqhttp/napcat.md b/docs/zh/platform/aiocqhttp/napcat.md deleted file mode 100644 index 042748dc4..000000000 --- a/docs/zh/platform/aiocqhttp/napcat.md +++ /dev/null @@ -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 才需填写。 - -图例：（最快只需要点击启用，然后保存即可） - -xinjianya - - -点击 `保存`。 - -### 配置管理员 - -填写完毕后，进入 `配置文件` 页，点击 `平台配置` 选项卡，找到 `管理员 ID`，填写你的账号（不是机器人的账号）。 - -切记点击右下角 `保存`，AstrBot 重启并会应用配置。 - -### 在 NapCat 中添加 WebSocket 客户端 - -切换回 NapCat 的管理面板，点击 `网络配置->新建->WebSockets客户端`。 - -jiaochenXJY - - -在新弹出的窗口中： - -- 勾选 `启用`。 -- `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` 以检查是否连接成功。 diff --git a/docs/zh/platform/aiocqhttp/others.md b/docs/zh/platform/aiocqhttp/others.md deleted file mode 100644 index fcce08327..000000000 --- a/docs/zh/platform/aiocqhttp/others.md +++ /dev/null @@ -1 +0,0 @@ -支持接入所有适配了 OneBotv11 反向 Websockets（AstrBot 做服务器端） 的机器人协议端。 \ No newline at end of file diff --git a/docs/zh/platform/satori/guide.md b/docs/zh/platform/satori/guide.md new file mode 100644 index 000000000..c60380de9 --- /dev/null +++ b/docs/zh/platform/satori/guide.md @@ -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)：根据协议端配置情况选择填写 + +点击 `保存`。 diff --git a/docs/zh/platform/satori/llonebot.md b/docs/zh/platform/satori/llonebot.md deleted file mode 100644 index 994c5de97..000000000 --- a/docs/zh/platform/satori/llonebot.md +++ /dev/null @@ -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 默认地址为： - ---- - -在WebUI的配置界面侧边，选择【Satori】选项卡，进行如下配置： - -1. 确认【启用 Satori 协议】配置项已开启 -2. 端口默认为 5600（如需修改请记住新端口） -3. 如有必要，可填写【Satori Token】 -4. 点击右下角的【保存配置】 - -![image](https://files.astrbot.app/docs/source/images/satori/2025-10-10_15-52-32.png) - -## 在 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协议运行在其他端口，请根据实际情况修改对应的配置！ - -![image](https://files.astrbot.app/docs/source/images/satori/2025-10-10_16-10-54.png) - -点击右下角 `保存` 完成配置。 - -## 🎉 大功告成 - -此时，你的 AstrBot 应该已经通过 Satori 协议成功连接到 LLTwoBot。 - -在 QQ 中发送 `/help` 以检查是否连接成功。 - -如果成功回复，则配置成功。 - -## 常见问题 - -如果遇到连接问题，请检查： - -1. LLTwoBot 是否正常运行 -2. Satori 服务是否已启用 -3. 端口配置是否正确 -4. Token 是否匹配（如设置了 Token）