STUNMESH-go: Wireguard NAT穿隧工具的源起與介紹

STUNMESH-go 是一個以 WireGuard 為核心，專為 NAT 穿透場景設計的輕量級連線工具。它不需要中心伺服器，利用 STUN 協議與 mesh 架構實現點對點通訊，即使雙方都在 CGNAT 或封閉網路下，也能自動協調連線路徑。本議程將分享 STUNMESH-go 的設計背景、核心機制與實務應用經驗，並探討其在自託管、分散式服務、自架 mesh VPN 等情境下的潛力。

Transcript

1. STUNMESH-go: Wireguard NAT穿隧工具 的源起與介紹 黃宇強 Date Huang @ COSCUP 2025 2025/08/10 tjjh89017@hotmail.com
2. About Me • 黃宇強 Date Huang AKA 伊達 • tjjh89017@hotmail.com • Speaking Experience: OpenStack Day Taiwan 2016-2017, Open Source Summit North America 2017, ISC High Performance Project Poster 2018, Hong Kong Open Source Conference 2019, OSC Tokyo 2019, COScon '19, TWNOG 4.0, COSCUP 2021, COSCUP 2023, Kubernetes Community Day 2023, OSC Nagoya 2024, COSCUP 2024, ALASCA tech talk
3. 當初想到這玩意的故事 • 那時候住在公司宿舍，沒有有線網路，都用 4G網卡上網這樣 • 同時間那時候在打PS4的魔物獵人世界 • 然後因為NAT因素，連線超爛，很不容易可以連接上 ◦ 一般來說我都直接PS4跟中華PPPoE接有最好的連接效果 • 總之就是想到覺得實在太雷了，怎麼沒有個更好的方案可以 P2P遊戲
12. 12 No Session From Site B to Site A Deny Site A to Site B Even Site A know NAT mapping about Site B It still cannot connect to Site B
13. Mobile Network • Through CGNAT ◦ Full Cone NAT ◦ 轉換成相同的 IP/Port 對應，即使目標IP/Port是不同的 • NAT Session ◦ 紀錄 Src IP, Src Port, Dst IP, Dst Port ◦ 放行防火牆規則 13
14. CGNAT 延伸閱讀 • NAT Hairpinning • EIF (Endpoint Independent Filtering) • EIM (Endpoint Independent Mapping) • RFC 7857 • Stateful Firewall
15. • UDP based VPN 協議，NAT and Firewall 穿透的可行性 • 內建 Keepalive & Roaming，自動調整遠端端點設定 • 效能好，Wireguard不需要硬體加解密就可以有一定程度效能 ◦ 很適合嵌入式環境 • 設定更簡單，跟IPsec與OpenVPN相比 ◦ OpenVPN設定檔大概5KB ◦ Wireguard只要數bytes • Encapsulate IPv6-in-IPv4, IPv4-in-IPv6 Why Wireguard 15
16. Why Wireguard • 比較重要的點 • 跟其他UDP VPN相比 • Wireguard是可以兩邊同時發起連線，然後任一 UDP成功穿越之後，連線可以建 立 • 大大提高穿透可能性
17. UDP Hole Punching 17 • 試圖讓兩個Client交換連線資訊，然後嘗試連線兩者 • STUN: Session Traversal Utilities for NAT • STUN is common implement for UDP Hole Punching (RFC 5389)
18. https://bford.info/pub/net/p2pnat/ 18
19. • Wireguard Helper工具來打通NAT • 基於Golang • 多硬體架構支援，x86_64, MIPS, ARM, ARM64 • Standalone Executable，不管執行環境的函式庫相依 • 靈感來源於wireguard-p2p project • 開源！ GPLv2 or later ◦ https://github.com/tjjh89017/stunmesh-go STUNMESH-go 19
20. • 目前測試過 ◦ VyOS 2025.07.14-0022-rolling (built-in Wireguard kernel module) ◦ Ubuntu with Wireguard in Kernel module ◦ MacOS Wireguard-go 0.0.20230223, Wireguard-tools 1.0.20210914 ◦ FreeBSD 14.3-RELEASE (built-in Wireguard) ◦ OPNSense 25.1 (built-in Wireguard) ◦ EdgeRouter X (EdgeOS 3.0.0) STUNMESH-go 20
21. STUNMESH-go 21 • 拿到 CGNAT 後的 Public IP 與 Port ◦ Linux 透過 raw socket + cBPF ◦ MacOS/FreeBSD 透過 raw socket + BPF capture • 把 IP/Port 資訊加密後發送給 plugin 做儲存（預設透過Cloudflare） • 去撈出對方的資訊與解密，並直接設定給 Wireguard 對點的端點 • 通常，只需要跑一兩次，當需要發起連線的時候 ◦ 或是兩者同時斷線
33. 肯定有人問：那跟Tailescale/Headscale? • 實作上的差異 ◦ Tailscale走wireguard-go的嵌入式模式 ◦ STUNMESH-go走外掛的模式（復用原本的Wireguard模組） • Controller差異 ◦ Tailscale需要一個該自訂協議的控制器，無論 self-hosted或是直接使用 Tailscale server ◦ STUNMESH-go盡可能讓你復用現有的任何服務
34. Why STUNMESH-go • 例如說你想控制更多部分，STUNMESH-go只幫你做Wireguard打通，剩下不做， 保留更多彈性給你 • 例如說可以配個BGP/OSPF做路由的調配 • 不支援Tailscale等地方，可以直接外掛STUNMESH-go上去（例如EdgeRouter X）
35. 從上次到現在之間的變化 • 感謝COSCUP 2024 Side Project Taiwan的議程軌 • 讓我有機會可以分享STUNMESH-go給大家 • 蒼時弦也(@elct9620)就這麼跳入我這個火坑，幫我寫了一陣子的重構 • 我們也新增了 plugin 系統，原本預設只能用Cloudflare，現在可以自訂了 • 我們支援了MacOS/FreeBSD! x86_64跟arm64都支援了！ • 多了Ping的機制來監控，如果Wireguard疑似斷線，就可以主動觸發STUN的一系 列流程 • Docker container支援！
36. 現在嘗試努力 • 搞一台OpenWRT的4G router，然後測試 • 嘗試盡可能縮小stunmesh-go需要的空間量，現在在MIPS環境，我盡可能擠，還 是需要3.3MB的空間，但是很多OpenWRT裝置的容量真的有夠小 • Windows的支援（但我真的不會），eBPF for Windows的範例我完全看不懂他們怎 麼用 • iOS/Android支援，這太難了，看有沒有有志之士來幫做，我就放棄了 • （會考慮Windows/iOS/Android走類似Tailscale的embedded Wireguard-go方案）
37. Demo 同時 Q&A • 這個Demo要成功，需要一點運氣跟時間，所以可以同時 Q&A