# simpletunnel

**Repository Path**: cg33/simpletunnel

## Basic Information

- **Project Name**: simpletunnel
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-23
- **Last Updated**: 2025-11-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SimpleTunnel

一个简单易用的内网穿透工具，使用 Go 语言实现。可以将局域网内的各种服务（Web、SSH、TCP）映射到远程公网服务器上。

## 功能特点

- 🚀 **简单易用** - 配置简单，启动快速
- 🔒 **安全认证** - 基于 Token 的认证机制
- 🔄 **自动重连** - 客户端断线自动重连
- 💓 **心跳检测** - 保持连接活性
- 📦 **零依赖部署** - 编译后单个二进制文件即可运行
- 🔐 **WSS 支持** - 安全的 WebSocket 连接
- 🔌 **多端口映射** - 单个客户端可映射多个本地端口
- 🖥️ **SSH 隧道支持** - 原生支持 SSH 协议内网穿透
- 🌐 **混合协议** - 同时支持 HTTP、SSH、TCP 服务

## 支持的服务类型

| 服务类型 | 说明 | 优化特性 |
|---------|------|---------|
| `http` | HTTP/Web 服务 | 默认类型，向后兼容 |
| `ssh` | SSH 服务 | TCP KeepAlive、NoDelay 优化 |
| `tcp` | 通用 TCP 服务 | 适用于数据库等服务 |

## 架构说明

SimpleTunnel 采用 WebSocket 建立服务端和客户端之间的长连接，实现数据转发：

```
外部用户 → 服务器远程端口 → WebSocket → 客户端 → 本地服务
```

## 快速开始

### 编译

```bash
# 编译服务端和客户端
make build

# 或者分别编译
make server
make client

# 跨平台编译
make build-linux
make build-windows
make build-darwin
```

### Web 服务示例

**服务端配置** `config/server.yaml`：

```yaml
ws_port: 8080
token: "your-secret-token-here"
```

**客户端配置** `config/client.yaml`：

```yaml
server_addr: "your-server.com"
ws_port: 8080
token: "your-secret-token-here"

port_mappings:
  - local_port: 3000
    remote_port: 8000
    service_type: "http"
    description: "Web 应用"
```

### SSH 隧道示例

**客户端配置** `config/client-ssh.yaml`：

```yaml
server_addr: "your-server.com"
ws_port: 8080
token: "your-secret-token-here"

port_mappings:
  - local_port: 22
    remote_port: 2222
    service_type: "ssh"
    description: "SSH 服务器"
```

**使用方式**：
```bash
# 启动服务端
./simpletunnel-server -config config/server.yaml

# 启动客户端
./simpletunnel-client -config config/client-ssh.yaml

# 通过隧道连接SSH
ssh user@your-server.com -p 2222
```

### 混合服务示例

同时映射多种类型的服务：

```yaml
server_addr: "your-server.com"
ws_port: 8080
token: "your-secret-token-here"

port_mappings:
  # SSH 访问
  - local_port: 22
    remote_port: 2222
    service_type: "ssh"
    description: "SSH 服务器"
  
  # Web 应用
  - local_port: 3000
    remote_port: 8000
    service_type: "http"
    description: "React 开发服务器"
  
  # API 服务
  - local_port: 8080
    remote_port: 8080
    service_type: "http"
    description: "API 服务器"
  
  # 数据库
  - local_port: 5432
    remote_port: 5432
    service_type: "tcp"
    description: "PostgreSQL 数据库"
```

## 使用场景

### 1. Web 开发和演示
将本地开发的 Web 应用快速暴露给外部访问，用于测试和客户演示。

### 2. SSH 远程访问
安全地将内网机器的SSH服务暴露到公网，支持远程开发和服务器管理。

### 3. 数据库远程连接
通过隧道安全访问内网数据库服务，无需直接暴露数据库端口。

### 4. 内网设备管理
访问内网中的各种设备管理界面，如路由器、NAS、监控系统等。

## 配置说明

### 服务端配置

| 参数 | 说明 | 必需 |
|------|------|------|
| `ws_port` | WebSocket 监听端口 | 是 |
| `token` | 认证 Token | 是 |

### 客户端配置

| 参数 | 说明 | 必需 |
|------|------|------|
| `server_addr` | 服务器地址 | 是 |
| `ws_port` | 服务器 WebSocket 端口 | 是 |
| `token` | 认证 Token | 是 |
| `port_mappings` | 端口映射配置列表 | 是 |

### 端口映射配置

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `local_port` | 本地服务端口 | - |
| `remote_port` | 远程映射端口 | - |
| `service_type` | 服务类型 | `http` |
| `description` | 描述信息 | 可选 |

## 命令行参数

### 服务端

```bash
./simpletunnel-server [选项]

选项：
  -config string
        配置文件路径 (默认 "config/server.yaml")
  -ws-port int
        WebSocket 端口（覆盖配置文件）
  -token string
        认证 Token（覆盖配置文件）
```

### 客户端

```bash
./simpletunnel-client [选项]

选项：
  -config string
        配置文件路径 (默认 "config/client.yaml")
  -server string
        服务器地址（覆盖配置文件）
  -ws-port int
        WebSocket 端口（覆盖配置文件）
  -token string
        认证 Token（覆盖配置文件）
  -local-port int
        本地端口（覆盖配置文件，兼容模式）
  -remote-port int
        远程端口（覆盖配置文件，兼容模式）
```

## SSH 隧道特性

### 自动优化
- **TCP KeepAlive**：保持连接活性，防止NAT超时
- **NoDelay**：禁用Nagle算法，减少延迟
- **连接缓冲区优化**：提高数据传输效率

### 安全建议
- 使用密钥认证替代密码认证
- 配置强Token认证
- 限制SSH访问用户和来源IP
- 定期更新SSH服务和密钥

### 使用技巧
- 支持SSH动态端口转发（SOCKS代理）
- 兼容VS Code Remote开发
- 支持文件传输（scp、rsync）
- 与tmux/screen等工具完美配合

## 文档

- 📘 [快速开始指南](QUICKSTART.md) - 10分钟快速上手
- 🖥️ **[SSH 隧道指南](docs/SSH_TUNNEL.md)** - SSH内网穿透完整指南
- 🏗️ [架构设计](docs/ARCHITECTURE.md) - 技术架构详解
- 🔧 [Nginx部署指南](docs/NGINX_SETUP.md) - 生产环境部署
- 🔌 [多端口映射](docs/MULTI_PORT.md) - 多端口映射指南
- 🚀 [部署示例](docs/DEPLOYMENT_EXAMPLES.md) - 各种部署场景
- 🤝 [贡献指南](CONTRIBUTING.md) - 如何参与贡献

## 注意事项

1. **防火墙配置**：确保服务器的 WebSocket 端口和远程映射端口在防火墙中开放
2. **Token 安全**：使用强密码作为 Token，定期更换
3. **端口冲突**：确保远程端口没有被其他程序占用
4. **本地服务**：确保本地服务在客户端启动前已经运行
5. **SSH 安全**：对于SSH服务，建议禁用密码认证，使用密钥认证

## 生产环境部署

### Systemd 服务

```bash
# 安装为系统服务
sudo ./scripts/install-service.sh

# 启动和启用服务
sudo systemctl start simpletunnel-server
sudo systemctl enable simpletunnel-server
```

### 配合 Nginx

支持通过 Nginx 反向代理实现 HTTPS：

```nginx
# WebSocket 代理
location /ws {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}
```

## 技术栈

- Go 1.21+
- [gorilla/websocket](https://github.com/gorilla/websocket) - WebSocket 实现
- [gopkg.in/yaml.v3](https://gopkg.in/yaml.v3) - YAML 配置解析

## 开发

```bash
# 安装依赖
go mod download

# 格式化代码
make fmt

# 代码检查
make lint

# 运行测试
make test

# 清理编译文件
make clean

# 查看所有命令
make help
```

## 常见问题

### Q: 如何同时支持Web和SSH服务？
A: 使用多端口映射配置，为不同服务指定不同的`service_type`：

```yaml
port_mappings:
  - local_port: 22
    remote_port: 2222
    service_type: "ssh"
  - local_port: 80
    remote_port: 8080
    service_type: "http"
```

### Q: SSH连接经常断线怎么办？
A: 确保配置了正确的`service_type: "ssh"`，这会自动启用连接优化。同时在SSH客户端配置中添加：

```
ServerAliveInterval 60
ServerAliveCountMax 3
```

### Q: 如何提高SSH连接性能？
A: SimpleTunnel会自动为SSH连接启用TCP优化。另外可以在SSH配置中启用压缩：

```
Compression yes
```

### Q: 客户端连接失败？
A: 请检查：
- 服务器地址和端口是否正确
- 服务器防火墙是否开放了 WebSocket 端口
- Token 是否与服务端一致

### Q: 外部访问远程端口无响应？
A: 请检查：
- 本地服务是否正常运行
- 客户端是否成功连接到服务端
- 服务器防火墙是否开放了远程映射端口

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！特别欢迎以下贡献：

- 🐛 Bug 修复
- ✨ 新功能建议
- 📝 文档改进
- 🧪 测试用例
- 🌐 多语言支持

---

⭐ 如果这个项目对您有帮助，请给我们一个 Star！