4623a7f031
All checks were successful
Build Multi-Platform Binaries / build (push) Successful in 11m9s
119 lines
4.3 KiB
Markdown
119 lines
4.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Build Commands
|
||
|
||
```bash
|
||
# Build server and client binaries
|
||
go build -o server ./cmd/server
|
||
go build -o client ./cmd/client
|
||
|
||
# Run server (zero-config, auto-generates token and TLS cert)
|
||
./server
|
||
./server -c server.yaml # with config file
|
||
|
||
# Run client
|
||
./client -s <server>:7000 -t <token> -id <client-id>
|
||
./client -s <server>:7000 -t <token> -id <client-id> -no-tls # disable TLS
|
||
|
||
# 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/)
|
||
```
|
||
|
||
## Architecture Overview
|
||
|
||
GoTunnel is an intranet penetration tool (similar to frp) with **server-centric configuration** - clients require zero configuration and receive mapping rules from the server after authentication.
|
||
|
||
### Core Design
|
||
|
||
- **Yamux Multiplexing**: Single TCP connection carries both control (auth, config, heartbeat) and data channels
|
||
- **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`
|
||
|
||
### Package Structure
|
||
|
||
```
|
||
cmd/server/ # Server entry point
|
||
cmd/client/ # Client entry point
|
||
internal/server/
|
||
├── tunnel/ # Core tunnel server, client session management
|
||
├── config/ # YAML configuration loading
|
||
├── db/ # SQLite storage (ClientStore interface)
|
||
├── app/ # Web server, SPA handler
|
||
├── router/ # REST API endpoints
|
||
└── plugin/ # Server-side plugin manager
|
||
internal/client/
|
||
├── tunnel/ # Client tunnel logic, auto-reconnect
|
||
└── plugin/ # Client-side plugin manager and cache
|
||
pkg/
|
||
├── protocol/ # Message types and serialization
|
||
├── crypto/ # TLS certificate generation
|
||
├── proxy/ # Legacy proxy implementations
|
||
├── relay/ # Bidirectional data relay (32KB buffers)
|
||
├── utils/ # Port availability checking
|
||
└── plugin/ # Plugin system core
|
||
├── types.go # ProxyHandler interface, PluginMetadata
|
||
├── registry.go # Plugin registry
|
||
├── builtin/ # Built-in plugins (socks5, http)
|
||
├── wasm/ # WASM runtime (wazero)
|
||
└── store/ # Plugin persistence (SQLite)
|
||
web/ # Vue 3 + TypeScript frontend (Vite)
|
||
```
|
||
|
||
### 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
|
||
|
||
### Proxy Types
|
||
|
||
**内置类型** (直接在 tunnel 中处理):
|
||
1. **TCP** (default): Direct port forwarding (remote_port → local_ip:local_port)
|
||
2. **UDP**: UDP port forwarding
|
||
3. **HTTP**: HTTP proxy through client network
|
||
4. **HTTPS**: HTTPS proxy through client network
|
||
|
||
**插件类型** (通过 plugin 系统提供):
|
||
- **SOCKS5**: Full SOCKS5 protocol (official plugin)
|
||
|
||
### Data Flow
|
||
|
||
External User → Server Port → Yamux Stream → Client → Local Service
|
||
|
||
### Configuration
|
||
|
||
- Server: YAML config + SQLite database for client rules
|
||
- 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.
|
||
|
||
### Plugin Architecture
|
||
|
||
- **内置类型**: tcp, udp, http, https 直接在 tunnel 代码中处理
|
||
- **Official Plugin**: SOCKS5 作为官方 plugin 提供
|
||
- **WASM Plugins**: 自定义 plugins 可通过 wazero 运行时动态加载
|
||
- **Hybrid Distribution**: 内置 plugins 离线可用；WASM plugins 可从服务端下载
|
||
|
||
### ProxyHandler Interface
|
||
|
||
```go
|
||
type ProxyHandler interface {
|
||
Metadata() PluginMetadata
|
||
Init(config map[string]string) error
|
||
HandleConn(conn net.Conn, dialer Dialer) error
|
||
Close() error
|
||
}
|
||
```
|
||
|
||
### Creating a Built-in Plugin
|
||
|
||
See `pkg/plugin/builtin/socks5.go` as reference implementation.
|