bce27db4ac
核心变更: - engine.py(1781行)拆分为8个独立模块: lifecycle/security/deps/ datastore/pl_injector/watcher/signature/manager - 新增plugin-bridge: 事件总线 + 服务注册 + RPC通信 - 新增i18n: 国际化/多语言翻译支持 - 新增plugin-storage: 插件键值/文件存储 - 新增ws-api: WebSocket实时通信(pub/sub + 自定义处理器) - nodejs-adapter统一为Plugin ABC模式 Bug修复: - 修复load_all()中store_dir未定义崩溃 - 修复DependencyResolver入度计算(拓扑排序) - 修复PermissionError隐藏内置异常 - 修复CORS中间件头部未附加到响应 - 修复IntegrityChecker跳过__pycache__目录 - 修复版本号不一致(v2.0.0→v1.2.0) - 修复测试文件的Logger导入/路径/私有方法调用 - 修复context.py缺少typing导入 - 修复config.py STORE_DIR默认路径(./mods→./store) 测试覆盖: 14→91个测试, 全部通过
213 lines
6.1 KiB
Markdown
213 lines
6.1 KiB
Markdown
# 🚀 NebulaShell v1.2.1 —— 重装修补版
|
||
|
||
> 从这一版开始，NebulaShell 正式转向重型框架路线。
|
||
> 目标打包体积 ≥ 1.2MB，功能全面，安全强化。
|
||
|
||
---
|
||
|
||
## 📅 发布信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 版本号 | v1.2.1 |
|
||
| 基础版本 | v1.2.0 → v1.2.2 |
|
||
| 发布类型 | 修补 + 安全增强 |
|
||
| Python 版本 | ≥ 3.10 |
|
||
| 打包格式 | .nbpf（插件包）+ 源码 |
|
||
|
||
---
|
||
|
||
## 🔧 问题修复
|
||
|
||
### P0 级修复
|
||
|
||
| # | 问题 | 文件 | 修复内容 |
|
||
|---|------|------|----------|
|
||
| 1 | 启动崩溃：config.py 语法错误 | `oss/config/config.py:33` | 修复 `"STORE_DIR"` 后缺失的逗号，字符串隐式拼接导致 SyntaxError |
|
||
| 2 | engine.py 超 400 行 | `oss/core/engine.py`（1730 行） | 按组件拆分：lifecycle / security / plugin_manager / data_store 独立模块 |
|
||
| 3 | 语法检查全线通过 | 全部 `.py` 文件 | `py_compile` 零错误，消除所有语法隐患 |
|
||
|
||
### 遗留问题修复（问题报告.md）
|
||
|
||
| 严重度 | 原问题 | 当前状态 |
|
||
|--------|--------|----------|
|
||
| 🟢 已修复 | CRITICAL × 4（路径穿越、方法错误、路由空实现、空指针） | 在新架构建模中已复现并修复 |
|
||
| 🟢 已修复 | HIGH × 3（安全检查可绕过、静默吞异常） | AST 解析替代字符串匹配、逐处异常日志 |
|
||
| 🟢 已修复 | MEDIUM × 5（CORS、限流线程安全、CSRF 导入、重复实现、写空数据） | 全部对齐当前架构 |
|
||
| 🟢 已修复 | LOW × 3（空存根、异常静默、配置不一致） | 逐一清理 |
|
||
|
||
---
|
||
|
||
## 🛡️ 安全增强
|
||
|
||
### 新增安全模块
|
||
|
||
| 模块 | 能力 | 文件 |
|
||
|------|------|------|
|
||
| **JWT 认证中间件** | Bearer Token + JWT 签发/验证，支持 API_KEY 回退 | `oss/core/security/jwt_auth.py` |
|
||
| **CSRF 防护中间件** | Token 校验 + SameSite Cookie，含 `json` 导入修复 | `oss/core/security/csrf.py` |
|
||
| **输入验证中间件** | JSON Schema 校验、参数白名单、类型强制 | `oss/core/security/input_validator.py` |
|
||
| **IP 黑白名单引擎** | 规则持久化、CIDR 匹配、攻击日志记录 | `oss/core/firewall/ip_filter.py` |
|
||
| **HTTPS 支持** | 自签名证书生成、TLS 上下文加载 | `oss/core/security/tls.py` |
|
||
|
||
### 现有安全增强
|
||
|
||
- 令牌桶限流器验证修复（线程锁 + `deque` 修正）
|
||
- CORS 预检请求 `Access-Control-Allow-Origin` 对齐配置
|
||
- 插件沙箱 AST 解析替代字符串包含检测
|
||
- `except: pass` 全面审查，替换为最小日志
|
||
|
||
---
|
||
|
||
## 🏗️ 架构变更
|
||
|
||
### `oss/core/` 模块拆分
|
||
|
||
```
|
||
oss/core/
|
||
├── __init__.py # 核心导出
|
||
├── engine.py # 主引擎（调用各子模块，不超过 400 行）
|
||
├── lifecycle.py # Lifecycle / LifecycleManager
|
||
├── plugin_manager.py # PluginManager（插件管理核心）
|
||
├── security/ # 安全中间件集合（新增）
|
||
│ ├── __init__.py
|
||
│ ├── jwt_auth.py
|
||
│ ├── csrf.py
|
||
│ ├── input_validator.py
|
||
│ └── tls.py
|
||
├── firewall/ # 动态防火墙（新增）
|
||
│ ├── __init__.py
|
||
│ └── ip_filter.py
|
||
├── ops/ # 运维工具箱（新增）
|
||
│ ├── __init__.py
|
||
│ ├── backup.py
|
||
│ ├── health.py
|
||
│ └── quota.py
|
||
├── http_api/ # HTTP 服务
|
||
│ ├── __init__.py
|
||
│ ├── server.py
|
||
│ ├── router.py
|
||
│ ├── middleware.py
|
||
│ └── rate_limiter.py
|
||
├── nbpf/ # NBPF 包处理
|
||
│ ├── __init__.py
|
||
│ ├── compiler.py
|
||
│ ├── crypto.py
|
||
│ ├── format.py
|
||
│ └── loader.py
|
||
├── repl/ # REPL 终端
|
||
│ ├── __init__.py
|
||
│ └── main.py
|
||
├── achievements.py # 成就系统
|
||
├── context.py # 上下文管理
|
||
└── data_store.py # 数据存储（从 engine 拆分）
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 健康检查与可观测性
|
||
|
||
### `/health` 端点增强
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"version": "1.2.1",
|
||
"uptime": 3600,
|
||
"plugins": { "total": 5, "active": 5, "degraded": [] },
|
||
"system": {
|
||
"cpu_percent": 12.5,
|
||
"memory_percent": 45.2,
|
||
"disk_percent": 32.1,
|
||
"disk_free_gb": 128.5
|
||
}
|
||
}
|
||
```
|
||
|
||
### `/metrics` 端点（Prometheus 兼容）
|
||
|
||
```
|
||
# HELP nebula_plugins_total 插件总数
|
||
# TYPE nebula_plugins_total gauge
|
||
nebula_plugins_total 5
|
||
|
||
# HELP nebula_http_requests_total HTTP 请求总数
|
||
# TYPE nebula_http_requests_total counter
|
||
nebula_http_requests_total 1024
|
||
|
||
# HELP nebula_http_request_duration_seconds HTTP 请求耗时
|
||
# TYPE nebula_http_request_duration_seconds histogram
|
||
nebula_http_request_duration_seconds_bucket{le="0.1"} 512
|
||
```
|
||
|
||
---
|
||
|
||
## 🖥️ WebUI 升级
|
||
|
||
管理面板新增模块：
|
||
|
||
| 面板 | 功能 |
|
||
|------|------|
|
||
| 🔒 **安全中心** | 限流配置、IP 黑/白名单、审计日志、熔断状态 |
|
||
| ⚙️ **运维工具箱** | 一键备份/恢复、健康检查仪表盘、资源配额管理 |
|
||
| 📊 **系统监控** | 实时 CPU/内存/磁盘曲线、请求速率、延迟分布 |
|
||
|
||
---
|
||
|
||
## 📦 打包体积
|
||
|
||
| 项目 | 大小 |
|
||
|------|------|
|
||
| 源码（不含 venv/.git） | ≥ 1,200 KB |
|
||
| 核心 Python 代码 | ~500 KB |
|
||
| WebUI 资产 | ~300 KB |
|
||
| 文档与架构图 | ~200 KB |
|
||
| 安全与运维模块 | ~200 KB |
|
||
|
||
---
|
||
|
||
## 🧪 测试覆盖
|
||
|
||
| 模块 | 测试数 | 覆盖率目标 |
|
||
|------|--------|-----------|
|
||
| 配置系统 | 10+ | ≥ 90% |
|
||
| 安全中间件 | 20+ | ≥ 85% |
|
||
| 防火墙引擎 | 15+ | ≥ 80% |
|
||
| HTTP API | 15+ | ≥ 80% |
|
||
| 运维工具 | 10+ | ≥ 75% |
|
||
| NBPF 包处理 | 10+ | ≥ 70% |
|
||
|
||
---
|
||
|
||
## ⬆️ 升级指南
|
||
|
||
```bash
|
||
# 1. 备份当前数据
|
||
cp -r data data.bak
|
||
|
||
# 2. 拉取 v1.2.1
|
||
git checkout v1.2.1
|
||
|
||
# 3. 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 4. 验证
|
||
python main.py info
|
||
python -m pytest tests/ -v
|
||
|
||
# 5. 启动
|
||
python main.py serve
|
||
```
|
||
|
||
---
|
||
|
||
## 📜 变更日志
|
||
|
||
| 提交 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| v1.2.1 | 2026-05-10 | 重装修补版：Bug 修复 + 安全增强 + 模块拆分 + WebUI 升级 |
|
||
|
||
---
|
||
|
||
**NebulaShell Team** © 2026 | 安全 · 灵活 · 高效
|