docs: 创建文档目录 + 更新LICENSE + 规范项目文档
- 创建 docs/ 文档目录，包含快速开始、架构说明、插件列表、插件开发、API参考、贡献指南 - 更新 LICENSE 完整 Apache 2.0 模板，添加作者 yongwanxing - README 许可证引用更新为 Copyright 2026 Falck, yongwanxing
This commit is contained in:
Falck
15
LICENSE
15
LICENSE
@@ -167,7 +167,7 @@
|
|||||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||||
or other liability obligations and/or rights consistent with this
|
or other liability obligations and/or rights consistent with this
|
||||||
License. However, in accepting such obligations, You may act only
|
License. However, in accepting such obligations, You may act only
|
||||||
on Your own behalf and on Your sole responsibility, not on behalf
|
on Your own behalf and on your sole responsibility, not on behalf
|
||||||
of any other Contributor, and only if You agree to indemnify,
|
of any other Contributor, and only if You agree to indemnify,
|
||||||
defend, and hold each Contributor harmless for any liability
|
defend, and hold each Contributor harmless for any liability
|
||||||
incurred by, or claims asserted against, such Contributor by reason
|
incurred by, or claims asserted against, such Contributor by reason
|
||||||
@@ -175,7 +175,18 @@
|
|||||||
|
|
||||||
END OF TERMS AND CONDITIONS
|
END OF TERMS AND CONDITIONS
|
||||||
|
|
||||||
Copyright 2026 Falck
|
APPENDIX: How to apply the Apache License to your work.
|
||||||
|
|
||||||
|
To apply the Apache License to your work, attach the following
|
||||||
|
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||||
|
replaced with your own identifying information. (Don't include
|
||||||
|
the brackets!) The text should be enclosed in the appropriate
|
||||||
|
comment syntax for the file format. We also recommend that a
|
||||||
|
file or class name and description of purpose be included on the
|
||||||
|
same "printed page" as the copyright notice for easier
|
||||||
|
identification within third-party archives.
|
||||||
|
|
||||||
|
Copyright 2026 Falck, yongwanxing
|
||||||
|
|
||||||
Licensed under the Apache License, Version 2.0 (the "License");
|
Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
you may not use this file except in compliance with the License.
|
you may not use this file except in compliance with the License.
|
||||||
|
|||||||
271
README.md
271
README.md
@@ -1,50 +1,24 @@
|
|||||||
# NebulaShell — 企业级插件化运行时框架
|
# NebulaShell
|
||||||
|
|
||||||
<div align="center">
|
[](https://python.org)
|
||||||
|
[](LICENSE)
|
||||||
|
[]()
|
||||||
|
|
||||||
|
NebulaShell 是一个插件化运行时框架。一切功能皆由插件实现，核心仅保留插件加载与调度能力。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
**进程级隔离 · 声明式依赖管理 · 多语言运行时 · 热插拔架构**
|
|
||||||
|
|
||||||
[快速开始](#快速开始) · [架构](#架构设计) · [插件生态](#插件生态) · [开发指南](#开发你的第一个插件) · [贡献指南](#贡献指南)
|
|
||||||
|
|
||||||
</div>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 项目简介
|
|
||||||
|
|
||||||
NebulaShell 是一个面向 **普通用户** 和 **开发者** 的企业级插件化运行时框架，旨在提供类似 Koishi Plus 的终端交互体验。核心设计哲学是「最小化核心」—— 所有功能皆由插件实现，系统核心仅保留最精简的加载与调度能力。
|
|
||||||
|
|
||||||
- **零配置部署**：安装即用，自动处理依赖关系
|
|
||||||
- **进程级隔离**：不可信插件运行在独立进程中，保障宿主安全
|
|
||||||
- **声明式依赖**：插件自行声明所需依赖，系统自动解析与安装
|
|
||||||
- **热插拔架构**：运行时动态加载/卸载/重载插件，业务零中断
|
|
||||||
- **多语言支持**：Python/Node.js/Go 等运行时无缝集成
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 快速开始
|
## 快速开始
|
||||||
|
|
||||||
### 前置要求
|
|
||||||
|
|
||||||
- Python `>= 3.10`
|
|
||||||
- Linux / macOS / WSL2
|
|
||||||
|
|
||||||
### 安装与启动
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 克隆仓库
|
# 克隆
|
||||||
git clone https://github.com/Starlight-apk/NebulaShell.git
|
git clone https://github.com/Starlight-apk/NebulaShell.git
|
||||||
cd NebulaShell
|
cd NebulaShell
|
||||||
|
|
||||||
# 安装依赖
|
# 安装依赖
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
|
|
||||||
# 启动核心
|
# 启动
|
||||||
python main.py
|
python main.py
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -52,232 +26,101 @@ python main.py
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 架构设计
|
## 插件
|
||||||
|
|
||||||
```
|
所有功能以插件形式提供，位于 `store/NebulaShell/` 目录下。当前内置 26 个插件。
|
||||||
用户/客户端
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
┌─────────────────────────────┐
|
|
||||||
│ HTTP API / WebSocket │
|
|
||||||
│ (统一安全网关) │
|
|
||||||
└─────────────────────────────┘
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
┌─────────────────────────────┐
|
|
||||||
│ NebulaShell 微内核 │
|
|
||||||
│ ┌───────────────────────┐ │
|
|
||||||
│ │ Plugin Loader │ │
|
|
||||||
│ │ • 插件发现与加载 │ │
|
|
||||||
│ │ • 依赖解析与注入 │ │
|
|
||||||
│ │ • 生命周期管理 │ │
|
|
||||||
│ └───────────────────────┘ │
|
|
||||||
└─────────────────────────────┘
|
|
||||||
│
|
|
||||||
├── 核心插件层 (可信域)
|
|
||||||
│ ├── HTTP API 服务
|
|
||||||
│ ├── WebSocket 服务
|
|
||||||
│ ├── 数据持久化
|
|
||||||
│ ├── 审计中心
|
|
||||||
│ └── 监控探针
|
|
||||||
│
|
|
||||||
└── 隔离插件层 (不可信域)
|
|
||||||
├── 动态防火墙
|
|
||||||
├── 内网穿透
|
|
||||||
├── FTP 文件服务
|
|
||||||
├── 多语言运行时
|
|
||||||
├── 运维工具箱
|
|
||||||
└── 安全网关
|
|
||||||
```
|
|
||||||
|
|
||||||
### 核心组件
|
| 插件 | 说明 |
|
||||||
|
|------|------|
|
||||||
| 组件 | 职责 | 技术选型 |
|
| `plugin-loader` | 插件加载核心 |
|
||||||
|------|------|----------|
|
| `plugin-bridge` | 插件间通信（事件总线 / RPC） |
|
||||||
| **Plugin Loader** | 插件发现、加载、依赖注入 | Python `importlib` + 进程隔离 |
|
| `http-api` | RESTful API 服务 |
|
||||||
| **Plugin Bridge** | 插件间通信（事件总线/RPC） | 自定义事件驱动架构 |
|
| `ws-api` | WebSocket 服务 |
|
||||||
| **HTTP API** | RESTful API 网关 | Python `http.server` |
|
| `webui` | 管理控制台 |
|
||||||
| **WebSocket API** | 实时双向通信 | 自定义 WebSocket 实现 |
|
| `dashboard` | 系统仪表盘 |
|
||||||
| **WebUI** | 管理控制台 | 纯静态 HTML/CSS/JS |
|
| `log-terminal` | 日志查看与终端 |
|
||||||
|
| `pkg-manager` | 插件包管理器 |
|
||||||
|
| `lifecycle` | 生命周期管理 |
|
||||||
|
| `i18n` | 国际化 |
|
||||||
|
| `plugin-storage` | 插件持久化存储 |
|
||||||
|
| `dependency` | 依赖关系解析 |
|
||||||
|
| `hot-reload` | 热重载 |
|
||||||
|
| `signature-verifier` | 签名验证 |
|
||||||
|
| `code-reviewer` | 代码审查 |
|
||||||
|
| `plugin-loader-pro` | 熔断/降级/容错 |
|
||||||
|
| `auto-dependency` | 系统依赖自动安装 |
|
||||||
|
| `performance-optimizer` | 性能优化 |
|
||||||
|
| `nodejs-adapter` | Node.js 运行时适配 |
|
||||||
|
| `http-tcp` | TCP 协议适配 |
|
||||||
|
| `firewall` | 防火墙 |
|
||||||
|
| `ftp-server` | 文件服务 |
|
||||||
|
| `frp-proxy` | 内网穿透 |
|
||||||
|
| `json-codec` | JSON 编解码 |
|
||||||
|
| `log-terminal` | 日志终端 |
|
||||||
|
| `polyglot-deploy` | 多语言部署 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 插件生态
|
## 开发一个插件
|
||||||
|
|
||||||
当前共有 **26 个官方插件**，涵盖基础设施、安全、网络、运维、开发者工具等领域。
|
在 `store/NebulaShell/` 下创建目录，包含 `manifest.json` 和 `main.py`：
|
||||||
|
|
||||||
### 基础设施
|
|
||||||
|
|
||||||
| 插件 | 描述 | 状态 |
|
|
||||||
|------|------|------|
|
|
||||||
| `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
|
```json
|
||||||
{
|
{
|
||||||
"metadata": {
|
"metadata": {
|
||||||
"name": "plugin-bridge",
|
"name": "my-plugin",
|
||||||
"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",
|
"version": "1.0.0",
|
||||||
"author": "Your Name",
|
"description": "我的插件"
|
||||||
"description": "你的插件描述",
|
|
||||||
"type": "plugin"
|
|
||||||
},
|
|
||||||
"config": {
|
|
||||||
"enabled": true,
|
|
||||||
"args": {}
|
|
||||||
},
|
},
|
||||||
|
"config": { "enabled": true, "args": {} },
|
||||||
"dependencies": [],
|
"dependencies": [],
|
||||||
"permissions": []
|
"permissions": []
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### main.py
|
|
||||||
|
|
||||||
插件需实现 `Plugin` 基类，并暴露 `New()` 工厂函数：
|
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from oss.plugin.types import Plugin
|
from oss.plugin.types import Plugin
|
||||||
|
|
||||||
class YourPlugin(Plugin):
|
class MyPlugin(Plugin):
|
||||||
def init(self, deps: dict = None):
|
def init(self, deps=None):
|
||||||
pass
|
pass
|
||||||
|
|
||||||
def start(self):
|
def start(self):
|
||||||
pass
|
pass
|
||||||
|
|
||||||
def stop(self):
|
def stop(self):
|
||||||
pass
|
pass
|
||||||
|
|
||||||
def New():
|
def New():
|
||||||
return YourPlugin()
|
return MyPlugin()
|
||||||
```
|
```
|
||||||
|
|
||||||
### 使用其他插件
|
### 使用其他插件
|
||||||
|
|
||||||
|
通过 `use()` 获取已加载的插件实例：
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from store.NebulaShell.plugin_bridge.main import use
|
from store.NebulaShell.plugin_bridge.main import use
|
||||||
|
|
||||||
class YourPlugin(Plugin):
|
http_api = use("http-api")
|
||||||
def init(self, deps: dict = None):
|
webui = use("webui")
|
||||||
http_api = use("http-api")
|
|
||||||
if http_api:
|
|
||||||
http_api.router.get("/api/your-endpoint", self.handler)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 贡献指南
|
## 贡献
|
||||||
|
|
||||||
我们欢迎所有形式的贡献，包括但不限于：新功能、Bug 修复、文档改进、测试覆盖。
|
欢迎提交 Issue 和 Pull Request。
|
||||||
|
|
||||||
### 开发流程
|
请确保代码通过语法检查：
|
||||||
|
|
||||||
1. Fork 仓库并创建特性分支
|
```bash
|
||||||
2. 编写代码并添加测试
|
find . -name "*.py" -not -path "./venv/*" -not -path "./.git/*" | \
|
||||||
3. 确保通过代码风格检查
|
xargs -I{} python3 -m py_compile {}
|
||||||
4. 提交 Pull Request
|
|
||||||
|
|
||||||
### 提交规范
|
|
||||||
|
|
||||||
采用 Conventional Commits 规范：
|
|
||||||
|
|
||||||
```
|
|
||||||
feat: 新功能
|
|
||||||
fix: 修复 Bug
|
|
||||||
refactor: 代码重构
|
|
||||||
docs: 文档变更
|
|
||||||
test: 测试相关
|
|
||||||
chore: 构建/工具/依赖
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 许可证
|
## 许可证
|
||||||
|
|
||||||
本项目基于 [Apache License 2.0](LICENSE) 开源。
|
Copyright 2026 Falck, yongwanxing
|
||||||
|
|
||||||
---
|
Licensed under the [Apache License, Version 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>
|
|
||||||
|
|||||||
69
docs/api/http-api.md
Normal file
69
docs/api/http-api.md
Normal file
@@ -0,0 +1,69 @@
|
|||||||
|
# HTTP API
|
||||||
|
|
||||||
|
`http-api` 插件提供 RESTful API 服务。启动后默认监听 `http://localhost:8080`。
|
||||||
|
|
||||||
|
## 路由
|
||||||
|
|
||||||
|
所有内置 API 端点以 `/api/` 开头。
|
||||||
|
|
||||||
|
### 系统
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| GET | `/api/status` | 系统状态（无需认证） |
|
||||||
|
| GET | `/api/health` | 健康检查 |
|
||||||
|
|
||||||
|
### 插件
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| GET | `/api/plugins` | 列出所有已加载插件 |
|
||||||
|
| GET | `/api/plugins/{name}` | 获取插件信息 |
|
||||||
|
| POST | `/api/plugins/{name}/init` | 初始化插件 |
|
||||||
|
| POST | `/api/plugins/{name}/start` | 启动插件 |
|
||||||
|
| POST | `/api/plugins/{name}/stop` | 停止插件 |
|
||||||
|
|
||||||
|
### 仪表盘
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| GET | `/api/dashboard/stats` | 系统实时状态（CPU/内存/网络） |
|
||||||
|
| GET | `/api/dashboard/history` | 历史数据 |
|
||||||
|
|
||||||
|
### 包管理
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| GET | `/api/packages/search` | 搜索可用插件 |
|
||||||
|
| GET | `/api/packages/list` | 列出已安装插件 |
|
||||||
|
| POST | `/api/packages/install` | 安装插件 |
|
||||||
|
| POST | `/api/packages/uninstall` | 卸载插件 |
|
||||||
|
|
||||||
|
### 国际化
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| GET | `/api/i18n/locales` | 获取支持的语言列表 |
|
||||||
|
| GET | `/api/i18n/translate` | 翻译文本 |
|
||||||
|
| POST | `/api/i18n/locale` | 切换语言 |
|
||||||
|
|
||||||
|
## 认证
|
||||||
|
|
||||||
|
如果配置了 `API_KEY`，所有 API 请求需要在 Header 中携带：
|
||||||
|
|
||||||
|
```
|
||||||
|
Authorization: Bearer <your-api-key>
|
||||||
|
```
|
||||||
|
|
||||||
|
当 `API_KEY` 为空时，认证中间件自动禁用，所有端点公开访问。
|
||||||
|
|
||||||
|
## 自定义路由
|
||||||
|
|
||||||
|
在插件中注册自定义路由：
|
||||||
|
|
||||||
|
```python
|
||||||
|
from store.NebulaShell.plugin_bridge.main import use
|
||||||
|
|
||||||
|
http_api = use("http-api")
|
||||||
|
http_api.router.get("/api/my-endpoint", my_handler)
|
||||||
|
```
|
||||||
69
docs/dev/contributing.md
Normal file
69
docs/dev/contributing.md
Normal file
@@ -0,0 +1,69 @@
|
|||||||
|
# 贡献指南
|
||||||
|
|
||||||
|
## 提交规范
|
||||||
|
|
||||||
|
采用 Conventional Commits 格式：
|
||||||
|
|
||||||
|
```
|
||||||
|
<type>: <描述>
|
||||||
|
|
||||||
|
feat: 新功能
|
||||||
|
fix: 修复 bug
|
||||||
|
refactor: 代码重构
|
||||||
|
docs: 文档变更
|
||||||
|
test: 测试相关
|
||||||
|
chore: 构建/工具/依赖
|
||||||
|
perf: 性能优化
|
||||||
|
style: 代码风格调整
|
||||||
|
```
|
||||||
|
|
||||||
|
## 开发环境
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 克隆并安装
|
||||||
|
git clone https://github.com/Starlight-apk/NebulaShell.git
|
||||||
|
cd NebulaShell
|
||||||
|
python -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
pip install -r requirements-dev.txt
|
||||||
|
|
||||||
|
# 创建特性分支
|
||||||
|
git checkout -b feature/your-feature
|
||||||
|
```
|
||||||
|
|
||||||
|
## 代码规范
|
||||||
|
|
||||||
|
- Python 代码遵循 PEP 8
|
||||||
|
- 使用 `black` 格式化（行长度 88）
|
||||||
|
- 使用 `pylint` 进行静态检查
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 代码格式化
|
||||||
|
black oss/ store/
|
||||||
|
|
||||||
|
# 语法检查
|
||||||
|
python -m pylint oss/ store/ --exit-zero
|
||||||
|
```
|
||||||
|
|
||||||
|
## 语法检查
|
||||||
|
|
||||||
|
所有 `.py` 文件必须通过 `py_compile` 检查：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
find . -name "*.py" \
|
||||||
|
-not -path "./venv/*" \
|
||||||
|
-not -path "./.git/*" \
|
||||||
|
| xargs -I{} python3 -m py_compile {}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 测试
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pytest oss/tests/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Pull Request
|
||||||
|
|
||||||
|
1. 确保代码通过语法检查和测试
|
||||||
|
2. 更新相关文档
|
||||||
|
3. 提交 PR 时描述变更内容和动机
|
||||||
74
docs/guide/architecture.md
Normal file
74
docs/guide/architecture.md
Normal file
@@ -0,0 +1,74 @@
|
|||||||
|
# 架构说明
|
||||||
|
|
||||||
|
## 设计原则
|
||||||
|
|
||||||
|
NebulaShell 遵循「最小化核心」设计哲学：
|
||||||
|
|
||||||
|
- 核心框架（`oss/`）只负责加载 `plugin-loader` 这一个插件
|
||||||
|
- 所有功能皆由插件实现，包括 HTTP 服务、WebSocket、WebUI 等
|
||||||
|
- 插件加载器负责发现、加载、管理所有其他插件
|
||||||
|
|
||||||
|
## 架构分层
|
||||||
|
|
||||||
|
```
|
||||||
|
用户/客户端
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────┐
|
||||||
|
│ HTTP API / WebSocket │ ← 由 http-api / ws-api 插件提供
|
||||||
|
└─────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────┐
|
||||||
|
│ Plugin Loader │ ← 由 oss/plugin/manager.py 加载
|
||||||
|
│ • 插件发现与加载 │
|
||||||
|
│ • 依赖解析与注入 │
|
||||||
|
│ • 生命周期管理 │
|
||||||
|
└─────────────────────────────┘
|
||||||
|
│
|
||||||
|
├── 核心插件
|
||||||
|
│ ├── plugin-bridge 插件间通信
|
||||||
|
│ ├── lifecycle 生命周期
|
||||||
|
│ ├── plugin-storage 持久化存储
|
||||||
|
│ └── i18n 国际化
|
||||||
|
│
|
||||||
|
├── 网络服务
|
||||||
|
│ ├── http-api RESTful API
|
||||||
|
│ ├── ws-api WebSocket
|
||||||
|
│ └── http-tcp TCP 适配
|
||||||
|
│
|
||||||
|
├── 管理工具
|
||||||
|
│ ├── webui 管理控制台
|
||||||
|
│ ├── dashboard 系统仪表盘
|
||||||
|
│ ├── log-terminal 日志终端
|
||||||
|
│ └── pkg-manager 包管理
|
||||||
|
│
|
||||||
|
└── 扩展
|
||||||
|
├── firewall 防火墙
|
||||||
|
├── ftp-server 文件服务
|
||||||
|
├── frp-proxy 内网穿透
|
||||||
|
└── ...
|
||||||
|
```
|
||||||
|
|
||||||
|
## 插件加载流程
|
||||||
|
|
||||||
|
1. `oss/plugin/manager.py` 通过 `PluginLoader` 加载 `plugin-loader` 插件
|
||||||
|
2. `plugin-loader` 扫描 `store/` 目录下所有插件的 `manifest.json`
|
||||||
|
3. 按 `load_priority` 排序，优先加载标记为 `"first"` 的插件（如 `plugin-bridge`）
|
||||||
|
4. 加载所有插件，解析 `dependencies` 字段并注入依赖
|
||||||
|
5. 按依赖顺序调用每个插件的 `init()` → `start()`
|
||||||
|
|
||||||
|
## 插件间通信
|
||||||
|
|
||||||
|
插件通过 `plugin-bridge` 提供的机制通信：
|
||||||
|
|
||||||
|
- **事件总线**：发布/订阅模式，解耦通信
|
||||||
|
- **服务注册表**：RPC 式服务调用
|
||||||
|
- **`use()` 函数**：直接获取已加载的插件实例
|
||||||
|
|
||||||
|
```python
|
||||||
|
from store.NebulaShell.plugin_bridge.main import use
|
||||||
|
|
||||||
|
storage = use("plugin-storage")
|
||||||
|
http_api = use("http-api")
|
||||||
|
```
|
||||||
34
docs/guide/getting-started.md
Normal file
34
docs/guide/getting-started.md
Normal file
@@ -0,0 +1,34 @@
|
|||||||
|
# 快速开始
|
||||||
|
|
||||||
|
## 前置条件
|
||||||
|
|
||||||
|
- Python >= 3.10
|
||||||
|
- Linux / macOS / WSL2
|
||||||
|
|
||||||
|
## 安装
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/Starlight-apk/NebulaShell.git
|
||||||
|
cd NebulaShell
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
## 启动
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
启动后访问 http://localhost:8080 进入管理控制台。
|
||||||
|
|
||||||
|
## 配置
|
||||||
|
|
||||||
|
首次启动会自动生成 `oss.config.json`，位于项目根目录。主要配置项：
|
||||||
|
|
||||||
|
| 配置项 | 默认值 | 说明 |
|
||||||
|
|--------|--------|------|
|
||||||
|
| `HOST` | `127.0.0.1` | 监听地址 |
|
||||||
|
| `HTTP_API_PORT` | `8080` | HTTP 服务端口 |
|
||||||
|
| `STORE_DIR` | `store` | 插件存放目录 |
|
||||||
|
| `DATA_DIR` | `data` | 数据存储目录 |
|
||||||
|
| `API_KEY` | 空 | API 认证密钥（为空时禁用认证） |
|
||||||
130
docs/plugins/development.md
Normal file
130
docs/plugins/development.md
Normal file
@@ -0,0 +1,130 @@
|
|||||||
|
# 插件开发
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
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": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| 字段 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| `metadata.name` | 插件名，用于 `use()` 调用和依赖声明 |
|
||||||
|
| `metadata.type` | 插件类型：`core` 为核心插件，`plugin` 为普通插件 |
|
||||||
|
| `config.enabled` | 是否启用 |
|
||||||
|
| `dependencies` | 依赖的其他插件名列表 |
|
||||||
|
| `permissions` | 权限声明列表 |
|
||||||
|
| `metadata.load_priority` | 设为 `"first"` 可在插件加载器中优先加载 |
|
||||||
|
|
||||||
|
## 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()
|
||||||
|
```
|
||||||
|
|
||||||
|
### 生命周期
|
||||||
|
|
||||||
|
| 方法 | 调用时机 | 说明 |
|
||||||
|
|------|----------|------|
|
||||||
|
| `__init__` | 插件实例创建时 | 初始化成员变量，不要做耗时操作 |
|
||||||
|
| `init(deps)` | 所有插件加载后 | 初始化资源，此时可安全调用其他插件 |
|
||||||
|
| `start()` | 所有插件 init 完成后 | 启动服务、注册路由、开始监听 |
|
||||||
|
| `stop()` | 关闭时 | 清理资源、保存状态 |
|
||||||
|
|
||||||
|
## 使用其他插件
|
||||||
|
|
||||||
|
通过 `use()` 函数获取已加载的插件实例：
|
||||||
|
|
||||||
|
```python
|
||||||
|
from store.NebulaShell.plugin_bridge.main import use
|
||||||
|
|
||||||
|
class YourPlugin(Plugin):
|
||||||
|
def init(self, deps: dict = None):
|
||||||
|
storage = use("plugin-storage")
|
||||||
|
if storage:
|
||||||
|
storage.set("my_key", "my_value")
|
||||||
|
|
||||||
|
def start(self):
|
||||||
|
http_api = use("http-api")
|
||||||
|
if http_api and hasattr(http_api, 'router'):
|
||||||
|
http_api.router.get("/api/hello", self._hello_handler)
|
||||||
|
|
||||||
|
def _hello_handler(self, request):
|
||||||
|
from oss.plugin.types import Response
|
||||||
|
return Response(status=200, body='{"message": "Hello"}',
|
||||||
|
headers={"Content-Type": "application/json"})
|
||||||
|
```
|
||||||
|
|
||||||
|
`use()` 会自动扫描 `store/` 下所有命名空间目录，读取 `manifest.json` 匹配插件名。已加载的插件会被缓存，不会重复加载。
|
||||||
|
|
||||||
|
## 注册 HTTP 路由
|
||||||
|
|
||||||
|
如果依赖了 `http-api` 插件，可以在其 router 上注册路由：
|
||||||
|
|
||||||
|
```python
|
||||||
|
http_api = use("http-api")
|
||||||
|
http_api.router.get("/api/my-endpoint", my_handler)
|
||||||
|
http_api.router.post("/api/my-endpoint", my_handler)
|
||||||
|
```
|
||||||
|
|
||||||
|
## 注册 WebUI 页面
|
||||||
|
|
||||||
|
如果依赖了 `webui` 插件，可以注册管理页面：
|
||||||
|
|
||||||
|
```python
|
||||||
|
webui = use("webui")
|
||||||
|
webui.register_page(
|
||||||
|
path='/my-page',
|
||||||
|
content_provider=my_content_provider,
|
||||||
|
nav_item={'icon': 'ri-star-line', 'text': '我的页面'}
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## 使用事件总线
|
||||||
|
|
||||||
|
`plugin-bridge` 提供事件总线，实现插件间解耦通信：
|
||||||
|
|
||||||
|
```python
|
||||||
|
bridge = use("plugin-bridge")
|
||||||
|
bridge.event_bus.on("user.login", self._on_user_login)
|
||||||
|
bridge.event_bus.emit(
|
||||||
|
bridge.BridgeEvent(type="user.login", source_plugin="my-plugin")
|
||||||
|
)
|
||||||
|
```
|
||||||
64
docs/plugins/list.md
Normal file
64
docs/plugins/list.md
Normal file
@@ -0,0 +1,64 @@
|
|||||||
|
# 插件列表
|
||||||
|
|
||||||
|
所有插件位于 `store/NebulaShell/` 目录下，每个插件包含 `manifest.json`（元数据）和 `main.py`（入口）。
|
||||||
|
|
||||||
|
## 基础设施
|
||||||
|
|
||||||
|
| 插件 | 说明 | 依赖 |
|
||||||
|
|------|------|------|
|
||||||
|
| plugin-loader | 插件加载核心，负责发现、加载、管理所有插件 | 无 |
|
||||||
|
| plugin-bridge | 插件间通信：事件总线、服务注册表、广播 | plugin-storage, i18n |
|
||||||
|
| plugin-storage | 插件持久化存储，提供键值存储和文件读写 | i18n |
|
||||||
|
| lifecycle | 插件生命周期管理，管理启动/停止顺序 | 无 |
|
||||||
|
| hot-reload | 文件变更监听，支持插件热重载 | 无 |
|
||||||
|
| i18n | 国际化支持，多语言翻译 | 无 |
|
||||||
|
| dependency | 依赖关系解析，拓扑排序 | 无 |
|
||||||
|
|
||||||
|
## 网络服务
|
||||||
|
|
||||||
|
| 插件 | 说明 | 依赖 |
|
||||||
|
|------|------|------|
|
||||||
|
| http-api | RESTful API 服务，路由注册与请求处理 | i18n |
|
||||||
|
| ws-api | WebSocket 服务，实时双向通信 | i18n |
|
||||||
|
| http-tcp | TCP 协议适配，将 TCP 连接转为 HTTP 请求 | i18n |
|
||||||
|
|
||||||
|
## 管理工具
|
||||||
|
|
||||||
|
| 插件 | 说明 | 依赖 |
|
||||||
|
|------|------|------|
|
||||||
|
| webui | Web 管理控制台，插件页面注册容器 | http-api, i18n |
|
||||||
|
| dashboard | 系统仪表盘，CPU/内存/网络实时监控 | http-api, webui |
|
||||||
|
| log-terminal | 日志查看器与 SSH 终端 | http-api, webui |
|
||||||
|
| pkg-manager | 插件包管理器，从 Gitee 仓库安装/卸载插件 | http-api, webui, plugin-storage, i18n |
|
||||||
|
|
||||||
|
## 安全
|
||||||
|
|
||||||
|
| 插件 | 说明 | 依赖 |
|
||||||
|
|------|------|------|
|
||||||
|
| signature-verifier | 插件签名验证，确保插件完整性 | plugin-storage, i18n |
|
||||||
|
| plugin-loader-pro | 高级插件加载器：熔断、降级、容错、自动修复 | plugin-loader |
|
||||||
|
|
||||||
|
## 开发者工具
|
||||||
|
|
||||||
|
| 插件 | 说明 | 依赖 |
|
||||||
|
|------|------|------|
|
||||||
|
| code-reviewer | 代码审查，检查代码质量、安全、风格 | 无 |
|
||||||
|
| nodejs-adapter | Node.js 运行时适配，在插件中运行 JavaScript | 无 |
|
||||||
|
| performance-optimizer | 性能优化器，缓存、对象池、字符串驻留 | 无 |
|
||||||
|
| auto-dependency | 系统依赖自动检测与安装 | plugin-loader |
|
||||||
|
| json-codec | JSON 编解码，提供高性能序列化 | 无 |
|
||||||
|
|
||||||
|
## 网络扩展
|
||||||
|
|
||||||
|
| 插件 | 说明 | 依赖 |
|
||||||
|
|------|------|------|
|
||||||
|
| firewall | 动态防火墙规则管理 | http-api, i18n |
|
||||||
|
| ftp-server | FTP 文件服务 | http-api, i18n |
|
||||||
|
| frp-proxy | FRP 内网穿透代理 | http-api, i18n |
|
||||||
|
| polyglot-deploy | 多语言项目部署（Python/Node.js/Go） | http-api, i18n, pkg-manager |
|
||||||
|
|
||||||
|
## 示例
|
||||||
|
|
||||||
|
| 插件 | 说明 | 依赖 |
|
||||||
|
|------|------|------|
|
||||||
|
| example-with-deps | 依赖声明示例（仅 manifest，无 main.py） | 无 |
|
||||||
Reference in New Issue
Block a user