Skip to content
BranchesTags

Repository files navigation

TunnelBridge

单二进制内网穿透网关 — P2P 直连优先，中继 fallback，TLS 1.3 端到端加密

English | 中文

CI Go Version License Release Downloads Go Report Card Platform Stars

🌟 如果 TunnelBridge 帮到了你，欢迎点个 Star 让更多人看到！
🇨🇳 国内用户推荐使用 Gitee 仓库（访问更快）

简介

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：

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）：

irm https://raw.githubusercontent.com/suoten/TunnelBridge/main/install.ps1 | iex

方式二：直接下载

从 GitHub Releases 或 Gitee Releases 下载对应平台的二进制文件。

方式三：Docker

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

穿透本地服务

# 穿透本地 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 参数（三级优先级）

使用示例

# 穿透 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

自建协调服务器

# 基础启动
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：

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（在日志中查看），或通过配置文件指定。

# 列出隧道
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 健康检查

自检

tunnelbridge --test

输出 7 项检测结果：STUN 连通性、NAT 类型、P2P 打洞、中继转发、TCP 转发、TLS/ECDH 密钥协商、带宽延迟基准。

管理面板预览

启动 tunnelbridge --demo 后访问 http://localhost:9876 即可看到管理面板：

  • 顶部状态栏：实时连接类型（P2P / Relay / Connecting），带脉冲动画
  • 信息卡片网格：隧道 ID、公网 URL、NAT 类型、反射地址、本地服务、运行时长
  • 活跃隧道列表：每条隧道的协议标签、流量统计、停止按钮
  • 流量图表：上下行带宽实时折线图
  • 连接日志：最近 80 条事件，按级别着色

📸 截图将在首个 Release 发布后补充至此处。

路线图

  • P2P 直连 + 中继 fallback
  • 端到端加密（ECDH + AES-GCM / TLS 1.3）
  • Web 管理面板 + REST API
  • 访问控制 + 审计日志
  • 一键安装脚本 + Docker
  • 系统服务化（systemd / launchd / NSSM）
  • QUIC 中继协议（降低尾部延迟）
  • 隧道持久化与断线恢复
  • 多协调服务器集群与故障转移
  • Prometheus 指标导出
  • WebAssembly 客户端

详见 Projects 看板。

从源码编译

git clone https://github.com/suoten/TunnelBridge.git
cd TunnelBridge
go build -ldflags="-s -w" -o tunnelbridge ./cmd/tunnelbridge

交叉编译

# 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 类型。

如何自建协调服务器？ 
tunnelbridge --server --domain-suffix yourdomain.com --https

需要将 *.yourdomain.com 的 DNS A 记录指向服务器 IP。

如何查看实时日志？ 
# systemd
journalctl -u tunnelbridge -f

# Docker
docker logs -f tunnelbridge

# 管理面板
浏览器打开 http://localhost:9876

贡献

欢迎参与贡献！请阅读 贡献指南。

Star History

Star History Chart

License

MIT License © 2026 suoten

仓库

About

Go 编写的单文件内网穿透工具，P2P UDP 打洞 + 中继 fallback，端到端加密，内置 Web 管理面板和 REST API。支持 TCP/UDP/WebSocket 多协议同时穿透。

Topics

end-to-end-encryptionexpose-localhostfrp-alternativegogolangintranet-penetrationnat-traversalngrok-alternativep2pport-forwardingreverse-proxyself-hostedtls13tunneludp-hole-punching

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages