# GoTunnel Official Plugins

GoTunnel 官方插件仓库，所有插件均经过官方签名验证。

## 安装插件

### 方式一：Web 控制台

1. 打开 GoTunnel Web 控制台
2. 进入「扩展商店」标签页
3. 浏览可用插件，点击「安装」
4. 选择目标客户端完成安装

### 方式二：客户端管理页面

1. 进入客户端详情页
2. 点击「从商店安装」按钮
3. 选择插件直接安装

---

## 可用插件

| 插件 | 版本 | 类型 | 说明 |
|------|------|------|------|
| [file-manager](plugins/file-manager/) | 1.0.0 | app | 文件管理器，远程浏览和管理文件 |

---

## 插件开发

### 目录结构

```
gotunnel-plugins/
├── icons/                # 插件图标目录
│   └── your-plugin.svg   # SVG 格式图标
├── plugins/
│   └── your-plugin/
│       ├── plugin.js       # 插件源码 (必须)
│       ├── plugin.js.sig   # 签名文件 (CI 自动生成)
│       └── manifest.json   # 插件元数据 (必须)
└── store.json            # 插件商店索引
```

### 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