liuwei_x_x/abot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

重构MaiBot适配器为官方API Server长连接采集模式并补全Dashboard说明

Browse Source
This commit is contained in:
liuwei
2026-04-29 09:58:50 +08:00
parent d22e380c4e
commit a6f3eb9688
4 changed files with 871 additions and 513 deletions
Download Patch File Download Diff File Expand all files Collapse all files

219
plugins/maibot_adapter/DEPLOY_192.168.2.240.md
View File

@@ -1,91 +1,50 @@
# 192.168.2.240 部署 MaiBot 清单 # 192.168.2.240 上的 MaiBot 部署说明
这份文档用于把 `MaiBot` 部署到 `192.168.2.240`，供 `plugins/maibot_adapter` 调用。 这份文档记录当前 `MaiBot 官方镜像` 在 `192.168.2.240` 的实际部署状态，供 `plugins/maibot_adapter` 对接使用。
## 当前状态 ## 当前结论
我已经在 `abot` 里新增了 `maibot_adapter` 插件，但当前还没有这台服务器的 SSH 凭据。 1. `MaiBot` 使用官方镜像 `sengokucola/maibot:latest` 部署。
如果你把 SSH 用户名/密码，或者私钥登录方式给我，我就可以直接按这份清单远程执行。 2. 没有改动 MaiBot 源码，dashboard 通过官方 `maibot-dashboard==1.0.0` 静态资源挂载方式补齐。
3. `abot` 侧不再走 WebUI 聊天页，而是改走 `官方 API Server`。
4. 现在的推荐接入地址如下：
- WebUI / Dashboard：`http://192.168.2.240:18001/`
- WebUI Health：`http://192.168.2.240:18001/api/webui/health`
- 官方 API Server WS：`ws://192.168.2.240:18009/ws`
## 目标 ## 当前 docker-compose 关键点
部署完成后，`abot` 将使用以下接口访问 MaiBot： 容器名：
1. `POST /api/webui/auth/verify` ```text
2. `GET /api/webui/ws-token` maibot-core-lite
3. `WS /ws?token=...`
因此最终需要保证：
1. `http://192.168.2.240:8001/api/webui/health` 可访问
2. 你手里有一个可用的 `MaiBot WebUI token`
3. `plugins/maibot_adapter/config.toml` 中填入同一个 `server_url` 与 `access_token`
## 推荐部署方式
当前优先建议“宿主机 Python 直跑”：
1. 部署简单，方便先打通插件联调
2. 日志更容易直接看
3. 后面稳定后再考虑改成 Docker Compose
## 服务器执行步骤
以下命令默认按 Linux 服务器写。
### 1. 安装基础依赖
```bash
sudo apt update
sudo apt install -y git python3 python3-venv python3-pip
``` ```
### 2. 拉取 MaiBot 镜像：
```bash ```text
cd /opt sengokucola/maibot:latest
sudo git clone https://github.com/Mai-with-u/MaiBot.git
sudo chown -R $USER:$USER /opt/MaiBot
cd /opt/MaiBot
``` ```
### 3. 创建虚拟环境并安装依赖 核心端口映射：
```bash ```text
python3 -m venv .venv 18001 -> 8001 # WebUI / Dashboard / WebUI API
source .venv/bin/activate 18009 -> 8090 # 官方 API Server
python -m pip install --upgrade pip
pip install -e .
``` ```
如果 `pip install -e .` 遇到单个依赖下载慢，可以切换镜像源再执行。 ## Dashboard 访问地址
### 4. 首次启动 当前已经补全完成，可直接访问：
```bash ```text
source /opt/MaiBot/.venv/bin/activate http://192.168.2.240:18001/
cd /opt/MaiBot
python bot.py
``` ```
说明： 如果只想看健康状态：
1. `bot.py` 是 MaiBot 主入口 ```text
2. 首次启动时通常需要你按它自己的配置流程完成基础设置 http://192.168.2.240:18001/api/webui/health
3. WebUI 默认监听端口通常是 `8001`
### 5. 验证健康状态
本机执行：
```bash
curl http://127.0.0.1:8001/api/webui/health
```
局域网执行：
```bash
curl http://192.168.2.240:8001/api/webui/health
``` ```
期待返回： 期待返回：
@@ -94,87 +53,61 @@ curl http://192.168.2.240:8001/api/webui/health
{"status":"healthy","service":"MaiBot WebUI"} {"status":"healthy","service":"MaiBot WebUI"}
``` ```
### 6. 获取 WebUI token ## embedding 模型现状
这一步有两种方式： 当前远端已切到 Ollama 向量服务：
1. 按 MaiBot 首次配置流程，在 WebUI 中设置 token ```text
2. 如果已经有现成 token，直接记下来给 `maibot_adapter` 使用 ollama_base_url = "http://192.168.2.50:11434/v1"
embedding_model = "bge-m3:latest"
```
最终你需要把 token 填到： 这套配置已经验证可用，MaiBot 日志里能看到 embedding 维度识别成功。
`plugins/maibot_adapter/config.toml` ## 官方 API Server 接入方式
`maibot_adapter` 现在用的是官方 API Server 协议，不再使用：
1. `POST /api/webui/auth/verify`
2. `GET /api/webui/ws-token`
3. `WS /api/webui/ws?token=...`
现在实际使用的是：
1. `WS ws://192.168.2.240:18009/ws`
2. 握手头：
- `x-uuid`
- `x-apikey`
- `x-platform`
3. 消息包类型：
- `sys_std`
4. 负载结构：
- `APIMessageBase`
## abot 配置建议
当前 `plugins/maibot_adapter/config.toml` 推荐值：
```toml ```toml
server_url = "http://192.168.2.240:8001" [MaiBotAdapter]
access_token = "你的MaiBotToken" enable = true
collect_group_messages = true
collect_private_messages = true
enable_reply_output = true
reply_group_messages = true
reply_private_messages = true
respect_group_feature_switch = true
mention_user_on_group_reply = false
api_server_ws_url = "ws://192.168.2.240:18009/ws"
api_key = "abot-maibot"
platform_name = "abot-maibot"
``` ```
### 7. 建议做成 systemd 服务 ## 设计边界
创建 `/etc/systemd/system/maibot.service` 当前这套接法遵循你已经确认过的原则：
```ini 1. 消息默认发送给 MaiBot 做采集。
[Unit] 2. 是否真的回复，由开关和群功能权限控制。
Description=MaiBot Service 3. 不重新开发 MaiBot 对话/记忆本体能力。
After=network.target 4. 尽量把“参与聊天”的判断留在 MaiBot 侧，而不是在 abot 里再做一遍复杂前置策略。
[Service]
Type=simple
User=root
WorkingDirectory=/opt/MaiBot
ExecStart=/opt/MaiBot/.venv/bin/python /opt/MaiBot/bot.py
Restart=always
RestartSec=5
Environment=PYTHONUNBUFFERED=1
[Install]
WantedBy=multi-user.target
```
启用并启动：
```bash
sudo systemctl daemon-reload
sudo systemctl enable maibot
sudo systemctl start maibot
sudo systemctl status maibot
```
看日志：
```bash
sudo journalctl -u maibot -f
```
## 与 abot 对接
部署好后，回到 `abot`：
1. 编辑 `plugins/maibot_adapter/config.toml`
2. 填入：
- `server_url = "http://192.168.2.240:8001"`
- `access_token = "你的MaiBotToken"`
3. 重启 `abot` 或热加载插件
测试指令：
```text
麦麦 你好
```
或者在群里直接：
```text
@机器人 你好
```
## 备注
如果你后面希望：
1. `ai_auto_response` 也复用 MaiBot
2. 做自动插话而不是只做命令对话
3. 做会话长驻、减少每次重新认证和建连成本
下一步就可以把 `maibot_adapter` 再往“共享长连接 + 自动回复桥”方向升级。

61
plugins/maibot_adapter/README.md
View File

@@ -1,35 +1,50 @@
# MaiBot Adapter 插件 # MaiBot Adapter 插件
这个插件用于把外部独立部署的 `MaiBot WebUI` 对接到 `abot` 的插件体系里。 这个插件现在已经改成对接 `MaiBot 官方 API Server`，不再依赖 `WebUI 聊天页` 那套 token + ws-token + `/api/webui/ws` 流程。
## 当前能力 ## 当前能力
1. 支持命令触发： 1. 默认把 abot 收到的群聊/私聊消息旁路发送给 MaiBot，作为上下文与记忆输入。
- `麦麦 你好` 2. 默认不阻断其它插件链路，`ai_auto_response`、`Dify`、命令插件仍可继续照常处理。
- `maibot 你是谁` 3. 是否真的把 MaiBot 的回复发回微信，由 `enable_reply_output`、`reply_group_messages`、`reply_private_messages` 以及群功能开关共同控制。
2. 支持群聊里 `@机器人` 后把文本转发给 MaiBot。 4. 使用官方 API Server 协议：
3. 插件内部会自动执行： - WebSocket 握手头：`x-uuid` / `x-apikey` / `x-platform`
- `POST /api/webui/auth/verify` - 消息包类型：`sys_std`
- `GET /api/webui/ws-token` - 负载结构：`APIMessageBase`
- `WS /ws?token=...` 5. 支持把图片、语音、视频、位置、应用消息转换成文本占位符发给 MaiBot，方便它做长期上下文理解。
4. 每次消息会走一个独立的 WebSocket 逻辑会话，并等待 `bot_message` 事件作为最终回复。
## 配置说明 ## 推荐定位
这套插件更适合做两件事：
1. 让 MaiBot 成为 `ai_auto_response` 之外的一条“长期对话与记忆”能力链路。
2. 先把全量消息采集给 MaiBot，等效果稳定后，再逐步提高它的主动参与度。
## 配置重点
见 `config.toml`： 见 `config.toml`：
1. `server_url` 1. `api_server_ws_url`
- MaiBot WebUI 地址，例如 `http://192.168.2.240:8001` - 例如 `ws://192.168.2.240:18009/ws`
2. `access_token` 2. `api_key`
- MaiBot WebUI 登录 token - 用于官方 API Server 路由
3. `session_scope` 3. `enable_reply_output`
- `room`：同群共享语境 - 控制“MaiBot 能不能实际开口说话”
- `sender`：同群内每个用户独立语境 4. `respect_group_feature_switch`
- 控制群里是否还要继续受 abot 功能权限开关约束
## 部署建议 ## 现阶段建议
如果你后面要让 `ai_auto_response` 也改走 MaiBot，建议顺序如下： 如果你打算逐步替代 `ai_auto_response`，建议按这个顺序推进：
1. 先用这个插件验证 MaiBot 对话质量与延迟。 1. 先保持 `collect_group_messages=true`、`enable_reply_output=false`，只观察 MaiBot 记忆与理解效果。
2. 确认稳定后，再把 `ai_auto_response` 的“决策/生成”改成调用同一套桥接逻辑。 2. 然后打开 `enable_reply_output=true`，但先让少量测试群开启 `MAIBOT_CHAT` 功能权限。
3. 最后再决定是否完全下线 `ai_auto_response` 原本的 LLM 直连链路。 3. 确认稳定后，再决定是让 MaiBot 成为独立对话插件，还是进一步吸收进 `ai_auto_response` 主流程。
## Dashboard / WebUI
当前远端 `192.168.2.240` 已经补好官方 dashboard 静态资源，访问地址如下：
1. WebUI 首页：`http://192.168.2.240:18001/`
2. 健康检查：`http://192.168.2.240:18001/api/webui/health`
3. 官方 API Server WebSocket：`ws://192.168.2.240:18009/ws`

129
plugins/maibot_adapter/config.toml
View File

@@ -1,45 +1,104 @@
[MaiBotAdapter] [MaiBotAdapter]
enable = true enable = true
# 命令触发词： # 是否默认采集群消息到 MaiBot：
# 1. 不需要前缀，直接使用 “麦麦 你好” 这种形式即可； # 1. 这是“把消息送给 MaiBot 做上下文与记忆”的总开关；
# 2. 群聊里也支持 @机器人 后直接转发给 MaiBot； # 2. 关闭后，群消息不会再进入 MaiBot；
# 3. 如果你后面希望只保留自动插话入口，可以把命令缩减到一个内部调试词。 # 3. 这个开关只影响采集，不影响 MaiBot 已经生成中的历史任务。
commands = ["麦麦", "maibot", "mai"] collect_group_messages = true
command-tip = """
🤖MaiBot 对话指令：
麦麦 你好
"""
# 是否允许群聊里通过 @机器人 触发。 # 是否默认采集私聊消息到 MaiBot：
allow_group_at = true # 1. 打开后，私聊也会进入 MaiBot 的上下文链路；
# 2. 如果你暂时只想把 MaiBot 当群聊人格，就可以先关掉；
# 3. 当前按你的要求默认开启“全量采集”能力。
collect_private_messages = true
# MaiBot WebUI 服务根地址： # 是否允许把 MaiBot 的回复真正发回微信：
# 1. 不要带末尾斜杠； # 1. true 表示 MaiBot 不仅接收消息，也可以实际参与说话；
# 2. 插件会基于这个地址自动请求： # 2. false 表示只做上下文采集与记忆沉淀，不做回声输出；
# - /api/webui/auth/verify # 3. 这是你要求的“采集默认开启，回复单独用开关控制”的核心开关。
# - /api/webui/ws-token enable_reply_output = true
# - /ws
server_url = "http://192.168.2.240:8001"
# MaiBot WebUI 的访问令牌： # 是否允许 MaiBot 往群里回复：
# 1. 这是你在 MaiBot WebUI 登录页里使用的 token； # 1. 只影响群输出，不影响群消息采集；
# 2. 插件会先调用 auth/verify 写入 Cookie，再换取一次性 ws-token； # 2. 如果你希望先观察 MaiBot 记忆效果、不让它插话，可以改成 false；
# 3. 建议部署完成后改成你自己的正式 token。 # 3. 与 enable_reply_output 共同生效。
access_token = "" reply_group_messages = true
# WebSocket 聊天的超时配置（秒）： # 是否允许 MaiBot 往私聊里回复：
# 1. connect_timeout 控制 HTTP/WS 建连超时； # 1. 只影响私聊输出，不影响私聊消息采集；
# 2. reply_timeout 控制发送问题后等待 MaiBot 回复的最长时间。 # 2. 如果你担心它先在私聊里误触发，可以单独关闭；
connect_timeout = 15 # 3. 与 enable_reply_output 共同生效。
reply_timeout = 90 reply_private_messages = true
# 会话维度： # 群功能开关是否参与“能不能往群里说话”的判断：
# 1. room 表示同一个群共享一个 MaiBot 身份语境； # 1. true：继续复用 abot 现有的群功能权限体系；
# 2. sender 表示每个发言人各自独立会话； # 2. false：只要 enable_reply_output/reply_group_messages 打开，就允许 MaiBot 在群里说话；
# 3. 当前默认 room，更适合群聊人格连续性。 # 3. 无论 true 还是 false，消息都会照常采集并发送给 MaiBot。
session_scope = "room" respect_group_feature_switch = true
# 是否校验 HTTPS 证书。 # 群回复时是否自动 @ 触发者：
# 如果你后面给 MaiBot 挂了自签名证书，可以临时改成 false。 # 1. false：直接发普通文本，更像群里自然插话；
# 2. true：会尝试 @ 原发言人，更适合点对点回应；
# 3. 当前默认 false，更贴近“参与聊天”的体验。
mention_user_on_group_reply = false
# MaiBot 官方 API Server 的 WebSocket 地址：
# 1. 这里必须填官方 API Server 暴露出来的 /ws；
# 2. 当前远端部署已经映射为 18009 -> 8090；
# 3. 不再使用 WebUI 的 /api/webui/ws-token 和 /api/webui/ws。
api_server_ws_url = "ws://192.168.2.240:18009/ws"
# MaiBot API Server 的 api_key：
# 1. 这个值会进入握手头 x-apikey 和消息维度 message_dim.api_key；
# 2. MaiBot 服务端会基于它做用户路由与会话归属；
# 3. 当前远端为了联调方便允许空列表校验，但客户端这里依旧建议明确填入一个稳定值。
api_key = "abot-maibot"
# 平台名：
# 1. 会进入握手头 x-platform；
# 2. 也会进入 message_info.platform 与 message_dim.platform；
# 3. 建议保持稳定，后续日志、路由和排障都会更清晰。
platform_name = "abot-maibot"
# 是否校验 SSL 证书：
# 1. 当前局域网 http/ws 直连场景保持 true 也不会有问题；
# 2. 如果以后切成 wss 且用自签名证书，可临时改成 false；
# 3. 生产上仍建议优先使用有效证书。
verify_ssl = true verify_ssl = true
# 建连超时（秒）：
# 1. 控制首次连接和重连时的握手超时；
# 2. 局域网场景通常 10~15 秒足够；
# 3. 太短容易误判网络抖动，太长则故障恢复慢。
connect_timeout = 15
# 接收超时（秒）：
# 1. 长连接空闲时不代表异常，因此这里要比 connect_timeout 大很多；
# 2. aiohttp 会结合 heartbeat 做活性检测；
# 3. 当前默认 120 秒，适合持续在线聊天场景。
receive_timeout = 120
# 心跳间隔（秒）：
# 1. 用于保持官方 API Server 长连接活性；
# 2. 太短会增加无意义流量，太长会让断线发现变慢；
# 3. 当前默认 20 秒，与 maim_message 默认配置接近。
heartbeat_interval = 20
# 重连间隔（秒）：
# 1. 长连接断开后，这里控制多久再尝试重连；
# 2. 当前默认 5 秒，适合局域网服务；
# 3. 如果后面网络更不稳定，可以适当调大。
reconnect_delay = 5
# 本地待发送消息队列长度：
# 1. 这是 abot -> MaiBot 的缓冲区；
# 2. 队列满了以后，新消息会直接丢弃并打印详细日志；
# 3. 默认 500，足够覆盖绝大多数群聊高峰。
queue_maxsize = 500
# 单条消息发送到 MaiBot 的最大重试次数：
# 1. 只处理瞬时断线这类临时故障；
# 2. 超过次数后会落日志并丢弃，避免消息永久堆积；
# 3. 当前默认 3 次，兼顾稳定性与可控性。
max_send_retries = 3

1027
plugins/maibot_adapter/main.py
View File

File diff suppressed because it is too large Load Diff