Initial commit: SenSu Alpha 0.2.0
- 13-service async plugin framework - Textual TUI with CLI fallback - Plugin hot-reload + permission system - Web management panel (aiohttp) - Bridge-based inter-module communication - 10 regression tests Fixes applied: - PBKDF2-SHA256 auth (was plain SHA256) - Auth bypass removed (was allow-all on fail) - Bare excepts replaced with logged errors - CatFramework/DreamSu -> SenSu naming unified - ServiceManager: health checks + startup_order - Env var credentials (SENSU_ADMIN_PASSWORD etc)
This commit is contained in:
@@ -0,0 +1,398 @@
|
||||
|
||||
## 一、项目架构与设计思路
|
||||
|
||||
### 1.1 核心设计理念
|
||||
|
||||
SenSu框架采用了**服务化、插件化、事件驱动**的设计理念：
|
||||
|
||||
- **模块化服务架构**：每个功能都是一个独立服务（Service），通过ServiceManager统一管理
|
||||
- **异步优先**：全面采用`asyncio`，支持高并发处理
|
||||
- **插件隔离**：插件有独立的命名空间和权限控制
|
||||
- **桥接通信**：通过消息桥接实现模块间解耦通信
|
||||
|
||||
### 1.2 框架启动流程
|
||||
|
||||
```
|
||||
main.py → CatFramework.initialize() → 依次初始化12个核心服务
|
||||
```
|
||||
|
||||
**启动顺序**：
|
||||
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 # 优雅关闭
|
||||
│
|
||||
├── fmfuncs/ # 框架功能集（工具函数）
|
||||
│ └── 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 fmfuncs.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`入手，逐步理解框架的各个组件，然后根据业务需求开发定制插件。
|
||||
Reference in New Issue
Block a user