update md files

2025-12-26 00:08:28 +08:00
parent 1870b59214
commit d56fdafc1e
2 changed files with 163 additions and 43 deletions
--- a/CLAUDE.md
+++ 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 <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
+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)
--- 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,20 +135,46 @@ 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}
+  ]
+}
+```

 ## 项目结构

@@ -149,12 +183,21 @@ GoTunnel/
 ├── cmd/
 │   ├── server/main.go       # 服务端入口
 │   └── client/main.go       # 客户端入口
+├── internal/
+│   ├── server/
+│   │   ├── tunnel/          # 隧道服务
+│   │   ├── config/          # 配置管理
+│   │   ├── db/              # 数据库存储
+│   │   ├── app/             # Web 服务
+│   │   └── router/          # API 路由
+│   └── client/
+│       └── tunnel/          # 客户端隧道
 ├── pkg/
-│   ├── protocol/         # 通信协议定义
-│   ├── config/           # 配置文件解析
-│   ├── tunnel/           # 核心隧道逻辑
+│   ├── protocol/            # 通信协议
+│   ├── crypto/              # TLS 加密
+│   ├── proxy/               # SOCKS5/HTTP 代理
+│   ├── relay/               # 数据转发
 │   └── utils/               # 工具函数
-├── server.yaml           # 配置示例
 └── go.mod
 ```