重构MaiBot适配器为官方API Server长连接采集模式并补全Dashboard说明
This commit is contained in:
liuwei
@@ -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 凭据。
|
||||
如果你把 SSH 用户名/密码，或者私钥登录方式给我，我就可以直接按这份清单远程执行。
|
||||
1. `MaiBot` 使用官方镜像 `sengokucola/maibot:latest` 部署。
|
||||
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`
|
||||
2. `GET /api/webui/ws-token`
|
||||
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
|
||||
```text
|
||||
maibot-core-lite
|
||||
```
|
||||
|
||||
### 2. 拉取 MaiBot
|
||||
镜像：
|
||||
|
||||
```bash
|
||||
cd /opt
|
||||
sudo git clone https://github.com/Mai-with-u/MaiBot.git
|
||||
sudo chown -R $USER:$USER /opt/MaiBot
|
||||
cd /opt/MaiBot
|
||||
```text
|
||||
sengokucola/maibot:latest
|
||||
```
|
||||
|
||||
### 3. 创建虚拟环境并安装依赖
|
||||
核心端口映射：
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
python -m pip install --upgrade pip
|
||||
pip install -e .
|
||||
```text
|
||||
18001 -> 8001 # WebUI / Dashboard / WebUI API
|
||||
18009 -> 8090 # 官方 API Server
|
||||
```
|
||||
|
||||
如果 `pip install -e .` 遇到单个依赖下载慢，可以切换镜像源再执行。
|
||||
## Dashboard 访问地址
|
||||
|
||||
### 4. 首次启动
|
||||
当前已经补全完成，可直接访问：
|
||||
|
||||
```bash
|
||||
source /opt/MaiBot/.venv/bin/activate
|
||||
cd /opt/MaiBot
|
||||
python bot.py
|
||||
```text
|
||||
http://192.168.2.240:18001/
|
||||
```
|
||||
|
||||
说明：
|
||||
如果只想看健康状态：
|
||||
|
||||
1. `bot.py` 是 MaiBot 主入口
|
||||
2. 首次启动时通常需要你按它自己的配置流程完成基础设置
|
||||
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
|
||||
```text
|
||||
http://192.168.2.240:18001/api/webui/health
|
||||
```
|
||||
|
||||
期待返回：
|
||||
@@ -94,87 +53,61 @@ curl http://192.168.2.240:8001/api/webui/health
|
||||
{"status":"healthy","service":"MaiBot WebUI"}
|
||||
```
|
||||
|
||||
### 6. 获取 WebUI token
|
||||
## embedding 模型现状
|
||||
|
||||
这一步有两种方式：
|
||||
当前远端已切到 Ollama 向量服务：
|
||||
|
||||
1. 按 MaiBot 首次配置流程，在 WebUI 中设置 token
|
||||
2. 如果已经有现成 token，直接记下来给 `maibot_adapter` 使用
|
||||
```text
|
||||
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
|
||||
server_url = "http://192.168.2.240:8001"
|
||||
access_token = "你的MaiBotToken"
|
||||
[MaiBotAdapter]
|
||||
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
|
||||
[Unit]
|
||||
Description=MaiBot Service
|
||||
After=network.target
|
||||
|
||||
[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` 再往“共享长连接 + 自动回复桥”方向升级。
|
||||
1. 消息默认发送给 MaiBot 做采集。
|
||||
2. 是否真的回复，由开关和群功能权限控制。
|
||||
3. 不重新开发 MaiBot 对话/记忆本体能力。
|
||||
4. 尽量把“参与聊天”的判断留在 MaiBot 侧，而不是在 abot 里再做一遍复杂前置策略。
|
||||
|
||||
@@ -1,35 +1,50 @@
|
||||
# MaiBot Adapter 插件
|
||||
|
||||
这个插件用于把外部独立部署的 `MaiBot WebUI` 对接到 `abot` 的插件体系里。
|
||||
这个插件现在已经改成对接 `MaiBot 官方 API Server`，不再依赖 `WebUI 聊天页` 那套 token + ws-token + `/api/webui/ws` 流程。
|
||||
|
||||
## 当前能力
|
||||
|
||||
1. 支持命令触发：
|
||||
- `麦麦 你好`
|
||||
- `maibot 你是谁`
|
||||
2. 支持群聊里 `@机器人` 后把文本转发给 MaiBot。
|
||||
3. 插件内部会自动执行：
|
||||
- `POST /api/webui/auth/verify`
|
||||
- `GET /api/webui/ws-token`
|
||||
- `WS /ws?token=...`
|
||||
4. 每次消息会走一个独立的 WebSocket 逻辑会话，并等待 `bot_message` 事件作为最终回复。
|
||||
1. 默认把 abot 收到的群聊/私聊消息旁路发送给 MaiBot，作为上下文与记忆输入。
|
||||
2. 默认不阻断其它插件链路，`ai_auto_response`、`Dify`、命令插件仍可继续照常处理。
|
||||
3. 是否真的把 MaiBot 的回复发回微信，由 `enable_reply_output`、`reply_group_messages`、`reply_private_messages` 以及群功能开关共同控制。
|
||||
4. 使用官方 API Server 协议：
|
||||
- WebSocket 握手头：`x-uuid` / `x-apikey` / `x-platform`
|
||||
- 消息包类型：`sys_std`
|
||||
- 负载结构：`APIMessageBase`
|
||||
5. 支持把图片、语音、视频、位置、应用消息转换成文本占位符发给 MaiBot，方便它做长期上下文理解。
|
||||
|
||||
## 配置说明
|
||||
## 推荐定位
|
||||
|
||||
这套插件更适合做两件事：
|
||||
|
||||
1. 让 MaiBot 成为 `ai_auto_response` 之外的一条“长期对话与记忆”能力链路。
|
||||
2. 先把全量消息采集给 MaiBot，等效果稳定后，再逐步提高它的主动参与度。
|
||||
|
||||
## 配置重点
|
||||
|
||||
见 `config.toml`：
|
||||
|
||||
1. `server_url`
|
||||
- MaiBot WebUI 地址，例如 `http://192.168.2.240:8001`
|
||||
2. `access_token`
|
||||
- MaiBot WebUI 登录 token
|
||||
3. `session_scope`
|
||||
- `room`：同群共享语境
|
||||
- `sender`：同群内每个用户独立语境
|
||||
1. `api_server_ws_url`
|
||||
- 例如 `ws://192.168.2.240:18009/ws`
|
||||
2. `api_key`
|
||||
- 用于官方 API Server 路由
|
||||
3. `enable_reply_output`
|
||||
- 控制“MaiBot 能不能实际开口说话”
|
||||
4. `respect_group_feature_switch`
|
||||
- 控制群里是否还要继续受 abot 功能权限开关约束
|
||||
|
||||
## 部署建议
|
||||
## 现阶段建议
|
||||
|
||||
如果你后面要让 `ai_auto_response` 也改走 MaiBot，建议顺序如下：
|
||||
如果你打算逐步替代 `ai_auto_response`，建议按这个顺序推进：
|
||||
|
||||
1. 先用这个插件验证 MaiBot 对话质量与延迟。
|
||||
2. 确认稳定后，再把 `ai_auto_response` 的“决策/生成”改成调用同一套桥接逻辑。
|
||||
3. 最后再决定是否完全下线 `ai_auto_response` 原本的 LLM 直连链路。
|
||||
1. 先保持 `collect_group_messages=true`、`enable_reply_output=false`，只观察 MaiBot 记忆与理解效果。
|
||||
2. 然后打开 `enable_reply_output=true`，但先让少量测试群开启 `MAIBOT_CHAT` 功能权限。
|
||||
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`
|
||||
|
||||
@@ -1,45 +1,104 @@
|
||||
[MaiBotAdapter]
|
||||
enable = true
|
||||
|
||||
# 命令触发词：
|
||||
# 1. 不需要前缀，直接使用 “麦麦 你好” 这种形式即可；
|
||||
# 2. 群聊里也支持 @机器人 后直接转发给 MaiBot；
|
||||
# 3. 如果你后面希望只保留自动插话入口，可以把命令缩减到一个内部调试词。
|
||||
commands = ["麦麦", "maibot", "mai"]
|
||||
command-tip = """
|
||||
🤖MaiBot 对话指令：
|
||||
麦麦 你好
|
||||
"""
|
||||
# 是否默认采集群消息到 MaiBot：
|
||||
# 1. 这是“把消息送给 MaiBot 做上下文与记忆”的总开关；
|
||||
# 2. 关闭后，群消息不会再进入 MaiBot；
|
||||
# 3. 这个开关只影响采集，不影响 MaiBot 已经生成中的历史任务。
|
||||
collect_group_messages = true
|
||||
|
||||
# 是否允许群聊里通过 @机器人 触发。
|
||||
allow_group_at = true
|
||||
# 是否默认采集私聊消息到 MaiBot：
|
||||
# 1. 打开后，私聊也会进入 MaiBot 的上下文链路；
|
||||
# 2. 如果你暂时只想把 MaiBot 当群聊人格，就可以先关掉；
|
||||
# 3. 当前按你的要求默认开启“全量采集”能力。
|
||||
collect_private_messages = true
|
||||
|
||||
# MaiBot WebUI 服务根地址：
|
||||
# 1. 不要带末尾斜杠；
|
||||
# 2. 插件会基于这个地址自动请求：
|
||||
# - /api/webui/auth/verify
|
||||
# - /api/webui/ws-token
|
||||
# - /ws
|
||||
server_url = "http://192.168.2.240:8001"
|
||||
# 是否允许把 MaiBot 的回复真正发回微信：
|
||||
# 1. true 表示 MaiBot 不仅接收消息，也可以实际参与说话；
|
||||
# 2. false 表示只做上下文采集与记忆沉淀，不做回声输出；
|
||||
# 3. 这是你要求的“采集默认开启，回复单独用开关控制”的核心开关。
|
||||
enable_reply_output = true
|
||||
|
||||
# MaiBot WebUI 的访问令牌：
|
||||
# 1. 这是你在 MaiBot WebUI 登录页里使用的 token；
|
||||
# 2. 插件会先调用 auth/verify 写入 Cookie，再换取一次性 ws-token；
|
||||
# 3. 建议部署完成后改成你自己的正式 token。
|
||||
access_token = ""
|
||||
# 是否允许 MaiBot 往群里回复：
|
||||
# 1. 只影响群输出，不影响群消息采集；
|
||||
# 2. 如果你希望先观察 MaiBot 记忆效果、不让它插话，可以改成 false；
|
||||
# 3. 与 enable_reply_output 共同生效。
|
||||
reply_group_messages = true
|
||||
|
||||
# WebSocket 聊天的超时配置（秒）：
|
||||
# 1. connect_timeout 控制 HTTP/WS 建连超时；
|
||||
# 2. reply_timeout 控制发送问题后等待 MaiBot 回复的最长时间。
|
||||
connect_timeout = 15
|
||||
reply_timeout = 90
|
||||
# 是否允许 MaiBot 往私聊里回复：
|
||||
# 1. 只影响私聊输出，不影响私聊消息采集；
|
||||
# 2. 如果你担心它先在私聊里误触发，可以单独关闭；
|
||||
# 3. 与 enable_reply_output 共同生效。
|
||||
reply_private_messages = true
|
||||
|
||||
# 会话维度：
|
||||
# 1. room 表示同一个群共享一个 MaiBot 身份语境；
|
||||
# 2. sender 表示每个发言人各自独立会话；
|
||||
# 3. 当前默认 room，更适合群聊人格连续性。
|
||||
session_scope = "room"
|
||||
# 群功能开关是否参与“能不能往群里说话”的判断：
|
||||
# 1. true：继续复用 abot 现有的群功能权限体系；
|
||||
# 2. false：只要 enable_reply_output/reply_group_messages 打开，就允许 MaiBot 在群里说话；
|
||||
# 3. 无论 true 还是 false，消息都会照常采集并发送给 MaiBot。
|
||||
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
|
||||
|
||||
# 建连超时（秒）：
|
||||
# 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
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user