SevenBot框架

SevenBot框架是一个独立的 OneBot v11 QQ 机器人框架，可以连接任意 OneBot11 实现端。

当前方案：

后端使用 Node.js + TypeScript，负责 OneBot 连接、多机器人、插件和管理 API。
主 WebUI 使用 React 19 + Vite + HeroUI，提供聊天、请求、机器人、插件、客户账号、安全文件管理、远程主机、系统配置和日志管理；另有完全隔离的客户面板。
聊天页直接读取 QQ 最近会话与历史消息，通过 SSE 实时接收新消息，并显示 Markdown、合并转发和常用 QQ 富消息段；群消息中的 @ 会按消息文本、群名片、昵称顺序显示，转发节点会过滤实现端的占位 QQ。
插件通过 ctx.seven 使用框架主人、共享 Puppeteer 等 SevenBot 能力。
框架内置共享 Puppeteer 服务，Chrome 默认不捆绑，按需从系统配置页安装。
系统配置页内置完整更新管理：版本选择、镜像测速、下载进度、降级确认、备份与回滚；Docker Compose 可一键拉取镜像并重建容器，普通 Node.js 部署使用校验后的运行包更新。
框架只对接标准 OneBot v11 协议，不包含、也不复制任何实现端的底层代码。

快速开始

cd D:\Seven\SevenBot
npm install
npm run build
npm start

前后端开发时分别运行：

npm run dev
npm run dev:web

Vite 开发页为 http://127.0.0.1:5173/webui/，API 自动代理到 9090 端口。

默认反向 WebSocket 监听所有网卡：

0.0.0.0:8081

WebUI 默认监听 0.0.0.0:9090，本机访问：

http://127.0.0.1:9090

首次启动会生成 8 位随机十六进制 WebUI Token。每次启动都会在日志中输出当前 Token 和带 ?token= 的面板地址；打开该地址会自动登录。登录凭证保存在浏览器 localStorage['token']，有效期 30 天，容器或框架重启后无需重新输入 Token。

连接 OneBot11 实现端

SevenBot框架支持三种连接方式：

反向 WebSocket（推荐）

本框架开启 WebSocket 服务，实现端主动连过来：

connection:
  type: ws-reverse
  host: 0.0.0.0
  port: 8081
  accessToken: ""     # 可选；配置后实现端需使用相同 Token

在 OneBot11 实现端里新增反向 WebSocket 客户端，地址指向：

ws://SevenBot所在主机地址:8081

正向 WebSocket

让 SevenBot框架主动连接实现端的 WebSocket 服务：

connection:
  type: ws
  url: ws://127.0.0.1:3001

HTTP

本框架监听实现端的 HTTP 上报，并通过 HTTP API 主动下发动作：

connection:
  type: http
  host: 0.0.0.0
  port: 8082          # 接收 HTTP 上报的端口
  apiUrl: http://127.0.0.1:3000   # 实现端的 HTTP API 地址
  secret: ""          # 可选；配置后用于校验 X-Signature

插件热重载

插件目录监听默认开启：文件保存后会重新扫描并热重载对应插件，新增目录会立即注册，删除目录会立即卸载，无需重启框架。WebUI 还支持单插件重载、全部重新扫描、配置保存后热生效，以及 ZIP 导入或更新后的即时注册。插件更新采用同一挂载卷内的暂存与原子替换，失败时会恢复原版本。

配置热加载

框架运行时会监听配置文件的外部修改，保存后自动生效，无需重启。源码运行默认使用根目录 config.yaml，Docker 镜像默认使用 /app/config/config.yaml：

日志级别（bot.debug）即时切换
机器人增删、连接方式/地址/端口变更会增量重建对应机器人，其余机器人保持连接
WebUI 监听地址/端口变更仍需重启后生效（会在日志中提示）

Docker 部署

直接拉取镜像运行

无需克隆仓库，进入一个空目录后直接运行。镜像会自动处理挂载目录权限，并将 WebUI 监听到容器外部：

mkdir -p SevenBot && cd SevenBot
docker run -d \
  --name sevenbot \
  -p 9090:9090 \
  -p 8081:8081 \
  -p 8082:8082 \
  -v ./config:/app/config \
  -v ./plugins:/app/plugins \
  -v ./data:/app/data \
  --restart unless-stopped \
  ghcr.io/seven-tmp/sevenbot:latest

启动后从日志查看 Token 和可直接打开的登录地址：

docker logs sevenbot

也可直接访问 http://服务器IP:9090 并输入日志中的 Token。需要固定 Token 时设置 SEVENBOT_WEBUI_TOKEN。如需图片渲染，登录后进入「系统配置 → Puppeteer」安装 Chrome，浏览器会保存到 data/puppeteer，更新镜像不会丢失。

单容器 docker run 不具备宿主机更新权限，更新页会提示改用受限宿主机更新助手。需要在 WebUI 点击「立即更新」时，使用下面的 Linux Compose 部署；Windows Docker Desktop 请继续在宿主机手动拉取镜像并重建容器。

镜像由 .github/workflows/docker-publish.yml 在 main 更新或推送 v* 标签时自动构建，支持 linux/amd64 和 linux/arm64。容器包已公开，任何机器都能免登录拉取。

使用 Compose

需要安装 Docker、Docker Compose v2、Python 3 和 systemd。首次部署同时下载 Compose、helper 与 systemd unit：

mkdir -p SevenBot/scripts SevenBot/deploy && cd SevenBot
curl -fsSLO https://raw.githubusercontent.com/Seven-TMP/SevenBot/main/docker-compose.yml
curl -fsSLo scripts/install-update-helper.sh https://raw.githubusercontent.com/Seven-TMP/SevenBot/main/scripts/install-update-helper.sh
curl -fsSLo scripts/sevenbot-update-helper.py https://raw.githubusercontent.com/Seven-TMP/SevenBot/main/scripts/sevenbot-update-helper.py
curl -fsSLo deploy/sevenbot-update-helper.service https://raw.githubusercontent.com/Seven-TMP/SevenBot/main/deploy/sevenbot-update-helper.service
chmod 0755 scripts/install-update-helper.sh
sudo ./scripts/install-update-helper.sh --compose-dir "$PWD" --uid "${SEVENBOT_UID:-1000}" --gid "${SEVENBOT_GID:-1000}"
docker compose up -d
docker compose ps
docker compose logs -f sevenbot

如果部署使用多个 Compose 文件，安装 helper 时必须按实际启动顺序重复传入 --compose-file；helper 会把这组 root 管理的固定文件原样用于更新，例如：

sudo ./scripts/install-update-helper.sh \
  --compose-dir "$PWD" \
  --compose-file docker-compose.yml \
  --compose-file docker-compose.local.yml
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d

新增、删除或调整 overlay 顺序后重新运行安装器。所有 Compose 文件都必须位于同一个部署目录内、不是符号链接，并且不可由 SevenBot 运行用户写入。

首次启动会运行一次性初始化容器，自动创建 config/、plugins/、data/，修正容器运行用户权限，并在 data/.secret-key 生成持久化随机密钥。
配置文件位于 config/config.yaml。已有旧版 Compose 部署在更新前先执行 mkdir -p config && mv config.yaml config/config.yaml。
WebUI 发布到宿主机 9090 端口，可直接访问 http://服务器IP:9090；公网部署请配置防火墙，并优先使用 HTTPS 反向代理。宿主端口可用 SEVENBOT_WEBUI_PORT、SEVENBOT_WS_PORT、SEVENBOT_HTTP_PORT 覆盖，容器内端口仍为 9090、8081、8082。
config/、plugins/、data/ 通过卷挂载，改插件/配置不用重新构建镜像。
容器默认以 UID/GID 1000、只读根文件系统、无 Linux capabilities 和 no-new-privileges 运行。Linux 宿主可在启动前设置 SEVENBOT_UID=$(id -u) 和 SEVENBOT_GID=$(id -g)，初始化容器会让挂载目录归对应用户所有。
更新助手是宿主机上的受限 systemd 服务。SevenBot 只读挂载它的 Unix Socket，主容器及其他辅助容器均不挂载 Docker Socket。helper 只接受带本机密钥的“更新 SevenBot”请求，镜像、Compose 服务和容器名均固定，不能通过 WebUI 传入命令。
安装器要求 Compose 目录位于 /opt、/srv、/usr/local 或 /root 下，并把 Compose 文件与 .env 交给 root 管理；不要把可由机器人运行用户修改的 Compose 文件交给 helper 执行。
Compose 已映射默认的反向 WS 8081 和 HTTP 8082 端口；添加更多监听端口时同步补充端口映射。容器内访问宿主机上的协议端用 host.docker.internal 代替 127.0.0.1。
docker compose ps 会显示 SevenBot 的 WebUI 健康状态；日志默认轮转为最多 3 个 10 MiB 文件，避免长期运行占满磁盘。
常用命令：docker compose logs -f 看日志，docker compose restart 重启，docker compose down 停止。

如果公网访问出现 502 Bad Gateway，先在 Compose 所在目录执行：

docker compose ps -a
docker compose logs --tail=200 sevenbot
curl -i http://127.0.0.1:9090/webui/

本机请求不是 200 时，先根据 sevenbot 日志处理启动失败或重启循环；本机为 200、客户侧仍为 502 时，问题在反向代理、端口转发或客户代理网络。Docker 更新会短暂替换单个 SevenBot 容器，待 docker compose ps 显示 healthy 后刷新即可。

内置更新

登录 WebUI 后进入「系统配置 → 框架更新」：

检查更新：Docker 部署直接读取 GHCR 镜像的版本与提交信息；普通部署读取 GitHub Release 和仍在保留期内的主分支临时构建。版本列表支持正式版、预发布版、临时构建、搜索、指定版本安装和当前版本重新安装。
下载源：普通部署可选择 GitHub 原始地址、内置镜像或自定义 HTTPS 镜像；自动模式会并行测速并缓存结果 30 分钟，下载失败会按延迟自动切换。更新包的 SHA-256 始终与 GitHub 发布信息交叉校验，镜像不能绕过完整性验证。
安装与降级：升级、重新安装和降级都使用同一套暂存流程；降级会显示明确风险确认。页面实时显示镜像测速、下载字节数、速度、解压、依赖安装和等待重启状态。
临时构建：main 每次成功构建都会上传保留 14 天的运行时制品。安装时先校验 GitHub Actions 制品摘要，再校验制品内的运行包 SHA-256；公开仓库使用工作流制品直链，私有仓库使用 SEVENBOT_GITHUB_TOKEN 鉴权下载。
备份与回滚：普通 Node.js 部署会下载 sevenbot-runtime.zip、验证 SHA-256、在独立目录执行 npm ci --omit=dev，然后写入待更新记录；下次通过 npm start 启动时原子替换运行文件并保留最近三个完整运行时备份。可在页面选择备份准备回滚，也可在重启前取消待处理更新。
Docker 更新：Compose 部署通过只读 Unix Socket 通知宿主机 helper 拉取 ghcr.io/seven-tmp/sevenbot:latest，只重建 SevenBot 服务，挂载的配置、插件和数据不变。新容器未通过健康检查时 helper 会恢复更新前的镜像。Docker 历史版本回滚仍应由管理员在宿主机切换镜像标签后重建容器。
单容器 Docker 部署没有受限 helper 通道，页面会显示 helper 安装命令；框架不会在容器内执行 Docker 命令，也不会要求把 Docker Socket 挂入容器。

安全边界

WebUI 管理 Token 永远不能为空；当前 Token 保存在私有配置文件并在启动日志中显示。登录仍有失败限速和同源校验；浏览器只在 localStorage['token'] 保存服务端签发的 30 天凭证，不保存原始 Token。修改 Token 会让既有凭证立即失效。
配置文件与本机密钥强制私有写入。生产环境使用 SEVENBOT_SECRET_KEY_FILE（Compose 自动生成并使用 /app/data/.secret-key），不要把密钥、配置或 data/ 提交到 Git。
WebUI 允许已登录管理员上传受限 ZIP 插件包；导入后默认禁用，必须人工确认后再启用。在线商店安装、任意 SSH 命令和浏览器 SSH 终端仍禁用。插件与主进程共享权限，只能安装经过人工审查的可信插件。
文件管理只开放 config/、plugins/、data/ 和存在时的 logs/。路径穿越、符号链接、隐藏目录、secrets、.git、浏览器资料、数据库和私钥文件会被服务端拒绝；文本编辑和上传分别有独立大小限制，所有变更操作写入安全审计日志。
客户面板使用独立账号、Cookie、浏览器凭证键和 HMAC 会话签名。每个账号强制绑定一个机器人，客户凭证不能通过主面板认证；插件仅只读，聊天不开放踢人、禁言、退群、改群资料、删除群文件/公告或精华管理。
RemoteOps 默认为关闭且所有高权限能力均为关闭。它只接受 remoteOps.allowedTargets 明确列出的目标、固定 SSH SHA-256 主机指纹以及非 root 账号。
OneBot WS/HTTP 的 accessToken/secret 可留空；公网监听时仍建议配置独立随机值，且反向 WS 同时只接受一个客户端。

RemoteOps 如确实需要使用，只能由服务器管理员直接编辑配置，WebUI 无权开启以下能力：

remoteOps:
  enabled: true
  allowedTargets:
    - "203.0.113.10:22"
  allowRoot: false
  allowDeploy: false
  allowDocker: false
  allowShell: false
  hosts:
    - id: host-example
      name: example
      host: 203.0.113.10
      port: 22
      username: sevenbot-deploy
      hostKeySha256: "SHA256:从可信控制台核验的主机指纹"
      authType: privateKey

固定部署任务即使开启，也只允许 image@sha256:digest 形式的 NapCat 镜像、UID/GID 1000 和远端回环端口。不要把宿主 root/Termark 密钥交给 SevenOB11；应为每台目标机使用独立、可撤销、来源受限且最小 sudo 权限的部署账号。

插件写法

📖 完整教程见 插件开发文档（PLUGIN_DEVELOPMENT.md） —— 涵盖生命周期钩子、事件对象、消息发送、配置系统、WebUI 面板扩展、多机器人、插件移植与完整示例。

插件放在 plugins/<插件目录>，入口默认是 index.mjs，也可以在 package.json 写 main。

构建后的插件包可以从 WebUI「插件 → 导入 ZIP」上传。导入目标是右上角当前选中的机器人：导入后只会在该机器人的插件页显示并对其分发事件，其他机器人默认不可见且不生效；可以在「管理 → 按机器人启停」中调整范围。ZIP 内应包含 package.json，入口可由 main 指定，也支持 index.mjs、index.js、main.mjs、main.js，以及外层目录或 dist/ 构建目录。无论上传哪一种受支持的 ZIP 结构，框架都会统一安装为 plugins/<插件 ID>/dist/，构建产物中的 webui/、资源文件和数据模板会保持原目录结构。新插件导入后默认禁用，检查插件信息后再手动启用；更新已有插件时会保留全局启用状态并立即热重载。离线部署也建议使用相同目录结构。依赖其他框架内部实现或额外运行时依赖的插件仍需移植。

export const configSchema = [
  { key: 'reply', type: 'string', label: '回复内容', default: '你好' }
];

export async function onLoad(ctx) {
  ctx.logger.info('loaded');
}

export async function onMessage(ctx, event) {
  if (event.post_type !== 'message') return;
  await ctx.api.sendMsg({
    message_type: event.message_type,
    group_id: event.group_id,
    user_id: event.user_id,
    message: '你好'
  });
}

常用能力：

ctx.api.call(action, params) 调 OneBot API
ctx.api.sendMsg(params) 发送消息
ctx.router.get/post/page/static(...) 注册插件 API 和页面
ctx.config.* 生成配置 Schema
ctx.dataPath、ctx.configPath 存插件数据
ctx.seven.owner 使用“框架主人或当前插件主人”权限规则
ctx.seven.puppeteer.renderHtml(...) 将 HTML 渲染为图片
ctx.seven.puppeteer.screenshot(...) 对网页截图
ctx.seven.puppeteer.status/start/stop/restart() 查看或控制共享浏览器

共享 Puppeteer 支持本地 Chromium 与远程 WebSocket 浏览器、并发队列、失败重试、请求头、等待选择器/延时和 HTML 模板变量。系统配置页提供安装/卸载、启动/停止/重启、代理、并发、视口和在线渲染测试。Docker 镜像只内置运行库与中文字体，Chrome 需要按需安装。常用环境变量：

SEVENBOT_CHROME_EXECUTABLE：本地 Chrome/Chromium 路径
SEVENBOT_CHROME_WS_ENDPOINT：远程浏览器地址，例如 ws://chrome:3000
SEVENBOT_CHROME_DATA_DIR：浏览器配置、缓存和用户目录（默认 data/puppeteer）
SEVENBOT_CHROME_PROFILE_DIR：可选的浏览器 profile 目录；Docker 建议放在容量至少 512 MiB 的 /tmp，避免容器重建后遗留 SingletonLock
SEVENBOT_PUPPETEER_MAX_PAGES：最大并发页面数（默认 5）
SEVENBOT_PUPPETEER_TIMEOUT_MS：默认超时（默认 30000）
SEVENBOT_CHROME_ARGS：JSON 数组或逗号分隔的额外启动参数

WebUI 与聊天接口

WebUI 源码在：

webui/

npm run build:web 使用 Vite 构建到 public/webui-react/。机器人连接、协议端登录、插件 ZIP、插件配置、扩展页和白名单文件管理均在 React WebUI 内管理；仓库不再包含第二套管理页面。打开协议端登录管理或点击「刷新二维码」会向协议端申请新二维码，并等待协议端返回不同的新 URL 后再显示；旧码会立即隐藏。页面每 3 秒只轮询登录状态，不会在轮询时反复更换二维码。

客户面板

只有主面板管理员能在「客户」中创建、修改、停用、删除或重置客户账号；客户不能创建下级账号。管理员为账号绑定一个机器人，并分别授予“聊天”“插件只读”“账号登录”权限。客户使用以下完全独立的入口：

http://服务器地址:9090/client/

客户面板只调用 /api/client/*。服务端会覆盖请求中的 botId，始终使用账号绑定的机器人；即使客户手动修改请求也不能切换机器人。插件列表还会过滤掉未分配给该机器人的插件。QQ 登录只提供二维码，不返回 NapCat 的快速登录历史账号列表。客户账号哈希保存在私有文件 data/client-users.json，停用、删除或重置密码会让既有客户会话立即失效。

常用路径：

/webui/ 管理首页
/client/ 独立客户面板
/api/ClientUsers/* 管理员创建、更新、重置或删除客户账号
/api/client/* 客户最小权限接口（独立认证并强制绑定机器人）
/api/Bots/* 机器人增删、启停与热应用
/api/Plugin/List 插件列表
/api/Plugin/Import ZIP 导入或原地更新
/api/Plugin/Reload 单插件重新扫描与热重载
/api/QQManage/Requests 待处理的加好友与拉群请求
/api/Chat/Conversations 最近会话
/api/Chat/History 群聊或私聊历史消息
/api/Chat/Forward 按消息 ID 读取合并转发内容
/api/Chat/Send 发送文本、回复、@、表情和图片消息段
/api/Chat/Delete、/api/Chat/Poke、/api/Chat/React 撤回、戳一戳和表情回应
/api/Chat/ForwardSingle、/api/Chat/ForwardMerged 单条或多选合并转发
/api/Chat/Upload 群文件或好友文件发送
/api/Chat/Group/* 群成员、文件、公告、精华与群设置管理
/api/File/* 管理员白名单文件浏览、文本编辑、上传下载与文件操作
/api/Chat/Events 新消息实时推送（SSE）
/api/System/Config 系统、WebUI 与 Puppeteer 配置
/api/System/Puppeteer/* 浏览器安装、控制与渲染测试
/api/System/Update/Status 当前版本与更新状态
/api/System/Update/Events 更新状态实时推送（SSE）
/api/System/Update/Versions 可安装 Release 与分页信息
/api/System/Update/Mirrors、/api/System/Update/Mirror/* 下载源选择与测速
/api/System/Update/Backups、/api/System/Update/Rollback 备份列表与回滚准备
/api/System/Update/Check 检查更新
/api/System/Update/Apply 指定版本准备运行包或触发容器更新
/api/System/Update/Cancel 取消尚未重启应用的更新
/api/Plugin/Config?id=插件ID 插件配置
/api/Remote/* 白名单远程主机、固定部署和 Docker 管理
/api/Metrics/Get 运行指标快照
/api/Metrics/GetRealTime 运行指标实时推送（SSE）
/api/Plugin/ext/插件ID/... 插件注册 API
/plugin/插件ID/api/... 插件公开 API
/plugin/插件ID/page/页面路径 插件注册页面

Puppeteer

SevenBot 使用一个懒启动的共享浏览器实例，默认最多同时打开 5 个页面。登录 WebUI 后可在「系统配置 → Puppeteer」安装 Chrome、管理浏览器并进行渲染测试。Windows 也会自动查找已有的 Chrome/Edge；还可连接远程 browserless/Chromium：

SEVENBOT_CHROME_EXECUTABLE=/path/to/chrome
SEVENBOT_CHROME_WS_ENDPOINT=ws://chrome:3000

Docker 镜像默认不安装 Chromium，只提供 Chrome 所需运行库和中文字体；从界面安装的 Chrome 与浏览器数据位于持久化的 data/puppeteer。容器本身采用非 root、只读根文件系统、无 capabilities 与 no-new-privileges 隔离，因此容器内通过 SEVENBOT_CHROME_NO_SANDBOX=1 关闭浏览器自身沙箱；宿主机运行时默认不会关闭 Chrome 沙箱。

若当前 CPU/系统没有对应的 Chrome for Testing 下载包（部分 ARM64 环境），请在页面填写已有浏览器路径，或使用 SEVENBOT_CHROME_WS_ENDPOINT 连接远程 browserless/Chromium。

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github/workflows		.github/workflows
deploy		deploy
public/webui-assets		public/webui-assets
scripts		scripts
src		src
test		test
webui		webui
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
PLUGIN_DEVELOPMENT.md		PLUGIN_DEVELOPMENT.md
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

SevenBot框架

快速开始

连接 OneBot11 实现端

反向 WebSocket（推荐）

正向 WebSocket

HTTP

插件热重载

配置热加载

Docker 部署

直接拉取镜像运行

使用 Compose

内置更新

安全边界

插件写法

WebUI 与聊天接口

客户面板

Puppeteer

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

SevenBot框架

快速开始

连接 OneBot11 实现端

反向 WebSocket（推荐）

正向 WebSocket

HTTP

插件热重载

配置热加载

Docker 部署

直接拉取镜像运行

使用 Compose

内置更新

安全边界

插件写法

WebUI 与聊天接口

客户面板

Puppeteer

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages