NebulaShell/RELEASE_v1.2.1.md

🚀 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 端点增强

{
  "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%

---

⬆️ 升级指南

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