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 持久化** — 插件状态、权限、审计日志统一存储
- 🌐 **Web 管理面板** — aiohttp + WebSocket，:4200 实时仪表盘
- 🔐 **安全认证** — PBKDF2-SHA256、环境变量密码、Token 管理
- 🐳 **Docker 部署** — Alpine 镜像 <100MB，systemd 服务文件
- 🧪 **23 个回归测试** — pytest，零失败
- 🌐 **Web 管理面板** — aiohttp + SSE，项目管理/代理/插件控制页
- 🔐 **安全认证** — PBKDF2-SHA256、环境变量密码
- 🐳 **Docker 部署** — Alpine 镜像，systemd 服务文件
- 🧪 **28 个回归测试** — pytest，零失败
- 🛠️ **插件 SDK** — 命令装饰器 + Web 面板 + API + SSE 推送
## 🚀 快速开始
```bash
# 安装依赖
pip install -r requirements.txt
# 启动 (TUI 模式)
python main.py
# 启动 (headless，适合 SSH/systemd/Docker)
python main.py --headless
# 运行测试
python -m pytest tests/ -v
python main.py # TUI 模式
python main.py --headless # 后台模式
python -m pytest tests/ -v # 运行测试
```
## 🏗️ 架构
```
main.py → SenSuFramework
├─ ServiceManager (15 服务)
├─ CoreBridge ⇄ PluginBridge ⇄ NetworkBridge
├─ PluginService (热加载 + 依赖解析)
├─ ProjectService (项目注册表 + 端口分配)
├─ SenSuDB (SQLite 5 表)
├─ TuiService (Textual + 系统监控)
├─ InternetService (HTTP :4200 + WS :4240)
├─ WebPanel (管理面板 /SenSu)
└─ PermissionService (4 级权限)
main.py → SenSuFramework (15 服务)
├── ProjectEngine ← 接管任何项目 (subprocess + 日志)
├── ProxyService ← 反向代理 (HTTP+WS)
├── PyEnvManager ← Python 版本 + venv + git clone
├── PluginWebMixin ← 插件 Web 控制面板 SDK
├── PluginService ← 热加载 + 状态追踪
├── SenSuDB ← SQLite 5 表
├── TuiService ← Textual + 系统监控
├── InternetService ← HTTP :4200 + WS :4240
└── WebPanelManager ← /SenSu 管理面板
```
## 📁 目录结构
## 📁 目录
```
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/ # 开发文档
├── main.py, service_manager.py
├── sdk/ plugin_command, plugin_status, plugin_error, plugin_web
├── services/ 15 个核心服务
├── bridges/ CoreBridge + PluginBridge + NetworkBridge
├── plugins/ 插件目录 + example_plugin (含 Web 面板)
├── deploy/ systemd + Dockerfile
├── tests/ 28 个测试
└── docs/ 开发文档
```
## 🌐 Web 面板
```
http://0.0.0.0:4200/SenSu/
├── /dashboard 仪表盘
├── /pages/projects 项目管理 (添加/启动/Git部署) ← NEW
├── /pages/proxy 反向代理管理 ← NEW
├── /plugin/{name} 插件控制面板 ← NEW
├── /console Web 终端
├── /logs 实时日志
└── /plugins 插件列表
```
## 🔌 插件开发
```python
# plugins/my_plugin/__init__.py
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):
PluginWebMixin.__init__(self)
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"])
self.register_web_page("my_plugin", "My Panel", "<h1>Hello</h1>")
@plugin_command(name="hello", description="打招呼")
@plugin_command(name="hello")
async def cmd_hello(self, *args):
return f"Hello from {self.plugin_name}!"
async def shutdown(self):
pass
return "Hello World!"
```
详细文档见 `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_API_PASSWORD` | `api123` | API 密码 |
| `SENSU_PANEL_USER` | `admin` | 面板用户名 |
| `SENSU_PANEL_PASS` | `admin` | 面板密码 |
| 变量 | 默认值 |
|------|------|
| `SENSU_ADMIN_PASSWORD` | `admin123` |
| `SENSU_API_PASSWORD` | `api123` |
| `SENSU_PANEL_USER` | `admin` |
| `SENSU_PANEL_PASS` | `admin` |
## 📄 许可证
docs/项目文件结构.txt
+44 -63
View File
@@ -1,75 +1,56 @@
SenSu/
├── main.py # 框架主入口 (--headless 参数)
├── service_manager.py # 服务管理器 (依赖注入 + 健康检查)
├── requirements.txt # Python 依赖 (版本锁定)
├── service_manager.py # 服务管理器 (健康检查 + 启动顺序)
├── requirements.txt # Python 依赖
├── README.md # 项目说明
├── ROADMAP.md # 开发路线图 (本地)
├── LICENSE # Apache 2.0
├── Dockerfile # Docker 镜像
│
├── sdk/ # 插件开发工具包
│ ├── plugin_command_decorator.py # @plugin_command 装饰器
│ ├── plugin_status.py # PluginStatus 枚举 (9 状态)
│ └── plugin_error.py # PluginError 异常层级 (6 类)
│ ├── plugin_command_decorator.py
│ ├── plugin_status.py # 9 状态枚举
│ ├── plugin_error.py # 6 异常层级
│ └── plugin_web.py # Web 控制面板 Mixin (NEW v0.6)
│
├── services/ # 核心服务 (15 个)
│ ├── init_service.py # 初始化 + 调试服务器自启
│ ├── 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)
├── services/ # 核心服务 (17 个)
│ ├── init_service.py
│ ├── log_service.py
│ ├── tui_service.py # TUI + 系统监控 + Tab补全
│ ├── command_service.py
│ ├── auth_service.py # PBKDF2-SHA256
│ ├── internet_service.py # HTTP :4200 + WS :4240
│ ├── plugin_service.py # 热加载 + 状态追踪
│ ├── permission_service.py
│ ├── api_service.py
│ ├── shutdown_service.py
│ ├── sensu_db.py # SQLite 5 表 (NEW v0.3)
│ ├── project_engine.py # 异步子进程管理 (NEW v0.6)
│ ├── project_service.py # 项目注册表 + 依赖解析 (NEW v0.3)
│ ├── 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 管理面板
│ ├── manager.py
│ ├── auth.py
│ └── routes/ # API 路由 (8 个模块)
│ ├── 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/ # 消息桥接
│ ├── core_bridge.py # 核心桥 (发布-订阅)
│ ├── plugin_bridge.py # 插件桥 (subscribe_plugin)
│ └── plugin_network_bridge.py # 网络桥 (setup_data_transfer, send_data)
│ ├── core_bridge.py
│ ├── plugin_bridge.py # subscribe_plugin
│ └── plugin_network_bridge.py
│
├── plugins/ # 插件目录
│ └── example_plugin/ # 示例插件 (echo, plugin_status)
├── plugins/
│ └── example_plugin/ # 示例插件 (命令+Web面板+SSE)
│
├── tests/ # 测试 (23 个, pytest)
│ ├── test_auth.py
│ ├── test_service_manager.py
│ ├── test_plugin_enhancements.py
│ └── test_v03.py
│
├── deploy/ # 部署文件
│ ├── 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
├── tests/ # 28 个测试
├── deploy/ # systemd + Dockerfile
├── docs/ # 开发文档 + Phase 报告
├── static/web_panel/ # 前端 (HTML/CSS/JS)
│ └── pages/ # 6 个 WebUI 页面
├── utils/, templates/, gui/
└── config/ # 运行时配置