话说,到底是谁在使用本项目?
BotShepherd 是一个基于OneBot v11协议WebSocket代理和管理系统,统一管理和协调多个Bot实例,实现一对多的连接管理、消息统计、跨框架黑名单、全框架分群组功能开关和别名防冲突。
人话:一个账号只需要一个ws连接接入本系统,就可以自由的连接到下游框架。本系统可以方便的统计单个账号消息量,管理黑名单,进行指令转化等。你不再需要为每个账号创建一个Nonebot或配置 账号数量x框架数量 个ws连接
- 每账号消息量,跨框架黑名单,每Bot、每群、全局可以将原有指令别名,支持不更改后端就能按Bot区分不同业务(使用不同别名),支持群管理员通过过滤词的方式自助禁用指令。
- 触发指令:自己上号或主人在群里,通过指令帮助其他用户执行任何指令(bs触发 123456 some_command),避免红温,现已支持at。
- 支持对接其他系统,可自动化更新群组到期时间等 API文档
- 消息落库改为攒 2 秒一批再提交。此前写入队列里有几条就提交几条,消息平均每秒两三条时几乎每条一个事务,每次都要把表尾和各个索引被改到的页整页写进 WAL;现在同一批共用的页只写一次。正常关闭会先把手上这批写完,进程被强杀时最多丢最后约 2 秒的记录
- 启动时删除 5 个冗余或用不上的索引:
ix_messages_self_id、ix_messages_user_id、ix_messages_group_id(已被对应的(列, timestamp)复合索引覆盖),ix_messages_message_id(没有按 message_id 查的地方),idx_messages_content_search(关键词查询是 contains,前缀查询是拼接出来的 LIKE,SQLite 都用不上这个索引)。每条消息的写入和过期删除少改 5 棵 B 树。释放的页由清理任务里的增量回收还给磁盘,一个约 14GB、每天约 20 万条消息的库升级后降到约 11GB;首次启动删索引约需十几秒 - WAL 自动 checkpoint 从 1000 页调到 4000 页(约 16MB),两次 checkpoint 之间反复修改的页只回写一次;checkpoint 后 WAL 文件超过 64MB 会截回
- 新增「控制台日志级别」(系统设置 → 日志设置,对应全局配置
logging.console_level),只影响控制台,日志文件不变。用 systemd 等托管运行时控制台输出会进系统日志,每条消息日志在磁盘上要多存一份,可调成 WARNING;默认与日志级别相同,行为不变
点此展开历史版本
2026-11-12 v1.3.0 半死连接及时回收,压缩按消息自动取舍
- 关闭握手加 5 秒上限(此前无限等待)。客户端半死(进程卡住、网络中断但连接没断)时,此前心跳判定超时后还会一直等对方回应:连接不释放、框架仍认为账号在线、发给它的消息卡住也不报错,要等 TCP 自己超时或客户端重连;现在心跳超时后 5 秒内断开并清理。有数据积压在发送缓冲里时心跳本身也发不出去,另加一道检查:连续 40 秒客户端一个字节都没收下就断开
- 压缩改为自动取舍,无需配置。此前所有连接、每条消息都压,而图片、视频的 base64 只能压到约 76%,25MB 压一次约 0.6 秒,期间进程不处理其他消息
- 本机连接(连到
localhost、127.0.0.1、::1的框架,以及从本机连进来的客户端)不再协商压缩:回环上省不了带宽,却要两头各压一遍、解一遍。经本机隧道(frp 等)进来的客户端也算本机 - 其余连接照常协商,对端发来的压缩消息照样接收;BotShepherd 自己发出的逐条判断:16KB 以内直接压,更大的抽样试压,压不动的原样发出
- 本机连接(连到
- 启动时把文件描述符上限提到 65536(不超过系统硬上限),此前沿用默认的 1024。每个连接配置占 1 个监听,账号在线后再占 1 + 目标框架数 个连接,四个框架时约 170 个账号同时在线就会用满,之后新连接进不来;Web 管理界面改用 poll,连接数超过 1024 后仍可访问
- 修复目标初次连接失败后,后台重连途中客户端断开,可能留下一条无人接手的目标连接(框架会一直当该账号在线)
- 客户端因消息过大(1009)断开后,不再多记一条
关闭WebSocket连接时出错: 'NoneType' object has no attribute 'call_soon' bs更新的版本检查和 git pull 改到线程里执行,期间不再卡住其他账号的消息转发(此前最长约 35 秒整个进程停住)- 连本机框架不再走环境变量里的代理(websockets 15 起默认会读
http_proxy等,从带代理的终端手动启动时本机连接也被绕过去) - 修复
ConfigManager.setup_initial_config()调用了不存在的方法(正常启动流程走不到这里,手动调用才会报错)
2026-11-11 v1.2.7 发送条数提示改为可配置,默认关闭
- 消息末尾的「今日发了 N 条咯…」提示改为默认关闭,升级后不再出现;需要的话到「系统设置 → 发送条数提示」打开
- 每日上限和群聊、私聊提示文案可以在设置页修改,对应全局配置
sendcount_notice;旧字段sendcount_notifications不再使用
2026-11-08 v1.2.6 连接断开即回失败,框架卡顿不再整批断线
- 客户端(如 NapCat)断开时,已转发给它、还没收到响应的 API 请求立即给对应框架回失败,框架不必等满自己的 API 超时(NoneBot 常设 300 秒)
- 失败响应的
retcode是 WebSocket 关闭码,message以「客户端连接已断开」开头。1009 表示消息过大被客户端拒收、请求没执行,框架可以缩小后重发;1006 等异常断开时请求可能已执行 - 只回 300 秒内发出、带 echo 的请求;每条在 websocket 日志记一行
API调用失败 - 对框架(target)连接的心跳超时由 20 秒放宽到 120 秒:框架多在本机,进程退出会立即断开,不靠心跳发现;此前框架事件循环卡顿 20 秒以上,挂在它上面的所有连接会一起被判死断开,卡顿期间的消息全部丢失,现在会排队等框架恢复后送达
2026-10-29 v1.2.5 过期消息清理后回收磁盘空间
- 数据库改为增量 auto_vacuum,每日清理过期消息后分批回收空闲页,库文件随之缩小(此前删掉的消息只留下空闲页,文件只增不减)
- 已有的库要停服执行一次
PRAGMA auto_vacuum=INCREMENTAL; VACUUM;才会切换;未切换且空闲页超过 1GB 时日志会提示
2026-10-28 v1.2.4 关闭的群拦截通知事件
- 群关闭/过期/拉黑时,该群的戳一戳、表情回应、撤回、入群申请等通知与请求事件也一并拦截(此前只拦群消息),超级用户触发的除外
2026-10-22 v1.2.3 安全更新
- 修补图片处理、Web 会话、证书信任及加密备份相关依赖。
2026-08-12 v1.2.2 修复多框架 API 响应串台
- 修复多个框架 echo 撞号时(各框架自增序号独立,必然撞)API 响应被投递给错误框架:转发请求时把目标序号编进 echo,回程精确路由并还原原值
2026-07-19 v1.2.1 安全更新
- 安全性更新,建议所有用户尽快升级到最新版本。
2026-07-16 v1.2.0 内置发言榜插件
- 新增
bs发言榜 [日期] [刷新](别名 水群榜),群管理员以上可用,统计本群发言排行出图;日期支持 昨天/N天前/本周/上月/7月5日 等,周期以每日 08:00 为界,依赖新增 pillow app/plugins/加入 gitignore,用户可在此编写自己的插件不污染仓库(内置插件保持跟踪,新增内置需git add -f)
2026-06-01 v1.1.4 重连退避优化(固定 10 分钟改 4s 起步封顶 300s 渐进退避)+ 修复每日备份月末跨月报错
2026-05-30 v1.1.3 过滤词支持 ^/$ 锚点:新增 ^ 开头、$ 结尾锚点(非完整正则),可与 +/| 组合;群过滤改多候选独立匹配;毫秒时间戳归一化
2026-05-30 v1.1.2 启动时回收 WAL:initialize() 跑一次 wal_checkpoint(TRUNCATE),每次(重)启动自动回收遗留的超大 WAL
2026-05-29 v1.1.1 修复 DB 层假死
- 每日清理改分批删除(小事务+批间让锁),消除巨型删除事务独占写锁导致的全局假死
- save_message 移出转发热路径(入队后台批量落库),DB 慢/锁不再卡消息转发
- 连接级 PRAGMA:busy_timeout=10000 + synchronous=NORMAL
2026-05-29 v1.1.0 修复 ws 假死
- 心跳间隔 300s→20s,半死连接探测从最坏 ~6 分钟缩短到 ~40s
- 新连接接入时主动 ping 探活旧连接,假死则由新连接接管(不再被锁在门外)
- target 发送加超时,防止单个卡死 target 造成队头阻塞
2026-01-12 v1.0.2 文案,拆分文件,log
2026-01-10 v1.0.1 小修,修复显示、账号在线检查
2026-01-10 v1.0.0 完善了最初设想的所有功能
- 连接配置的更改不再需要重启
- 优化显示,完整易用的webui
- 新压力测试:每日收20W消息、发1.8W消息,占用R9 9950x的单核约2%,内存150M
2026-01-09 v0.5.4 排除包发送行为
2026-01-03 v0.5.3 改用state判断ws状态
2026-01-02 v0.5.2 莉莉娅喵
2025-12-22 v0.5.1 界面优化
2025-12-21 v0.5.0 读写安全、功能更新
- 自动更新依赖,配置支持添加代理,使用代理更新和检查版本
- 添加 bs更新、bs备份 指令,加入更新和备份的UI,建议使用指令获得备份或从UI下载
- 修复 通知事件(如入群)、戳一戳等 不受黑名单和过滤的问题,某群某Bot某功能 的禁用都可以使用群过滤功能来实现
2025-12-10 v0.4.4 修复数据库配置-1,文案、数据库记录消息类型防止空消息
2025-10-25 v0.4.3 写入配置原子操作
2025-10-25 v0.4.2 发现了,转发消息不能附带装饰消息。我的。
2025-10-15 v0.4.0 修了一个严重的bug,情况是由于nb的api请求中params可能为str导致发送成功或失败后无法将echo发回nb,为止别的框架是否有同类问题,反正处理了。
2025-09-24 v0.3.5 减少消息数提示频率,强制旁路别名
2025-09-24 v0.3.4 webui编辑bug,新增过滤词and/or模式
2025-09-08 v0.3.3 若干小bug,以及小维稳定运行接近两个月
2025-08-19 v0.3.2 修复若干连接问题,修复重启,修复koishi echo为int的问题
2025-08-04 v0.3.0 修复了前端数据统计和导出和所有已知bug
2025-08-01 v0.2.6 没有更新,庆祝一下无严重bug持续一整周。后台收发消息量达到 100w/6.5w
2025-07-29 v0.2.5 版本支持到python3.10,取消依赖py3.12的高级字符串解析
2025-07-29 v0.2.4 优化了自动初始化环境,已在windows和root环境的vps下测试
2025-07-26 v0.2.3 修复了重连问题
2025-07-25 v0.2.2 调整数据库
2025-07-25 v0.2.1 根据实际部署情况进行修复
2025-07-24 v0.1.0 完成基本功能
2025-07-15 v0.0.0 画饼
碎碎念:虽然有些地方看上去有点AI,但实际上试了几次以后就放弃用AI写了,虽然一开始AI构建了基本框架,但后面除了webui几乎没有用上AI。框架其实也还行,就是指令框架写的比较烂。改着改着实际上只剩指令框架的基础和webui是AI写的了,而且AI还造成了大部分的bug。。。
点此展开
- 实时监控:WebSocket连接状态实时监控和管理
- 自动重连:连接断开时自动重连机制
- OneBot v11标准:兼容OneBot v11协议规范
- 消息标准化:可选的消息格式标准化(如NapCat补充Onebot消息类兼容,自身上报支持Nonebot触发)
- 别名系统:全局指令别名替换功能
- 三级权限:superuser > 群管/群主 > 普通用户
- 智能过滤:全局+群组双层过滤系统
- 黑白名单:支持用户和群组黑名单管理
- 前缀保护:防止诱导触发的前缀保护机制
- 实时统计:消息数量、指令使用、关键词统计
- 趋势分析:7天/24小时消息量趋势图表
- 用户感知:当消息量逐渐增加时,自动通知用户即将达到发送量上限
- 现代化UI:基于Bootstrap 5的响应式界面
- 配置管理:所有配置项的可视化管理
- API支持:支持API控制配置,内置群组到期时间配置,可接入自动化付费系统。
- 自动备份:每日凌晨3点自动备份配置文件
- 加密保护:使用AES-256加密,密码为Web登录密码
- 灵活管理:可配置备份保留天数,自动清理过期备份
- 即时备份:支持通过指令或Web界面立即创建备份
- 便捷下载:Web界面一键下载备份文件
| Nonebot | Yunzai/TRSS | AstrBot | Koishi | |
|---|---|---|---|---|
| Lagrange.Onebot | ✔️ | ✔️ | ✔️ | ✔️ |
| Napcat | ✔️ | ✔️ | ✔️ | ✔️ |
| LuckyLilliaBot(obv11) | ✔️ | ✔️ | ✔️ | ✔️ |
- Python 3.11+(请使用该分支最新安全补丁)
- Git
- 克隆项目
git clone https://github.com/Loping151/BotShepherd.git
cd BotShepherd- 初始化环境和配置
建议使用虚拟环境,不需要自行pip安装,将自动生成环境:
python main.py --setup仅需要运行一次。
如想要自定义环境,想必了解python的基本使用,不再赘述。
- 启动系统
# 如果使用虚拟环境(推荐)
# 如果是Windows
./venv/Scripts/python.exe main.py
# 如果是Linux
./venv/bin/python main.py
# 或者直接使用系统Python
python main.py- 访问Web管理界面
http://localhost:5100
默认用户名/密码: admin/admin
端口可在初始化完成后于config/global_config.json中修改。
- 配置连接
如图所示
其中:客户端端点 是 bs监听的端口,bs代替了框架成为了server,所以bs的客户端端点填写localhost即可。如果目标框架和bs不在同一台机器上,需要填写目标框架所在机器的ip。而nc的客户端端点则填写bs所在机器的ip。如果需要token,可以使用ws连接的参数,例如ws://127.0.0.1:1212?token=123456。
注意多个客户端不能公用一个连接配置(客户端端点),因为需要拿这个ws连接头去连接下游框架。按照标准,self_id,如QQ号,就在连接头中,一号一头。
创建完第一个连接配置后,可以点击复制快速创建多个连接配置。
示例:使用Tmux(Linux)
sudo apt install tmux
tmux new-session -d -s botshepherd
tmux send-keys -t botshepherd "cd path/to/BotShepherd" Enter
tmux send-keys -t botshepherd '[ ! -d ./venv ] && python main.py --setup' Enter
tmux send-keys -t botshepherd "source venv/bin/activate" Enter
tmux send-keys -t botshepherd "python main.py" Enter使用Docker:Windows(TODO,感觉端口映射有点烦,最好自定义范围映射)
写在webui里了
BotShepherd/
├── app/ # 核心应用代码
│ ├── onebotv11/ # OneBotv11协议解析
│ ├── config/ # 配置管理
│ ├── database/ # 数据库操作
│ ├── server/ # WebSocket代理
│ ├── web_api/ # Web API接口
│ ├── commands/ # 指令系统
│ ├── plugins/ # 插件系统
│ └── utils/ # 工具类
├── config/ # 配置文件目录,备份此处即可
├── data/ # 数据库文件目录,用于储存聊天记录
├── logs/ # 日志文件目录
├── templates/ # HTML模板
├── static/ # 结果变成assets了
└── main.py # 主程序入口,包含环境初始化
仅支持单次回复,支持图文。app/plugins/ 已加入 gitignore,可直接在其中编写自己的插件(单文件或包目录,启动时自动加载),示例见内置插件:bs_plugin_ping.py 最小示例、bs_plugin_talkrank 查库+PIL 出图完整示例。
class MyCommand(Command):
def __init__(self):
super().__init__(
name="我的指令",
description="指令描述",
usage="bs我的指令 [参数]"
)
async def execute(self, event, args, context):
return "指令执行结果"欢迎提交Issue!
- OneBot - 聊天机器人应用接口标准
- NapCat - Napcat
- Lagrange.Onebot - Lagrange.Onebot
- TRSS-Yunzai - TRSS-Yunzai
- Nonebot - Nonebot框架
- AstrBot - AstrBot框架
- Bootstrap - UI框架,这个是AI自己加的,前端不会写喵
BotShepherd - 让Bot管理变得简单而强大 🐑✨ By Loping151 and 小维





