Update docs: README + project structure for v0.5
This commit is contained in:
@@ -1,145 +1,125 @@
|
|||||||
# 🐱 SenSu
|
# 🐱 SenSu
|
||||||
|
|
||||||
一个功能强大的Python后端框架，具有插件化架构和丰富的功能集。
|
万能 Python TUI 项目管理器 — 插件化架构，任何项目都能挂载运行。
|
||||||
|
|
||||||
|
[](LICENSE)
|
||||||
|
[]()
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## ✨ 特性
|
## ✨ 特性
|
||||||
|
|
||||||
- 🎨 **TUI界面**: 基于Textual的终端用户界面
|
- 🎨 **Textual TUI** — 三栏界面 + 系统监控面板 + CLI 回退
|
||||||
- 📝 **强大日志系统**: 多输出、文件切割、实时日志流
|
- 🔌 **插件系统** — 热加载、权限隔离、依赖解析、进程隔离
|
||||||
- 🔌 **插件化架构**: 热加载、权限管理、插件隔离
|
- 🗄️ **项目注册表** — 插件声明 `project.yaml` 申请端口和资源
|
||||||
- 🌐 **网络服务**: WebSocket、HTTP API、反向代理
|
- 📊 **SQLite 持久化** — 插件状态、权限、审计日志统一存储
|
||||||
- 🔐 **认证系统**: 用户认证、令牌管理、权限验证
|
- 🌐 **Web 管理面板** — aiohttp + WebSocket，:4200 实时仪表盘
|
||||||
- 🔄 **消息桥接**: 模块间通信、插件间通信
|
- 🔐 **安全认证** — PBKDF2-SHA256、环境变量密码、Token 管理
|
||||||
- ⚡ **高性能**: 异步架构、协程支持
|
- 🐳 **Docker 部署** — Alpine 镜像 <100MB，systemd 服务文件
|
||||||
- 🛡️ **安全**: 权限验证、输入验证、错误隔离
|
- 🧪 **23 个回归测试** — pytest，零失败
|
||||||
|
|
||||||
## 🚀 快速开始
|
## 🚀 快速开始
|
||||||
|
|
||||||
### 安装依赖
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# 安装依赖
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
```
|
|
||||||
|
|
||||||
### 运行框架
|
# 启动 (TUI 模式)
|
||||||
|
|
||||||
```bash
|
|
||||||
python main.py
|
python main.py
|
||||||
|
|
||||||
|
# 启动 (headless，适合 SSH/systemd/Docker)
|
||||||
|
python main.py --headless
|
||||||
|
|
||||||
|
# 运行测试
|
||||||
|
python -m pytest tests/ -v
|
||||||
```
|
```
|
||||||
|
|
||||||
### 基本命令
|
## 🏗️ 架构
|
||||||
|
|
||||||
在TUI底部输入框中输入命令：
|
|
||||||
|
|
||||||
- `help` - 显示帮助信息
|
|
||||||
- `status` - 显示框架状态
|
|
||||||
- `history` - 显示命令历史
|
|
||||||
|
|
||||||
## 📁 项目结构
|
|
||||||
|
|
||||||
```
|
```
|
||||||
project_root/
|
main.py → SenSuFramework
|
||||||
├── main.py # 框架主入口
|
├─ ServiceManager (15 服务)
|
||||||
├── service_manager.py # 服务管理器
|
├─ CoreBridge ⇄ PluginBridge ⇄ NetworkBridge
|
||||||
├── requirements.txt # 依赖包列表
|
├─ PluginService (热加载 + 依赖解析)
|
||||||
├── README.md # 项目说明
|
├─ ProjectService (项目注册表 + 端口分配)
|
||||||
│
|
├─ SenSuDB (SQLite 5 表)
|
||||||
├── config/ # 运行时生成的配置文件
|
├─ TuiService (Textual + 系统监控)
|
||||||
│ ├── framework/ # 框架核心配置
|
├─ InternetService (HTTP :4200 + WS :4240)
|
||||||
│ ├── plugins/ # 插件配置
|
├─ WebPanel (管理面板 /SenSu)
|
||||||
│ ├── services/ # 服务配置
|
└─ PermissionService (4 级权限)
|
||||||
│ └── permissions/ # 权限配置
|
```
|
||||||
│
|
|
||||||
├── logs/ # 日志文件目录
|
## 📁 目录结构
|
||||||
│ ├── debug/ # debug级别日志
|
|
||||||
│ └── runtime/ # 运行时日志
|
```
|
||||||
│
|
SenSu-Alpha/
|
||||||
├── services/ # 核心服务模块
|
├── main.py # 框架入口
|
||||||
│ ├── init_service.py # 初始化服务
|
├── service_manager.py # 服务注册表
|
||||||
│ ├── log_service.py # 日志服务
|
├── sdk/ # 插件开发工具包
|
||||||
│ ├── tui_service.py # TUI服务
|
│ ├── plugin_command_decorator.py
|
||||||
│ ├── command_service.py # 指令服务
|
│ ├── plugin_status.py
|
||||||
│ ├── auth_service.py # 认证服务
|
│ └── plugin_error.py
|
||||||
│ ├── internet_service.py # 互联网服务
|
├── services/ # 核心服务 (15 个)
|
||||||
│ ├── plugin_service.py # 插件服务
|
│ ├── sensu_db.py # SQLite 持久化
|
||||||
│ ├── permission_service.py # 权限服务
|
│ ├── project_service.py # 项目注册表
|
||||||
│ ├── api_service.py # API服务
|
│ ├── process_isolated.py # 进程隔离
|
||||||
│ └── shutdown_service.py # 关闭服务
|
│ └── sysmon_widget.py # 系统监控
|
||||||
│
|
├── bridges/ # 消息桥接
|
||||||
├── bridges/ # 桥接模块
|
|
||||||
│ ├── core_bridge.py # 核心桥接
|
|
||||||
│ └── plugin_bridge.py # 插件桥接
|
|
||||||
│
|
|
||||||
├── core/ # 框架功能集
|
|
||||||
│ ├── file_utils.py # 文件操作工具
|
|
||||||
│ ├── config_utils.py # 配置工具
|
|
||||||
│ ├── validation_utils.py # 验证工具
|
|
||||||
│ ├── network_utils.py # 网络工具
|
|
||||||
│ └── plugin_utils.py # 插件工具
|
|
||||||
│
|
|
||||||
├── plugins/ # 插件目录
|
├── plugins/ # 插件目录
|
||||||
│ └── example_plugin/ # 示例插件
|
├── deploy/ # 部署文件
|
||||||
│
|
│ ├── sensu.service # systemd
|
||||||
└── gui/ # GUI接口
|
│ └── Dockerfile # Docker
|
||||||
└── api.py # GUI操作接口
|
├── tests/ # 23 个测试
|
||||||
|
└── docs/ # 开发文档
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🔌 插件开发
|
## 🔌 插件开发
|
||||||
|
|
||||||
### 创建插件
|
```python
|
||||||
|
# plugins/my_plugin/__init__.py
|
||||||
|
from sdk.plugin_command_decorator import plugin_command
|
||||||
|
|
||||||
1. 在 `plugins/` 目录下创建插件文件夹
|
class Plugin:
|
||||||
2. 创建必要的配置文件：
|
def __init__(self, plugin_name=None, config=None, bridge=None):
|
||||||
- `__init__.py` - 插件主模块
|
self.plugin_name = plugin_name
|
||||||
- `config.yaml` - 插件配置
|
self.bridge = bridge
|
||||||
- `permissions.yaml` - 权限申请
|
|
||||||
|
|
||||||
### 插件示例
|
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` - 基础框架配置
|
## 🌐 API 端点
|
||||||
- `permission_rules.yaml` - 权限规则配置
|
|
||||||
|
|
||||||
## 📡 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`
|
| `SENSU_ADMIN_PASSWORD` | `admin123` | 管理员密码 |
|
||||||
|
| `SENSU_API_PASSWORD` | `api123` | API 密码 |
|
||||||
## 🐛 问题排查
|
| `SENSU_PANEL_USER` | `admin` | 面板用户名 |
|
||||||
|
| `SENSU_PANEL_PASS` | `admin` | 面板密码 |
|
||||||
查看 `logs/` 目录中的日志文件获取详细错误信息。
|
|
||||||
|
|
||||||
## 📄 许可证
|
## 📄 许可证
|
||||||
|
|
||||||
Apache License 2.0
|
Apache License 2.0 · Copyright 2026 AskaEth
|
||||||
|
|
||||||
## 🤝 贡献
|
|
||||||
|
|
||||||
欢迎提交Issue和Pull Request！
|
|
||||||
```
|
|
||||||
|
|
||||||
这个完整的Python后端框架包含了这些功能：
|
|
||||||
|
|
||||||
- ✅ TUI渲染界面（三部分布局）
|
|
||||||
- ✅ 强大的日志处理模块
|
|
||||||
- ✅ 初始化系统和指令模块
|
|
||||||
- ✅ 核心桥接和插件桥接
|
|
||||||
- ✅ 互联网模块集（WebSocket、HTTP API）
|
|
||||||
- ✅ 插件管理器（热加载、错误隔离）
|
|
||||||
- ✅ 权限管理器（权限申请和验证）
|
|
||||||
- ✅ API管理器
|
|
||||||
- ✅ 优雅的关闭方法
|
|
||||||
- ✅ 丰富的debug日志
|
|
||||||
- ✅ GUI API接口
|
|
||||||
- ✅ 清晰的目录结构
|
|
||||||
|
|
||||||
每个文件都有完整的错误处理和详细的日志记录 可以直接运行 `python main.py` 来启动框架
|
|
||||||
```
|
|
||||||
|
|||||||
+66
-35
@@ -1,44 +1,75 @@
|
|||||||
SenSu/
|
SenSu/
|
||||||
├── main.py # 框架主入口
|
├── main.py # 框架主入口 (--headless 参数)
|
||||||
├── requirements.txt # 依赖包列表
|
├── service_manager.py # 服务管理器 (依赖注入 + 健康检查)
|
||||||
|
├── requirements.txt # Python 依赖 (版本锁定)
|
||||||
├── README.md # 项目说明
|
├── README.md # 项目说明
|
||||||
|
├── ROADMAP.md # 开发路线图 (本地)
|
||||||
|
├── LICENSE # Apache 2.0
|
||||||
|
├── Dockerfile # Docker 镜像
|
||||||
│
|
│
|
||||||
├── config/ # 运行时生成的配置文件
|
├── sdk/ # 插件开发工具包
|
||||||
│ ├── framework/ # 框架核心配置
|
│ ├── plugin_command_decorator.py # @plugin_command 装饰器
|
||||||
│ ├── plugins/ # 插件配置
|
│ ├── plugin_status.py # PluginStatus 枚举 (9 状态)
|
||||||
│ ├── services/ # 服务配置
|
│ └── plugin_error.py # PluginError 异常层级 (6 类)
|
||||||
│ └── permissions/ # 权限配置
|
|
||||||
│
|
│
|
||||||
├── logs/ # 日志文件目录
|
├── services/ # 核心服务 (15 个)
|
||||||
│ ├── debug/ # debug级别日志
|
│ ├── init_service.py # 初始化 + 调试服务器自启
|
||||||
│ └── runtime/ # 运行时日志
|
│ ├── log_service.py # 日志 (多输出, 切割, TUI捕获)
|
||||||
|
│ ├── tui_service.py # Textual TUI (4栏 + 系统监控)
|
||||||
|
│ ├── command_service.py # 命令系统 (注册/历史/补全)
|
||||||
|
│ ├── auth_service.py # 认证 (PBKDF2, Token)
|
||||||
|
│ ├── internet_service.py # HTTP + WebSocket
|
||||||
|
│ ├── plugin_service.py # 插件管理 (热加载, 状态追踪)
|
||||||
|
│ ├── permission_service.py # 权限验证 (4级, 通配符)
|
||||||
|
│ ├── api_service.py # API 端点
|
||||||
|
│ ├── shutdown_service.py # 优雅关闭
|
||||||
|
│ ├── sensu_db.py # SQLite 持久化 (5表)
|
||||||
|
│ ├── project_service.py # 项目注册表 + 依赖解析
|
||||||
|
│ ├── process_isolated.py # 插件进程隔离
|
||||||
|
│ ├── sysmon_widget.py # TUI 系统监控组件
|
||||||
|
│ └── web_panel/ # Web 管理面板
|
||||||
|
│ ├── manager.py # 路由注册
|
||||||
|
│ ├── auth.py # 面板认证
|
||||||
|
│ ├── routes/ # API 路由 (auth/status/plugins/commands/logs)
|
||||||
|
│ └── utils/ # 工具 (auth/system_info/response)
|
||||||
│
|
│
|
||||||
├── fmfuncs/ # 框架功能集
|
├── bridges/ # 消息桥接
|
||||||
│ ├── __init__.py
|
│ ├── core_bridge.py # 核心桥 (发布-订阅)
|
||||||
│ ├── tui_renderer.py # TUI渲染器
|
│ ├── plugin_bridge.py # 插件桥 (subscribe_plugin)
|
||||||
│ ├── log_handler.py # 日志处理模块
|
│ └── plugin_network_bridge.py # 网络桥 (setup_data_transfer, send_data)
|
||||||
│ ├── init_system.py # 初始化系统
|
|
||||||
│ ├── command_handler.py # 指令处理模块
|
|
||||||
│ ├── bridge_core.py # 核心桥模块
|
|
||||||
│ ├── bridge_plugin.py # 插件桥模块
|
|
||||||
│ ├── internet_module.py # 互联网模块集
|
|
||||||
│ ├── auth_system.py # 访问验证系统
|
|
||||||
│ ├── plugin_manager.py # 插件管理器
|
|
||||||
│ ├── permission_validator.py # 权限验证器
|
|
||||||
│ ├── api_manager.py # API管理器
|
|
||||||
│ └── shutdown_handler.py # 终止处理器
|
|
||||||
│
|
│
|
||||||
├── plugins/ # 插件目录
|
├── plugins/ # 插件目录
|
||||||
│ └── example_plugin/ # 示例插件结构
|
│ └── example_plugin/ # 示例插件 (echo, plugin_status)
|
||||||
│ ├── __init__.py
|
|
||||||
│ ├── permissions.yaml
|
|
||||||
│ └── config.yaml
|
|
||||||
│
|
│
|
||||||
├── gui/ # GUI接口目录
|
├── tests/ # 测试 (23 个, pytest)
|
||||||
│ └── api.py # GUI操作接口
|
│ ├── test_auth.py
|
||||||
|
│ ├── test_service_manager.py
|
||||||
|
│ ├── test_plugin_enhancements.py
|
||||||
|
│ └── test_v03.py
|
||||||
│
|
│
|
||||||
└── utils/ # 工具函数
|
├── deploy/ # 部署文件
|
||||||
├── __init__.py
|
│ ├── sensu.service # systemd unit
|
||||||
├── file_utils.py # 文件操作工具
|
│ └── Dockerfile
|
||||||
├── config_utils.py # 配置工具
|
│
|
||||||
└── validation_utils.py # 验证工具
|
├── docs/ # 文档
|
||||||
|
│ ├── SenSu 框架基本架构.md
|
||||||
|
│ ├── SenSu 插件开发详细指南.md
|
||||||
|
│ └── 项目文件结构.txt
|
||||||
|
│
|
||||||
|
├── config/ # 运行时配置
|
||||||
|
│ ├── framework/ # 框架配置
|
||||||
|
│ ├── permissions/ # 权限数据
|
||||||
|
│ ├── plugins/ # 插件配置
|
||||||
|
│ └── services/ # 服务配置
|
||||||
|
│
|
||||||
|
├── static/ # 前端静态资源
|
||||||
|
│ └── web_panel/
|
||||||
|
│
|
||||||
|
├── utils/ # 通用工具
|
||||||
|
│ └── async_file_utils.py # 异步文件IO
|
||||||
|
│
|
||||||
|
├── templates/ # 插件模板
|
||||||
|
│ └── plugin/
|
||||||
|
│
|
||||||
|
└── gui/ # GUI 接口 (预留)
|
||||||
|
└── api.py
|
||||||
|
|||||||
Reference in New Issue
Block a user