微信公众号：你起来我讲两句

P2P TCP tunnel with STUN hole punching and automatic server relay fallback.
Cross-platform GUI + CLI. Zero configuration networking.

---

• P2P Direct Connection — STUN hole punch with Birthday Attack (256 sockets) + port prediction (±1000), data never touches the server
• Auto Relay Fallback — If P2P fails, seamlessly falls back to server relay; background retry upgrades back to P2P
• NAT Traversal — Detects NAT1 (Cone) / NAT4 (Symmetric), adapts punch strategy; ~98% success for NAT3+NAT4 pairs
• gVisor TCP/IP Stack — Production-grade userspace TCP (same as Tailscale/tun2socks) for VPN proxy and port forwarding
• TUN VPN — Full subnet routing with SNAT, multi-VPN support (multiple peers simultaneously), VPN auto-restore on reconnect
• Port Forwarding — Map any remote peer's host:port to your localhost, with gVisor reliable transport
• Speed Test — P2P bandwidth test with cancel support and real-time progress
• File Transfer — Send files with compression, CRC verification, rate-limited P2P UDP, auto relay fallback
• Proxy Bypass — Auto-detects physical NIC, bypasses TUN proxies (Clash/V2Ray), skips CGNAT ranges
• LAN Auto-Detection — Same public IP peers connect via local address (zero latency)
• Auto Reconnect — Network changes trigger reconnect with backoff (1s→5s), P2P + VPN auto-restore
• Room Management — Client-created rooms auto-delete when owner leaves; dashboard rooms persist; per-room relay control
• GUI + CLI — Gio UI desktop app (Windows/Mac/Android) + readline CLI with tab completion
• Android App — Full-featured with VPN, auto permission, native icon, WiFi-priority networking
• Server Dashboard — Room management, peer monitoring, IP geolocation, STUN stats, Kick/Ban, relay control
• NAT Diagnostic — natcheck tool with RFC 5780 support, Chinese UI, proxy bypass, comprehensive report
• E2E Encryption — X25519 + XChaCha20-Poly1305, thread-safe, 24-byte nonce
• SQLite Persistence — Rooms and blacklists survive server restart
• Self-Hosted STUN — Lightweight STUN server with HTTP stats API

┌──────────┐    1. UDP hole punch       ┌──────────┐
│ Client A │◄ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ►│ Client B │
│ (GUI/CLI)│    2. P2P UDP direct       │ (GUI/CLI)│
│          │◄══════════════════════════►│          │
└────┬─────┘    (gVisor TCP/IP stack)   └────┬─────┘
     │                                       │
     │   WebSocket (signaling + relay)       │
     └───────────────┬───────────────────────┘
                     │
              ┌──────┴──────┐
              │   Server    │
              │ Signal+Relay│
              │ + Dashboard │
              └─────────────┘

Connection flow:

1. Both clients connect to signal server via WebSocket
2. STUN discovery finds public IP:port (supports custom/self-hosted STUN)
3. UDP hole punch with Birthday Attack + port prediction
4. Data flows over P2P UDP — server not in the data path
5. gVisor userspace TCP/IP stack handles congestion control, retransmission, SACK
6. If punch fails 5 times → auto relay, background retry continues
7. If P2P later succeeds → auto upgrade back from relay

Dashboard	GUI - Connect

GUI - Logs	GUI - Peers

GUI - Forwards	GUI - TUN VPN

GUI - Settings	GUI - Files

Peers	Forwards	Files	VPN

Speed Test	Tools	Settings	Logs

curl -fsSL https://raw.githubusercontent.com/uk0/stun_max/main/install.sh | sudo bash

Custom password:

curl -fsSL https://raw.githubusercontent.com/uk0/stun_max/main/install.sh | STUN_MAX_PASSWORD=your_password sudo bash

Custom ports:

curl -fsSL https://raw.githubusercontent.com/uk0/stun_max/main/install.sh | STUN_MAX_PORT=9090 STUN_MAX_STUN_PORT=3479 sudo bash

The script auto-downloads the latest release, configures systemd, and opens firewall ports.

./build.sh

# Upload to your server
scp build/stun_max-server-linux-amd64 root@SERVER:/usr/local/bin/stun_max-server
scp build/stun_max-stunserver-linux-amd64 root@SERVER:/usr/local/bin/stun_max-stunserver
ssh root@SERVER "mkdir -p /opt/stun_max/web"
scp -r build/web/* root@SERVER:/opt/stun_max/web/

Create systemd services:

# Signal Server
cat > /etc/systemd/system/stun-max.service << 'EOF'
[Unit]
Description=STUN Max Signal Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/stun_max-server --addr :8080 --web-dir /opt/stun_max/web --db /opt/stun_max/stun_max.db --ipdb /opt/stun_max/ip2region.xdb --stun-http http://127.0.0.1:3479
Restart=always
RestartSec=3
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

# STUN Server (optional, recommended for restricted networks)
cat > /etc/systemd/system/stun-max-stun.service << 'EOF'
[Unit]
Description=STUN Max STUN Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/stun_max-stunserver --addr :3478 --http :3479
Restart=always

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now stun-max stun-max-stun

Get the auto-generated dashboard password:

journalctl -u stun-max | grep Password

Firewall: Open TCP 8080 and UDP 3478.

Open http://SERVER:8080, login, create a room with name + password.

GUI (Windows/Mac/Android):

Run stun_max-client-windows-amd64.exe or stun_max-client-darwin-arm64, fill in server URL, room, password, name → Connect.

Android: Install stun_max-android-v*.apk, same UI as desktop with touch-optimized layout.

CLI:

./stun_max-cli --server ws://SERVER:8080/ws --room myroom --password secret --name laptop

# Forward peer's port to local
> forward peer-name 127.0.0.1:3389
> forward peer-name 192.168.1.100:8080 9090

# Manage
> forwards          # list with traffic stats
> unforward 3389    # stop

# Route a remote subnet through peer
> vpn peer-name 192.168.1.0/24
> vpn peer-name 192.168.1.0/24 --exit-ip 192.168.1.1

# Check status
> vpn status

# Stop
> vpn stop

> speedtest peer-name          # default 10MB, auto mode
> speedtest peer-name 50       # 50MB test
> speedtest peer-name 10 p2p   # force P2P transport

> send peer-name /path/to/file
> transfers                     # list active transfers

./build.sh                                    # all platforms (server + desktop + CLI)
bash android/build-apk.sh v1.0.0             # Android APK
go build ./server/                            # server only
go build ./client/                            # GUI client
go build -tags cli ./client/                  # CLI client
go build ./tools/natcheck/                    # NAT diagnostic
go build ./tools/stunserver/                  # STUN server

Android build requires: Android SDK (ANDROID_HOME), NDK, gogio (go install gioui.org/cmd/gogio@latest).

Command	Description
peers	List peers with P2P/RELAY mode
forward <peer> <host:port> [local]	Forward remote port
unforward <port>	Stop forward
forwards	List forwards with traffic stats
expose <host:port> <peer> [port]	Reverse forward (expose local service)
stun	STUN/P2P connection details
speedtest <peer> [size] [p2p|relay]	Bandwidth test
send <peer> <file>	Send file to peer
transfers	List file transfers
vpn <peer> [subnets...] [--exit-ip IP]	Start TUN VPN
vpn status	VPN status with traffic
vpn stop	Stop VPN
hop <peer-b> <peer-c> <host:port>	Multi-hop forward via B to C
help	All commands
quit	Disconnect

Tab completion for commands, peer names, and ports.

Tab	Description
Peers	Peer list with P2P/RELAY badges, STUN endpoints
Forwards	Create/stop forwards, live traffic (bytes + speed), peer dropdown selector
VPN	Start/stop TUN VPN, subnet routing, traffic stats
Speed Test	P2P bandwidth test with progress bar and transport display
Files	Send/receive files with progress
Settings	Forward control, STUN server selector, autostart, auto-connect
Tools	Windows RDP remote desktop setup
Logs	Scrollable event log with severity colors

All tabs support vertical scrolling on both desktop and mobile.

Feature	Detail
E2E encryption	X25519 + XChaCha20-Poly1305 for all P2P and relay data
Room isolation	Relay verifies sender and receiver in same room
Room auth	Dashboard-only creation, SHA-256 password hash
Rate limiting	Login 5/min, WebSocket 20/min, Join 10/min per IP
Connection limit	Global max (default 5000, --max-connections)
Session expiry	Dashboard tokens expire after 24 hours
Blacklist	Ban/unban clients per room
Forward control	Per-client allow/deny + local-only mode

Flag	Default	Description
--addr	:8080	Listen address
--web-password	(built-in)	Dashboard password
--web-dir	../web	Static files path
--db	stun_max.db	SQLite database file
--ipdb	ip2region.xdb	IP geolocation database
--stun-http	http://127.0.0.1:3479	STUN server stats URL
--max-connections	5000	Max WebSocket connections
--tls-cert		TLS certificate file
--tls-key		TLS key file

Flag	Default	Description
--server	ws://localhost:8080/ws	Server URL
--room	(required)	Room name
--password		Room password
--name	(hostname)	Display name
--stun	stun.cloudflare.com:3478	STUN servers (comma-separated)
--no-stun	false	Relay only
-v	false	Verbose

server/                  Signal + relay + dashboard
  main.go                HTTP/WS, auth, rate limiting, TLS, graceful shutdown
  hub.go                 Rooms, peers, blacklist, room ownership
  client.go              Message routing, join validation, same-name kick
  relay.go               Data relay with per-room toggle
  store.go               SQLite persistence (rooms, blacklists)
  ipinfo.go              Offline IP geolocation (ip2region)
  stats.go               Server statistics

client/core/             Networking (shared by GUI + CLI)
  client.go              Connection, reconnect, signaling
  tunnel.go              Port forwarding with gVisor transport
  forward_netstack.go    Per-peer gVisor TCP/IP stack for forwards
  tun.go                 TUN VPN device, SNAT, MSS clamping
  tun_netstack.go        gVisor TCP/IP stack for VPN subnet proxy
  tun_proxy.go           Legacy ICMP proxy (raw socket)
  tun_config_*.go        Platform-specific TUN setup (darwin/linux/windows)
  stun.go                STUN discovery, hole punch, UDP read loop
  speedtest.go           P2P bandwidth testing
  crypto.go              X25519 + XChaCha20-Poly1305 encryption
  proxy_bypass.go        TUN proxy bypass (physical NIC detection)
  compress.go            Deflate compression with smart bypass
  udp_reliable.go        RUTP reliable UDP (legacy, used by old tunnels)
  types.go               Protocol types
  events.go              Event system

client/ui/               Gio UI cross-platform app
  app.go                 Window, events, auto-connect
  connect.go             Login screen
  dashboard.go           Tab navigation
  peers.go               Peer list
  forwards.go            Forward management with traffic stats
  vpn.go                 TUN VPN control
  speedtest.go           Speed test with P2P mode
  files.go               File transfer
  tools.go               Windows RDP tools
  peer_selector.go       Dropdown peer selector with P2P/RELAY badge
  settings.go            Settings + STUN selector
  config.go              Config persistence
  logs.go                Event log viewer
  logo.go                Embedded app logo
  platform_android.go    Android platform detection
  platform_other.go      Desktop platform detection

client/core/
  vpn_android.go         Android VPN via JNI (VpnService bridge)
  vpn_stub.go            No-op VPN stub for non-Android
  tun_config_android.go  Android TUN device via VpnService fd
  autohop.go             Auto-hop P2P relay discovery

android/                 Android build pipeline
  build-apk.sh           gogio + dex injection + manifest + signing
  AndroidManifest.xml    VpnService + permissions declaration
  app/src/main/java/     VpnPermissionActivity, StunMaxVpnService, GoBridge

web/                     Admin dashboard (HTML/JS/CSS)
tools/natcheck/          NAT type diagnostic (RFC 5780, Chinese, proxy bypass)
tools/stunserver/        Self-hosted STUN server with HTTP stats
tools/punchtest/         Standalone NAT3/NAT4 hole punch test tool

AGPL-3.0 — See LICENSE for details.