docs: 更新项目文档至2026-05-17现状

- 问题报告.md: 重新审查代码，更新路径和问题列表 - RELEASE_v1.2.1.md: 改为路线图，标注实际完成状态 - CODE_VERIFICATION_REPORT.md: 重新验证核心功能 - FATAL_FIXES_REPORT.md: 按当前代码重写 - ai.md: 清理无关内容，更新统计和路线图 - 项目的后续计划.md: 补充详细开发计划 - README.md: 添加功能说明提示 - RELEASE_v1.1.0.md: 添加历史存档标记
2026-05-17 15:17:50 +08:00
parent 5fbc5cc335
commit 1736bb5801
8 changed files with 644 additions and 1293 deletions
--- a/RELEASE_v1.2.1.md
+++ b/RELEASE_v1.2.1.md
@@ -1,113 +1,114 @@
-# 🚀 NebulaShell v1.2.1 —— 重装修补版
+# 🚀 NebulaShell v1.2.1 —— 开发路线图

-> 从这一版开始，NebulaShell 正式转向重型框架路线。
-> 目标打包体积 ≥ 1.2MB，功能全面，安全强化。
+> ⚠️ **重要说明**：本文档记录的是 v1.2.1 的**规划目标**，不代表当前代码已实现。
+> 当前仓库代码基于 v1.2.0，以下功能正在开发中。
+>
+> 最后更新：2026-05-17

 ---

-## 📅 发布信息
+## 📅 版本信息

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

 ---

-## 🔧 问题修复
+## ✅ 已完成（基于 v1.2.0）

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

-| # | 问题 | 文件 | 修复内容 |
-|---|------|------|----------|
-| 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` 零错误，消除所有语法隐患 |
+### NBPF 包格式
+- 完整实现：compiler / crypto / format / loader
+- 三层签名（Ed25519 + RSA-4096 + HMAC）
+- 双层加密（AES-256-GCM）
+- NIR 中间表示编译器
+- 19 个测试用例覆盖全链路

-### 遗留问题修复（问题报告.md）
+### CLI 工具链
+- `nbpf pack/unpack/verify/sign` 全生命周期
+- `create mod/key` 脚手架
+- `dev/serve` 启动模式

-| 严重度 | 原问题 | 当前状态 |
-|--------|--------|----------|
-| 🟢 已修复 | CRITICAL × 4（路径穿越、方法错误、路由空实现、空指针） | 在新架构建模中已复现并修复 |
-| 🟢 已修复 | HIGH × 3（安全检查可绕过、静默吞异常） | AST 解析替代字符串匹配、逐处异常日志 |
-| 🟢 已修复 | MEDIUM × 5（CORS、限流线程安全、CSRF 导入、重复实现、写空数据） | 全部对齐当前架构 |
-| 🟢 已修复 | LOW × 3（空存根、异常静默、配置不一致） | 逐一清理 |
+### 测试框架
+- 16 个测试文件，覆盖配置、日志、HTTP API、插件管理、NBPF
+
+### 语法修复
+- `py_compile` 零错误，消除所有语法隐患
+- 废弃代码清理（`store/@{Falck}/`、`oss/tui/`、重复副本）

 ---

-## 🛡️ 安全增强
+## 🚧 开发中

-### 新增安全模块
+### 安全中间件（`oss/core/security/`）

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

-### 现有安全增强
+### 防火墙引擎（`oss/core/firewall/`）

- 令牌桶限流器验证修复（线程锁 + `deque` 修正）
- CORS 预检请求 `Access-Control-Allow-Origin` 对齐配置
- 插件沙箱 AST 解析替代字符串包含检测
- `except: pass` 全面审查，替换为最小日志
+| 模块 | 状态 | 说明 |
+|------|------|------|
+| IP 黑白名单引擎 | ⏳ 未开始 | 规则持久化、CIDR 匹配、攻击日志记录 |
+
+### 运维工具箱（`oss/core/ops/`）
+
+| 模块 | 状态 | 说明 |
+|------|------|------|
+| 一键备份/恢复 | ⏳ 未开始 | 配置文件、插件数据、日志打包 |
+| 健康检查仪表盘 | ⏳ 未开始 | CPU、内存、磁盘实时监控 |
+| 资源配额管理 | ⏳ 未开始 | 限制插件最大资源使用 |
+
+### WebUI 管理面板
+
+| 功能 | 状态 | 说明 |
+|------|------|------|
+| 安全中心 | ⏳ 未开始 | 限流配置、IP 黑/白名单、审计日志 |
+| 运维工具箱 | ⏳ 未开始 | 备份/恢复、健康检查仪表盘 |
+| 系统监控 | ⏳ 未开始 | 实时 CPU/内存/磁盘曲线 |
+| 当前 WebUI | ❌ 待重写 | 目前仍是 v1.1.0 静态 HTML 页面 |

 ---

-## 🏗️ 架构变更
+## 🛡️ 安全增强计划

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

-```
-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 拆分）
-```
+### 待实现安全模块
+- JWT 认证（Bearer Token）
+- CSRF 防护
+- 输入验证（JSON Schema）
+- IP 黑白名单（CIDR）
+- HTTPS/TLS
+- 速率限制增强
+- Dashboard 鉴权

 ---

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

-### `/health` 端点增强
+### `/health` 端点目标

 ```json
 {
@@ -130,34 +131,14 @@ oss/core/
 # 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 |
@@ -166,46 +147,25 @@ nebula_http_request_duration_seconds_bucket{le="0.1"} 512

 ---

-## 🧪 测试覆盖
+## 🧪 测试覆盖目标

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

 ---

 ## 📜 变更日志

-| 提交 | 日期 | 说明 |
+| 版本 | 日期 | 说明 |
 |------|------|------|
-| v1.2.1 | 2026-05-10 | 重装修补版：Bug 修复 + 安全增强 + 模块拆分 + WebUI 升级 |
+| v1.2.0 | 2026-05-04 | 核心模块拆分、NBPF 包格式、CLI 工具链、废弃清理 |
+| v1.2.1 | 开发中 | 安全中间件、防火墙、运维工具箱、WebUI 重写 |

 ---