# 🚀 NebulaShell v1.2.1 —— 开发路线图

> ⚠️ **重要说明**：本文档记录的是 v1.2.1 的**规划目标**，不代表当前代码已实现。
> 当前仓库代码基于 v1.2.0，以下功能正在开发中。
>
> 最后更新：2026-05-17

---

## 📅 版本信息

| 项目 | 内容 |
|------|------|
| 版本号 | v1.2.1（开发中） |
| 基础版本 | v1.2.0 |
| Python 版本 | ≥ 3.10 |
| 当前代码量 | ~9,481 行 Python（61 文件） |
| 打包格式 | .nbpf（插件包）+ 源码 |

---

## ✅ 已完成（基于 v1.2.0）

### 核心模块拆分
- `oss/core/engine.py` 从 ~1730 行拆分为 27 行，作为子模块的 re-export 层
- 独立模块：`lifecycle.py`、`manager.py`、`security.py`、`datastore.py`、`watcher.py`

### NBPF 包格式
- 完整实现：compiler / crypto / format / loader
- 三层签名（Ed25519 + RSA-4096 + HMAC）
- 双层加密（AES-256-GCM）
- NIR 中间表示编译器
- 19 个测试用例覆盖全链路

### CLI 工具链
- `nbpf pack/unpack/verify/sign` 全生命周期
- `create mod/key` 脚手架
- `dev/serve` 启动模式

### 测试框架
- 16 个测试文件，覆盖配置、日志、HTTP API、插件管理、NBPF

### 语法修复
- `py_compile` 零错误，消除所有语法隐患
- 废弃代码清理（`store/@{Falck}/`、`oss/tui/`、重复副本）

---

## 🚧 开发中

### 安全中间件（`oss/core/security/`）

| 模块 | 状态 | 说明 |
|------|------|------|
| JWT 认证中间件 | ⏳ 未开始 | Bearer Token + JWT 签发/验证 |
| CSRF 防护中间件 | ⏳ 未开始 | Token 校验 + SameSite Cookie |
| 输入验证中间件 | ⏳ 未开始 | JSON Schema 校验、参数白名单、类型强制 |
| HTTPS 支持 | ⏳ 未开始 | 自签名证书生成、TLS 上下文加载 |

### 防火墙引擎（`oss/core/firewall/`）

| 模块 | 状态 | 说明 |
|------|------|------|
| IP 黑白名单引擎 | ⏳ 未开始 | 规则持久化、CIDR 匹配、攻击日志记录 |

### 运维工具箱（`oss/core/ops/`）

| 模块 | 状态 | 说明 |
|------|------|------|
| 一键备份/恢复 | ⏳ 未开始 | 配置文件、插件数据、日志打包 |
| 健康检查仪表盘 | ⏳ 未开始 | CPU、内存、磁盘实时监控 |
| 资源配额管理 | ⏳ 未开始 | 限制插件最大资源使用 |

### WebUI 管理面板

| 功能 | 状态 | 说明 |
|------|------|------|
| 安全中心 | ⏳ 未开始 | 限流配置、IP 黑/白名单、审计日志 |
| 运维工具箱 | ⏳ 未开始 | 备份/恢复、健康检查仪表盘 |
| 系统监控 | ⏳ 未开始 | 实时 CPU/内存/磁盘曲线 |
| 当前 WebUI | ❌ 待重写 | 目前仍是 v1.1.0 静态 HTML 页面 |

---

## 🛡️ 安全增强计划

### 现有安全模块（已完成）
- `PluginProxy` 沙箱：防止未授权的插件间访问
- `IntegrityChecker`：SHA-256 文件 hash 监控
- `MemoryGuard`：冻结核心属性
- `AuditLogger`：插件行为审计
- `TamperMonitor`：防篡改监控后台线程
- `FallbackManager`：自动重试（最多 3 次）
- `SignatureVerifier`：RSA-SHA256 插件签名验证
- NBPF 三层签名 + 双层加密
- `pl_injector.py`：PL 注入沙箱

### 待实现安全模块
- JWT 认证（Bearer Token）
- CSRF 防护
- 输入验证（JSON Schema）
- IP 黑白名单（CIDR）
- HTTPS/TLS
- 速率限制增强
- Dashboard 鉴权

---

## 📊 健康检查与可观测性（规划中）

### `/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
```

---

## 📦 目标打包体积

| 项目 | 预期大小 |
|------|----------|
| 源码（不含 venv/.git） | ≥ 1,200 KB |
| 核心 Python 代码 | ~500 KB |
| WebUI 资产 | ~300 KB |
| 文档与架构图 | ~200 KB |
| 安全与运维模块 | ~200 KB |

---

## 🧪 测试覆盖目标

| 模块 | 当前测试数 | 覆盖率目标 |
|------|-----------|-----------|
| 配置系统 | 有 | ≥ 90% |
| 安全中间件 | 0 | ≥ 85% |
| 防火墙引擎 | 0 | ≥ 80% |
| HTTP API | 有 | ≥ 80% |
| 运维工具 | 0 | ≥ 75% |
| NBPF 包处理 | 19 | ≥ 70% |

---

## 📜 变更日志

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.2.0 | 2026-05-04 | 核心模块拆分、NBPF 包格式、CLI 工具链、废弃清理 |
| v1.2.1 | 开发中 | 安全中间件、防火墙、运维工具箱、WebUI 重写 |

---

**NebulaShell Team** © 2026 | 安全 · 灵活 · 高效