# TunnelBridge **Repository Path**: suoten/TunnelBridge ## Basic Information - **Project Name**: TunnelBridge - **Description**: Go 编写的单文件内网穿透工具，P2P UDP 打洞 + 中继 fallback，端到端加密，内置 Web 管理面板和 REST API。支持 TCP/UDP/WebSocket 多协议同时穿透。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-07-26 - **Last Updated**: 2026-09-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: tunnel, ngrok-alternative, frp-alternative, intranet-penetration, nat-traversal ## README # TunnelBridge > 单二进制内网穿透网关 — P2P 直连优先，中继 fallback，TLS 1.3 端到端加密 **[English](README_EN.md)** | **中文** [![CI](https://github.com/suoten/TunnelBridge/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/suoten/TunnelBridge/actions/workflows/ci.yml) [![Go Version](https://img.shields.io/badge/Go-1.22+-00ADD8?logo=go)](https://golang.org) [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Release](https://img.shields.io/github/v/release/suoten/TunnelBridge?display_name=tag&include_prereleases)](https://github.com/suoten/TunnelBridge/releases) [![Downloads](https://img.shields.io/github/downloads/suoten/TunnelBridge/total?color=brightgreen)](https://github.com/suoten/TunnelBridge/releases) [![Go Report Card](https://goreportcard.com/badge/github.com/suoten/TunnelBridge)](https://goreportcard.com/report/github.com/suoten/TunnelBridge) [![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey)](#交叉编译) [![Stars](https://img.shields.io/github/stars/suoten/TunnelBridge?style=social)](https://github.com/suoten/TunnelBridge/stargazers) > 🌟 如果 TunnelBridge 帮到了你，欢迎点个 Star 让更多人看到！ > 🇨🇳 国内用户推荐使用 [Gitee 仓库](https://gitee.com/suoten/TunnelBridge)（访问更快） --- ## 简介 TunnelBridge 是一个用 Go 语言编写的单二进制内网穿透网关。它优先使用 P2P 直连（UDP 打洞），当 NAT 类型不允许时自动降级到中继转发。全程加密：P2P 场景使用 ECDH + AES-256-GCM，中继场景强制 TLS 1.3。 **适用场景**：本地 Web 开发预览、远程 SSH、数据库连接、UDP 游戏服务器、WebSocket 服务、微信公众号回调调试等。 ## 为什么选择 TunnelBridge 与同类工具相比，TunnelBridge 聚焦"**单文件部署 + P2P 优先 + 端到端加密**"三个核心定位： | 特性 | TunnelBridge | ngrok | frp | rathole | |------|:---:|:---:|:---:|:---:| | 单二进制零依赖 | ✅ | ❌ 需账号 | ✅ | ✅ | | P2P 直连（低延迟） | ✅ 自动 UDP 打洞 | ❌ | ❌ | ❌ | | 中继 fallback | ✅ 自动降级 | ✅ | ✅ | ✅ | | 端到端加密 | ✅ ECDH+AES-GCM/TLS 1.3 | TLS | 需自配 | TLS | | Web 管理面板 | ✅ 内置 | 付费版 | ❌ | ❌ | | REST API | ✅ Token 认证 | 付费版 | ❌ | ❌ | | 审计日志 | ✅ JSON 自动轮转 | 付费版 | ❌ | ❌ | | 多端口同时穿透 | ✅ CSV 一次穿透 | 付费版 | ✅ | ✅ | | 自建协调服务器 | ✅ 完整开源 | ❌ | ✅ | ✅ | | 商用限制 | ❌ MIT 完全免费 | 有 | 无 | 无 | | 二进制大小 | ~10MB | ~30MB | ~15MB | ~5MB | **一句话定位**：ngrok 的开源自建替代品，但比 frp 多了 P2P 直连和管理面板，比 rathole 多了 Web UI 和审计能力。 ## 60 秒上手 ### 方式一：一键安装 **Linux / macOS：** ```bash curl -fsSL https://raw.githubusercontent.com/suoten/TunnelBridge/main/install.sh | bash # 国内用户使用 Gitee 镜像 curl -fsSL https://gitee.com/suoten/TunnelBridge/raw/main/install.sh | bash ``` **Windows（PowerShell）：** ```powershell irm https://raw.githubusercontent.com/suoten/TunnelBridge/main/install.ps1 | iex ``` ### 方式二：直接下载 从 [GitHub Releases](https://github.com/suoten/TunnelBridge/releases) 或 [Gitee Releases](https://gitee.com/suoten/TunnelBridge/releases) 下载对应平台的二进制文件。 ### 方式三：Docker ```bash docker run -d --name tunnelbridge \ -p 80:8080 -p 443:8443 -p 9876:9876 \ -p 3478:3478/udp -p 10000:10000 \ ghcr.io/suoten/tunnelbridge:latest ``` ### 穿透本地服务 ```bash # 穿透本地 8080 端口的 Web 服务 tunnelbridge --port 8080 # 指定子域名 tunnelbridge --port 8080 --subdomain myapp # 体验演示模式（无需本地服务） tunnelbridge --demo ``` 运行后会输出公网访问地址： ``` ✅ 隧道注册成功 公网 URL: http://myapp.tunnelbridge.io ``` ## 功能特性 | 特性 | 说明 | |------|------| | P2P 直连 | STUN NAT 穿透，UDP 打洞，延迟 < 5ms | | 中继 fallback | Symmetric NAT 自动降级到 TCP 中继，延迟 < 30ms | | 端到端加密 | P2P：ECDH P-256 + AES-256-GCM；中继：TLS 1.3 | | 多协议 | TCP、UDP、WebSocket、多端口同时穿透 | | 单二进制 | 零外部依赖，< 10MB，内存占用 < 20MB | | 管理面板 | Web UI 实时监控隧道状态和流量 | | REST API | Token 认证，创建/删除/查询隧道 | | 访问控制 | IP 白名单（CIDR）、Basic Auth、速率限制 | | 审计日志 | JSON 结构化日志，自动轮转，7 天保留 | | 配置灵活 | YAML 配置 + 环境变量 + CLI 参数（三级优先级） | ## 使用示例 ```bash # 穿透 SSH tunnelbridge --port 22 --proto tcp # 多端口同时穿透（Web + 数据库 + SSH） tunnelbridge --port 8080,3306,22 # UDP 穿透（游戏/RTP） tunnelbridge --port 20000 --proto udp # WebSocket 代理 tunnelbridge --port 8080 --proto ws # 自动识别协议 tunnelbridge --port 8080 --auto-proto # 端口-协议一一对应 tunnelbridge --port 8080,20000 --proto tcp,udp # 强制中继模式 tunnelbridge --port 8080 --relay-only # 强制 P2P 模式（不降级到中继，NAT 不通会失败） tunnelbridge --port 8080 --p2p-only # 指定协调服务器（默认连接 tunnelbridge.io:9876 公共服务） tunnelbridge --port 8080 --coordinator your-server.com:9876 # 启用 pprof 性能分析端点 tunnelbridge --port 8080 --profile # 使用配置文件 tunnelbridge --port 8080 --config tunnelbridge.yaml ``` ## 自建协调服务器 ```bash # 基础启动 tunnelbridge --server # 启用 HTTPS（自动申请 Let's Encrypt 证书） tunnelbridge --server --https --domain-suffix yourdomain.com # 安装为系统服务 sudo tunnelbridge --service install --server sudo systemctl start tunnelbridge sudo systemctl enable tunnelbridge ``` ## 配置文件 创建 `tunnelbridge.yaml`： ```yaml server: http_port: 80 https_port: 443 signal_port: 9876 stun_port: 3478 relay_port: 10000 domain_suffix: tunnelbridge.io enable_https: false client: local_host: 127.0.0.1 admin_port: 9876 security: enable_tls: true enable_e2ee: true ip_whitelist: - 192.168.1.0/24 basic_auth_user: admin basic_auth_pass: your-password rate_limit: 100 audit: enabled: true log_dir: /var/log/tunnelbridge max_file_size: 104857600 # 100MB max_age: 7 json_format: true ``` **优先级**：CLI 参数 > 环境变量（`TB_PORT`、`TB_SUBDOMAIN` 等）> 配置文件 > 默认值 ## REST API 服务器启动时自动生成 API Token（在日志中查看），或通过配置文件指定。 ```bash # 列出隧道 curl -H "Authorization: Bearer tb_xxx.yyy" \ http://localhost:9876/api/tunnels # 创建隧道 curl -X POST -H "Authorization: Bearer tb_xxx.yyy" \ -H "Content-Type: application/json" \ -d '{"local_port":8080,"protocol":"tcp"}' \ http://localhost:9876/api/v1/tunnels # 查看配额使用 curl -H "Authorization: Bearer tb_xxx.yyy" \ http://localhost:9876/api/v1/usage ``` | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/tunnels` | 列出隧道 | | POST | `/api/v1/tunnels` | 创建隧道 | | DELETE | `/api/v1/tunnels/{id}` | 删除隧道 | | GET | `/api/v1/usage` | 配额统计 | | POST | `/api/v1/tokens` | 生成新 Token | | GET | `/health` | 健康检查 | ## 自检 ```bash tunnelbridge --test ``` 输出 7 项检测结果：STUN 连通性、NAT 类型、P2P 打洞、中继转发、TCP 转发、TLS/ECDH 密钥协商、带宽延迟基准。 ## 管理面板预览 启动 `tunnelbridge --demo` 后访问 [http://localhost:9876](http://localhost:9876) 即可看到管理面板： - **顶部状态栏**：实时连接类型（P2P / Relay / Connecting），带脉冲动画 - **信息卡片网格**：隧道 ID、公网 URL、NAT 类型、反射地址、本地服务、运行时长 - **活跃隧道列表**：每条隧道的协议标签、流量统计、停止按钮 - **流量图表**：上下行带宽实时折线图 - **连接日志**：最近 80 条事件，按级别着色 > 📸 截图将在首个 Release 发布后补充至此处。 ## 路线图 - [x] P2P 直连 + 中继 fallback - [x] 端到端加密（ECDH + AES-GCM / TLS 1.3） - [x] Web 管理面板 + REST API - [x] 访问控制 + 审计日志 - [x] 一键安装脚本 + Docker - [x] 系统服务化（systemd / launchd / NSSM） - [ ] QUIC 中继协议（降低尾部延迟） - [ ] 隧道持久化与断线恢复 - [ ] 多协调服务器集群与故障转移 - [ ] Prometheus 指标导出 - [ ] WebAssembly 客户端 详见 [Projects 看板](https://github.com/suoten/TunnelBridge/projects)。 ## 从源码编译 ```bash git clone https://github.com/suoten/TunnelBridge.git cd TunnelBridge go build -ldflags="-s -w" -o tunnelbridge ./cmd/tunnelbridge ``` ### 交叉编译 ```bash # Linux amd64 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o tunnelbridge-linux-amd64 ./cmd/tunnelbridge # Windows amd64 CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o tunnelbridge-windows-amd64.exe ./cmd/tunnelbridge # macOS arm64 CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o tunnelbridge-darwin-arm64 ./cmd/tunnelbridge ``` ## 项目结构 ``` TunnelBridge/ ├── cmd/tunnelbridge/ # 单二进制入口 │ ├── main.go # 入口 + 自检 + 演示 │ ├── client.go # 穿透客户端 │ ├── coordinator.go # 协调服务器 │ ├── service.go # 系统服务管理 │ └── demo.go # 演示 HTTP 服务 ├── internal/ │ ├── config/ # 配置系统（YAML/Env/CLI） │ ├── signal/ # 信令通道（WebSocket） │ ├── nat/ # STUN NAT 探测 │ ├── p2p/ # P2P 打洞 │ ├── relay/ # 中继转发 │ ├── local/ # 本地转发 + 管理面板 │ ├── security/ # 加密 + 认证 + 访问控制 │ └── audit/ # 结构化日志 + 审计 ├── Dockerfile ├── docker-compose.yml ├── install.sh # Linux/macOS 安装脚本 ├── install.ps1 # Windows 安装脚本 └── README.md ``` ## 技术架构 ``` 访客 ──HTTP──▶ 协调服务器 ──信令──▶ 客户端（内网） │ │ │ P2P 直连 │ └──────UDP───────────┘ │ │ │ 中继 fallback │ └──────TCP───────────┘ │ 本地服务 (:8080) ``` 1. 客户端连接协调服务器的信令通道（WebSocket） 2. STUN 探测 NAT 类型 3. P2P 优先：Full Cone / Restricted Cone NAT → UDP 打洞直连 4. 中继 fallback：Symmetric NAT → TCP 中继转发 5. 全程加密：P2P 用 ECDH+AES-GCM，中继用 TLS 1.3 ## 性能指标 | 指标 | P2P 直连 | 中继转发 | |------|----------|----------| | 延迟 | < 5 ms | < 30 ms | | 二进制大小 | < 10 MB | < 10 MB | | 内存占用 | < 20 MB | < 20 MB | | CPU（空闲） | < 1% | < 1% | ## 常见问题
P2P 打洞失败怎么办？ P2P 适用于 Full Cone、Restricted Cone、Port Restricted Cone NAT。Symmetric NAT 会自动降级到中继。强制指定模式：`--p2p-only` 或 `--relay-only`。可用 `tunnelbridge --test` 探测当前 NAT 类型。
如何自建协调服务器？ ```bash tunnelbridge --server --domain-suffix yourdomain.com --https ``` 需要将 `*.yourdomain.com` 的 DNS A 记录指向服务器 IP。
如何查看实时日志？ ```bash # systemd journalctl -u tunnelbridge -f # Docker docker logs -f tunnelbridge # 管理面板 浏览器打开 http://localhost:9876 ```
## 贡献 欢迎参与贡献！请阅读 [贡献指南](CONTRIBUTING.md)。 - 🐛 发现 Bug？[提交 Issue](https://gitee.com/suoten/TunnelBridge/issues) - 💡 有想法？[功能建议](https://github.com/suoten/TunnelBridge/issues/new?template=feature_request.yml) - 🔧 想贡献代码？[提交 Pull Request](https://github.com/suoten/TunnelBridge/compare) - 📖 想改进文档？直接 PR 即可 ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=suoten/TunnelBridge&type=Date)](https://star-history.com/#suoten/TunnelBridge&Date) ## License [MIT License](LICENSE) © 2026 suoten ## 仓库 - **GitHub**: https://github.com/suoten/TunnelBridge - **Gitee（国内镜像）**: https://gitee.com/suoten/TunnelBridge