docs: 创建文档目录 + 更新LICENSE + 规范项目文档
- 创建 docs/ 文档目录，包含快速开始、架构说明、插件列表、插件开发、API参考、贡献指南 - 更新 LICENSE 完整 Apache 2.0 模板，添加作者 yongwanxing - README 许可证引用更新为 Copyright 2026 Falck, yongwanxing
This commit is contained in:
Falck
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