From ff693465f61f993196a7f63645339fdc57efabad Mon Sep 17 00:00:00 2001
From: qinglong <qinglong@@users.noreply.github.com>
Date: Sat, 13 Jun 2026 20:56:50 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20README=20+=20API=5FAuth=20+=20Security?=
 =?UTF-8?q?=5FPlan=20+=20Plugin=5FGuide=20=E6=9B=B4=E6=96=B0=E8=87=B3=20v0?=
 =?UTF-8?q?.7.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README: 新功能列表、start.sh、架构图
- API_Auth_Flow: 新增 API Key 认证章节
- Security_Hardening_Plan: 标记全部完成
- Plugin_Dev_Guide: 新增插件导入安装章节

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md                      |  7 +++++++
 docs/API_Auth_Flow.md          | 28 ++++++++++++++++++++++++++++
 docs/SenSu 插件开发详细指南.md | 11 +++++++++++
 3 files changed, 46 insertions(+)

diff --git a/README.md b/README.md
index 27c1d74..93cae00 100644
--- a/README.md
+++ b/README.md
@@ -19,12 +19,17 @@
 - 🔐 **安全认证** — PBKDF2-SHA256、环境变量密码
 - 🐳 **Docker 部署** — Alpine 镜像，systemd 服务文件
 - 🧪 **28 个回归测试** — pytest，零失败
+- 🔑 **API Key 系统** — 权限模板(readonly/monitor/full)、过期时间、用量追踪
+- 🛡️ **Sentinel 集群监控** — 多设备实时性能仪表盘 + 节点管理
+- 🔄 **版本更新检测** — 自动检查/下载/备份/回滚
+- 🛡️ **安全加固** — 全端点认证、CSRF防护、SSRF防护、错误脱敏
 - 🛠️ **插件 SDK** — 命令装饰器 + Web 面板 + API + SSE 推送 + 文件选择器
 
 ## 🚀 快速开始
 
 ```bash
 pip install -r requirements.txt
+./start.sh                   # 一键启动(依赖检测+后台)
 python main.py                 # TUI 模式
 python main.py --headless      # 后台模式 (Web 面板 :4200)
 python -m pytest tests/ -v     # 运行测试
@@ -34,9 +39,11 @@ python -m pytest tests/ -v     # 运行测试
 
 ```
 main.py → SenSuFramework (15+ 服务)
+├── UpdateService     ← 版本检测 + 备份 + 回滚
 ├── ProjectEngine     ← 接管任何项目 (subprocess + 日志)
 ├── ProxyService      ← 反向代理 (HTTP+WS)
 ├── PyEnvManager      ← Python 版本 + venv + git clone
+├── SenSuDB           ← SQLite 持久化 (5表)
 ├── PluginWebMixin    ← 插件 Web 控制面板 SDK
 ├── PluginService     ← 热加载 + 状态追踪
 ├── SenSuDB           ← SQLite 5 表
diff --git a/docs/API_Auth_Flow.md b/docs/API_Auth_Flow.md
index 2b0cdbe..38c6384 100644
--- a/docs/API_Auth_Flow.md
+++ b/docs/API_Auth_Flow.md
@@ -239,6 +239,34 @@ Content-Type: application/json
 
 ---
 
+
+## 十一、API Key 认证 (服务器间通信)
+
+### 创建 API Key
+在 WebUI "框架设置" → "API Key 管理" 中创建，支持三种权限模板：
+| 模板 | 权限 |
+|------|------|
+| `readonly` | framework.status.read, plugin.info.read |
+| `monitor` | + framework.event.subscribe |
+| `full` | admin (全部) |
+
+每个 Key 可选 TTL 过期时间，格式 `sk-` + 48 hex chars。
+
+### 使用方式
+```
+GET /SenSu/api/system
+Authorization: Bearer sk-xxxxxxxx...
+```
+
+### 验证流程
+```
+panel_auth() 拦截
+  ├─ Cookie panel_token → Session Store
+  ├─ 失败 → API Key Store (validate_api_key)
+  ├─ 检查过期时间
+  └─ 注入 key 自身权限范围
+```
+
 ## 八、安全响应头
 
 所有响应自动添加：
diff --git a/docs/SenSu 插件开发详细指南.md b/docs/SenSu 插件开发详细指南.md
index 10fc181..fe5eddc 100644
--- a/docs/SenSu 插件开发详细指南.md	
+++ b/docs/SenSu 插件开发详细指南.md	
@@ -3404,6 +3404,17 @@ class PluginResourceManager:
 
 ### 2.6 插件 WebUI 页面 (v0.6.0)
 
+### 2.7 插件导入安装 (v0.7.0)
+
+框架支持在 WebUI 插件管理页直接导入安装插件：
+
+**ZIP 导入**：上传 .zip 包 → 自动解压到 plugins/ → pip install -r requirements.txt → 加载
+
+**Git Clone 导入**：输入仓库 URL → git clone → pip install → 加载
+
+安装过程在子进程中执行，失败不影响框架主进程。安装失败的插件在统计面板中显示。
+
+
 插件可以注册 WebUI 页面，自动出现在 SenSu 管理面板侧边栏的「插件面板」折叠项中。
 
 #### 2.6.1 注册页面