# 🚀 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 | 安全 · 灵活 · 高效