qinglong
eeca8e37e1
- README: 新增文件管理器特性/Web面板路由/架构更新 - 框架架构文档: 新增第十章 v0.6.0 WebUI重构+文件管理器+WS推送+MD3主题 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
484 lines
15 KiB
Markdown
484 lines
15 KiB
Markdown
|
||
## 一、项目架构与设计思路
|
||
|
||
### 1.1 核心设计理念
|
||
|
||
SenSu框架采用了**服务化、插件化、事件驱动**的设计理念：
|
||
|
||
- **模块化服务架构**：每个功能都是一个独立服务（Service），通过ServiceManager统一管理
|
||
- **异步优先**：全面采用`asyncio`，支持高并发处理
|
||
- **插件隔离**：插件有独立的命名空间和权限控制
|
||
- **桥接通信**：通过消息桥接实现模块间解耦通信
|
||
|
||
### 1.2 框架启动流程
|
||
|
||
```
|
||
main.py → SenSuFramework.initialize() → 依次初始化15+个核心服务
|
||
```
|
||
|
||
**启动顺序**：
|
||
1. InitService（配置加载）
|
||
2. LogService（日志系统）
|
||
3. CoreBridge（核心消息桥接）
|
||
4. CommandService（命令系统）
|
||
5. AuthService（认证系统）
|
||
6. PluginBridge（插件桥接）
|
||
7. ShutdownService（优雅关闭）
|
||
8. TuiService（终端界面）
|
||
9. PermissionService（权限管理）
|
||
10. InternetService（网络服务）
|
||
11. PluginService（插件管理）
|
||
12. APIService（API服务）
|
||
|
||
## 二、目录结构详细分析
|
||
|
||
### 2.1 核心目录说明
|
||
|
||
```
|
||
SenSu-Alpha0.2/
|
||
├── main.py # 框架主入口，定义CatFramework类
|
||
├── service_manager.py # 服务管理器（全局服务注册表）
|
||
├── requirements.txt # Python依赖包
|
||
├── README.md # 项目文档
|
||
│
|
||
├── bridges/ # 消息桥接系统
|
||
│ ├── __init__.py
|
||
│ ├── core_bridge.py # 核心模块间通信（发布-订阅模式）
|
||
│ ├── plugin_bridge.py # 插件间通信
|
||
│ └── plugin_network_bridge.py # 插件网络桥接
|
||
│
|
||
├── services/ # 核心服务模块（核心业务逻辑）
|
||
│ ├── init_service.py # 框架初始化
|
||
│ ├── log_service.py # 日志服务（多输出、文件切割）
|
||
│ ├── tui_service.py # TUI终端界面（基于Textual）
|
||
│ ├── command_service.py # 命令处理系统
|
||
│ ├── auth_service.py # 认证系统
|
||
│ ├── internet_service.py # 网络服务（HTTP+WebSocket）
|
||
│ ├── plugin_service.py # 插件管理器
|
||
│ ├── permission_service.py # 权限验证器
|
||
│ ├── api_service.py # API端点管理
|
||
│ └── shutdown_service.py # 优雅关闭
|
||
│
|
||
├── core/ # 框架功能集（工具函数）
|
||
│ └── plugin_command_decorator.py # 插件命令装饰器
|
||
│
|
||
├── utils/ # 通用工具类
|
||
│ ├── file_utils.py # 文件操作
|
||
│ ├── config_utils.py # 配置管理
|
||
│ ├── validation_utils.py # 数据验证
|
||
│ ├── network_utils.py # 网络工具
|
||
│ └── plugin_utils.py # 插件工具
|
||
│
|
||
├── config/ # 运行时配置文件
|
||
│ ├── framework/ # 框架核心配置
|
||
│ ├── plugins/ # 插件配置
|
||
│ ├── services/ # 服务配置
|
||
│ └── permissions/ # 权限配置
|
||
│
|
||
├── plugins/ # 插件目录
|
||
│ └── example_plugin/ # 示例插件
|
||
│
|
||
└── gui/ # GUI接口（预留）
|
||
└── api.py # Web API接口
|
||
```
|
||
|
||
### 2.3 配置管理系统
|
||
|
||
框架使用**两级配置**：
|
||
1. **Base Config** (`config/framework/base_config.yaml`): 框架基础配置
|
||
2. **Runtime Config**: 运行时动态生成的配置（保存在config目录）
|
||
|
||
## 三、核心模块深度解析
|
||
|
||
### 3.1 服务管理器（ServiceManager）
|
||
|
||
**作用**：全局服务注册表，实现依赖注入
|
||
```python
|
||
# 注册服务
|
||
service_manager.register_service("log", log_service)
|
||
|
||
# 获取服务
|
||
log_service = service_manager.get_service("log")
|
||
```
|
||
|
||
### 3.2 桥接系统（Bridges）
|
||
|
||
**核心设计**：
|
||
- **CoreBridge**: 模块间通信，支持`MessageType`枚举
|
||
- **PluginBridge**: 插件间通信，支持`PluginMessageType`枚举
|
||
- **消息格式**：topic + data + timestamp
|
||
|
||
**消息类型**：
|
||
```python
|
||
class MessageType(Enum):
|
||
EVENT = "event" # 事件通知
|
||
COMMAND = "command" # 命令执行
|
||
DATA = "data" # 数据传输
|
||
STATUS = "status" # 状态更新
|
||
ERROR = "error" # 错误报告
|
||
```
|
||
|
||
### 3.3 日志系统（LogService）
|
||
|
||
**特性**：
|
||
- 支持控制台和文件双输出
|
||
- 按级别分离（runtime/debug）
|
||
- 自动文件切割和清理
|
||
- 日志消费者模式（TUI实时显示）
|
||
- 彩色日志输出
|
||
|
||
**配置示例**：
|
||
```yaml
|
||
logging:
|
||
level: DEBUG
|
||
debug_level_file: true
|
||
max_file_size: 10MB
|
||
max_log_files: 20
|
||
```
|
||
|
||
### 3.4 TUI界面（TuiService）
|
||
|
||
**基于Textual框架的三栏布局**：
|
||
1. **日志区域**（4fr）: 显示所有日志输出
|
||
2. **消息区域**（5fr）: 显示系统消息和命令结果
|
||
3. **输入区域**（1fr）: 命令输入框
|
||
|
||
**特性**：
|
||
- 实时日志捕获和显示
|
||
- 命令自动补全（预留）
|
||
- 滚动控制（自动/手动）
|
||
- 彩色消息显示
|
||
|
||
### 3.5 网络服务（InternetService）
|
||
|
||
**功能**：
|
||
- HTTP服务器（aiohttp）
|
||
- WebSocket服务器
|
||
- 插件路由自动注册
|
||
- 反向代理支持（预留）
|
||
|
||
**端口配置**：
|
||
```yaml
|
||
internet:
|
||
websocket:
|
||
port: 8765
|
||
http:
|
||
port: 8000
|
||
```
|
||
|
||
### 3.6 插件系统（PluginService）
|
||
|
||
**关键特性**：
|
||
- 热加载/卸载
|
||
- 权限隔离
|
||
- 命令自动注册
|
||
- 错误隔离（插件崩溃不影响框架）
|
||
- 网络路由自动注册
|
||
|
||
## 四、插件开发详解
|
||
|
||
### 4.1 插件目录结构
|
||
|
||
```
|
||
plugins/
|
||
└── example_plugin/
|
||
├── __init__.py # 插件主类（必须包含Plugin类）
|
||
├── config.yaml # 插件配置
|
||
└── permissions.yaml # 权限申请
|
||
```
|
||
|
||
### 4.2 插件主类模板
|
||
|
||
```python
|
||
class Plugin:
|
||
def __init__(self, plugin_name: str, config: Dict, bridge):
|
||
self.plugin_name = plugin_name
|
||
self.config = config
|
||
self.bridge = bridge # PluginBridge实例
|
||
self.network_bridge = None # PluginNetworkBridge实例
|
||
|
||
async def initialize(self):
|
||
"""插件初始化"""
|
||
# 1. 创建网络桥接
|
||
self.network_bridge = PluginNetworkBridge(...)
|
||
|
||
# 2. 注册网络路由
|
||
await self.network_bridge.register_http_route(...)
|
||
await self.network_bridge.register_websocket(...)
|
||
|
||
# 3. 注册事件处理器
|
||
self.bridge.subscribe_plugin(...)
|
||
|
||
# 使用装饰器注册命令
|
||
@plugin_command(name="mycmd", description="我的命令")
|
||
async def my_command(self, *args):
|
||
return "命令执行结果"
|
||
|
||
async def shutdown(self):
|
||
"""插件关闭"""
|
||
# 清理资源
|
||
```
|
||
|
||
### 4.3 权限申请文件（permissions.yaml）
|
||
|
||
```yaml
|
||
plugin_name: "example_plugin"
|
||
permissions:
|
||
- "plugin.example.read"
|
||
- "plugin.example.write"
|
||
- "plugin.example.execute"
|
||
- "framework.event.subscribe"
|
||
- "framework.command.execute"
|
||
```
|
||
|
||
### 4.4 插件配置文件（config.yaml）
|
||
|
||
```yaml
|
||
name: "ExamplePlugin"
|
||
version: "1.0.0"
|
||
description: "插件描述"
|
||
author: "作者名"
|
||
|
||
settings:
|
||
enabled: true
|
||
auto_start: true
|
||
log_level: "INFO"
|
||
|
||
features:
|
||
# 插件特有配置
|
||
```
|
||
|
||
### 4.5 插件命令装饰器
|
||
|
||
框架提供了`@plugin_command`装饰器：
|
||
|
||
```python
|
||
from core.plugin_command_decorator import plugin_command
|
||
|
||
@plugin_command(name="echo", description="回显消息")
|
||
async def cmd_echo(self, *args):
|
||
return " ".join(args)
|
||
|
||
# 简化版
|
||
@plugin_command()
|
||
async def hello(self, *args):
|
||
'''打招呼命令'''
|
||
return "Hello World!"
|
||
```
|
||
|
||
### 4.6 插件网络功能
|
||
|
||
**HTTP路由注册**：
|
||
```python
|
||
await self.network_bridge.register_http_route(
|
||
"/api/info",
|
||
self._handle_api_info,
|
||
methods=["GET"],
|
||
require_auth=False
|
||
)
|
||
```
|
||
|
||
**WebSocket注册**：
|
||
```python
|
||
await self.network_bridge.register_websocket(
|
||
"/chat",
|
||
self._handle_websocket_chat
|
||
)
|
||
```
|
||
|
||
## 五、命令系统详解
|
||
|
||
### 5.1 内置命令
|
||
|
||
框架提供丰富的内置命令：
|
||
- `help` - 显示帮助
|
||
- `status` - 框架状态
|
||
- `history` - 命令历史
|
||
- `testlog` - 测试日志生成
|
||
- `netdiag` - 网络诊断
|
||
- `permissions` - 权限管理
|
||
- `scroll` - 滚动控制
|
||
- `autoscroll` - 自动滚动开关
|
||
|
||
### 5.2 权限管理命令
|
||
|
||
框架提供完整的权限管理命令集（pm前缀）：
|
||
- `pmallow` - 同意权限请求
|
||
- `pmdeny` - 拒绝权限请求
|
||
- `pmignore` - 忽略权限请求
|
||
- `permissions` - 显示权限状态
|
||
- `pmpending` - 查看待授权请求
|
||
- `pmhelp` - 权限命令帮助
|
||
|
||
### 5.3 命令注册机制
|
||
|
||
**插件命令注册流程**：
|
||
1. PluginService扫描插件方法
|
||
2. 识别`@plugin_command`装饰器
|
||
3. 注册到CommandService
|
||
4. 命令格式：`命令名 [参数...]`
|
||
|
||
## 六、开发建议与最佳实践
|
||
|
||
### 6.1 插件开发建议
|
||
|
||
1. **错误处理**：插件内应妥善处理异常，避免影响框架
|
||
2. **资源管理**：在`shutdown`方法中清理所有资源
|
||
3. **异步安全**：确保异步方法正确处理取消和超时
|
||
4. **权限最小化**：只申请必要的权限
|
||
|
||
### 6.2 性能优化
|
||
|
||
1. **异步IO**：所有网络和文件操作使用异步版本
|
||
2. **连接池**：数据库/网络连接使用连接池
|
||
3. **缓存机制**：频繁读取的数据适当缓存
|
||
4. **懒加载**：大型资源按需加载
|
||
|
||
### 6.3 安全性考虑
|
||
|
||
1. **输入验证**：所有外部输入都应验证
|
||
2. **权限验证**：敏感操作前检查权限
|
||
3. **日志脱敏**：避免在日志中记录敏感信息
|
||
4. **API限流**：防止API被滥用
|
||
|
||
## 七、框架优势与特点
|
||
|
||
### 7.1 优势
|
||
1. **完整的生态**：日志、网络、UI、插件系统一应俱全
|
||
2. **良好的扩展性**：插件系统设计完善
|
||
3. **生产级质量**：完善的错误处理和日志记录
|
||
4. **开发者友好**：详细的文档和示例插件
|
||
|
||
### 7.2 适用场景
|
||
1. **后台管理工具**：需要终端界面的管理工具
|
||
2. **API网关**：插件化路由和认证
|
||
3. **自动化平台**：可扩展的任务调度和执行
|
||
4. **监控系统**：实时数据展示和告警
|
||
|
||
### 7.3 技术栈亮点
|
||
- **异步架构**：asyncio全面应用
|
||
- **现代化UI**：基于Textual的TUI
|
||
- **微服务理念**：服务化模块设计
|
||
- **企业级特性**：权限、认证、日志一应俱全
|
||
|
||
## 八、后续发展建议
|
||
|
||
### 8.1 功能增强
|
||
1. **数据库支持**：添加ORM或数据库连接池
|
||
2. **任务队列**：集成Celery或类似系统
|
||
3. **监控指标**：集成Prometheus指标导出
|
||
4. **配置文件热重载**：支持运行时配置更新
|
||
|
||
### 8.2 易用性改进
|
||
1. **插件市场**：在线插件安装和管理
|
||
2. **配置生成器**：图形化配置界面
|
||
3. **调试工具**：集成调试和性能分析
|
||
4. **文档生成**：自动生成API文档
|
||
|
||
### 8.3 生态建设
|
||
1. **插件模板**：快速创建插件的脚手架
|
||
2. **测试框架**：插件测试工具
|
||
3. **CI/CD集成**：自动化测试和部署
|
||
4. **社区建设**：建立插件开发者社区
|
||
|
||
## 总结
|
||
|
||
SenSu框架是一个设计精良、功能完整的Python后端框架，具有以下核心价值：
|
||
|
||
1. **工程化设计**：服务化架构、完善的错误处理、详细的日志
|
||
2. **强大的插件系统**：支持热加载、权限隔离、网络路由自动注册
|
||
3. **现代化的用户体验**：基于Textual的TUI界面，美观实用
|
||
4. **企业级特性**：完整的权限管理、认证系统、网络服务
|
||
|
||
框架代码结构清晰，文档详细，适合作为：
|
||
- 企业级后台系统的基础框架
|
||
- 插件化应用的核心引擎
|
||
- 学习和研究现代Python框架设计的优秀案例
|
||
|
||
对于想要基于此框架进行开发的开发者，建议从`example_plugin`入手，逐步理解框架的各个组件，然后根据业务需求开发定制插件。
|
||
---
|
||
|
||
## 九、v0.2.1 新增：插件系统增强
|
||
|
||
### 9.1 PluginStatus 枚举 (`core/plugin_status.py`)
|
||
统一的插件生命周期状态：
|
||
- `UNLOADED` → `LOADING` → `LOADED` → `INITIALIZING` → `RUNNING`
|
||
- 异常路径: `ERROR`, `STOPPING`, `STOPPED`, `UNLOADING`
|
||
|
||
### 9.2 PluginError 异常层级 (`core/plugin_error.py`)
|
||
```
|
||
PluginError (基础)
|
||
├── PluginLoadError (加载失败)
|
||
├── PluginConfigError (配置错误)
|
||
├── PluginPermissionError (权限不足)
|
||
├── PluginCommandError (命令执行错误)
|
||
└── PluginNetworkError (网络操作错误)
|
||
```
|
||
|
||
### 9.3 PluginBridge 新方法
|
||
- `subscribe_plugin(topic, handler, plugin_name)` — 便捷订阅，同时注册到 CoreBridge 和插件订阅表
|
||
|
||
### 9.4 PluginNetworkBridge 新方法
|
||
- `setup_data_transfer(event_type, handler)` — 跨插件数据传输通道
|
||
- `send_data(target_plugin, event_type, data)` — 向其他插件发送数据
|
||
|
||
### 9.5 PluginService 增强
|
||
- 配置验证：加载时检查 `name`、`version` 必需字段
|
||
- 状态追踪：`plugin_status` 字典跟踪每个插件的 `PluginStatus`
|
||
|
||
## 十、v0.6.0 新增：WebUI 重构 + 文件管理器
|
||
|
||
### 10.1 Web 面板路由 (services/web_panel/)
|
||
|
||
v0.6.0 将 Web 面板重构为模块化路由架构：
|
||
|
||
```
|
||
services/web_panel/
|
||
├── manager.py # WebPanelManager — 路由注册 + 静态挂载
|
||
├── routes/
|
||
│ ├── auth.py # 认证 API (login/logout/status)
|
||
│ ├── status.py # 框架/系统状态 + WS 实时推送
|
||
│ ├── plugins.py # 插件管理 API
|
||
│ ├── commands.py # 命令执行 API
|
||
│ ├── logs.py # 日志 WS 广播
|
||
│ ├── projects.py # 项目引擎 API (run/stop/logs/stdin)
|
||
│ ├── proxy.py # 反向代理 API
|
||
│ ├── plugin_web.py # 插件 Web 页面动态路由
|
||
│ └── files.py # 文件管理器 API (11 个端点) ← NEW
|
||
└── utils/
|
||
├── auth.py # panel_auth 装饰器
|
||
└── system_info.py # 跨平台系统信息采集
|
||
```
|
||
|
||
### 10.2 文件管理器 (v0.6.0)
|
||
|
||
- **后端**: `services/web_panel/routes/files.py` — 11 个 REST 端点
|
||
- 列表/新建/删除/重命名/上传/下载/读写/文件信息
|
||
- 全文件系统访问，`os.path.normpath` 防路径穿越
|
||
- 跨平台: Windows 盘符枚举 + Linux `/` 根
|
||
- 符号链接: `stat()` 跟踪 → `lstat()` fallback 处理损坏
|
||
- **前端**: `pages/files.html` + `pages/files.js`
|
||
- 面包屑导航 (每层级可点击) + 可编辑路径跳转
|
||
- 双层面包屑 (逻辑路径 + 物理路径，符号链接目录)
|
||
- 右键菜单 (下载/重命名/编辑/删除)
|
||
- 文本编辑器 (全屏覆盖层)
|
||
- 文件上传 (多文件, ≤50MB)
|
||
- `..` 行返回上级
|
||
- **插件接口**: Picker API (`/api/files/picker`)
|
||
- 插件通过 `window.open` + `postMessage` 唤出选择器
|
||
- 权限: `filemanager.picker` / `filemanager.access` / `filemanager.write`
|
||
|
||
### 10.3 WebSocket 实时推送
|
||
|
||
- `/api/system/ws` — 每 2s 推送系统 + 框架数据 (替代 HTTP 轮询)
|
||
- `/api/logs/ws` — 日志广播，前端批量渲染 + 500 行上限防卡死
|
||
- 仪表盘: DualLineChart 双线图 (下载实线/上传虚线)，Y 轴零点偏移
|
||
|
||
### 10.4 MD3 主题系统
|
||
|
||
- CSS 变量完整 MD3 color tokens (Dark + Light 双主题)
|
||
- `data-theme` 属性切换，localStorage 持久化
|
||
- 按钮组合模式: `btn` + `btn-tonal`/`btn-outlined`/`btn-filled` + `btn-sm`
|
||
- SVG 全局 `fill: currentColor` 自适应主题色
|
||
- 动画: 波纹/卡片悬浮/页面淡入/状态脉冲/骨架屏
|