diff --git a/README.md b/README.md index 476288c..a3bdca5 100644 --- a/README.md +++ b/README.md @@ -2,24 +2,260 @@ GoTunnel 官方插件仓库，所有插件均经过官方签名验证。 -## 目录结构 +## 安装插件 -``` -plugins/ - ├── file-manager/ # 文件管理器插件 - │ ├── plugin.js # 插件源码 - │ ├── plugin.js.sig # 签名文件（CI自动生成） - │ └── manifest.json # 插件元数据 - └── ... -``` +### 方式一：Web 控制台 + +1. 打开 GoTunnel Web 控制台 +2. 进入「扩展商店」标签页 +3. 浏览可用插件，点击「安装」 +4. 选择目标客户端完成安装 + +### 方式二：客户端管理页面 + +1. 进入客户端详情页 +2. 点击「从商店安装」按钮 +3. 选择插件直接安装 + +--- + +## 可用插件 + +| 插件 | 版本 | 类型 | 说明 | +|------|------|------|------| +| [file-manager](plugins/file-manager/) | 1.0.0 | app | 文件管理器，远程浏览和管理文件 | + +--- ## 插件开发 -1. 在 `plugins/` 下创建插件目录 -2. 编写 `plugin.js` 和 `manifest.json` -3. 提交 PR，CI 会自动验证格式 -4. 合并后 CI 自动签名并发布 +### 目录结构 -## 签名验证 +``` +gotunnel-plugins/ +├── icons/ # 插件图标目录 +│ └── your-plugin.svg # SVG 格式图标 +├── plugins/ +│ └── your-plugin/ +│ ├── plugin.js # 插件源码 (必须) +│ ├── plugin.js.sig # 签名文件 (CI 自动生成) +│ └── manifest.json # 插件元数据 (必须) +└── store.json # 插件商店索引 +``` -所有插件由 GoTunnel 官方私钥签名，客户端内置公钥验证。 +### manifest.json 格式 + +```json +{ + "name": "your-plugin", + "version": "1.0.0", + "type": "app", + "description": "插件描述", + "author": "Your Name", + "icon": "icons/your-plugin.svg", + "homepage": "https://github.com/...", + "config_schema": [ + { + "key": "port", + "label": "端口", + "type": "number", + "default": "8080" + } + ] +} +``` + +### plugin.js 基本结构 + +```javascript +// 定义插件元数据 +function metadata() { + return { + name: "your-plugin", + version: "1.0.0", + type: "app", + description: "插件描述", + author: "Your Name" + }; +} + +// 插件启动 +function start() { + log("Plugin started"); +} + +// 处理连接 (必须实现) +function handleConn(conn) { + // 处理逻辑 + conn.Close(); +} + +// 插件停止 +function stop() { + log("Plugin stopped"); +} +``` + +--- + +## API 参考 + +### 基础 API + +| 函数 | 说明 | 示例 | +|------|------|------| +| `log(msg)` | 输出日志 | `log("Hello")` | +| `config(key)` | 获取配置 | `config("port")` | + +### 连接 API (conn) + +| 方法 | 说明 | 返回值 | +|------|------|--------| +| `conn.Read(size)` | 读取数据 | `[]byte` 或 `null` | +| `conn.Write(data)` | 写入数据 | 写入字节数 | +| `conn.Close()` | 关闭连接 | - | + +### 文件系统 API (fs) + +| 方法 | 说明 | +|------|------| +| `fs.readFile(path)` | 读取文件 → `{data, error}` | +| `fs.writeFile(path, content)` | 写入文件 → `{ok, error}` | +| `fs.readDir(path)` | 读取目录 → `{entries, error}` | +| `fs.stat(path)` | 文件信息 → `{name, size, isDir, modTime, error}` | +| `fs.exists(path)` | 是否存在 → `{exists, error}` | +| `fs.mkdir(path)` | 创建目录 → `{ok, error}` | +| `fs.remove(path)` | 删除文件 → `{ok, error}` | + +### HTTP API (http) + +| 方法 | 说明 | +|------|------| +| `http.serve(conn, handler)` | 处理 HTTP 请求 | +| `http.json(data)` | 对象转 JSON 字符串 | +| `http.sendFile(conn, path)` | 发送文件响应 | + +**HTTP Handler 示例：** + +```javascript +function handleConn(conn) { + http.serve(conn, function(req) { + // req: {method, path, body} + return { + status: 200, + contentType: "application/json", + body: http.json({message: "OK"}) + }; + }); +} +``` + +--- + +## 示例插件 + +### Echo 服务 + +```javascript +function metadata() { + return { name: "echo", version: "1.0.0", type: "app" }; +} + +function handleConn(conn) { + var data = conn.Read(4096); + if (data) conn.Write(data); + conn.Close(); +} +``` + +### HTTP API 服务 + +```javascript +function metadata() { + return { name: "api", version: "1.0.0", type: "app" }; +} + +function handleConn(conn) { + http.serve(conn, function(req) { + if (req.path === "/health") { + return { status: 200, body: '{"status":"ok"}' }; + } + return { status: 404, body: '{"error":"not found"}' }; + }); +} +``` + +--- + +## 提交插件 + +### 步骤 + +1. Fork 本仓库 +2. 在 `plugins/` 下创建插件目录 +3. 添加 `plugin.js` 和 `manifest.json` +4. 更新 `store.json` 添加插件信息 +5. 提交 Pull Request + +### store.json 格式 + +```json +[ + { + "name": "your-plugin", + "version": "1.0.0", + "type": "app", + "description": "插件描述", + "author": "Your Name", + "icon": "icons/your-plugin.svg", + "download_url": "https://raw.githubusercontent.com/.../plugin.js" + } +] +``` + +### 图标规范 + +- **格式**: SVG (推荐) 或 PNG +- **尺寸**: 24x24 或 48x48 +- **位置**: `icons/` 目录下 +- **命名**: 与插件名称一致，如 `your-plugin.svg` + +**SVG 图标示例：** + +```xml + + + +``` + +### CI 自动化 + +- PR 提交后自动验证插件格式 +- 合并后自动签名并更新 `store.json` + +--- + +## 签名机制 + +所有插件必须经过官方签名才能在 GoTunnel 中运行。 + +- 签名算法：Ed25519 +- 公钥内置于 GoTunnel 客户端 +- 签名文件：`plugin.js.sig` + +--- + +## 沙箱限制 + +| 限制项 | 默认值 | +|--------|--------| +| 最大读取文件 | 10 MB | +| 最大写入文件 | 10 MB | +| 文件访问路径 | 插件数据目录 | + +--- + +## 许可证 + +MIT License diff --git a/icons/file-manager.svg b/icons/file-manager.svg new file mode 100644 index 0000000..6389a9e --- /dev/null +++ b/icons/file-manager.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/plugins/file-manager/manifest.json b/plugins/file-manager/manifest.json index 49b0753..1a8ecfd 100644 --- a/plugins/file-manager/manifest.json +++ b/plugins/file-manager/manifest.json @@ -4,5 +4,6 @@ "description": "文件管理器插件，提供远程文件浏览和管理功能", "author": "GoTunnel Official", "run_at": "client", - "type": "app" + "type": "app", + "icon": "icons/file-manager.svg" } diff --git a/store.json b/store.json index 92967ca..d03ef97 100644 --- a/store.json +++ b/store.json @@ -4,6 +4,8 @@ "version": "1.0.0", "type": "app", "description": "文件管理器插件，提供远程文件浏览和管理功能", - "author": "GoTunnel Official" + "author": "GoTunnel Official", + "icon": "icons/file-manager.svg", + "download_url": "https://git.92coco.cn:8443/flik/gotunnel-plugins/raw/branch/main/plugins/file-manager/plugin.js" } ]