262 lines
5.2 KiB
Markdown
262 lines
5.2 KiB
Markdown
# 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
|