flik/GoTunnel
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update md files

Browse Source
This commit is contained in:
Flik
2026-01-03 13:36:07 +08:00
parent 46f912423e
commit 6de57a284d
4 changed files with 131 additions and 377 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
CLAUDE.md
View File

@@ -20,6 +20,12 @@ go build -o client ./cmd/client
# Web UI development (in web/ directory)
cd web && npm install && npm run dev # development server
cd web && npm run build # production build (outputs to web/dist/)
# Cross-platform build (Windows PowerShell)
.\scripts\build.ps1
# Cross-platform build (Linux/Mac)
./scripts/build.sh all
```
## Architecture Overview
@@ -32,6 +38,7 @@ GoTunnel is an intranet penetration tool (similar to frp) with **server-centric
- **Binary Protocol**: `[Type(1 byte)][Length(4 bytes)][Payload(JSON)]` - see `pkg/protocol/message.go`
- **TLS by Default**: Auto-generated self-signed ECDSA P-256 certificates, no manual setup required
- **Embedded Web UI**: Vue.js SPA embedded in server binary via `//go:embed`
- **JS Plugin System**: Extensible plugin system using goja JavaScript runtime
### Package Structure
@@ -41,34 +48,36 @@ cmd/client/ # Client entry point
internal/server/
├── tunnel/ # Core tunnel server, client session management
├── config/ # YAML configuration loading
├── db/ # SQLite storage (ClientStore interface)
├── db/ # SQLite storage (ClientStore, JSPluginStore interfaces)
├── app/ # Web server, SPA handler
├── router/ # REST API endpoints
└── plugin/ # Server-side plugin manager
├── router/ # REST API endpoints (Swagger documented)
└── plugin/ # Server-side JS plugin manager
internal/client/
├── tunnel/ # Client tunnel logic, auto-reconnect
└── plugin/ # Client-side plugin manager and cache
└── tunnel/ # Client tunnel logic, auto-reconnect, plugin execution
pkg/
├── protocol/ # Message types and serialization
├── crypto/ # TLS certificate generation
├── proxy/ # Legacy proxy implementations
├── relay/ # Bidirectional data relay (32KB buffers)
├── auth/ # JWT authentication
├── utils/ # Port availability checking
├── version/ # Version info and update checking (Gitea API)
├── update/ # Shared update logic (download, extract tar.gz/zip)
└── plugin/ # Plugin system core
├── types.go # ProxyHandler interface, PluginMetadata
├── types.go # Plugin interfaces
├── registry.go # Plugin registry
├── builtin/ # Built-in plugins (socks5, http)
├── wasm/ # WASM runtime (wazero)
├── script/ # JS plugin runtime (goja)
├── sign/ # Plugin signature verification
└── store/ # Plugin persistence (SQLite)
web/ # Vue 3 + TypeScript frontend (Vite)
web/ # Vue 3 + TypeScript frontend (Vite + naive-ui)
scripts/ # Build scripts (build.sh, build.ps1)
```
### Key Interfaces
- `ClientStore` (internal/server/db/): Database abstraction for client rules storage
- `ServerInterface` (internal/server/router/): API handler interface
- `ProxyHandler` (pkg/plugin/): Plugin interface for proxy handlers
- `PluginStore` (pkg/plugin/store/): Plugin persistence interface
- `JSPluginStore` (internal/server/db/): JS plugin persistence
- `ServerInterface` (internal/server/router/handler/): API handler interface
- `ClientPlugin` (pkg/plugin/): Plugin interface for client-side plugins
### Proxy Types
@@ -77,9 +86,11 @@ web/ # Vue 3 + TypeScript frontend (Vite)
2. **UDP**: UDP port forwarding
3. **HTTP**: HTTP proxy through client network
4. **HTTPS**: HTTPS proxy through client network
5. **SOCKS5**: SOCKS5 proxy through client network
**插件类型** (通过 plugin 系统提供):
- **SOCKS5**: Full SOCKS5 protocol (official plugin)
**JS 插件类型** (通过 goja 运行时):
- Custom application plugins (file-server, api-server, etc.)
- Runs on client side with sandbox restrictions
### Data Flow
@@ -87,32 +98,68 @@ External User → Server Port → Yamux Stream → Client → Local Service
### Configuration
- Server: YAML config + SQLite database for client rules
- Server: YAML config + SQLite database for client rules and JS plugins
- Client: Command-line flags only (server address, token, client ID)
- Default ports: 7000 (tunnel), 7500 (web console)
## Plugin System
GoTunnel supports a WASM-based plugin system for extensible proxy handlers.
GoTunnel supports a JavaScript-based plugin system using the goja runtime.
### Plugin Architecture
- **内置类型**: tcp, udp, http, https 直接在 tunnel 代码中处理
- **Official Plugin**: SOCKS5 作为官方 plugin 提供
- **WASM Plugins**: 自定义 plugins 可通过 wazero 运行时动态加载
- **Hybrid Distribution**: 内置 plugins 离线可用；WASM plugins 可从服务端下载
- **内置协议**: tcp, udp, http, https, socks5 直接在 tunnel 代码中处理
- **JS Plugins**: 自定义应用插件通过 goja 运行时在客户端执行
- **Plugin Store**: 从官方商店浏览和安装插件
- **Signature Verification**: 插件需要签名验证才能运行
### ProxyHandler Interface
### JS Plugin Lifecycle
```go
type ProxyHandler interface {
Metadata() PluginMetadata
Init(config map[string]string) error
HandleConn(conn net.Conn, dialer Dialer) error
Close() error
```javascript
function metadata() {
return {
name: "plugin-name",
version: "1.0.0",
type: "app",
description: "Plugin description",
author: "Author"
};
}
function start() { /* called on plugin start */ }
function handleConn(conn) { /* handle each connection */ }
function stop() { /* called on plugin stop */ }
```
### Creating a Built-in Plugin
### Plugin APIs
See `pkg/plugin/builtin/socks5.go` as reference implementation.
- **Basic**: `log()`, `config()`
- **Connection**: `conn.Read()`, `conn.Write()`, `conn.Close()`
- **File System**: `fs.readFile()`, `fs.writeFile()`, `fs.readDir()`, `fs.stat()`, etc.
- **HTTP**: `http.serve()`, `http.json()`, `http.sendFile()`
See `PLUGINS.md` for detailed plugin development documentation.
## API Documentation
The server provides Swagger-documented REST APIs at `/api/`.
### Key Endpoints
- `POST /api/auth/login` - JWT authentication
- `GET /api/clients` - List all clients
- `GET /api/client/{id}` - Get client details
- `PUT /api/client/{id}` - Update client config
- `POST /api/client/{id}/push` - Push config to online client
- `POST /api/client/{id}/plugin/{name}/{action}` - Plugin actions (start/stop/restart/delete)
- `GET /api/plugins` - List registered plugins
- `GET /api/update/check/server` - Check server updates
- `POST /api/update/apply/server` - Apply server update
## Update System
Both server and client support self-update from Gitea releases.
- Release assets are compressed archives (`.tar.gz` for Linux/Mac, `.zip` for Windows)
- The `pkg/update/` package handles download, extraction, and binary replacement
- Updates can be triggered from the Web UI at `/update` page

27
PLUGINS.md
View File

@@ -1,6 +1,6 @@
# GoTunnel 插件开发指南
本文档介绍如何为 GoTunnel 开发 JS 插件。
本文档介绍如何为 GoTunnel 开发 JS 插件。JS 插件基于 [goja](https://github.com/dop251/goja) 运行时，运行在客户端上。
## 目录
@@ -66,8 +66,7 @@ function metadata() {
return {
name: "plugin-name", // 插件名称
version: "1.0.0", // 版本号
type: "app", // 类型: "app" 或 "proxy"
run_at: "client", // 运行位置: "client" 或 "server"
type: "app", // 类型: "app" (应用插件)
description: "描述", // 插件描述
author: "作者" // 作者名称
};
@@ -519,16 +518,20 @@ if (result.error) {
### 配置测试
在服务端配置中测试插件：
在 Web 控制台的插件管理页面安装并配置插件，或通过 API 安装：
```yaml
js_plugins:
- name: my-plugin
path: /path/to/my-plugin.js
sig_path: /path/to/my-plugin.js.sig
config:
debug: "true"
port: "8080"
```bash
# 安装 JS 插件到客户端
POST /api/client/{id}/plugin/js/install
Content-Type: application/json
{
"plugin_name": "my-plugin",
"source": "function metadata() {...}",
"rule_name": "my-rule",
"remote_port": 8080,
"config": {"debug": "true"},
"auto_start": true
}
```
---

55
README.md
View File

@@ -50,6 +50,7 @@ GoTunnel 是一个类似 frp 的内网穿透解决方案，核心特点是**服
- **多客户端支持** - 支持多个客户端同时连接，每个客户端独立的映射规则
- **端口冲突检测** - 自动检测系统端口占用和客户端间端口冲突
- **SOCKS5/HTTP 代理** - 支持通过客户端网络访问任意网站
- **自动更新** - 服务端和客户端支持从 Web 界面一键更新
### 安全性
@@ -192,11 +193,7 @@ web:
| `http` | HTTP 代理 | 通过客户端网络访问 HTTP/HTTPS |
| `https` | HTTPS 代理 | 同 HTTP，支持 CONNECT 方法 |
### 插件类型
| 类型 | 说明 | 示例用途 |
|------|------|----------|
| `socks5` | SOCKS5 代理（官方插件） | 通过客户端网络访问任意地址 |
| `socks5` | SOCKS5 代理 | 通过客户端网络访问任意地址 |
**规则配置示例（通过 Web API）：**
@@ -226,9 +223,11 @@ GoTunnel/
│ │ ├── config/ # 配置管理
│ │ ├── db/ # 数据库存储
│ │ ├── app/ # Web 服务
│ │ └── router/ # API 路由
│ │ ├── router/ # API 路由
│ │ └── plugin/ # 服务端插件管理
│ └── client/
│ └── tunnel/ # 客户端隧道
│ ├── tunnel/ # 客户端隧道
│ └── plugin/ # 客户端插件管理和缓存
├── pkg/
│ ├── protocol/ # 通信协议
│ ├── crypto/ # TLS 加密
@@ -236,32 +235,31 @@ GoTunnel/
│ ├── relay/ # 数据转发
│ ├── auth/ # JWT 认证
│ ├── utils/ # 工具函数
│ └── plugin/ # 插件系统核心
│ ├── builtin/ # 内置插件 (socks5)
│ ├── wasm/ # WASM 运行时 (wazero)
│ ├── version/ # 版本信息和更新检查
│ ├── update/ # 共享更新逻辑 (下载、解压)
│ └── plugin/ # JS 插件系统核心 (goja)
│ └── store/ # 插件持久化 (SQLite)
├── web/ # Vue 3 + naive-ui 前端
├── scripts/ # 构建脚本
│ └── build.sh # 跨平台构建脚本
│ ├── build.sh # Linux/macOS 构建脚本
│ └── build.ps1 # Windows 构建脚本
└── go.mod
```
## 插件系统
GoTunnel 支持灵活的插件系统，可扩展代理协议和应用功能。
GoTunnel 支持灵活的 JS 插件系统，可扩展代理协议和应用功能。
### 插件类型
| 类型 | 说明 | 运行位置 |
|------|------|----------|
| `proxy` | 代理协议插件 (如 SOCKS5) | 服务端 |
| `app` | 应用插件 (如 HTTP 文件服务) | 客户端 |
| `app` | 应用插件 (如 HTTP 文件服务、Echo 服务) | 客户端 |
### 插件来源
- **内置插件**: 编译在二进制中，离线可用
- **JS 插件**: 基于 goja 运行时，支持动态加载和热更新
- **扩展商店**: 从官方商店浏览和安装插件
- **插件商店**: 从服务端管理的插件商店浏览和安装
### 开发 JS 插件
@@ -423,10 +421,16 @@ A: 服务端会自动检测端口冲突，请检查日志并更换端口。
A: 如果客户端未指定 `-id` 参数，服务端会自动生成 16 位随机 ID。
**Q: 如何更新服务端/客户端？**
A: 在 Web 控制台的"更新"页面，可以检查并应用更新。服务端/客户端会自动从 Release 下载压缩包、解压并重启。
## 构建
使用构建脚本可以一键构建前后端：
**Linux/macOS:**
```bash
# 构建当前平台
./scripts/build.sh current
@@ -444,6 +448,25 @@ A: 如果客户端未指定 `-id` 参数，服务端会自动生成 16 位随机
VERSION=1.0.0 ./scripts/build.sh all
```
**Windows (PowerShell):**
```powershell
# 构建当前平台
.\scripts\build.ps1 current
# 构建所有平台
.\scripts\build.ps1 all
# 仅构建 Web UI
.\scripts\build.ps1 web
# 清理构建产物
.\scripts\build.ps1 clean
# 指定版本号
$env:VERSION="1.0.0"; .\scripts\build.ps1 all
```
构建产物输出到 `build/<os>_<arch>/` 目录。
## 架构时序图

319
plan.md
View File

@@ -1,319 +0,0 @@
# GoTunnel 重构计划
## 概述
本次重构包含三个主要目标：
1. 移除 WASM 支持，只保留 JS 插件系统
2. 优化 Web 界面，支持协议动态配置和 JS 插件管理
3. 实现动态重启客户端和插件功能
---
## 第一部分：移除 WASM，简化插件系统
### 1.1 需要删除的文件/目录
- `pkg/plugin/wasm/` - WASM 运行时目录（如果存在）
### 1.2 需要修改的文件
#### 数据库层 (`internal/server/db/`)
- **interface.go**: 移除 `PluginStore` 接口中的 `GetPluginWASM` 方法
- **sqlite.go**:
- 移除 `plugins` 表（WASM 插件表）
- 移除相关的 CRUD 方法
- 保留 `js_plugins` 表
#### 插件类型 (`pkg/plugin/types.go`)
- 移除 `PluginSource` 中的 `"wasm"` 选项，只保留 `"builtin"` 和 `"script"`
#### 依赖清理
- 检查 `go.mod` 是否有 wazero 依赖，如有则移除
---
## 第二部分：优化 Web 界面
### 2.1 协议动态配置
#### 后端修改
##### A. 扩展 ConfigField 类型 (`pkg/plugin/types.go`)
```go
type ConfigField struct {
Key string `json:"key"`
Label string `json:"label"`
Type string `json:"type"` // string, number, bool, select, password
Default string `json:"default,omitempty"`
Required bool `json:"required,omitempty"`
Options []string `json:"options,omitempty"`
Description string `json:"description,omitempty"`
}
type RuleSchema struct {
NeedsLocalAddr bool `json:"needs_local_addr"`
ExtraFields []ConfigField `json:"extra_fields"`
}
```
##### B. 内置协议配置模式
为 SOCKS5 和 HTTP 代理添加认证配置字段：
```go
// SOCKS5 配置模式
var Socks5Schema = RuleSchema{
NeedsLocalAddr: false,
ExtraFields: []ConfigField{
{Key: "auth_enabled", Label: "启用认证", Type: "bool", Default: "false"},
{Key: "username", Label: "用户名", Type: "string"},
{Key: "password", Label: "密码", Type: "password"},
},
}
// HTTP 代理配置模式
var HTTPProxySchema = RuleSchema{
NeedsLocalAddr: false,
ExtraFields: []ConfigField{
{Key: "auth_enabled", Label: "启用认证", Type: "bool", Default: "false"},
{Key: "username", Label: "用户名", Type: "string"},
{Key: "password", Label: "密码", Type: "password"},
},
}
```
##### C. API 端点 (`internal/server/router/api.go`)
- **GET `/api/rule-schemas`**: 返回所有协议类型的配置模式
- 内置类型 (tcp, udp, http, https) 的模式
- 已注册插件的模式（从插件 Metadata 获取）
#### 前端修改 (`web/src/views/ClientView.vue`)
- 页面加载时获取 rule-schemas
- 根据选择的协议类型动态渲染额外配置字段
- 支持的字段类型：string, number, bool, select, password
### 2.2 JS 插件管理界面优化
#### 后端修改
##### A. 扩展 JSPlugin 结构 (`internal/server/db/interface.go`)
```go
type JSPlugin struct {
Name string `json:"name"`
Source string `json:"source"` // JS 源码
Signature string `json:"signature"` // 官方签名
Description string `json:"description"`
Author string `json:"author"`
Version string `json:"version"`
AutoPush []string `json:"auto_push"` // 自动推送客户端列表
Config map[string]string `json:"config"` // 插件运行时配置
ConfigSchema []ConfigField `json:"config_schema"` // 配置字段定义
AutoStart bool `json:"auto_start"`
Enabled bool `json:"enabled"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
```
##### B. 新增/修改 API 端点
- **GET `/api/js-plugins`**: 获取所有 JS 插件列表（包含配置模式）
- **GET `/api/js-plugin/{name}`**: 获取单个插件详情
- **PUT `/api/js-plugin/{name}/config`**: 更新插件运行时配置
- **POST `/api/js-plugin/{name}/push/{clientId}`**: 推送插件到指定客户端
- **POST `/api/js-plugin/{name}/reload`**: 重新加载插件（重新解析源码）
#### 前端修改 (`web/src/views/PluginsView.vue`)
##### A. 重新设计 JS 插件 Tab
```
┌─────────────────────────────────────────────────────────────┐
│ 已安装的 JS 插件 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 📦 socks5-auth v1.0.0 │ │
│ │ 带认证的 SOCKS5 代理 │ │
│ │ 作者: official │ │
│ │ ────────────────────────────────────────────────────── │ │
│ │ 状态: ✅ 启用 自动启动: ✅ │ │
│ │ 推送目标: 所有客户端 │ │
│ │ ────────────────────────────────────────────────────── │ │
│ │ [⚙️ 配置] [🔄 重载] [📤 推送] [🗑️ 删除] │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
##### B. 插件配置模态框
- 动态渲染 ConfigSchema 定义的字段
- 支持 string, number, bool, select, password 类型
- 保存后可选择是否同步到已连接的客户端
##### C. 推送配置
- 选择目标客户端（支持多选）
- 选择是否自动启动
- 显示推送结果
---
## 第三部分：动态重启功能
### 3.1 协议消息定义 (`pkg/protocol/message.go`)
```go
// 已有消息类型
const (
MsgTypeClientPluginStart = 40 // 启动插件
MsgTypeClientPluginStop = 41 // 停止插件 (需实现)
MsgTypeClientPluginStatus = 42 // 插件状态
MsgTypeClientPluginConn = 43 // 插件连接
// 新增消息类型
MsgTypeClientRestart = 44 // 客户端重启
MsgTypePluginConfigUpdate = 45 // 插件配置更新
)
// 新增请求/响应结构
type ClientPluginStopRequest struct {
PluginName string `json:"plugin_name"`
RuleName string `json:"rule_name"`
}
type ClientRestartRequest struct {
Reason string `json:"reason,omitempty"`
}
type PluginConfigUpdateRequest struct {
PluginName string `json:"plugin_name"`
RuleName string `json:"rule_name"`
Config map[string]string `json:"config"`
}
```
### 3.2 客户端实现 (`internal/client/tunnel/client.go`)
#### A. 实现插件停止处理
```go
func (c *Client) handleClientPluginStop(stream net.Conn, msg *protocol.Message) {
defer stream.Close()
var req protocol.ClientPluginStopRequest
if err := msg.ParsePayload(&req); err != nil {
return
}
key := req.PluginName + ":" + req.RuleName
c.pluginMu.Lock()
if handler, ok := c.runningPlugins[key]; ok {
handler.Stop()
delete(c.runningPlugins, key)
}
c.pluginMu.Unlock()
// 发送确认
resp := protocol.ClientPluginStatusResponse{
PluginName: req.PluginName,
RuleName: req.RuleName,
Running: false,
}
respMsg, _ := protocol.NewMessage(protocol.MsgTypeClientPluginStatus, resp)
protocol.WriteMessage(stream, respMsg)
}
```
#### B. 实现配置热更新
```go
func (c *Client) handlePluginConfigUpdate(stream net.Conn, msg *protocol.Message) {
// 更新运行中插件的配置（如果插件支持热更新）
}
```
#### C. 实现客户端优雅重启
```go
func (c *Client) handleClientRestart(stream net.Conn, msg *protocol.Message) {
// 1. 停止所有运行中的插件
// 2. 关闭当前会话
// 3. 触发重连（Run() 循环会自动处理）
}
```
### 3.3 服务端实现 (`internal/server/tunnel/server.go`)
```go
// 停止客户端插件
func (s *Server) StopClientPlugin(clientID, pluginName, ruleName string) error
// 重启客户端插件
func (s *Server) RestartClientPlugin(clientID, pluginName, ruleName string) error
// 更新插件配置
func (s *Server) UpdateClientPluginConfig(clientID, pluginName, ruleName string, config map[string]string) error
// 重启整个客户端
func (s *Server) RestartClient(clientID string) error
```
### 3.4 REST API (`internal/server/router/api.go`)
```go
// 客户端控制
POST /api/client/{id}/restart // 重启整个客户端
// 插件控制
POST /api/client/{id}/plugin/{name}/stop // 停止插件
POST /api/client/{id}/plugin/{name}/restart // 重启插件
PUT /api/client/{id}/plugin/{name}/config // 更新配置并可选重启
```
### 3.5 前端界面 (`web/src/views/ClientView.vue`)
在客户端详情页添加控制按钮：
- **客户端级别**: "重启客户端" 按钮
- **插件级别**: 每个运行中的插件显示 "停止"、"重启"、"配置" 按钮
---
## 实施顺序
### 阶段 1: 清理 WASM 代码
1. 删除 WASM 相关文件和代码
2. 更新数据库 schema
3. 清理依赖
### 阶段 2: 协议动态配置
1. 定义 ConfigField 和 RuleSchema 类型
2. 实现内置协议的配置模式
3. 添加 `/api/rule-schemas` 端点
4. 更新前端规则编辑界面
### 阶段 3: JS 插件管理优化
1. 扩展 JSPlugin 结构和数据库
2. 实现插件配置 API
3. 重新设计前端插件管理界面
### 阶段 4: 动态重启功能
1. 实现客户端 pluginStop 处理
2. 实现服务端重启方法
3. 添加 REST API 端点
4. 更新前端添加控制按钮
### 阶段 5: 测试和文档
1. 端到端测试
2. 更新 CLAUDE.md
---
## 文件变更清单
### 后端 Go 文件
- `pkg/plugin/types.go` - 添加 ConfigField, RuleSchema
- `pkg/plugin/schema.go` (新建) - 内置协议配置模式
- `pkg/protocol/message.go` - 新增消息类型
- `internal/server/db/interface.go` - 更新接口
- `internal/server/db/sqlite.go` - 更新数据库操作
- `internal/server/router/api.go` - 新增 API 端点
- `internal/server/tunnel/server.go` - 重启控制方法
- `internal/client/tunnel/client.go` - 插件停止/重启处理
### 前端文件
- `web/src/types/index.ts` - 类型定义
- `web/src/api/index.ts` - API 调用
- `web/src/views/ClientView.vue` - 规则配置和重启控制
- `web/src/views/PluginsView.vue` - 插件管理界面