6460b28060
✨ 本次更新内容： 📋 ai.md 更新 - 更新最后更新时间和变更记录 - 更新Phase A/B待办状态为已完成 - 删除@{Falck}相关引用 - 新增第21节变更记录 📖 README 重写为专业企业级开源风格 - 805行 → 283行，去除过度营销化语气 - 精简架构图、插件列表标注实际状态 - 保留核心技术内容：快速开始、开发指南、贡献规范 🧹 清理远程分支 - 删除Gitee/Github上除main外的所有冗余分支
284 lines
7.3 KiB
Markdown
284 lines
7.3 KiB
Markdown
# NebulaShell — 企业级插件化运行时框架
|
||
|
||
<div align="center">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
**进程级隔离 · 声明式依赖管理 · 多语言运行时 · 热插拔架构**
|
||
|
||
[快速开始](#快速开始) · [架构](#架构设计) · [插件生态](#插件生态) · [开发指南](#开发你的第一个插件) · [贡献指南](#贡献指南)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 项目简介
|
||
|
||
NebulaShell 是一个面向 **普通用户** 和 **开发者** 的企业级插件化运行时框架，旨在提供类似 Koishi Plus 的终端交互体验。核心设计哲学是「最小化核心」—— 所有功能皆由插件实现，系统核心仅保留最精简的加载与调度能力。
|
||
|
||
- **零配置部署**：安装即用，自动处理依赖关系
|
||
- **进程级隔离**：不可信插件运行在独立进程中，保障宿主安全
|
||
- **声明式依赖**：插件自行声明所需依赖，系统自动解析与安装
|
||
- **热插拔架构**：运行时动态加载/卸载/重载插件，业务零中断
|
||
- **多语言支持**：Python/Node.js/Go 等运行时无缝集成
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- Python `>= 3.10`
|
||
- Linux / macOS / WSL2
|
||
|
||
### 安装与启动
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/Starlight-apk/NebulaShell.git
|
||
cd NebulaShell
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 启动核心
|
||
python main.py
|
||
```
|
||
|
||
启动后访问 [http://localhost:8080](http://localhost:8080) 进入管理控制台。
|
||
|
||
---
|
||
|
||
## 架构设计
|
||
|
||
```
|
||
用户/客户端
|
||
│
|
||
▼
|
||
┌─────────────────────────────┐
|
||
│ HTTP API / WebSocket │
|
||
│ (统一安全网关) │
|
||
└─────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────┐
|
||
│ NebulaShell 微内核 │
|
||
│ ┌───────────────────────┐ │
|
||
│ │ Plugin Loader │ │
|
||
│ │ • 插件发现与加载 │ │
|
||
│ │ • 依赖解析与注入 │ │
|
||
│ │ • 生命周期管理 │ │
|
||
│ └───────────────────────┘ │
|
||
└─────────────────────────────┘
|
||
│
|
||
├── 核心插件层 (可信域)
|
||
│ ├── HTTP API 服务
|
||
│ ├── WebSocket 服务
|
||
│ ├── 数据持久化
|
||
│ ├── 审计中心
|
||
│ └── 监控探针
|
||
│
|
||
└── 隔离插件层 (不可信域)
|
||
├── 动态防火墙
|
||
├── 内网穿透
|
||
├── FTP 文件服务
|
||
├── 多语言运行时
|
||
├── 运维工具箱
|
||
└── 安全网关
|
||
```
|
||
|
||
### 核心组件
|
||
|
||
| 组件 | 职责 | 技术选型 |
|
||
|------|------|----------|
|
||
| **Plugin Loader** | 插件发现、加载、依赖注入 | Python `importlib` + 进程隔离 |
|
||
| **Plugin Bridge** | 插件间通信（事件总线/RPC） | 自定义事件驱动架构 |
|
||
| **HTTP API** | RESTful API 网关 | Python `http.server` |
|
||
| **WebSocket API** | 实时双向通信 | 自定义 WebSocket 实现 |
|
||
| **WebUI** | 管理控制台 | 纯静态 HTML/CSS/JS |
|
||
|
||
---
|
||
|
||
## 插件生态
|
||
|
||
当前共有 **26 个官方插件**，涵盖基础设施、安全、网络、运维、开发者工具等领域。
|
||
|
||
### 基础设施
|
||
|
||
| 插件 | 描述 | 状态 |
|
||
|------|------|------|
|
||
| `plugin-loader` | 插件加载核心 | 稳定 |
|
||
| `plugin-bridge` | 插件间通信/事件总线/RPC | 稳定 |
|
||
| `plugin-storage` | 插件持久化存储 | 稳定 |
|
||
| `lifecycle` | 插件生命周期管理 | 稳定 |
|
||
| `hot-reload` | 热重载支持 | 稳定 |
|
||
| `i18n` | 国际化支持 | 稳定 |
|
||
| `dependency` | 依赖关系解析 | 稳定 |
|
||
|
||
### 网络与安全
|
||
|
||
| 插件 | 描述 | 状态 |
|
||
|------|------|------|
|
||
| `http-api` | RESTful API 服务 | 稳定 |
|
||
| `http-tcp` | TCP 协议适配 | 稳定 |
|
||
| `ws-api` | WebSocket 服务 | 稳定 |
|
||
| `firewall` | 动态防火墙 | Beta |
|
||
| `ftp-server` | FTP 文件服务 | Beta |
|
||
| `frp-proxy` | 内网穿透 | Beta |
|
||
|
||
### 运维与管理
|
||
|
||
| 插件 | 描述 | 状态 |
|
||
|------|------|------|
|
||
| `webui` | Web 管理控制台 | 稳定 |
|
||
| `dashboard` | 系统仪表盘 | 稳定 |
|
||
| `log-terminal` | 日志查看与 SSH 终端 | 稳定 |
|
||
| `pkg-manager` | 插件包管理器 | 稳定 |
|
||
| `auto-dependency` | 系统依赖自动安装 | 稳定 |
|
||
| `performance-optimizer` | 性能优化器 | Beta |
|
||
|
||
### 开发者工具
|
||
|
||
| 插件 | 描述 | 状态 |
|
||
|------|------|------|
|
||
| `code-reviewer` | 代码审查 | Beta |
|
||
| `nodejs-adapter` | Node.js 运行时适配 | Beta |
|
||
| `signature-verifier` | 插件签名验证 | 稳定 |
|
||
| `plugin-loader-pro` | 高级插件加载器（熔断/降级/容错） | Beta |
|
||
|
||
### 插件依赖管理
|
||
|
||
插件通过 `manifest.json` 声明其依赖关系，系统自动处理：
|
||
|
||
```json
|
||
{
|
||
"metadata": {
|
||
"name": "plugin-bridge",
|
||
"version": "1.1.0",
|
||
"type": "core"
|
||
},
|
||
"dependencies": ["plugin-storage", "i18n"],
|
||
"permissions": ["plugin-storage", "lifecycle"]
|
||
}
|
||
```
|
||
|
||
依赖注入通过 `use()` 函数实现，无需硬编码路径：
|
||
|
||
```python
|
||
from store.NebulaShell.plugin_bridge.main import use
|
||
|
||
storage = use("plugin-storage")
|
||
i18n = use("i18n")
|
||
```
|
||
|
||
---
|
||
|
||
## 开发你的第一个插件
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
store/NebulaShell/your-plugin/
|
||
├── manifest.json # 插件元数据与依赖声明
|
||
├── main.py # 插件入口
|
||
└── SIGNATURE # 签名文件（可选）
|
||
```
|
||
|
||
### manifest.json
|
||
|
||
```json
|
||
{
|
||
"metadata": {
|
||
"name": "your-plugin",
|
||
"version": "1.0.0",
|
||
"author": "Your Name",
|
||
"description": "你的插件描述",
|
||
"type": "plugin"
|
||
},
|
||
"config": {
|
||
"enabled": true,
|
||
"args": {}
|
||
},
|
||
"dependencies": [],
|
||
"permissions": []
|
||
}
|
||
```
|
||
|
||
### main.py
|
||
|
||
插件需实现 `Plugin` 基类，并暴露 `New()` 工厂函数：
|
||
|
||
```python
|
||
from oss.plugin.types import Plugin
|
||
|
||
class YourPlugin(Plugin):
|
||
def init(self, deps: dict = None):
|
||
pass
|
||
|
||
def start(self):
|
||
pass
|
||
|
||
def stop(self):
|
||
pass
|
||
|
||
def New():
|
||
return YourPlugin()
|
||
```
|
||
|
||
### 使用其他插件
|
||
|
||
```python
|
||
from store.NebulaShell.plugin_bridge.main import use
|
||
|
||
class YourPlugin(Plugin):
|
||
def init(self, deps: dict = None):
|
||
http_api = use("http-api")
|
||
if http_api:
|
||
http_api.router.get("/api/your-endpoint", self.handler)
|
||
```
|
||
|
||
---
|
||
|
||
## 贡献指南
|
||
|
||
我们欢迎所有形式的贡献，包括但不限于：新功能、Bug 修复、文档改进、测试覆盖。
|
||
|
||
### 开发流程
|
||
|
||
1. Fork 仓库并创建特性分支
|
||
2. 编写代码并添加测试
|
||
3. 确保通过代码风格检查
|
||
4. 提交 Pull Request
|
||
|
||
### 提交规范
|
||
|
||
采用 Conventional Commits 规范：
|
||
|
||
```
|
||
feat: 新功能
|
||
fix: 修复 Bug
|
||
refactor: 代码重构
|
||
docs: 文档变更
|
||
test: 测试相关
|
||
chore: 构建/工具/依赖
|
||
```
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
本项目基于 [Apache License 2.0](LICENSE) 开源。
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**Built with ❤️ by NebulaShell Team**
|
||
|
||
[GitHub](https://github.com/Starlight-apk/NebulaShell) · [Gitee](https://gitee.com/NebulaBase/NebulaShell)
|
||
|
||
</div>
|