Update docs: README + project structure for v0.5
This commit is contained in:
@@ -1,145 +1,125 @@
|
||||
# 🐱 SenSu
|
||||
|
||||
一个功能强大的Python后端框架，具有插件化架构和丰富的功能集。
|
||||
万能 Python TUI 项目管理器 — 插件化架构，任何项目都能挂载运行。
|
||||
|
||||
[](LICENSE)
|
||||
[]()
|
||||
|
||||
---
|
||||
|
||||
## ✨ 特性
|
||||
|
||||
- 🎨 **TUI界面**: 基于Textual的终端用户界面
|
||||
- 📝 **强大日志系统**: 多输出、文件切割、实时日志流
|
||||
- 🔌 **插件化架构**: 热加载、权限管理、插件隔离
|
||||
- 🌐 **网络服务**: WebSocket、HTTP API、反向代理
|
||||
- 🔐 **认证系统**: 用户认证、令牌管理、权限验证
|
||||
- 🔄 **消息桥接**: 模块间通信、插件间通信
|
||||
- ⚡ **高性能**: 异步架构、协程支持
|
||||
- 🛡️ **安全**: 权限验证、输入验证、错误隔离
|
||||
- 🎨 **Textual TUI** — 三栏界面 + 系统监控面板 + CLI 回退
|
||||
- 🔌 **插件系统** — 热加载、权限隔离、依赖解析、进程隔离
|
||||
- 🗄️ **项目注册表** — 插件声明 `project.yaml` 申请端口和资源
|
||||
- 📊 **SQLite 持久化** — 插件状态、权限、审计日志统一存储
|
||||
- 🌐 **Web 管理面板** — aiohttp + WebSocket，:4200 实时仪表盘
|
||||
- 🔐 **安全认证** — PBKDF2-SHA256、环境变量密码、Token 管理
|
||||
- 🐳 **Docker 部署** — Alpine 镜像 <100MB，systemd 服务文件
|
||||
- 🧪 **23 个回归测试** — pytest，零失败
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 运行框架
|
||||
|
||||
```bash
|
||||
# 启动 (TUI 模式)
|
||||
python main.py
|
||||
|
||||
# 启动 (headless，适合 SSH/systemd/Docker)
|
||||
python main.py --headless
|
||||
|
||||
# 运行测试
|
||||
python -m pytest tests/ -v
|
||||
```
|
||||
|
||||
### 基本命令
|
||||
|
||||
在TUI底部输入框中输入命令：
|
||||
|
||||
- `help` - 显示帮助信息
|
||||
- `status` - 显示框架状态
|
||||
- `history` - 显示命令历史
|
||||
|
||||
## 📁 项目结构
|
||||
## 🏗️ 架构
|
||||
|
||||
```
|
||||
project_root/
|
||||
├── main.py # 框架主入口
|
||||
├── service_manager.py # 服务管理器
|
||||
├── requirements.txt # 依赖包列表
|
||||
├── README.md # 项目说明
|
||||
│
|
||||
├── config/ # 运行时生成的配置文件
|
||||
│ ├── framework/ # 框架核心配置
|
||||
│ ├── plugins/ # 插件配置
|
||||
│ ├── services/ # 服务配置
|
||||
│ └── permissions/ # 权限配置
|
||||
│
|
||||
├── logs/ # 日志文件目录
|
||||
│ ├── debug/ # debug级别日志
|
||||
│ └── runtime/ # 运行时日志
|
||||
│
|
||||
├── services/ # 核心服务模块
|
||||
│ ├── init_service.py # 初始化服务
|
||||
│ ├── log_service.py # 日志服务
|
||||
│ ├── tui_service.py # TUI服务
|
||||
│ ├── command_service.py # 指令服务
|
||||
│ ├── auth_service.py # 认证服务
|
||||
│ ├── internet_service.py # 互联网服务
|
||||
│ ├── plugin_service.py # 插件服务
|
||||
│ ├── permission_service.py # 权限服务
|
||||
│ ├── api_service.py # API服务
|
||||
│ └── shutdown_service.py # 关闭服务
|
||||
│
|
||||
├── bridges/ # 桥接模块
|
||||
│ ├── core_bridge.py # 核心桥接
|
||||
│ └── plugin_bridge.py # 插件桥接
|
||||
│
|
||||
├── core/ # 框架功能集
|
||||
│ ├── file_utils.py # 文件操作工具
|
||||
│ ├── config_utils.py # 配置工具
|
||||
│ ├── validation_utils.py # 验证工具
|
||||
│ ├── network_utils.py # 网络工具
|
||||
│ └── plugin_utils.py # 插件工具
|
||||
│
|
||||
├── plugins/ # 插件目录
|
||||
│ └── example_plugin/ # 示例插件
|
||||
│
|
||||
└── gui/ # GUI接口
|
||||
└── api.py # GUI操作接口
|
||||
main.py → SenSuFramework
|
||||
├─ ServiceManager (15 服务)
|
||||
├─ CoreBridge ⇄ PluginBridge ⇄ NetworkBridge
|
||||
├─ PluginService (热加载 + 依赖解析)
|
||||
├─ ProjectService (项目注册表 + 端口分配)
|
||||
├─ SenSuDB (SQLite 5 表)
|
||||
├─ TuiService (Textual + 系统监控)
|
||||
├─ InternetService (HTTP :4200 + WS :4240)
|
||||
├─ WebPanel (管理面板 /SenSu)
|
||||
└─ PermissionService (4 级权限)
|
||||
```
|
||||
|
||||
## 📁 目录结构
|
||||
|
||||
```
|
||||
SenSu-Alpha/
|
||||
├── main.py # 框架入口
|
||||
├── service_manager.py # 服务注册表
|
||||
├── sdk/ # 插件开发工具包
|
||||
│ ├── plugin_command_decorator.py
|
||||
│ ├── plugin_status.py
|
||||
│ └── plugin_error.py
|
||||
├── services/ # 核心服务 (15 个)
|
||||
│ ├── sensu_db.py # SQLite 持久化
|
||||
│ ├── project_service.py # 项目注册表
|
||||
│ ├── process_isolated.py # 进程隔离
|
||||
│ └── sysmon_widget.py # 系统监控
|
||||
├── bridges/ # 消息桥接
|
||||
├── plugins/ # 插件目录
|
||||
├── deploy/ # 部署文件
|
||||
│ ├── sensu.service # systemd
|
||||
│ └── Dockerfile # Docker
|
||||
├── tests/ # 23 个测试
|
||||
└── docs/ # 开发文档
|
||||
```
|
||||
|
||||
## 🔌 插件开发
|
||||
|
||||
### 创建插件
|
||||
```python
|
||||
# plugins/my_plugin/__init__.py
|
||||
from sdk.plugin_command_decorator import plugin_command
|
||||
|
||||
1. 在 `plugins/` 目录下创建插件文件夹
|
||||
2. 创建必要的配置文件：
|
||||
- `__init__.py` - 插件主模块
|
||||
- `config.yaml` - 插件配置
|
||||
- `permissions.yaml` - 权限申请
|
||||
class Plugin:
|
||||
def __init__(self, plugin_name=None, config=None, bridge=None):
|
||||
self.plugin_name = plugin_name
|
||||
self.bridge = bridge
|
||||
|
||||
### 插件示例
|
||||
async def initialize(self):
|
||||
# 注册网络路由
|
||||
await self.network_bridge.register_http_route(
|
||||
"/api/my/info", self._handler, methods=["GET"])
|
||||
|
||||
参考 `plugins/example_plugin/` 目录中的示例插件。
|
||||
@plugin_command(name="hello", description="打招呼")
|
||||
async def cmd_hello(self, *args):
|
||||
return f"Hello from {self.plugin_name}!"
|
||||
|
||||
## 🔧 配置说明
|
||||
async def shutdown(self):
|
||||
pass
|
||||
```
|
||||
|
||||
框架配置位于 `config/framework/` 目录：
|
||||
详细文档见 `docs/SenSu 插件开发详细指南.md`
|
||||
|
||||
- `base_config.yaml` - 基础框架配置
|
||||
- `permission_rules.yaml` - 权限规则配置
|
||||
## 🌐 API 端点
|
||||
|
||||
## 📡 API接口
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/health` | 健康检查 |
|
||||
| GET | `/SenSu/` | Web 管理面板 |
|
||||
| POST | `/SenSu/api/login` | 面板登录 |
|
||||
| GET | `/SenSu/api/system` | 系统状态 |
|
||||
| GET | `/SenSu/api/plugins` | 插件列表 |
|
||||
| POST | `/SenSu/api/command` | 执行命令 |
|
||||
| GET | `/api/example/info` | 示例插件 |
|
||||
|
||||
框架提供以下API接口：
|
||||
## 🔧 环境变量
|
||||
|
||||
- WebSocket服务: `ws://localhost:8765`
|
||||
- HTTP API服务: `http://localhost:8000`
|
||||
- GUI API服务: `http://localhost:8080`
|
||||
|
||||
## 🐛 问题排查
|
||||
|
||||
查看 `logs/` 目录中的日志文件获取详细错误信息。
|
||||
| 变量 | 默认值 | 说明 |
|
||||
|------|------|------|
|
||||
| `SENSU_ADMIN_PASSWORD` | `admin123` | 管理员密码 |
|
||||
| `SENSU_API_PASSWORD` | `api123` | API 密码 |
|
||||
| `SENSU_PANEL_USER` | `admin` | 面板用户名 |
|
||||
| `SENSU_PANEL_PASS` | `admin` | 面板密码 |
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
Apache License 2.0
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
欢迎提交Issue和Pull Request！
|
||||
```
|
||||
|
||||
这个完整的Python后端框架包含了这些功能：
|
||||
|
||||
- ✅ TUI渲染界面（三部分布局）
|
||||
- ✅ 强大的日志处理模块
|
||||
- ✅ 初始化系统和指令模块
|
||||
- ✅ 核心桥接和插件桥接
|
||||
- ✅ 互联网模块集（WebSocket、HTTP API）
|
||||
- ✅ 插件管理器（热加载、错误隔离）
|
||||
- ✅ 权限管理器（权限申请和验证）
|
||||
- ✅ API管理器
|
||||
- ✅ 优雅的关闭方法
|
||||
- ✅ 丰富的debug日志
|
||||
- ✅ GUI API接口
|
||||
- ✅ 清晰的目录结构
|
||||
|
||||
每个文件都有完整的错误处理和详细的日志记录 可以直接运行 `python main.py` 来启动框架
|
||||
```
|
||||
Apache License 2.0 · Copyright 2026 AskaEth
|
||||
|
||||
Reference in New Issue
Block a user