1

2025-12-29 23:33:16 +08:00
parent 92f42ba7de
commit 174146fb7a
4 changed files with 261 additions and 17 deletions
--- 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
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"
+     fill="none" stroke="currentColor" stroke-width="2">
+  <path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"/>
+</svg>
+```
+
+### CI 自动化
+
+- PR 提交后自动验证插件格式
+- 合并后自动签名并更新 `store.json`
+
+---
+
+## 签名机制
+
+所有插件必须经过官方签名才能在 GoTunnel 中运行。
+
+- 签名算法：Ed25519
+- 公钥内置于 GoTunnel 客户端
+- 签名文件：`plugin.js.sig`
+
+---
+
+## 沙箱限制
+
+| 限制项 | 默认值 |
+|--------|--------|
+| 最大读取文件 | 10 MB |
+| 最大写入文件 | 10 MB |
+| 文件访问路径 | 插件数据目录 |
+
+---
+
+## 许可证
+
+MIT License
--- a/icons/file-manager.svg
+++ b/icons/file-manager.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"/>
+  <line x1="12" y1="11" x2="12" y2="17"/>
+  <line x1="9" y1="14" x2="15" y2="14"/>
+</svg>
--- 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"
 }
--- 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"
  }
 ]