diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f5747cb --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,77 @@ +# 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 :7000 -t -id +./client -s :7000 -t -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 +internal/client/ + └── tunnel/ # Client tunnel logic, auto-reconnect +pkg/ + ├── protocol/ # Message types and serialization + ├── crypto/ # TLS certificate generation + ├── proxy/ # SOCKS5 and HTTP proxy implementations + ├── relay/ # Bidirectional data relay (32KB buffers) + └── utils/ # Port availability checking +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 + +### Proxy Types + +1. **TCP** (default): Direct port forwarding (remote_port → local_ip:local_port) +2. **SOCKS5**: Full SOCKS5 protocol via `TunnelDialer` +3. **HTTP**: HTTP/HTTPS proxy through client network + +### 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) diff --git a/README.md b/README.md index a46b585..e21a16c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # GoTunnel -一个轻量级、高性能的内网穿透工具，采用服务端集中化管理模式。 +一个轻量级、高性能的内网穿透工具，采用服务端集中化管理模式，支持 TLS 加密通信。 ## 项目简介 -GoTunnel 是一个类似 frp 的内网穿透解决方案，核心特点是**服务端集中管理配置**。客户端只需提供认证信息即可自动获取映射规则，无需在客户端维护复杂配置。 +GoTunnel 是一个类似 frp 的内网穿透解决方案，核心特点是**服务端集中管理配置**和**零配置 TLS 加密**。客户端只需提供认证信息即可自动获取映射规则，无需在客户端维护复杂配置。 ### 架构设计 @@ -36,6 +36,13 @@ GoTunnel 是一个类似 frp 的内网穿透解决方案，核心特点是**服 - **多路复用** - 基于 Yamux 实现控制通道与数据通道分离，高效复用单一 TCP 连接 - **多客户端支持** - 支持多个客户端同时连接，每个客户端独立的映射规则 - **端口冲突检测** - 自动检测系统端口占用和客户端间端口冲突 +- **SOCKS5/HTTP 代理** - 支持通过客户端网络访问任意网站 + +### 安全性 + +- **TLS 加密** - 默认启用 TLS 加密，证书自动生成，零配置 +- **Token 认证** - 基于 Token 的身份验证机制 +- **客户端白名单** - 仅配置的客户端 ID 可以连接 ### 可靠性 @@ -43,11 +50,11 @@ GoTunnel 是一个类似 frp 的内网穿透解决方案，核心特点是**服 - **断线重连** - 客户端自动重连机制，网络恢复后自动恢复服务 - **优雅关闭** - 客户端断开时自动释放端口资源 -### 安全性 +### Web 管理 -- **Token 认证** - 基于 Token 的身份验证机制 -- **客户端白名单** - 仅配置的客户端 ID 可以连接 -- **TLS 预留** - 预留 TLS 加密扩展接口 +- **Web 控制台** - 内置 Web 管理界面，可视化管理客户端和规则 +- **实时状态** - 查看客户端在线状态 +- **动态配置** - 在线添加/修改客户端规则 ## 快速开始 @@ -69,9 +76,19 @@ go build -o client ./cmd/client ### 服务端启动 ```bash +# 零配置启动（自动生成 Token，启用 TLS 和 Web 控制台） +./server + +# 或指定配置文件 ./server -c server.yaml ``` +首次启动会自动： +- 生成随机 Token（打印在日志中） +- 启用 TLS 加密（证书在内存中自动生成） +- 启动 Web 控制台（默认 http://localhost:7500） +- 创建 SQLite 数据库存储客户端配置 + ### 客户端启动 ```bash @@ -85,10 +102,11 @@ go build -o client ./cmd/client | `-s` | 服务器地址 (ip:port) | 是 | | `-t` | 认证 Token | 是 | | `-id` | 客户端 ID（需与服务端配置匹配） | 否（自动生成） | +| `-no-tls` | 禁用 TLS 加密 | 否 | ## 配置系统 -服务端使用 YAML 格式的配置文件，集中管理所有客户端的映射规则。 +服务端使用 YAML 配置文件 + SQLite 数据库管理。YAML 配置服务端参数，SQLite 存储客户端规则。 ### 配置文件示例 @@ -97,28 +115,18 @@ go build -o client ./cmd/client server: bind_addr: "0.0.0.0" # 监听地址 bind_port: 7000 # 监听端口 - token: "your-secret-token" # 认证 Token + token: "your-secret-token" # 认证 Token（不配置则自动生成） heartbeat_sec: 30 # 心跳间隔（秒） heartbeat_timeout: 90 # 心跳超时（秒） + db_path: "gotunnel.db" # 数据库路径 + tls_disabled: false # 是否禁用 TLS（默认启用） -clients: - - id: "client-a" - rules: - - name: "web" - local_ip: "127.0.0.1" - local_port: 80 - remote_port: 8080 - - name: "ssh" - local_ip: "127.0.0.1" - local_port: 22 - remote_port: 2222 - - - id: "client-b" - rules: - - name: "mysql" - local_ip: "127.0.0.1" - local_port: 3306 - remote_port: 13306 +web: + enabled: true # 启用 Web 控制台 + bind_addr: "0.0.0.0" + bind_port: 7500 + username: "admin" # 可选，设置后启用认证 + password: "password" ``` ### 配置参数说明 @@ -127,34 +135,69 @@ clients: | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| -| `bind_addr` | string | - | 服务端监听地址 | -| `bind_port` | int | - | 服务端监听端口 | -| `token` | string | - | 客户端认证 Token | +| `bind_addr` | string | 0.0.0.0 | 服务端监听地址 | +| `bind_port` | int | 7000 | 服务端监听端口 | +| `token` | string | 自动生成 | 客户端认证 Token | | `heartbeat_sec` | int | 30 | 心跳发送间隔（秒） | | `heartbeat_timeout` | int | 90 | 心跳超时时间（秒） | +| `db_path` | string | gotunnel.db | SQLite 数据库路径 | +| `tls_disabled` | bool | false | 是否禁用 TLS | -**Rule 配置：** +**Web 配置：** -| 参数 | 类型 | 说明 | -|------|------|------| -| `name` | string | 规则名称（用于日志标识） | -| `local_ip` | string | 客户端本地服务 IP | -| `local_port` | int | 客户端本地服务端口 | -| `remote_port` | int | 服务端对外暴露端口 | +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `enabled` | bool | true | 是否启用 Web 控制台 | +| `bind_addr` | string | 0.0.0.0 | Web 监听地址 | +| `bind_port` | int | 7500 | Web 监听端口 | +| `username` | string | - | 认证用户名（可选） | +| `password` | string | - | 认证密码（可选） | + +## 代理规则类型 + +通过 Web 控制台配置客户端规则时，支持以下类型： + +| 类型 | 说明 | 示例用途 | +|------|------|----------| +| `tcp` | TCP 端口转发（默认） | SSH、MySQL、Web 服务 | +| `socks5` | SOCKS5 代理 | 通过客户端网络访问任意地址 | +| `http` | HTTP 代理 | 通过客户端网络访问 HTTP/HTTPS | + +**规则配置示例（通过 Web API）：** + +```json +{ + "id": "client-a", + "rules": [ + {"name": "web", "type": "tcp", "local_ip": "127.0.0.1", "local_port": 80, "remote_port": 8080}, + {"name": "socks5-proxy", "type": "socks5", "remote_port": 1080}, + {"name": "http-proxy", "type": "http", "remote_port": 8888} + ] +} +``` ## 项目结构 ``` GoTunnel/ ├── cmd/ -│ ├── server/main.go # 服务端入口 -│ └── client/main.go # 客户端入口 +│ ├── server/main.go # 服务端入口 +│ └── client/main.go # 客户端入口 +├── internal/ +│ ├── server/ +│ │ ├── tunnel/ # 隧道服务 +│ │ ├── config/ # 配置管理 +│ │ ├── db/ # 数据库存储 +│ │ ├── app/ # Web 服务 +│ │ └── router/ # API 路由 +│ └── client/ +│ └── tunnel/ # 客户端隧道 ├── pkg/ -│ ├── protocol/ # 通信协议定义 -│ ├── config/ # 配置文件解析 -│ ├── tunnel/ # 核心隧道逻辑 -│ └── utils/ # 工具函数 -├── server.yaml # 配置示例 +│ ├── protocol/ # 通信协议 +│ ├── crypto/ # TLS 加密 +│ ├── proxy/ # SOCKS5/HTTP 代理 +│ ├── relay/ # 数据转发 +│ └── utils/ # 工具函数 └── go.mod ```