From 16a238f34669357371ad3fc1b1aa0285419c7abf Mon Sep 17 00:00:00 2001 From: Flik Date: Thu, 25 Dec 2025 17:20:57 +0800 Subject: [PATCH] add readme.md --- .gitea/workflows/build.yaml | 1 + LICENSE | 21 +++++ README.md | 164 ++++++++++++++++++++++++++++++++++++ server.yaml | 27 ------ 4 files changed, 186 insertions(+), 27 deletions(-) create mode 100644 LICENSE create mode 100644 README.md delete mode 100644 server.yaml diff --git a/.gitea/workflows/build.yaml b/.gitea/workflows/build.yaml index e5b4dc2..a094026 100644 --- a/.gitea/workflows/build.yaml +++ b/.gitea/workflows/build.yaml @@ -19,6 +19,7 @@ jobs: uses: actions/setup-go@v5 with: go-version: '1.21' + cache: true - name: Build all platforms run: | diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3a7c008 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 GoTunnel + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..a46b585 --- /dev/null +++ b/README.md @@ -0,0 +1,164 @@ +# GoTunnel + +一个轻量级、高性能的内网穿透工具，采用服务端集中化管理模式。 + +## 项目简介 + +GoTunnel 是一个类似 frp 的内网穿透解决方案，核心特点是**服务端集中管理配置**。客户端只需提供认证信息即可自动获取映射规则，无需在客户端维护复杂配置。 + +### 架构设计 + +``` +┌──────────────┐ ┌──────────────────────┐ +│ Client │ Control Channel │ Server │ +│ │ ◄────────────────►│ │ +│ ┌────────┐ │ (Yamux Mux) │ ┌────────────────┐ │ +│ │ Agent │ │ │ │ Control Manager│ │ +│ └────────┘ │ │ └────────────────┘ │ +│ │ │ │ │ │ +│ ▼ │ Data Streams │ ▼ │ +│ ┌────────┐ │ ◄────────────────►│ ┌────────────────┐ │ +│ │ Proxy │ │ │ │ Proxy Listener │ │ +│ └────────┘ │ │ │ :8080,:9090 │ │ +│ │ │ │ └────────────────┘ │ +│ ▼ │ │ ▲ │ +│ ┌────────┐ │ │ │ │ +│ │Local:80│ │ │ External Users │ +│ └────────┘ │ │ │ +└──────────────┘ └──────────────────────┘ +``` + +## 功能特性 + +### 核心功能 + +- **服务端集中管理** - 所有客户端的映射规则由服务端统一配置，客户端零配置 +- **多路复用** - 基于 Yamux 实现控制通道与数据通道分离，高效复用单一 TCP 连接 +- **多客户端支持** - 支持多个客户端同时连接，每个客户端独立的映射规则 +- **端口冲突检测** - 自动检测系统端口占用和客户端间端口冲突 + +### 可靠性 + +- **心跳检测** - 可配置的心跳间隔和超时时间，及时发现断线 +- **断线重连** - 客户端自动重连机制，网络恢复后自动恢复服务 +- **优雅关闭** - 客户端断开时自动释放端口资源 + +### 安全性 + +- **Token 认证** - 基于 Token 的身份验证机制 +- **客户端白名单** - 仅配置的客户端 ID 可以连接 +- **TLS 预留** - 预留 TLS 加密扩展接口 + +## 快速开始 + +### 安装 + +**从源码编译：** + +```bash +git clone https://github.com/your-repo/gotunnel.git +cd gotunnel +go build -o server ./cmd/server +go build -o client ./cmd/client +``` + +**下载预编译二进制：** + +从 Releases 页面下载对应平台的二进制文件。 + +### 服务端启动 + +```bash +./server -c server.yaml +``` + +### 客户端启动 + +```bash +./client -s <服务器IP>:7000 -t -id <客户端ID> +``` + +**参数说明：** + +| 参数 | 说明 | 必填 | +|------|------|------| +| `-s` | 服务器地址 (ip:port) | 是 | +| `-t` | 认证 Token | 是 | +| `-id` | 客户端 ID（需与服务端配置匹配） | 否（自动生成） | + +## 配置系统 + +服务端使用 YAML 格式的配置文件，集中管理所有客户端的映射规则。 + +### 配置文件示例 + +```yaml +# server.yaml +server: + bind_addr: "0.0.0.0" # 监听地址 + bind_port: 7000 # 监听端口 + token: "your-secret-token" # 认证 Token + heartbeat_sec: 30 # 心跳间隔（秒） + heartbeat_timeout: 90 # 心跳超时（秒） + +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 +``` + +### 配置参数说明 + +**Server 配置：** + +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `bind_addr` | string | - | 服务端监听地址 | +| `bind_port` | int | - | 服务端监听端口 | +| `token` | string | - | 客户端认证 Token | +| `heartbeat_sec` | int | 30 | 心跳发送间隔（秒） | +| `heartbeat_timeout` | int | 90 | 心跳超时时间（秒） | + +**Rule 配置：** + +| 参数 | 类型 | 说明 | +|------|------|------| +| `name` | string | 规则名称（用于日志标识） | +| `local_ip` | string | 客户端本地服务 IP | +| `local_port` | int | 客户端本地服务端口 | +| `remote_port` | int | 服务端对外暴露端口 | + +## 项目结构 + +``` +GoTunnel/ +├── cmd/ +│ ├── server/main.go # 服务端入口 +│ └── client/main.go # 客户端入口 +├── pkg/ +│ ├── protocol/ # 通信协议定义 +│ ├── config/ # 配置文件解析 +│ ├── tunnel/ # 核心隧道逻辑 +│ └── utils/ # 工具函数 +├── server.yaml # 配置示例 +└── go.mod +``` + +## 许可证 + +本项目采用 [MIT License](LICENSE) 开源许可证。 + diff --git a/server.yaml b/server.yaml deleted file mode 100644 index 43299e6..0000000 --- a/server.yaml +++ /dev/null @@ -1,27 +0,0 @@ -# GoTunnel Server Configuration -server: - bind_addr: "0.0.0.0" - bind_port: 7000 - token: "your-secret-token" - heartbeat_sec: 30 - heartbeat_timeout: 90 - -# Client configurations (centralized management) -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