From 7436f699fb953ed2329d856fdbd21f7e7f41b7fb Mon Sep 17 00:00:00 2001 From: AskaEth Date: Thu, 11 Jun 2026 10:48:58 +0800 Subject: [PATCH] Update docs: README + project structure for v0.6 --- README.md | 131 ++++++++++++++++++------------------------ docs/项目文件结构.txt | 107 ++++++++++++++-------------------- 2 files changed, 99 insertions(+), 139 deletions(-) diff --git a/README.md b/README.md index cee3125..2d4ec55 100644 --- a/README.md +++ b/README.md @@ -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", "

Hello

") - @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` | ## 📄 许可证 diff --git a/docs/项目文件结构.txt b/docs/项目文件结构.txt index 2c4fab1..d27c69c 100644 --- a/docs/项目文件结构.txt +++ b/docs/项目文件结构.txt @@ -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/ # 运行时配置