AskaEth/SenSu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs: README + project structure for v0.6

Browse Source
This commit is contained in:
AskaEth
2026-06-11 10:48:58 +08:00
parent 7dc87d9f3a
commit 7436f699fb
2 changed files with 99 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+55 -76
View File
@@ -9,116 +9,95 @@
## ✨ 特性 ## ✨ 特性
- 🎨 **Textual TUI** — 三栏界面 + 系统监控面板 + CLI 回退 - 🎨 **Textual TUI** — 系统监控面板 + 命令补全 + CLI 回退
- 🔌 **插件系统** — 热加载、权限隔离、依赖解析、进程隔离 - 🔌 **插件系统** — 热加载、权限隔离、依赖解析、进程隔离
- 🗄️ **项目注册表** — 插件声明 `project.yaml` 申请端口和资源 - 🗄️ **项目引擎** — 接管任何 Python/命令行项目 (subprocess + 日志 + stdin)
- 🔀 **反向代理** — HTTP/WS 代理，本地/局域网/公网端口映射
- 📊 **SQLite 持久化** — 插件状态、权限、审计日志统一存储 - 📊 **SQLite 持久化** — 插件状态、权限、审计日志统一存储
- 🌐 **Web 管理面板** — aiohttp + WebSocket，:4200 实时仪表盘 - 🌐 **Web 管理面板** — aiohttp + SSE，项目管理/代理/插件控制页
- 🔐 **安全认证** — PBKDF2-SHA256、环境变量密码、Token 管理 - 🔐 **安全认证** — PBKDF2-SHA256、环境变量密码
- 🐳 **Docker 部署** — Alpine 镜像 <100MB，systemd 服务文件 - 🐳 **Docker 部署** — Alpine 镜像，systemd 服务文件
- 🧪 **23 个回归测试** — pytest，零失败 - 🧪 **28 个回归测试** — pytest，零失败
- 🛠️ **插件 SDK** — 命令装饰器 + Web 面板 + API + SSE 推送
## 🚀 快速开始 ## 🚀 快速开始
```bash ```bash
# 安装依赖
pip install -r requirements.txt pip install -r requirements.txt
python main.py # TUI 模式
# 启动 (TUI 模式) python main.py --headless # 后台模式
python main.py python -m pytest tests/ -v # 运行测试
# 启动 (headless，适合 SSH/systemd/Docker)
python main.py --headless
# 运行测试
python -m pytest tests/ -v
``` ```
## 🏗️ 架构 ## 🏗️ 架构
``` ```
main.py → SenSuFramework main.py → SenSuFramework (15 服务)
├─ ServiceManager (15 服务) ├── ProjectEngine ← 接管任何项目 (subprocess + 日志)
├─ CoreBridge ⇄ PluginBridge ⇄ NetworkBridge ├── ProxyService ← 反向代理 (HTTP+WS)
├─ PluginService (热加载 + 依赖解析) ├── PyEnvManager ← Python 版本 + venv + git clone
├─ ProjectService (项目注册表 + 端口分配) ├── PluginWebMixin ← 插件 Web 控制面板 SDK
├─ SenSuDB (SQLite 5 表) ├── PluginService ← 热加载 + 状态追踪
├─ TuiService (Textual + 系统监控) ├── SenSuDB ← SQLite 5 表
├─ InternetService (HTTP :4200 + WS :4240) ├── TuiService ← Textual + 系统监控
├─ WebPanel (管理面板 /SenSu) ├── InternetService ← HTTP :4200 + WS :4240
└─ PermissionService (4 级权限) └── WebPanelManager ← /SenSu 管理面板
``` ```
## 📁 目录结构 ## 📁 目录
``` ```
SenSu-Alpha/ SenSu-Alpha/
├── main.py # 框架入口 ├── main.py, service_manager.py
├── service_manager.py # 服务注册表 ├── sdk/ plugin_command, plugin_status, plugin_error, plugin_web
├── sdk/ # 插件开发工具包 ├── services/ 15 个核心服务
│ ├── plugin_command_decorator.py ├── bridges/ CoreBridge + PluginBridge + NetworkBridge
│ ├── plugin_status.py ├── plugins/ 插件目录 + example_plugin (含 Web 面板)
│ └── plugin_error.py ├── deploy/ systemd + Dockerfile
├── services/ # 核心服务 (15 个) ├── tests/ 28 个测试
│ ├── sensu_db.py # SQLite 持久化 └── docs/ 开发文档
│ ├── project_service.py # 项目注册表 ```
│ ├── process_isolated.py # 进程隔离
│ └── sysmon_widget.py # 系统监控 ## 🌐 Web 面板
├── bridges/ # 消息桥接
├── plugins/ # 插件目录 ```
├── deploy/ # 部署文件 http://0.0.0.0:4200/SenSu/
│ ├── sensu.service # systemd ├── /dashboard 仪表盘
│ └── Dockerfile # Docker ├── /pages/projects 项目管理 (添加/启动/Git部署) ← NEW
├── tests/ # 23 个测试 ├── /pages/proxy 反向代理管理 ← NEW
└── docs/ # 开发文档 ├── /plugin/{name} 插件控制面板 ← NEW
├── /console Web 终端
├── /logs 实时日志
└── /plugins 插件列表
``` ```
## 🔌 插件开发 ## 🔌 插件开发
```python ```python
# plugins/my_plugin/__init__.py
from sdk.plugin_command_decorator import plugin_command from sdk.plugin_command_decorator import plugin_command
from sdk.plugin_web import PluginWebMixin
class Plugin: class Plugin(PluginWebMixin):
def __init__(self, plugin_name=None, config=None, bridge=None): def __init__(self, plugin_name=None, config=None, bridge=None):
PluginWebMixin.__init__(self)
self.plugin_name = plugin_name self.plugin_name = plugin_name
self.bridge = bridge
async def initialize(self): async def initialize(self):
# 注册网络路由 self.register_web_page("my_plugin", "My Panel", "<h1>Hello</h1>")
await self.network_bridge.register_http_route(
"/api/my/info", self._handler, methods=["GET"])
@plugin_command(name="hello", description="打招呼") @plugin_command(name="hello")
async def cmd_hello(self, *args): async def cmd_hello(self, *args):
return f"Hello from {self.plugin_name}!" return "Hello World!"
async def shutdown(self):
pass
``` ```
详细文档见 `docs/SenSu 插件开发详细指南.md`
## 🌐 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` | 示例插件 |
## 🔧 环境变量 ## 🔧 环境变量
| 变量 | 默认值 | 说明 | | 变量 | 默认值 |
|------|------|------| |------|------|
| `SENSU_ADMIN_PASSWORD` | `admin123` | 管理员密码 | | `SENSU_ADMIN_PASSWORD` | `admin123` |
| `SENSU_API_PASSWORD` | `api123` | API 密码 | | `SENSU_API_PASSWORD` | `api123` |
| `SENSU_PANEL_USER` | `admin` | 面板用户名 | | `SENSU_PANEL_USER` | `admin` |
| `SENSU_PANEL_PASS` | `admin` | 面板密码 | | `SENSU_PANEL_PASS` | `admin` |
## 📄 许可证 ## 📄 许可证
docs/项目文件结构.txt
+43 -62
View File
@@ -1,75 +1,56 @@
SenSu/ SenSu/
├── main.py # 框架主入口 (--headless 参数) ├── main.py # 框架主入口 (--headless 参数)
├── service_manager.py # 服务管理器 (依赖注入 + 健康检查) ├── service_manager.py # 服务管理器 (健康检查 + 启动顺序)
├── requirements.txt # Python 依赖 (版本锁定) ├── requirements.txt # Python 依赖
├── README.md # 项目说明 ├── README.md # 项目说明
├── ROADMAP.md # 开发路线图 (本地) ├── ROADMAP.md # 开发路线图 (本地)
├── LICENSE # Apache 2.0 ├── LICENSE # Apache 2.0
├── Dockerfile # Docker 镜像
│ │
├── sdk/ # 插件开发工具包 ├── sdk/ # 插件开发工具包
│ ├── plugin_command_decorator.py # @plugin_command 装饰器 │ ├── plugin_command_decorator.py
│ ├── plugin_status.py # PluginStatus 枚举 (9 状态) │ ├── plugin_status.py # 9 状态枚举
│ └── plugin_error.py # PluginError 异常层级 (6 类) │ ├── plugin_error.py # 6 异常层级
│ └── plugin_web.py # Web 控制面板 Mixin (NEW v0.6)
│ │
├── services/ # 核心服务 (15 个) ├── services/ # 核心服务 (17 个)
│ ├── init_service.py # 初始化 + 调试服务器自启 │ ├── init_service.py
│ ├── log_service.py # 日志 (多输出, 切割, TUI捕获) │ ├── log_service.py
│ ├── tui_service.py # Textual TUI (4栏 + 系统监控) │ ├── tui_service.py # TUI + 系统监控 + Tab补全
│ ├── command_service.py # 命令系统 (注册/历史/补全) │ ├── command_service.py
│ ├── auth_service.py # 认证 (PBKDF2, Token) │ ├── auth_service.py # PBKDF2-SHA256
│ ├── internet_service.py # HTTP + WebSocket │ ├── internet_service.py # HTTP :4200 + WS :4240
│ ├── plugin_service.py # 插件管理 (热加载, 状态追踪) │ ├── plugin_service.py # 热加载 + 状态追踪
│ ├── permission_service.py # 权限验证 (4级, 通配符) │ ├── permission_service.py
│ ├── api_service.py # API 端点 │ ├── api_service.py
│ ├── shutdown_service.py # 优雅关闭 │ ├── shutdown_service.py
│ ├── sensu_db.py # SQLite 持久化 (5表) │ ├── sensu_db.py # SQLite 5 表 (NEW v0.3)
│ ├── project_service.py # 项目注册表 + 依赖解析 │ ├── project_engine.py # 异步子进程管理 (NEW v0.6)
│ ├── process_isolated.py # 插件进程隔离 │ ├── project_service.py # 项目注册表 + 依赖解析 (NEW v0.3)
│ ├── sysmon_widget.py # TUI 系统监控组件 │ ├── proxy_service.py # 反向代理 HTTP+WS (NEW v0.6)
│ ├── pyenv_manager.py # Python版本+venv+git (NEW v0.6)
│ ├── process_isolated.py # 插件进程隔离 (NEW v0.5)
│ ├── sysmon_widget.py # TUI 系统监控 (NEW v0.4)
│ └── web_panel/ # Web 管理面板 │ └── web_panel/ # Web 管理面板
│ ├── manager.py # 路由注册 │ ├── manager.py
│ ├── auth.py # 面板认证 │ ├── auth.py
│ ├── routes/ # API 路由 (auth/status/plugins/commands/logs) │ └── routes/ # API 路由 (8 个模块)
│ └── utils/ # 工具 (auth/system_info/response) │ ├── auth.py, status.py, plugins.py, commands.py, logs.py
│ ├── projects.py # 项目管理 (NEW v0.6)
│ ├── proxy.py # 反向代理 (NEW v0.6)
│ └── plugin_web.py # 插件面板 (NEW v0.6)
│ │
├── bridges/ # 消息桥接 ├── bridges/ # 消息桥接
│ ├── core_bridge.py # 核心桥 (发布-订阅) │ ├── core_bridge.py
│ ├── plugin_bridge.py # 插件桥 (subscribe_plugin) │ ├── plugin_bridge.py # subscribe_plugin
│ └── plugin_network_bridge.py # 网络桥 (setup_data_transfer, send_data) │ └── plugin_network_bridge.py
│ │
├── plugins/ # 插件目录 ├── plugins/
│ └── example_plugin/ # 示例插件 (echo, plugin_status) │ └── example_plugin/ # 示例插件 (命令+Web面板+SSE)
│ │
├── tests/ # 测试 (23 个, pytest) ├── tests/ # 28 个测试
│ ├── test_auth.py ├── deploy/ # systemd + Dockerfile
│ ├── test_service_manager.py ├── docs/ # 开发文档 + Phase 报告
│ ├── test_plugin_enhancements.py ├── static/web_panel/ # 前端 (HTML/CSS/JS)
│ └── test_v03.py │ └── pages/ # 6 个 WebUI 页面
│ ├── utils/, templates/, gui/
├── deploy/ # 部署文件 └── config/ # 运行时配置
│ ├── sensu.service # systemd unit
│ └── Dockerfile
│
├── 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