README.md

TunnelBridge

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

English | 中文

🌟 如果 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

贡献

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

• 🐛 发现 Bug？提交 Issue
• 💡 有想法？功能建议
• 🔧 想贡献代码？提交 Pull Request
• 📖 想改进文档？直接 PR 即可

Star History

License

MIT License © 2026 suoten

仓库

• GitHub: https://github.com/suoten/TunnelBridge
• Gitee（国内镜像）: https://gitee.com/suoten/TunnelBridge