🌐 WebUI 管理面板使用指南

本文档介绍 Sakura-Bot WebUI 管理面板的配置和使用方法。

分类: 用户文档
类型: 操作指南
难度: ⭐⭐
更新时间: 2026-05-02

← 返回用户文档 | Wiki 首页

📖 概述

Sakura-Bot WebUI 是一个基于 Vue.js 的 Web 管理界面，提供了可视化的频道管理、统计查看、总结触发等功能，无需通过 Telegram 命令即可完成大部分管理操作。

主要功能

📊 仪表盘 - 查看 Bot 运行状态、总结数量、频道统计等
📺 频道管理 - 查看、添加、删除监控频道
⏰ 调度配置 - 配置频道自动总结时间
📝 总结生成 - 从 WebUI 直接触发频道总结
📤 转发管理 - 管理频道转发规则
🗄️ 数据库管理 - 浏览 MySQL 表、分页查询和执行受控数据操作
🤖 AI 配置 - 查看 AI 配置信息
📊 统计信息 - 查看详细的运行统计
⚙️ 系统操作 - 查看状态、调整日志级别、暂停/恢复任务和优雅重启
🌙 深色主题 - 支持深色/浅色主题切换

🚀 快速开始

1. 启用 WebUI

在 data/.env 中添加以下配置：

env

# ===== WebUI 管理面板配置 =====
WEBUI_ENABLED=true
WEBUI_HOST=0.0.0.0
WEBUI_PORT=8080

2. 启动 Bot

bash

python main.py

Bot 启动后会自动启动 WebUI 服务器。

3. 访问面板

打开浏览器访问：

本地：http://localhost:8080
局域网：http://<服务器IP>:8080

🔐 认证说明

JWT 认证

WebUI 使用 JWT（JSON Web Token）进行身份验证：

使用管理员 Telegram ID 进行登录
登录后生成 JWT Token，后续请求自动携带
Token 有效期内无需重复登录

开发模式

在开发环境中，可以启用免认证登录：

env

WEBUI_DEV_MODE=true

⚠️ 警告：开发模式会跳过身份验证，仅用于本地开发环境，切勿在生产环境中启用！

📋 功能详解

仪表盘

仪表盘页面展示 Bot 的整体运行状态：

总结总数
监控频道数量
转发规则数量
Bot 运行状态
最近活动记录

频道总结生成

在 WebUI 中可以直接触发频道总结：

导航到总结页面
选择目标频道
点击「生成总结」按钮
等待 AI 完成总结生成

转发规则管理

转发页面支持可视化管理频道转发规则：

启用或禁用全局转发功能
添加、编辑、删除转发规则
配置关键词/正则白名单和黑名单
切换复制模式、只转发原创消息和默认底栏
使用底栏模板与占位符快速生成自定义底栏

常用底栏占位符包括：{source_link}、{source_title}、{target_title}、{source_channel}、{target_channel}、{message_id}、{assistant_bot}、{submission}。

配置保存后会显式触发热重载，转发规则通常无需重启即可生效；系统会对重复热重载事件进行去重。

数据库管理

数据库页面用于管理员排查和维护 MySQL 数据：

查看允许管理的数据表列表和行数
按页浏览表数据，避免一次加载大量记录
新增、编辑、删除单行数据
在必要时执行清空数据并重启等维护操作

⚠️ 数据库管理属于高危功能。操作前请确认已备份数据，并仅允许可信管理员访问 WebUI。

配置保存即时生效

WebUI 保存配置后会主动触发配置热重载，使以下配置更快应用：

AI 客户端与提示词配置
自动总结调度任务
频道转发规则和底栏模板
日志级别等运行时配置

如果外部工具直接修改 data/config.json，文件监听仍会处理变更；WebUI 保存与文件监听同时触发时会尽量去重。

深色主题

WebUI 支持深色/浅色主题切换：

点击右上角主题切换按钮
主题选择会自动保存到浏览器
下次访问时自动应用上次选择的主题

🔧 配置参考

配置项	环境变量	默认值	说明
启用 WebUI	`WEBUI_ENABLED`	`false`	是否启用 WebUI 管理面板
监听地址	`WEBUI_HOST`	`0.0.0.0`	WebUI 监听的 IP 地址
监听端口	`WEBUI_PORT`	`8080`	WebUI 监听的端口号
开发模式	`WEBUI_DEV_MODE`	`false`	启用免认证开发模式

❓ 常见问题

无法访问 WebUI

确认 WEBUI_ENABLED=true 已设置
检查防火墙是否放行了 WebUI 端口
确认 Bot 已正常启动并初始化了 WebUI

登录失败

确认使用的 Telegram ID 在管理员列表中
检查 .env 中 REPORT_ADMIN_IDS 配置是否正确

深色主题不生效

清除浏览器缓存后重试
确认浏览器支持 localStorage

配置保存后没有生效

确认保存请求返回成功
查看 Bot 日志中是否出现配置重载错误
对转发规则，确认源频道和目标频道可被 Bot 或 UserBot 访问
如仍未生效，可通过 WebUI 或命令执行优雅重启

数据库管理操作失败

确认当前用户是管理员
确认 MySQL 连接正常
检查目标表和列是否在允许管理范围内
查看日志中的详细错误，避免重复提交危险操作

🏗️ 技术架构

WebUI 采用前后端分离架构：

后端：FastAPI (Python) - 提供 RESTful API
前端：Vue.js 3 + Vite - 构建现代化单页应用
认证：JWT Token
路由：SPA 路由（前端路由 + 后端 fallback）

← 返回用户文档 | Wiki 首页

🌐 WebUI 管理面板使用指南 ​

📖 概述 ​

主要功能 ​

🚀 快速开始 ​

1. 启用 WebUI ​

2. 启动 Bot ​

3. 访问面板 ​

🔐 认证说明 ​

JWT 认证 ​

开发模式 ​

📋 功能详解 ​

仪表盘 ​

频道总结生成 ​

转发规则管理 ​

数据库管理 ​

配置保存即时生效 ​

深色主题 ​

🔧 配置参考 ​

❓ 常见问题 ​

无法访问 WebUI ​

登录失败 ​

深色主题不生效 ​

配置保存后没有生效 ​

数据库管理操作失败 ​

🏗️ 技术架构 ​