插件化运行时框架 · 多重签名加密分发 · NIR 一次编译到处运行 · 企业级安全体系

---

目录

• 项目定位
• 架构总览
• 核心能力
• 快速开始
• NBPF 包格式
• NIR 中间表示
• 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 文件双向转换
• 验证/签名：独立验证工具 + 重新签名能力

---

快速开始

# 克隆仓库
git clone https://github.com/Starlight-apk/NebulaShell.git
cd NebulaShell

# 安装依赖
pip install -r requirements.txt

# 启动 NebulaShell
python main.py

启动后访问 http://localhost:8080 进入管理控制台。

生成密钥并打包一个插件

# 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 工具链

# 密钥管理
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

---

插件开发

最小插件

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()

清单文件

{
  "metadata": {
    "name": "hello-plugin",
    "version": "1.0.0",
    "description": "示例插件",
    "author": "developer"
  },
  "config": {
    "enabled": true,
    "args": {}
  },
  "dependencies": [],
  "permissions": ["storage:read"]
}

使用其他插件

from store.NebulaShell.plugin_bridge.main import use

# 获取 HTTP API 插件实例
http_api = use("http-api")

# 注册路由
http_api.add_route("/hello", lambda: {"message": "world"})

打包分发

# 开发阶段：源码直接放入 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）

---

贡献指南

开发流程

# 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.