插件化运行时框架 · 多重签名加密分发 · NIR 一次编译到处运行 · 企业级安全体系
---
## 目录
- [项目定位](#项目定位)
- [架构总览](#架构总览)
- [核心能力](#核心能力)
- [快速开始](#快速开始)
- [NBPF 包格式](#nbpf-包格式)
- [NIR 中间表示](#nir-中间表示)
- [CLI 工具链](#cli-工具链)
- [插件开发](#插件开发)
- [内置插件](#内置插件)
- [安全体系](#安全体系)
- [性能指标](#性能指标)
- [贡献指南](#贡献指南)
- [许可证](#许可证)
---
## 项目定位
NebulaShell 是一个**以安全为基石、以插件为灵魂**的运行时框架。核心只做两件事：**加载插件**与**调度插件**，其余一切功能均由插件生态提供。
### 设计原则
| 原则 | 说明 |
|------|------|
| **最小核心** | 核心仅 1100+ 行，职责单一，可独立审计 |
| **插件即产品** | 所有业务功能以插件形式交付，核心不耦合任何业务 |
| **安全默认** | 插件分发强制签名加密，运行时隔离，防篡改防逆向 |
| **一次编译** | NIR 中间表示确保插件跨平台运行，无需为架构适配 |
| **零信任分发** | 每个包经过三层签名验证 + 两层加密解密才可加载 |
---
## 架构总览
### 分层架构
### 数据流
---
## 核心能力
### 插件化架构
- **热插拔**：插件可在运行时动态加载/卸载，无需重启
- **依赖注入**：通过 `use()` 获取任意已加载插件实例
- **生命周期管理**：`init → start → stop` 三阶段标准化生命周期
- **优先级控制**：支持 `load_priority` 标记控制加载顺序
- **熔断降级**：插件异常自动隔离，不影响核心运行
### NBPF 包格式
- **多重签名**：Ed25519（外层）→ RSA-4096-PSS（中层）→ HMAC-SHA256（内层）
- **多重加密**：AES-256-GCM 双层加密，密钥经 RSA-OAEP 封装
- **代码隐藏**：混淆导入路径、常量运行时计算、反调试检测、内存擦除、花指令混淆
- **防篡改**：任何字节级别的修改都会导致签名验证失败
### NIR 中间表示
- **一次编译，到处运行**：基于 Python `compile()` + `marshal` 序列化
- **跨平台**：code object 是 Python 虚拟机原生格式，与 CPU 架构无关
- **目标版本**：Python 3.10+
- **代码保护**：编译产物不可读，增加逆向难度
### CLI 工具链
- **`nebula nbpf`**：完整的包管理命令组
- **密钥生成**：一键生成 Ed25519 + RSA-4096 密钥对
- **打包/解包**：插件目录 ↔ .nbpf 文件双向转换
- **验证/签名**：独立验证工具 + 重新签名能力
---
## 快速开始
```bash
# 克隆仓库
git clone https://github.com/Starlight-apk/NebulaShell.git
cd NebulaShell
# 安装依赖
pip install -r requirements.txt
# 启动 NebulaShell
python main.py
```
启动后访问 [http://localhost:8080](http://localhost:8080) 进入管理控制台。
### 生成密钥并打包一个插件
```bash
# 1. 生成密钥对
nebula nbpf keygen --output ./nbpf-keys
# 2. 打包插件为 .nbpf
nebula nbpf pack ./store/NebulaShell/my-plugin -o my-plugin.nbpf \
--ed25519-key ./nbpf-keys/private/ed25519.pem \
--rsa-key ./nbpf-keys/private/rsa.pem
# 3. 验证包完整性
nebula nbpf verify my-plugin.nbpf
# 4. 将密钥放入信任目录
cp ./nbpf-keys/trusted/* ./data/nbpf-keys/trusted/
cp ./nbpf-keys/rsa/* ./data/nbpf-keys/rsa/
# 5. 重启 NebulaShell，插件自动加载
```
---
## NBPF 包格式
### 包结构
### 加密层级
| 层级 | 算法 | 密钥来源 | 保护范围 |
|------|------|----------|----------|
| 外层加密 | AES-256-GCM | key1（RSA-OAEP 封装） | META-INF/ 和 NIR/ 目录 |
| 中层加密 | AES-256-GCM | key2（RSA-OAEP 封装） | NIR 数据内容 |
| 外层签名 | Ed25519 | 开发者私钥 | 加密层完整性 |
| 中层签名 | RSA-4096-PSS | 作者私钥 | 模块内容完整性 |
| 内层签名 | HMAC-SHA256 | 派生密钥（key1+key2） | 单个模块完整性 |
### 安全流程
---
## NIR 中间表示
NIR（Nebula Intermediate Representation）是 NebulaShell 的跨平台编译方案。
### 技术原理
### 代码保护
| 技术 | 说明 |
|------|------|
| 混淆导入路径 | 动态 `__import__()` + 字符串拼接，隐藏依赖关系 |
| 常量运行时计算 | 关键字符串在运行时拼接，避免静态分析 |
| 反调试检测 | `sys.gettrace()` 检测调试器附加 |
| 内存擦除 | `bytearray` 覆盖清零，防止内存 dump |
| 花指令混淆 | 向 `co_consts` 插入无害垃圾常量，干扰分析 |
---
## CLI 工具链
```bash
# 密钥管理
nebula nbpf keygen # 生成 Ed25519 + RSA-4096 密钥对
nebula nbpf keygen --output ./keys # 指定输出目录
# 打包
nebula nbpf pack ./plugin-dir # 打包为 .nbpf
nebula nbpf pack ./plugin-dir -o out.nbpf --keys-dir ./keys
# 解包
nebula nbpf unpack package.nbpf # 解包到目录
nebula nbpf unpack package.nbpf -o ./out
# 验证
nebula nbpf verify package.nbpf # 验证完整签名链
# 重新签名
nebula nbpf sign package.nbpf # 使用新密钥重新签名
nebula nbpf sign package.nbpf --ed25519-key ./key.pem --rsa-key ./rsa.pem
```
---
## 插件开发
### 最小插件
```python
from oss.plugin.types import Plugin
class HelloPlugin(Plugin):
def init(self, deps=None):
self.name = "hello"
def start(self):
print(f"{self.name} started")
def stop(self):
print(f"{self.name} stopped")
def New():
return HelloPlugin()
```
### 清单文件
```json
{
"metadata": {
"name": "hello-plugin",
"version": "1.0.0",
"description": "示例插件",
"author": "developer"
},
"config": {
"enabled": true,
"args": {}
},
"dependencies": [],
"permissions": ["storage:read"]
}
```
### 使用其他插件
```python
from store.NebulaShell.plugin_bridge.main import use
# 获取 HTTP API 插件实例
http_api = use("http-api")
# 注册路由
http_api.add_route("/hello", lambda: {"message": "world"})
```
### 打包分发
```bash
# 开发阶段：源码直接放入 store/ 目录
# 分发阶段：打包为 .nbpf
nebula nbpf pack ./store/NebulaShell/hello-plugin -o hello-plugin.nbpf \
--ed25519-key ./nbpf-keys/private/ed25519.pem \
--rsa-key ./nbpf-keys/private/rsa.pem
```
---
## 内置插件
NebulaShell 内置 26+ 个插件，覆盖 Web 服务、系统管理、安全防护、协议适配等场景。
### Web 与 API
| 插件 | 说明 |
|------|------|
| `http-api` | RESTful API 服务，支持路由注册、中间件 |
| `ws-api` | WebSocket 实时通信服务 |
| `webui` | 管理控制台 Web 界面 |
| `dashboard` | 系统仪表盘，实时监控 |
### 系统管理
| 插件 | 说明 |
|------|------|
| `plugin-loader` | 插件加载核心，manifest 解析 |
| `plugin-loader-pro` | 熔断、降级、容错机制 |
| `pkg-manager` | 插件包管理器，在线安装/更新 |
| `lifecycle` | 插件生命周期管理 |
| `hot-reload` | 插件热重载，开发模式自动刷新 |
| `dependency` | 依赖关系解析与冲突检测 |
### 安全防护
| 插件 | 说明 |
|------|------|
| `signature-verifier` | 运行时签名验证 |
| `code-reviewer` | 插件代码安全审查 |
| `firewall` | 网络防火墙规则引擎 |
### 通信与协议
| 插件 | 说明 |
|------|------|
| `plugin-bridge` | 插件间通信（事件总线 / RPC / use()） |
| `http-tcp` | TCP 协议适配 |
| `nodejs-adapter` | Node.js 运行时适配 |
| `frp-proxy` | 内网穿透代理 |
| `ftp-server` | 文件服务 |
### 工具与增强
| 插件 | 说明 |
|------|------|
| `plugin-storage` | 插件持久化存储 |
| `i18n` | 国际化支持 |
| `auto-dependency` | 系统依赖自动安装 |
| `performance-optimizer` | 性能优化引擎 |
| `json-codec` | JSON 编解码 |
| `log-terminal` | 日志查看与终端 |
| `polyglot-deploy` | 多语言部署支持 |
---
## 安全体系
### 全链路安全
### 加密标准
| 组件 | 标准 | 密钥长度 |
|------|------|----------|
| 对称加密 | AES-256-GCM | 256 位 |
| 非对称加密 | RSA-OAEP | 4096 位 |
| 外层签名 | Ed25519 | 256 位 |
| 中层签名 | RSA-PSS | 4096 位 |
| 内层签名 | HMAC-SHA256 | 256 位 |
### 密钥管理
---
## 性能指标
| 指标 | 数值 |
|------|------|
| 核心代码行数 | ~1,100 行 |
| 内置插件数量 | 26+ |
| 测试覆盖率 | ~92% |
| 语法检查通过率 | 100% |
| Python 版本要求 | 3.10+ |
| 依赖库数量 | 精简（核心仅依赖 cryptography） |
---
## 贡献指南
### 开发流程
```bash
# 1. Fork 仓库
# 2. 创建特性分支
git checkout -b feat/my-feature
# 3. 安装开发依赖
pip install -r requirements.txt
# 4. 确保语法检查通过
find . -name "*.py" -not -path "./venv/*" -not -path "./.git/*" | \
xargs -I{} python3 -m py_compile {}
# 5. 运行测试
python -m pytest tests/
# 6. 提交 PR
```
### 代码规范
- 遵循 PEP 8 编码规范
- 所有插件必须实现 `init()`、`start()`、`stop()` 方法
- 插件清单必须包含完整的元数据和权限声明
- 提交前确保语法检查零错误
---
## 许可证
Copyright 2026 Falck, yongwanxing, NebulaShell Contributors
Licensed under the [Apache License, Version 2.0](LICENSE).
