# NebulaShell 项目后续计划

> 最后更新：2026-05-17
> 当前版本：v1.2.0（commit: 5fbc5cc）
> 代码量：~9,481 行 Python，117 文件，5 官方插件

---

## 概述

NebulaShell 已完成核心架构和 NBPF 包格式的开发，当前处于 v1.2.0 稳定阶段。以下为后续开发计划。

---

## Phase 1：安全体系完善（v1.2.1）

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

| 模块 | 说明 | 优先级 |
|------|------|--------|
| JWT 认证 | Bearer Token + JWT 签发/验证，支持 API_KEY 回退 | P0 |
| CSRF 防护 | Token 校验 + SameSite Cookie | P0 |
| 输入验证 | JSON Schema 校验、参数白名单、类型强制 | P1 |
| HTTPS 支持 | 自签名证书生成、TLS 上下文加载 | P1 |

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

| 模块 | 说明 | 优先级 |
|------|------|--------|
| IP 黑白名单 | 规则持久化、CIDR 匹配 | P0 |
| 攻击日志记录 | 异常请求检测与记录 | P1 |

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

| 模块 | 说明 | 优先级 |
|------|------|--------|
| 一键备份/恢复 | 配置、插件数据、日志打包 | P0 |
| 健康检查仪表盘 | CPU、内存、磁盘实时监控 | P1 |
| 资源配额管理 | 限制插件最大资源使用 | P2 |

---

## Phase 2：WebUI 重写（v1.2.1）

### 前端技术栈（待定）
| 选项 | 优点 | 缺点 |
|------|------|------|
| Vue 3 + Naive UI | 轻量、生态好 | 学习成本 |
| React + MUI | 社区大、组件丰富 | 包体积大 |
| 纯 HTML + HTMX | 无需构建、轻量 | 功能受限 |

### 页面规划
- 仪表盘（系统概览）
- 插件管理（安装/卸载/配置）
- 安全中心（限流、IP黑白名单、审计日志）
- 运维工具（备份/恢复、健康检查）
- 系统监控（CPU/内存/磁盘曲线）

---

## Phase 3：可观测性增强

| 功能 | 说明 | 优先级 |
|------|------|--------|
| `/health` 增强 | 返回插件状态、系统资源、运行时间 | P0 |
| `/metrics` 端点 | Prometheus 兼容格式 | P1 |
| 审计日志 | 操作记录、异常检测 | P1 |
| 告警系统 | 资源超限、插件崩溃通知 | P2 |

---

## Phase 4：测试与质量

| 项 | 目标 | 优先级 |
|----|------|--------|
| 单元测试覆盖 | 核心模块 ≥ 80% | P0 |
| 集成测试 | 端到端插件加载链路 | P1 |
| 安全测试 | 沙箱逃逸、签名绕过 | P1 |
| 性能测试 | 插件加载延迟、内存泄漏 | P2 |
| lint/type check | flake8 + mypy | P2 |
| pre-commit hooks | 自动化代码质量门禁 | P2 |

---

## Phase 5：部署与运维

| 项 | 说明 | 优先级 |
|----|------|--------|
| Docker 部署优化 | 多阶段构建优化、docker-compose 完善 | P1 |
| `.env.example` | 环境变量文档 | P1 |
| K8s manifests | Deployment、Service、ConfigMap | P2 |
| CI/CD 流水线 | GitHub Actions 自动测试+发布 | P2 |

---

## 关键里程碑

| 里程碑 | 目标日期 | 可交付物 |
|--------|----------|----------|
| v1.2.1 安全体系完成 | TBD | security/ + firewall/ + ops/ 子目录 |
| v1.2.1 WebUI 完成 | TBD | 可用的管理面板 |
| v1.2.1 正式发布 | TBD | 所有安全+运维功能完成 |
| v1.3.0 | TBD | 测试覆盖80% + CI/CD + K8s |

---

## 技术债务清单

| 项 | 类别 | 预估工时 |
|----|------|----------|
| `except: pass` 清理 | 代码质量 | 2h |
| 配置 Schema 验证 | 可靠性 | 3h |
| 统一错误响应格式 | 可维护性 | 2h |
| `ENABLE_ASYNC` 未使用配置 | 清理 | 0.5h |
| 全局状态单例重构 | 架构 | 4h |
| 日志 correlation ID | 可观测性 | 3h |

---

## 资源需求

- 开发：1-2 人（Python 全栈）
- 时间：Phase 1-2 约 2-3 周
- 测试：需要 mock 环境 + 多 Python 版本

---

## 成功指标

- [ ] 安全中间件完整实现（JWT + CSRF + 输入验证 + HTTPS）
- [ ] 防火墙引擎可用（IP 黑白名单）
- [ ] 运维工具箱可用（备份 + 健康检查）
- [ ] WebUI 对接真实 API
- [ ] 测试覆盖率 ≥ 60%
- [ ] `/metrics` 端点可用
- [ ] Docker 一键部署