分片部署

August 12, 2026 · View on GitHub

把单进程扩成 hub + worker。适合已验证单进程事件循环/连接压力仍不够、或需要强隔离炸点的场景。依赖明确的角色分工、共享 data/，以及 Redis 协调。

默认建议：先用单进程部署（unified）+ 辅进程（如本机 Embedding 的 bot_embed）。热路径不阻塞时，多账号也可先留在单 ingress；分片是可选进阶，不是人人必会的主路径。

尚未验证单进程瓶颈时，请先用单进程部署。

适用条件

适合	不适合 / 可先不上
单进程已卡顿、连接或调度压力明确	仅 1–2 只 Bot，或尚未验证瓶颈
需要账号级炸点隔离	可用 unified + aux 消化重活时
多协议实例必须按端口切开	无法提供共享 `data/` 与 Redis
需拆开 WebUI / 协议端 / AI 回调与消息处理

单进程热群常见表现：命令尚可、闲聊/接话变慢或偶发不回。入站会优先保命令并节流闲聊（见热闹群与入站设计）。先把重活（如 local Embedding）放到辅进程后再评估是否仍需分片。

结构图

flowchart LR
    WebUI[WebUI]
    Hub[Hub]
    Redis[(Redis)]
    W1[Worker 1]
    W2[Worker 2]
    Proto[Protocol / QQ]
    AI[AI Runtime]

    WebUI --> Hub
    Hub <--> Redis
    Hub --> W1
    Hub --> W2
    W1 <--> Redis
    W2 <--> Redis
    Proto --> W1
    Proto --> W2
    W1 --> AI
    W2 --> AI

角色分工

角色	职责
`hub`	WebUI、协议端管理、注册表、部分协调、媒体 / RWKV callback 入口
`worker`	消息处理、群聊玩法、绝大多数业务插件
`Redis`	跨 worker claim、活动协调、部分广播与状态同步
`Protocol`	QQ 协议接入；反向连接到对应 worker（不是 hub）

前置条件

1. 共享 `data/`

hub 与所有 worker 必须共用同一份 data/，否则会错乱：

registry.json
协调状态
协议端账号映射
worker presence
WebUI 聚合状态

2. Redis

4.0 分片关键协调依赖 Redis（单进程不强制）。

config/pallas.toml 的 [env]：

[env]
REDIS_URL = "redis://127.0.0.1:6379/0"

3. 端口规划

hub：8088
worker：从 8090 起分配

协议端 ws_url 必须与实际 worker 端口一致。

启动

::: tip 优先用仓库脚本，勿手动拼环境变量起多个进程。 :::

./scripts/run_sharded_bot.sh start
./scripts/run_sharded_bot.sh status
./scripts/run_sharded_bot.sh stop

常见补充：

./scripts/run_sharded_bot.sh start --workers 5
./scripts/run_sharded_bot.sh restart
./scripts/run_sharded_bot.sh test init
./scripts/run_sharded_bot.sh test start

脚本处理：hub / worker 拉起、注册表端口对齐、协议端 ws_url 同步、日志目录与 PID。

也可用部署模板：uv run python tools/apply_deploy_profile.py shard，再配置 REDIS_URL 后启动。

入口与运行

对外	对内
WebUI 主要访问 hub	worker 跑大多数插件
媒体 / RWKV callback 先打到 hub	hub 聚合 worker 状态给控制台
协议端账号连到 worker	无 Redis 时跨 worker 能力失效