Pallas-Bot

外观

协议端 ​

字数
1135 字
阅读时间
5 分钟

把 QQ 账号接进 Pallas-Bot；接不上时按下面定位。

协议端负责把 QQ 侧连接带进 Pallas 运行时。它不是“Bot 本体的一部分”，而是独立的一层接入运行时。

4.0 下，协议端一般通过官方插件 pallas-plugin-protocol 管理，并在 WebUI 里有控制台页面。

先分清两层 ​

  • Pallas-Bot 负责接收 OneBot 事件、运行插件、提供 WebUI 与治理接口。
  • 协议端负责登录 QQ、维护账号实例、向 Bot 发起反向 WebSocket 连接。

所以：

  • 协议端异常，不等于 Bot 本体异常。
  • Bot 正常启动，不代表 QQ 账号已经真正接入。
  • 分片时，协议端要连到正确的 worker，别默认只看 hub。

什么时候需要 ​

这些情况优先查协议端链路：

  • 新号接入后，控制台显示账号不在线。
  • 协议端实例能启动，但 Bot 不收消息。
  • 分片切换后，部分账号连错 worker。
  • Docker 场景下，反向 WS 一直连不上。

4.0 里的接入位置 ​

典型链路：

text
QQ / 协议端实例
  -> OneBot 反向 WebSocket
  -> Pallas worker 或单进程 Bot
  -> 插件与运行时

分片下特别注意

  • hub 负责 WebUI、注册表、协议端管理与部分回调。
  • worker 才是真正接消息、跑大部分插件逻辑的进程。
  • 协议端实例里每个账号的 ws_url 必须指向所属 worker 端口。

维护者的最短接入顺序 ​

  1. 先确认本体和 WebUI 已经正常启动。
  2. 安装并启用 pallas-plugin-protocol。
  3. 在协议端管理页创建或导入协议端实例。
  4. 核对实例程序目录、实例根目录和登录方式。
  5. 让账号连到正确的反向 WS 地址。
  6. 回到 Bot 侧确认 /pallas/api/bots 或控制台在线状态已更新。

WARNING

分片部署别跳过第 5 步。账号连到 hub 端口，通常拿不到预期的群消息处理结果。

维护者最常检查的三项 ​

1. 协议端实例本身是否真的在线 ​

先看：

  • 协议端实例日志
  • 账号登录状态
  • 实例程序目录是否正确

实例都没真正跑起来，就别先去怀疑 Bot 侧插件。

2. 反向 WS 地址是否连对 ​

单进程时，确认它连到当前 Bot 监听地址就行。

分片时，要确认：

  • data/pallas_shard/registry.json 里的 worker 端口分配
  • 协议端实例中的 ws_url
  • PALLAS_SHARD_WS_HOST 或 Docker 下的可达主机名

核心原则很简单：

  • 账号属于哪个 worker，就连到哪个 worker。
  • hub 负责治理和聚合，不替所有账号接 OneBot 消息。

3. Bot 侧是否真的收到连接 ​

再看：

  • hub / worker 日志
  • 控制台账号在线状态
  • 分片 registry 与协议端同步结果

日志里没有对应连接建立记录时，继续查协议端和网络层，别先改插件逻辑。

Docker 场景下最容易错的地方 ​

  • 容器内外主机名不一致，协议端写了错误的 WS 主机。
  • 只映射了 hub 端口，没映射实际 worker 端口。
  • Compose 服务名在协议端侧不可达，却被当成对外地址写进去。

Docker 下更稳妥的思路

先确认协议端容器或宿主机能访问目标 worker 端口，再确认写入实例配置的地址和实际网络拓扑一致。

排障顺序 ​

按这个顺序查：

  1. 协议端实例是否启动成功。
  2. QQ 账号是否已登录并保持在线。
  3. 反向 WS 地址是否正确。
  4. 分片 registry 与账号归属是否一致。
  5. worker 日志里是否看到连接建立与事件进入。

不要这样查 ​

  • 还没确认 WS 连通，就直接怀疑命令权限或插件故障。
  • 分片场景只看 hub 日志，不看具体 worker。
  • 看到 WebUI 能打开，就以为协议端已经接好。

相关阅读 ​