diff --git a/README-CN.md b/README-CN.md new file mode 100644 index 0000000..823c4c4 --- /dev/null +++ b/README-CN.md @@ -0,0 +1,360 @@ +# gotun + +[English](README.md) | 简䜓䞭文 + +[![Go Reference](https://pkg.go.dev/badge/github.com/Sesame2/gotun.svg)](https://pkg.go.dev/github.com/Sesame2/gotun) +[![Go Report Card](https://goreportcard.com/badge/github.com/Sesame2/gotun)](https://goreportcard.com/report/github.com/Sesame2/gotun) +[![Release](https://img.shields.io/github/v/release/Sesame2/gotun)](https://github.com/Sesame2/gotun/releases) +[![Downloads](https://img.shields.io/github/downloads/Sesame2/gotun/total.svg)](https://github.com/Sesame2/gotun/releases) +[![Homebrew](https://img.shields.io/homebrew/v/gotun)](https://formulae.brew.sh/formula/gotun) +![Go Version](https://img.shields.io/github/go-mod/go-version/Sesame2/gotun) +[![License](https://img.shields.io/github/license/Sesame2/gotun.svg)](LICENSE) + +> 🚀 基于 SSH 的蜻量级 HTTP 代理工具䜿甚 Go 猖写跚平台匀箱即甚。 + +--- + +## ✹ 项目简介 + +`gotun` 是䞀䞪 HTTP-over-SSH 的呜什行代理工具。它通过 SSH 协议连接远皋䞻机利甚该䞻机䜜䞺 **眑络出口**将本地发起的 HTTP 请求安党地通过远皋䞻机访问目标地址。䜠可以䜿甚它来访问 + +- 内眑䞭的路由噚、服务噚、API 等资源 +- 仅远皋䞻机可访问的眑络公叞内眑、隔犻眑段等 +- 任意 HTTP 眑站䜿甚远皋䞻机䜜䞺「䞭蜬代理」 + +## 🎚 工䜜原理瀺意囟 + +### 䜿甚前无法盎接访问内眑资源 +``` +䜠的电脑 防火墙/NAT 内眑环境 +┌─────────┐ ┌─────────┐ ┌─────────────┐ +│ │ ❌ 盎接访问 │ │ │ 📱 路由噚 │ +│ 💻 PC │ ──────────────▶│ 🔥🚫 │ │ 📺 NAS │ +│ │ 被阻止/拒绝 │ │ │ 🖥 服务噚 │ +└─────────┘ └─────────┘ │ 📟 IoT讟倇 │ + └─────────────┘ +``` + +### 䜿甚后通过SSH跳板访问所有内眑资源 +``` +䜠的电脑 SSH连接(22端口) 跳板机 内眑环境 +┌─────────┐ ┌─────────────┐ ┌─────────┐ ┌─────────────┐ +│ │ 🔐 │ │ 🌐 │ │ ✅ │ 📱 路由噚 │ +│ 💻 PC │◀────────▶│ gotun代理隧道│◀───────▶│ 🖥 跳板机 │◀───────▶│ 📺 NAS │ +│ │ HTTP请求 │ (加密䌠蟓) │ SSH │ │ 内眑访问 │ 🖥 服务噚 │ +└─────────┘ └─────────────┘ └─────────┘ │ 📟 IoT讟倇 │ + ↑ └─────────────┘ + └── 浏览噚讟眮代理: 127.0.0.1:8080 +``` + +### 🔑 栞心䌘势 + +| 䌠统方案 | gotun | +|---------|-----------| +| ❌ 需芁倍杂的端口蜬发配眮 | ✅ 仅需䞀䞪SSH连接 | +| ❌ 每䞪服务需芁单独映射端口 | ✅ 访问所有内眑资源无需额倖配眮 | +| ❌ 容易暎露内眑服务到公眑 | ✅ 流量党皋加密安党可靠 | +| ❌ 管理倚䞪连接倍杂 | ✅ 䞀条隧道解决所有问题 | + +**简单来诎**: gotun 让䜠的电脑就像"坐圚"跳板机旁蟹䞀样可以访问跳板机胜访问的任䜕资源 + +--- + +## 🧱 项目特点 + +- ✅ 无需圚远皋䞻机郚眲任䜕代理服务 +- ✅ 党郚请求自劚通过 SSH 加密隧道䌠蟓 +- ✅ 支持访问任䜕远皋䞻机可访问的地址含内眑 +- ✅ 支持倚级跳板机 (Jump Host)蜻束穿透倍杂眑络 +- ✅ 支持跚平台运行Windows / Linux / macOS +- ✅ 支持䜜䞺系统 HTTP 代理可选扩展 +- ✅ 自定义路由规则: 支持通过自定义的规则文件进行流量分流 +- ✅ 呜什行自劚补党: 支持 Bash, Zsh, Fish, PowerShell + +--- + +## 🚀 快速匀始 + +### 安装 + +#### 䜿甚安装脚本 + +```bash +curl -fsSL https://raw.githubusercontent.com/Sesame2/gotun/main/scripts/install.sh | sh +``` + +脚本䌚将 `gotun` 安装到 `~/.local/bin` 或 `/usr/local/bin`。安装完成后请确保安装目圕已添加到悚的 `PATH` 环境变量䞭。 + +#### 䜿甚Homebrew安装 ( macOS / Linux ) + +```bash +brew install gotun +``` + +#### 䞋蜜预猖译二进制文件 + +前埀 [Releases](https://github.com/Sesame2/gotun/releases) 页面䞋蜜适合䜠系统的预猖译版本。 + +#### 从源码猖译 + +```bash +git clone https://github.com/Sesame2/gotun.git +cd gotun +make build +``` + +猖译后的可执行文件䜍于 `build/` 目圕䞋。 + +#### 䜿甚 go install 安装 + +Go 1.17 及以䞊版本可盎接通过以䞋呜什安装 + +```bash +go install github.com/Sesame2/gotun/cmd/gotun@latest +``` + +> **⚠ 泚意**: 䜿甚 `go install` 安装的版本可胜无法通过 `--version` 参数正确星瀺版本号因䞺它盎接从源码猖译猺少版本信息的泚入。䞺了星瀺正确的版本信息掚荐䜿甚安装脚本。 + +安装后请确保䜠的 `$GOPATH/bin` 或 `$GOBIN` 目圕已添加到系统 `PATH` 环境变量䞭。 + +### 基本䜿甚 + +```bash +# 基本甚法连接到SSH服务噚并启劚系统代理 +gotun user@example.com + +# 指定SSH端口 +gotun -p 2222 user@example.com + +# 䜿甚私钥讀证 +gotun -i ~/.ssh/id_rsa user@example.com + +# 自定义代理监听端口 +gotun --listen :8888 user@example.com + +# 自劚讟眮系统代理默讀匀启 +# 若䜠垌望启劚时䞍修改系统代理请星匏关闭 +gotun --sys-proxy=false user@example.com +``` + +### 圚浏览噚䞭䜿甚 + +启劚代理后圚浏览噚䞭配眮HTTP代理 + +- **代理地址**: `127.0.0.1` +- **端口**: `8080` (默讀或䜠指定的端口) + +--- + +## 📖 操䜜手册 + +### 呜什行参数 + +| 参数 | 简写 | 诎明 | 默讀倌 | +|------|------|------|--------| +| `--listen` | `-l` | 本地HTTP代理监听地址 | `:8080` | +| `--port` | `-p` | SSH服务噚端口 | `22` | +| `--pass` | | SSH密码 (䞍安党, 建议䜿甚亀互匏讀证) | | +| `--identity_file` | `-i` | 甚于讀证的私钥文件路埄 | | +| `--jump` | `-J` | 跳板机列衚,甚逗号分隔 (栌匏: user@host:port) | | +| `--target` | | 可选的目标眑络芆盖 | | +| `--timeout` | | 连接超时时闎 | `10s` | +| `--verbose` | `-v` | 启甚诊细日志 | `false` | +| `--log` | | 日志文件路埄 | 蟓出到标准蟓出 | +| `--sys-proxy` | | 自劚讟眮/恢倍系统代理 | `true` | +| `--rules` | | 代理规则配眮文件路埄 | | + +### 䜿甚场景 + +#### 1. 访问内眑服务 + +假讟 `jumpserver.company.com` 可以访问内眑IP `192.168.1.100`。 + +```bash +# 连接到跳板机启劚代理服务 +gotun admin@jumpserver.company.com +``` + +启劚后浏览噚和其他支持系统代理的应甚将自劚通过 `gotun` 访问眑络。现圚可以盎接圚浏览噚䞭打匀 `http://192.168.1.100:8080` 等内眑地址。 + +#### 2. 匀发调试 + +圚本地匀发时需芁连接到远皋匀发服务噚才胜访问数据库或API。 + +```bash +# 启甚诊细日志进行调试并指定监听端口 +gotun --listen :8888 -v developer@dev-server.com +``` + +`gotun` 䌚自劚讟眮系统代理指向 `127.0.0.1:8888`。匀发工具劂果支持系统代理将胜盎接访问远皋资源。劂果䞍想圱响系统其他应甚的联眑可以犁甚系统代理并手劚配眮匀发工具 +`gotun --sys-proxy=false --listen :8888 -v developer@dev-server.com` + +#### 3. 䜜䞺眑络出口 + +将远皋服务噚䜜䞺䜠圓前眑络的出口适合需芁固定IP或访问特定眑络资源的场景。 + +```bash +# 启劚并自劚配眮䞺系统代理 +gotun user@proxy-server.com +``` + +### 跳板机 (Jump Host) + +圓目标服务噚无法盎接访问需芁先登圕䞀台或倚台机噚进行䞭蜬时可以䜿甚跳板机功胜。 + +#### 工䜜原理瀺意囟 +``` +䜠的电脑 SSH隧道 第䞀跳板机 SSH隧道 最终服务噚 +┌─────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ +│ │ 🔐 │ │ 🔐 │ │ 🔐 │ │ 🌐 │ │ +│ 💻 PC │◀───────▶│ gotun隧道 │◀───────▶│ 堡垒机/跳板机│◀───────▶│gotun隧道 │◀───────▶│ 目标䞻机 │ +│ │ HTTP请求│ (加密) │ │ │ │ (加密) │ │ │ +└─────────┘ └───────────┘ └──────────┘ └───────────┘ └──────────┘ +``` + +#### 单级跳板机 + +通过 `jump.host.com` 连接到 `target.server.com`。 + +```bash +gotun -J user1@jump.host.com user2@target.server.com +``` + +#### 倚级跳板机 + +通过 `jump1` -> `jump2` -> `target` 的顺序连接。 + +```bash +gotun -J user1@jump1.com,user2@jump2.com user3@target.com +``` + +`gotun` 䌚䟝次建立SSH隧道最终连接到目标服务噚。 + +### 讀证方匏 + +#### SSH私钥讀证掚荐 + +```bash +# 䜿甚指定私钥文件 +gotun -i ~/.ssh/id_rsa user@example.com + +# 䜿甚默讀私钥自劚检测 ~/.ssh/ 目圕䞋的密钥 +gotun user@example.com +``` + +#### 密码讀证 + +```bash +# 亀互匏蟓入密码掚荐 +gotun user@example.com +# 皋序䌚提瀺蟓入密码 + +# 呜什行指定密码䞍安党䞍掚荐 +gotun --pass yourpassword user@example.com +``` + +### 系统代理讟眮 + +默讀情况䞋 (`--sys-proxy=true`)`gotun` 䌚自劚管理悚操䜜系统的 HTTP 代理。劂果悚䞍垌望 `gotun` 修改悚的系统讟眮可以圚启劚时䜿甚 `--sys-proxy=false` 参数来犁甚歀功胜。 + +圓系统代理功胜匀启时皋序䌚 + +1. **启劚时**: 保存圓前系统代理讟眮然后讟眮䞺䜿甚 gotun 代理 +2. **运行䞭**: 所有系统眑络流量通过 gotun 代理 +3. **退出时**: 自劚恢倍原始的系统代理讟眮 + +支持的操䜜系统 + +- ✅ **macOS**: 通过 `networksetup` 呜什配眮 +- ✅ **Windows**: 通过泚册衚配眮 +- ✅ **Linux**: 通过 GNOME 讟眮和环境变量配眮 + +### 自定义路由规则 (高级) + +`gotun` 支持通过䞀䞪兌容 Clash 栌匏的 YAML 规则文件来粟细化地控制哪些眑络请求通过 SSH 代理哪些则盎接连接。这对于垌望同时访问内眑资源盎连和倖郚资源代理的场景非垞有甚。 + +#### 1. 创建规则文件 + +銖先创建䞀䞪规则文件䟋劂 `rules.yaml` + +```yaml +# rules.yaml +# 暡匏: rule (规则暡匏), global (党局代理), direct (党局盎连) +mode: rule + +# 规则列衚 (从䞊到䞋匹配第䞀䞪匹配的规则生效) +rules: + # 规则让公叞内眑和垞甚囜内眑站盎连 + - DOMAIN-SUFFIX,internal.company.com,DIRECT + - IP-CIDR,10.0.0.0/8,DIRECT + - IP-CIDR,192.168.0.0/16,DIRECT + - DOMAIN-SUFFIX,cn,DIRECT + - DOMAIN-SUFFIX,qq.com,DIRECT + + # 规则让特定服务走代理 + - DOMAIN-SUFFIX,google.com,PROXY + - DOMAIN-SUFFIX,github.com,PROXY + + # 规则所有其他未匹配的流量郜走代理 + - MATCH,PROXY +``` + +#### 2. 启劚 gotun + +䜿甚 `--rules` 参数指定规则文件的路埄来启劚 `gotun`。 + +```bash +gotun --rules ./rules.yaml user@your_ssh_server.com +``` + +现圚圓悚访问 `internal.company.com` 时流量䌚盎接发送而访问 `google.com` 时流量则䌚通过 SSH 隧道代理。 + + +### 故障排陀 + +#### 连接问题 + +```bash +# 启甚诊细日志进行调试 +gotun -v user@example.com + +# 指定日志文件 +gotun -v --log ./gotun.log user@example.com +``` + +#### 权限问题 + +圚某些系统䞊讟眮系统代理需芁管理员权限 + +```bash +# macOS/Linux +sudo gotun user@example.com + +# Windows (以管理员身仜运行 PowerShell/CMD) +.\gotun.exe user@example.com +``` + +--- + + +## 🎯 功胜状态 + +- [x] **HTTP 代理**: 完敎的 HTTP 请求代理 +- [x] **HTTPS 代理**: 支持 CONNECT 方法的 HTTPS 隧道 +- [x] **SSH 私钥讀证**: 支持倚种私钥栌匏 +- [x] **自劚配眮系统代理**: 跚平台系统代理讟眮 +- [x] **亀互匏密码蟓入**: 安党的密码讀证方匏 +- [x] **诊细日志记圕**: 支持调试和故障排陀 +- [x] **跚平台支持**: Windows/Linux/macOS +- [x] **呜什行界面**: 完敎的 CLI 参数支持 +- [x] **跳板机 (Jump Host)**: 支持单级和倚级SSH跳板机 +- [x] **自定义路由规则**: 支持自定义的规则文件进行流量分流 +- [x] **呜什行自劚补党**: 基于 Cobra 的智胜提瀺 +- [ ] **RDP眑关**支持RDP远皋桌面眑关 +- [ ] **托盘 GUI 界面**: 囟圢化甚户界面 +- [ ] **配眮文件富出/富入**: 配眮管理功胜 +- [ ] **SOCKS5 代理支持**: 曎广泛的协议支持 +- [ ] **连接池䌘化**: 提升性胜和皳定性 +- [ ] **统计和监控**: 流量统计和连接监控 + +--- \ No newline at end of file diff --git a/README.md b/README.md index b9c4ea8..d1a2011 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # gotun +English | [简䜓䞭文](README-CN.md) [![Go Reference](https://pkg.go.dev/badge/github.com/Sesame2/gotun.svg)](https://pkg.go.dev/github.com/Sesame2/gotun) [![Go Report Card](https://goreportcard.com/badge/github.com/Sesame2/gotun)](https://goreportcard.com/report/github.com/Sesame2/gotun) @@ -8,92 +9,96 @@ ![Go Version](https://img.shields.io/github/go-mod/go-version/Sesame2/gotun) [![License](https://img.shields.io/github/license/Sesame2/gotun.svg)](LICENSE) -> 🚀 基于 SSH 的蜻量级 HTTP 代理工具䜿甚 Go 猖写跚平台匀箱即甚。 +> Lightweight HTTP-over-SSH proxy written in Go, designed to be cross-platform and easy to deploy. --- -## ✹ 项目简介 +## Overview -`gotun` 是䞀䞪 HTTP-over-SSH 的呜什行代理工具。它通过 SSH 协议连接远皋䞻机利甚该䞻机䜜䞺 **眑络出口**将本地发起的 HTTP 请求安党地通过远皋䞻机访问目标地址。䜠可以䜿甚它来访问 +`gotun` is a command-line HTTP-over-SSH proxy. It establishes an SSH connection to a remote host and uses that host as the **egress point** for HTTP(S) traffic. Local HTTP requests are forwarded through the SSH tunnel and executed from the remote host. -- 内眑䞭的路由噚、服务噚、API 等资源 -- 仅远皋䞻机可访问的眑络公叞内眑、隔犻眑段等 -- 任意 HTTP 眑站䜿甚远皋䞻机䜜䞺「䞭蜬代理」 +Typical use cases: -## 🎚 工䜜原理瀺意囟 +- Accessing routers, servers, APIs and other resources in a private network +- Reaching networks that are only visible from a specific host (bastion/jump host, corporate network, isolated segments, etc.) +- Using the remote host as an outbound HTTP proxy -### 䜿甚前无法盎接访问内眑资源 -``` -䜠的电脑 防火墙/NAT 内眑环境 -┌─────────┐ ┌─────────┐ ┌─────────────┐ -│ │ ❌ 盎接访问 │ │ │ 📱 路由噚 │ -│ 💻 PC │ ──────────────▶│ 🔥🚫 │ │ 📺 NAS │ -│ │ 被阻止/拒绝 │ │ │ 🖥 服务噚 │ -└─────────┘ └─────────┘ │ 📟 IoT讟倇 │ - └─────────────┘ -``` +--- -### 䜿甚后通过SSH跳板访问所有内眑资源 -``` -䜠的电脑 SSH连接(22端口) 跳板机 内眑环境 -┌─────────┐ ┌─────────────┐ ┌─────────┐ ┌─────────────┐ -│ │ 🔐 │ │ 🌐 │ │ ✅ │ 📱 路由噚 │ -│ 💻 PC │◀────────▶│ gotun代理隧道│◀───────▶│ 🖥 跳板机 │◀───────▶│ 📺 NAS │ -│ │ HTTP请求 │ (加密䌠蟓) │ SSH │ │ 内眑访问 │ 🖥 服务噚 │ -└─────────┘ └─────────────┘ └─────────┘ │ 📟 IoT讟倇 │ - ↑ └─────────────┘ - └── 浏览噚讟眮代理: 127.0.0.1:8080 +## How it works + +### Before: no direct access to internal resources + +```text +Your machine Firewall/NAT Internal network +┌─────────┐ ┌─────────┐ ┌─────────────┐ +│ │ ❌ direct │ │ │ Router │ +│ PC │ ─────────────▶ │ FW/NAT │ │ NAS │ +│ │ blocked │ │ │ Servers │ +└─────────┘ └─────────┘ └─────────────┘ ``` -### 🔑 栞心䌘势 +### After: access via SSH bastion with gotun + +```text +Your machine SSH (tcp/22) Bastion Internal network +┌─────────┐ ┌─────────────┐ ┌─────────┐ ┌─────────────┐ +│ │ HTTP │ gotun HTTP │ SSH tunnel │ │ internal │ Router │ +│ PC │ ◀──────▶ │ proxy │◀──────────────▶│ Bastion │◀────────────▶│ NAS │ +│ │ └─────────────┘ │ │ │ Servers │ +└─────────┘ └─────────┘ └─────────────┘ + ↑ + └─ HTTP proxy set to 127.0.0.1:8080 +``` -| 䌠统方案 | gotun | -|---------|-----------| -| ❌ 需芁倍杂的端口蜬发配眮 | ✅ 仅需䞀䞪SSH连接 | -| ❌ 每䞪服务需芁单独映射端口 | ✅ 访问所有内眑资源无需额倖配眮 | -| ❌ 容易暎露内眑服务到公眑 | ✅ 流量党皋加密安党可靠 | -| ❌ 管理倚䞪连接倍杂 | ✅ 䞀条隧道解决所有问题 | +### Why use gotun? -**简单来诎**: gotun 让䜠的电脑就像"坐圚"跳板机旁蟹䞀样可以访问跳板机胜访问的任䜕资源 +| Traditional approach | With gotun | +|---------------------------------------------|-------------------------------------------------| +| Manual port forwards per service | One SSH tunnel for all HTTP(S) traffic | +| Multiple ports exposed on the bastion | No extra open ports; uses existing SSH only | +| Hard to manage multiple mappings | Single proxy endpoint | +| Easy to accidentally expose internal hosts | All traffic stays inside an encrypted SSH tunnel | --- -## 🧱 项目特点 +## Features -- ✅ 无需圚远皋䞻机郚眲任䜕代理服务 -- ✅ 党郚请求自劚通过 SSH 加密隧道䌠蟓 -- ✅ 支持访问任䜕远皋䞻机可访问的地址含内眑 -- ✅ 支持倚级跳板机 (Jump Host)蜻束穿透倍杂眑络 -- ✅ 支持跚平台运行Windows / Linux / macOS -- ✅ 支持䜜䞺系统 HTTP 代理可选扩展 -- ✅ 自定义路由规则: 支持通过自定义的规则文件进行流量分流 -- ✅ 呜什行自劚补党: 支持 Bash, Zsh, Fish, PowerShell +- No additional software required on the remote host (only SSH) +- All traffic is carried over an SSH tunnel +- Can reach any address that the remote host can reach (including internal addresses) +- Supports single and multi-hop SSH jump hosts +- Cross-platform: Windows, Linux, macOS +- Can be used as a system HTTP proxy (optional) +- Rule-based traffic splitting via configuration file +- Shell completion support for Bash, Zsh, Fish, PowerShell +- Structured logging and verbose mode for debugging --- -## 🚀 快速匀始 - -### 安装 +## Installation -#### 䜿甚安装脚本 (掚荐) +### Install script ```bash curl -fsSL https://raw.githubusercontent.com/Sesame2/gotun/main/scripts/install.sh | sh ``` -脚本䌚将 `gotun` 安装到 `~/.local/bin` 或 `/usr/local/bin`。安装完成后请确保安装目圕已添加到悚的 `PATH` 环境变量䞭。 +The script installs `gotun` into `~/.local/bin` or `/usr/local/bin`. +Make sure that directory is included in your `PATH`. -#### 䜿甚Homebrew安装 ( macOS / Linux ) +### Homebrew (macOS / Linux) ```bash brew install gotun ``` -#### 䞋蜜预猖译二进制文件 +### Download prebuilt binaries -前埀 [Releases](https://github.com/Sesame2/gotun/releases) 页面䞋蜜适合䜠系统的预猖译版本。 +Download the appropriate binary for your platform from the +[Releases page](https://github.com/Sesame2/gotun/releases). -#### 从源码猖译 +### Build from source ```bash git clone https://github.com/Sesame2/gotun.git @@ -101,258 +106,312 @@ cd gotun make build ``` -猖译后的可执行文件䜍于 `build/` 目圕䞋。 +The binary will be placed under `build/`. -#### 䜿甚 go install 安装 +### `go install` -Go 1.17 及以䞊版本可盎接通过以䞋呜什安装 +With Go 1.17+: ```bash go install github.com/Sesame2/gotun/cmd/gotun@latest ``` -> **⚠ 泚意**: 䜿甚 `go install` 安装的版本可胜无法通过 `--version` 参数正确星瀺版本号因䞺它盎接从源码猖译猺少版本信息的泚入。䞺了星瀺正确的版本信息掚荐䜿甚安装脚本。 +> Note: when installing via `go install`, the `--version` output may not include an exact version number, as it depends on build-time metadata. For reproducible version information, prefer the install script, Homebrew, or release binaries. -安装后请确保䜠的 `$GOPATH/bin` 或 `$GOBIN` 目圕已添加到系统 `PATH` 环境变量䞭。 +Ensure `$GOBIN` or `$GOPATH/bin` is on your `PATH`. -### 基本䜿甚 +--- + +## Quick start + +### Basic usage ```bash -# 基本甚法连接到SSH服务噚并启劚系统代理 +# Basic: connect to an SSH server and start an HTTP proxy gotun user@example.com -# 指定SSH端口 +# Use a non-default SSH port gotun -p 2222 user@example.com -# 䜿甚私钥讀证 +# Use a specific private key gotun -i ~/.ssh/id_rsa user@example.com -# 自定义代理监听端口 +# Change local proxy listen address/port gotun --listen :8888 user@example.com -# 自劚讟眮系统代理默讀匀启 -# 若䜠垌望启劚时䞍修改系统代理请星匏关闭 +# Disable automatic system proxy configuration gotun --sys-proxy=false user@example.com ``` -### 圚浏览噚䞭䜿甚 +### Browser configuration + +By default, gotun listens on `127.0.0.1:8080` (unless changed by `--listen`). -启劚代理后圚浏览噚䞭配眮HTTP代理 +In your browser’s proxy settings: -- **代理地址**: `127.0.0.1` -- **端口**: `8080` (默讀或䜠指定的端口) +- HTTP proxy host: `127.0.0.1` +- HTTP proxy port: `8080` (or the port you configured) + +If system proxy support is enabled, some platforms can be configured automatically. --- -## 📖 操䜜手册 +## Command-line options + +| Flag | Short | Description | Default | +|-------------------|-------|---------------------------------------------------|--------------| +| `--listen` | `-l` | Local HTTP proxy bind address | `:8080` | +| `--port` | `-p` | SSH server port | `22` | +| `--pass` | | SSH password (not recommended; use interactively) | | +| `--identity_file` | `-i` | Private key file path | | +| `--jump` | `-J` | Comma-separated jump hosts (`user@host:port`) | | +| `--target` | | Optional target network scope/coverage | | +| `--timeout` | | SSH connection timeout | `10s` | +| `--verbose` | `-v` | Enable verbose logging | `false` | +| `--log` | | Log file path | stdout | +| `--sys-proxy` | | Enable automatic system proxy configuration | `true` | +| `--rules` | | Path to routing rules configuration file | | -### 呜什行参数 +Run `gotun --help` for the full list of options. -| 参数 | 简写 | 诎明 | 默讀倌 | -|------|------|------|--------| -| `--listen` | `-l` | 本地HTTP代理监听地址 | `:8080` | -| `--port` | `-p` | SSH服务噚端口 | `22` | -| `--pass` | | SSH密码 (䞍安党, 建议䜿甚亀互匏讀证) | | -| `--identity_file` | `-i` | 甚于讀证的私钥文件路埄 | | -| `--jump` | `-J` | 跳板机列衚,甚逗号分隔 (栌匏: user@host:port) | | -| `--target` | | 可选的目标眑络芆盖 | | -| `--timeout` | | 连接超时时闎 | `10s` | -| `--verbose` | `-v` | 启甚诊细日志 | `false` | -| `--log` | | 日志文件路埄 | 蟓出到标准蟓出 | -| `--sys-proxy` | | 自劚讟眮/恢倍系统代理 | `true` | -| `--rules` | | 代理规则配眮文件路埄 | | +--- -### 䜿甚场景 +## Typical scenarios -#### 1. 访问内眑服务 +### 1. Accessing internal services through a bastion -假讟 `jumpserver.company.com` 可以访问内眑IP `192.168.1.100`。 +Assume `jumpserver.company.com` can reach `192.168.1.100` inside a private network: ```bash -# 连接到跳板机启劚代理服务 gotun admin@jumpserver.company.com ``` -启劚后浏览噚和其他支持系统代理的应甚将自劚通过 `gotun` 访问眑络。现圚可以盎接圚浏览噚䞭打匀 `http://192.168.1.100:8080` 等内眑地址。 +Once running and proxy is configured, you can browse: -#### 2. 匀发调试 +- `http://192.168.1.100:8080` +- Other HTTP(S) endpoints reachable from the jumpserver -圚本地匀发时需芁连接到远皋匀发服务噚才胜访问数据库或API。 +### 2. Development and debugging + +You need to reach a remote dev environment (APIs, DB, etc.) from your local machine: ```bash -# 启甚诊细日志进行调试并指定监听端口 +# Verbose logging and custom listen port gotun --listen :8888 -v developer@dev-server.com ``` -`gotun` 䌚自劚讟眮系统代理指向 `127.0.0.1:8888`。匀发工具劂果支持系统代理将胜盎接访问远皋资源。劂果䞍想圱响系统其他应甚的联眑可以犁甚系统代理并手劚配眮匀发工具 -`gotun --sys-proxy=false --listen :8888 -v developer@dev-server.com` +If you do not want gotun to modify system proxy settings: + +```bash +gotun --sys-proxy=false --listen :8888 -v developer@dev-server.com +``` -#### 3. 䜜䞺眑络出口 +Then configure your IDE or tooling to use `127.0.0.1:8888` as HTTP proxy. -将远皋服务噚䜜䞺䜠圓前眑络的出口适合需芁固定IP或访问特定眑络资源的场景。 +### 3. Using a remote host as internet egress ```bash -# 启劚并自劚配眮䞺系统代理 gotun user@proxy-server.com ``` -### 跳板机 (Jump Host) +All (or selected) HTTP(S) traffic will exit from the remote server’s network. -圓目标服务噚无法盎接访问需芁先登圕䞀台或倚台机噚进行䞭蜬时可以䜿甚跳板机功胜。 +--- -#### 工䜜原理瀺意囟 -``` -䜠的电脑 SSH隧道 第䞀跳板机 SSH隧道 最终服务噚 +## Jump hosts + +When the final target is only reachable via one or more intermediate hosts, you can configure jump hosts. + + +### Workflow diagram + +```text +Your machine SSH Tunnel Jump Host SSH Tunnel Target Host ┌─────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ │ │ 🔐 │ │ 🔐 │ │ 🔐 │ │ 🌐 │ │ -│ 💻 PC │◀───────▶│ gotun隧道 │◀───────▶│ 堡垒机/跳板机│◀───────▶│gotun隧道 │◀───────▶│ 目标䞻机 │ -│ │ HTTP请求│ (加密) │ │ │ │ (加密) │ │ │ +│ PC │◀───────▶│ gotun tun │◀───────▶│ Bastion │◀───────▶│ gotun tun │◀───────▶│ Target │ +│ │ HTTP │ (encrypt) │ │ │ │ (encrypt) │ │ │ └─────────┘ └───────────┘ └──────────┘ └───────────┘ └──────────┘ ``` -#### 单级跳板机 - -通过 `jump.host.com` 连接到 `target.server.com`。 +### Single jump host ```bash gotun -J user1@jump.host.com user2@target.server.com ``` -#### 倚级跳板机 +Traffic flow: -通过 `jump1` -> `jump2` -> `target` 的顺序连接。 +```text +PC → SSH to jump.host.com → SSH to target.server.com → HTTP request +``` + +### Multiple jump hosts ```bash gotun -J user1@jump1.com,user2@jump2.com user3@target.com ``` -`gotun` 䌚䟝次建立SSH隧道最终连接到目标服务噚。 +`gotun` will establish nested SSH tunnels through each hop in order. -### 讀证方匏 +--- -#### SSH私钥讀证掚荐 +## Authentication + +### SSH key authentication (recommended) ```bash -# 䜿甚指定私钥文件 +# Explicit key gotun -i ~/.ssh/id_rsa user@example.com -# 䜿甚默讀私钥自劚检测 ~/.ssh/ 目圕䞋的密钥 +# Rely on default keys in ~/.ssh gotun user@example.com ``` -#### 密码讀证 +### Password authentication ```bash -# 亀互匏蟓入密码掚荐 +# Interactive (recommended over CLI flags) gotun user@example.com -# 皋序䌚提瀺蟓入密码 +# gotun will prompt for the password -# 呜什行指定密码䞍安党䞍掚荐 -gotun --pass yourpassword user@example.com +# Non-interactive (not recommended) +gotun --pass 'yourpassword' user@example.com ``` -### 系统代理讟眮 +Avoid passing passwords directly on the command line when possible. + +--- + +## System proxy integration + +By default (`--sys-proxy=true`), gotun attempts to: + +1. Capture the current system proxy settings +2. Set the system HTTP proxy to its local listening address (e.g. `127.0.0.1:8080`) +3. Restore the original settings on exit + +If you prefer to manage proxy settings yourself, run: -默讀情况䞋 (`--sys-proxy=true`)`gotun` 䌚自劚管理悚操䜜系统的 HTTP 代理。劂果悚䞍垌望 `gotun` 修改悚的系统讟眮可以圚启劚时䜿甚 `--sys-proxy=false` 参数来犁甚歀功胜。 +```bash +gotun --sys-proxy=false user@example.com +``` -圓系统代理功胜匀启时皋序䌚 +Platform notes: -1. **启劚时**: 保存圓前系统代理讟眮然后讟眮䞺䜿甚 gotun 代理 -2. **运行䞭**: 所有系统眑络流量通过 gotun 代理 -3. **退出时**: 自劚恢倍原始的系统代理讟眮 +- **macOS**: uses `networksetup` +- **Windows**: uses registry-based proxy configuration +- **Linux**: attempts to use desktop settings (e.g. GNOME) and/or environment variables where applicable -支持的操䜜系统 +--- -- ✅ **macOS**: 通过 `networksetup` 呜什配眮 -- ✅ **Windows**: 通过泚册衚配眮 -- ✅ **Linux**: 通过 GNOME 讟眮和环境变量配眮 +## Rule-based routing (advanced) -### 自定义路由规则 (高级) +`gotun` can read a Clash-style YAML rules file to decide which traffic is sent via the SSH proxy and which goes directly. -`gotun` 支持通过䞀䞪兌容 Clash 栌匏的 YAML 规则文件来粟细化地控制哪些眑络请求通过 SSH 代理哪些则盎接连接。这对于垌望同时访问内眑资源盎连和倖郚资源代理的场景非垞有甚。 +This is useful when you need: -#### 1. 创建规则文件 +- Direct access to local or corporate networks +- Proxy only for selected destinations (e.g. external services) -銖先创建䞀䞪规则文件䟋劂 `rules.yaml` +### Example rules file + +`rules.yaml`: ```yaml -# rules.yaml -# 暡匏: rule (规则暡匏), global (党局代理), direct (党局盎连) mode: rule -# 规则列衚 (从䞊到䞋匹配第䞀䞪匹配的规则生效) rules: - # 规则让公叞内眑和垞甚囜内眑站盎连 + # Direct access for internal domains and networks - DOMAIN-SUFFIX,internal.company.com,DIRECT - IP-CIDR,10.0.0.0/8,DIRECT - IP-CIDR,192.168.0.0/16,DIRECT - DOMAIN-SUFFIX,cn,DIRECT - DOMAIN-SUFFIX,qq.com,DIRECT - # 规则让特定服务走代理 + # Specific domains via proxy - DOMAIN-SUFFIX,google.com,PROXY - DOMAIN-SUFFIX,github.com,PROXY - # 规则所有其他未匹配的流量郜走代理 + # Everything else via proxy - MATCH,PROXY ``` -#### 2. 启劚 gotun - -䜿甚 `--rules` 参数指定规则文件的路埄来启劚 `gotun`。 +Start gotun with the rules file: ```bash gotun --rules ./rules.yaml user@your_ssh_server.com ``` -现圚圓悚访问 `internal.company.com` 时流量䌚盎接发送而访问 `google.com` 时流量则䌚通过 SSH 隧道代理。 +Requests will be matched from top to bottom; the first matching rule applies. +--- -### 故障排陀 +## Troubleshooting -#### 连接问题 +### Connection issues ```bash -# 启甚诊细日志进行调试 +# Enable verbose logs gotun -v user@example.com -# 指定日志文件 +# Log to a file gotun -v --log ./gotun.log user@example.com ``` -#### 权限问题 +Check: -圚某些系统䞊讟眮系统代理需芁管理员权限 +- SSH connectivity (`ssh user@example.com`) +- Firewall or security groups +- Correct key/port/jump configuration + +### Permission issues (system proxy) + +On some systems, changing system proxy settings requires elevated privileges: ```bash -# macOS/Linux +# macOS / Linux sudo gotun user@example.com -# Windows (以管理员身仜运行 PowerShell/CMD) -.\gotun.exe user@example.com +# Windows: run cmd/PowerShell as Administrator +gotun.exe user@example.com +``` + +If this is not acceptable, disable system proxy management and configure proxy settings manually: + +```bash +gotun --sys-proxy=false user@example.com ``` --- +## Status and roadmap + +Implemented: + +- [x] HTTP proxy +- [x] HTTPS tunneling via `CONNECT` +- [x] SSH key-based authentication +- [x] Interactive password authentication +- [x] Optional automatic system proxy configuration +- [x] Cross-platform support (Windows/Linux/macOS) +- [x] Verbose logging and log file output +- [x] CLI flags and subcommands +- [x] Single and multi-hop jump host support +- [x] Rule-based routing +- [x] Shell completion for common shells + +Planned: + +- [ ] RDP gateway support +- [ ] Tray/GUI frontend +- [ ] Export/import of configuration profiles +- [ ] SOCKS5 proxy support +- [ ] Connection pooling and performance tuning +- [ ] Traffic statistics and basic monitoring + +--- + +## License -## 🎯 功胜状态 - -- [x] **HTTP 代理**: 完敎的 HTTP 请求代理 -- [x] **HTTPS 代理**: 支持 CONNECT 方法的 HTTPS 隧道 -- [x] **SSH 私钥讀证**: 支持倚种私钥栌匏 -- [x] **自劚配眮系统代理**: 跚平台系统代理讟眮 -- [x] **亀互匏密码蟓入**: 安党的密码讀证方匏 -- [x] **诊细日志记圕**: 支持调试和故障排陀 -- [x] **跚平台支持**: Windows/Linux/macOS -- [x] **呜什行界面**: 完敎的 CLI 参数支持 -- [x] **跳板机 (Jump Host)**: 支持单级和倚级SSH跳板机 -- [x] **自定义路由规则**: 支持自定义的规则文件进行流量分流 -- [x] **呜什行自劚补党**: 基于 Cobra 的智胜提瀺 -- [ ] **RDP眑关**支持RDP远皋桌面眑关 -- [ ] **托盘 GUI 界面**: 囟圢化甚户界面 -- [ ] **配眮文件富出/富入**: 配眮管理功胜 -- [ ] **SOCKS5 代理支持**: 曎广泛的协议支持 -- [ ] **连接池䌘化**: 提升性胜和皳定性 -- [ ] **统计和监控**: 流量统计和连接监控 - ---- \ No newline at end of file +This project is licensed under the [MIT License](LICENSE).