Skip to content

Commit d099f6a

Browse files
committed
docs: 更新README,添加快速开始,添加工作示意图,添加操作手册,修改功能列表
1 parent c5af9e1 commit d099f6a

1 file changed

Lines changed: 207 additions & 9 deletions

File tree

README.md

Lines changed: 207 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,42 @@
1212
- 仅远程主机可访问的网络(公司内网、隔离网段等)
1313
- 任意 HTTP 网站,使用远程主机作为「中转代理」
1414

15+
## 🎨 工作原理示意图
16+
17+
### 使用前:无法直接访问内网资源
18+
```
19+
你的电脑 防火墙/NAT 内网环境
20+
┌─────────┐ ┌─────────┐ ┌─────────────┐
21+
│ │ ❌ 直接访问 │ │ │ 📱 路由器 │
22+
│ 💻 PC │ ──────────────▶│ 🔥🚫 │ │ 📺 NAS │
23+
│ │ 被阻止/拒绝 │ │ │ 🖥️ 服务器 │
24+
└─────────┘ └─────────┘ │ 📟 IoT设备 │
25+
└─────────────┘
26+
```
27+
28+
### 使用后:通过SSH跳板访问所有内网资源
29+
```
30+
你的电脑 SSH连接(22端口) 跳板机 内网环境
31+
┌─────────┐ ┌─────────────┐ ┌─────────┐ ┌─────────────┐
32+
│ │ 🔐 │ │ 🌐 │ │ ✅ │ 📱 路由器 │
33+
│ 💻 PC │◀────────▶│ gotun代理隧道│◀───────▶│ 🖥️ 跳板机 │◀───────▶│ 📺 NAS │
34+
│ │ HTTP请求 │ (加密传输) │ SSH │ │ 内网访问 │ 🖥️ 服务器 │
35+
└─────────┘ └─────────────┘ └─────────┘ │ 📟 IoT设备 │
36+
↑ └─────────────┘
37+
└── 浏览器设置代理: 127.0.0.1:8080
38+
```
39+
40+
### 🔑 核心优势
41+
42+
| 传统方案 | gotun |
43+
|---------|-----------|
44+
| ❌ 需要复杂的端口转发配置 | ✅ 仅需一个SSH连接 |
45+
| ❌ 每个服务需要单独映射端口 | ✅ 访问所有内网资源无需额外配置 |
46+
| ❌ 容易暴露内网服务到公网 | ✅ 流量全程加密,安全可靠 |
47+
| ❌ 管理多个连接复杂 | ✅ 一条隧道解决所有问题 |
48+
49+
**简单来说**: gotun 让你的电脑就像"坐在"跳板机旁边一样,可以访问跳板机能访问的任何资源!
50+
1551
---
1652

1753
## 🧱 项目特点
@@ -24,16 +60,178 @@
2460

2561
---
2662

27-
## 🚀 未来规划
63+
## 🚀 快速开始
64+
65+
### 安装
66+
67+
#### 下载预编译二进制文件
68+
69+
前往 [Releases](https://github.com/Sesame2/gotun/releases) 页面下载适合你系统的预编译版本:
70+
71+
72+
#### 从源码编译
73+
74+
```bash
75+
git clone https://github.com/Sesame2/gotun.git
76+
cd gotun
77+
make build
78+
```
79+
80+
编译后的可执行文件位于 `build/` 目录下。
81+
82+
### 基本使用
83+
84+
```bash
85+
# 基本用法:连接到SSH服务器并启动代理
86+
87+
88+
# 指定SSH端口
89+
./gotun -p 2222 [email protected]
90+
91+
# 使用私钥认证
92+
./gotun -i ~/.ssh/id_rsa [email protected]
93+
94+
# 自定义代理监听端口
95+
./gotun -listen :8888 [email protected]
96+
97+
# 自动设置系统代理
98+
./gotun -sys-proxy [email protected]
99+
```
100+
101+
### 在浏览器中使用
102+
103+
启动代理后,在浏览器中配置HTTP代理:
104+
105+
- **代理地址**: `127.0.0.1`
106+
- **端口**: `8080` (默认,或你指定的端口)
107+
108+
---
109+
110+
## 📖 操作手册
111+
112+
### 命令行参数
113+
114+
| 参数 | 简写 | 说明 | 默认值 |
115+
|------|------|------|--------|
116+
| `-listen` | | 本地HTTP代理监听地址 | `:8080` |
117+
| `-p` | | SSH服务器端口 | `22` |
118+
| `-pass` | | SSH密码(不推荐,建议使用私钥) | |
119+
| `-i` | | SSH私钥文件路径 | |
120+
| `-target` | | 可选的目标网络覆盖 | |
121+
| `-timeout` | | 连接超时时间 | `10s` |
122+
| `-v` | | 启用详细日志 | `false` |
123+
| `-log` | | 日志文件路径 | 输出到标准输出 |
124+
| `-sys-proxy` | | 自动设置系统代理 | `true` |
125+
| `-proxy-pac` | | 代理自动配置(PAC)文件URL | |
126+
127+
### 使用场景
128+
129+
#### 1. 访问内网服务
130+
131+
通过具有内网访问权限的跳板机访问内网资源:
132+
133+
```bash
134+
./gotun -sys-proxy [email protected]
135+
```
136+
137+
启动后,浏览器中访问内网地址如 `http://192.168.1.100:8080`
138+
139+
#### 2. 开发调试
140+
141+
在开发环境中通过远程服务器访问特定网络:
142+
143+
```bash
144+
./gotun -listen :8888 -v [email protected]
145+
```
146+
147+
#### 3. 网络代理
148+
149+
使用远程服务器作为网络出口:
150+
151+
```bash
152+
./gotun -sys-proxy -log /var/log/gotun.log [email protected]
153+
```
154+
155+
### 认证方式
156+
157+
#### SSH私钥认证(推荐)
158+
159+
```bash
160+
# 使用指定私钥文件
161+
./gotun -i ~/.ssh/id_rsa [email protected]
162+
163+
# 使用默认私钥(自动检测 ~/.ssh/ 目录下的密钥)
164+
165+
```
166+
167+
#### 密码认证
168+
169+
```bash
170+
# 交互式输入密码(推荐)
171+
172+
# 程序会提示输入密码
173+
174+
# 命令行指定密码(不安全,不推荐)
175+
./gotun -pass yourpassword [email protected]
176+
```
177+
178+
### 系统代理设置
179+
180+
当使用 `-sys-proxy` 参数时,程序会自动:
181+
182+
1. **启动时**: 保存当前系统代理设置,然后设置为使用 gotun 代理
183+
2. **运行中**: 所有系统网络流量通过 gotun 代理
184+
3. **退出时**: 自动恢复原始的系统代理设置
185+
186+
支持的操作系统:
187+
188+
-**macOS**: 通过 `networksetup` 命令配置
189+
-**Windows**: 通过注册表配置
190+
-**Linux**: 通过 GNOME 设置和环境变量配置
191+
192+
### 故障排除
193+
194+
#### 连接问题
195+
196+
```bash
197+
# 启用详细日志进行调试
198+
199+
200+
# 指定日志文件
201+
./gotun -v -log /tmp/gotun.log [email protected]
202+
```
203+
204+
#### 权限问题
205+
206+
在某些系统上设置系统代理需要管理员权限:
207+
208+
```bash
209+
# macOS/Linux
210+
sudo ./gotun -sys-proxy [email protected]
211+
212+
# Windows (以管理员身份运行 PowerShell/CMD)
213+
.\gotun.exe -sys-proxy [email protected]
214+
```
215+
216+
---
217+
28218

29-
以下是我们正在开发的功能:
219+
## 🎯 功能状态
30220

31-
- 🔄 支持 HTTPS 协议
32-
- 🔑 支持 SSH 私钥认证
33-
- ⚙️ 支持自动配置系统代理
34-
- 💻 支持托盘 GUI 界面
35-
- 📁 支持配置文件导出/导入
36-
- 🔒 支持密码连接时使用交互式输入(类似原生 SSH 命令),避免明文传递密码
37-
- 💡 支持命令行参数智能提示和自动补全(基于 Cobra 实现)
221+
- [x] **HTTP 代理**: 完整的 HTTP 请求代理
222+
- [x] **HTTPS 代理**: 支持 CONNECT 方法的 HTTPS 隧道
223+
- [x] **SSH 私钥认证**: 支持多种私钥格式
224+
- [x] **自动配置系统代理**: 跨平台系统代理设置
225+
- [x] **交互式密码输入**: 安全的密码认证方式
226+
- [x] **详细日志记录**: 支持调试和故障排除
227+
- [x] **跨平台支持**: Windows/Linux/macOS
228+
- [x] **命令行界面**: 完整的 CLI 参数支持
229+
- [ ] **PAC 文件支持**: 代理自动配置文件
230+
- [ ] **托盘 GUI 界面**: 图形化用户界面
231+
- [ ] **配置文件导出/导入**: 配置管理功能
232+
- [ ] **命令行自动补全**: 基于 Cobra 的智能提示
233+
- [ ] **SOCKS5 代理支持**: 更广泛的协议支持
234+
- [ ] **连接池优化**: 提升性能和稳定性
235+
- [ ] **统计和监控**: 流量统计和连接监控
38236

39237
---

0 commit comments

Comments
 (0)