协议端管理 pallas-plugin-protocol

提供 NapCat / SnowLuma 协议端管理与牛牛重新上号能力。

本包绑定三个 NoneBot 插件：

模块	插件	角色
pallas_plugin_protocol	协议端管理	hub / unified
pallas_plugin_relogin_bot	重新上号、创建牛牛	hub / unified
pallas_plugin_relogin_forward	分片 worker 口令转发	worker

安装方式

需已安装 Pallas-Bot ≥ 4.0。

推荐直接在控制台插件商店安装，或在本体项目中执行：

uv run pallas ext install pallas-plugin-protocol

也可单独安装本包：

uv pip install pallas-plugin-protocol

未安装时 Web 控制台仍可打开；协议端 / 实例 页会提示安装本扩展。

开发联调：clone 本仓库后 uv pip install -e .。

多进程分片

• hub 加载 protocol + relogin_bot；worker 加载 relogin_forward。
• 各牛牛账号的 ws_url 指向所属 worker 端口；共享 data/。
• run_sharded_bot.sh start 会同步注册表与协议端配置。

详见：多进程分片

怎么使用

协议端管理

多账号 NapCat / SnowLuma：创建牛牛、启停实例、日志与 OneBot 反向 WebSocket。与 Web 控制台共用浏览器登录。

入口	说明
/pallas/protocol	协议端管理页（维护者向）
/protocol/console/	旧书签，自动跳转到 Bot 控制台

典型流程：登录控制台 → 创建实例 → 配置反向 WS → 启动。Docker 下注意 PALLAS_PROTOCOL_DOCKER_ONEBOT_HOST。

常用配置（WebUI 插件 → pallas_protocol）：

键	说明
pallas_protocol_enabled	是否加载协议端
pallas_protocol_webui_enabled	兼容旧配置；协议页面统一由 Bot 控制台提供
pallas_protocol_instances_root	实例根目录
pallas_protocol_program_dir	NapCat 程序目录

完整键：src/pallas_plugin_protocol/config.py

重新上号（relogin_bot）

口令	场景	说明
牛牛重新上号 [QQ]	私聊	号主重启本账号协议端
创建牛牛 …	私聊	超管新建实例

命令 ID	默认等级
relogin.relogin	号主
relogin.create	仅超管

详细用法、限制条件和可用范围以帮助为主。

排障

现象	处理
账号无法启动	查实例日志、程序目录
Bot 不回复	确认反向 WS 连上 hub/worker 端口
无二维码	SnowLuma：Hub 宿主机需 libzbar0、imagemagick；容器内建议安装 xdotool（自动点「刷新」）。查 GET /protocol/console/api/snowluma/host-deps
Docker WS 连不上	见文档站 FAQ · 协议端反向 WebSocket

实现

源码位置：

• src/pallas_plugin_protocol/
• src/pallas_plugin_relogin_bot/
• src/pallas_plugin_relogin_forward/

实现要点：

• protocol 负责实例管理、配置落盘与 Web 控制台接入。
• relogin_bot 提供号主重登和创建牛牛入口。
• relogin_forward 只在 worker 侧负责分片口令转发。

相关链接

说明	链接
协议端管理	文档站 · pallas_protocol
重新上号	文档站 · relogin_bot
插件开发入门	develop/plugin/getting-started