timmy
c5a8757da4
Document the 'Force relay connection' switch that silently disables ICE gathering on iOS NetBird (and similar on macOS), which was the real cause of all peers showing Connection type: Relayed despite STUN being correctly configured. Also document bufferbloat diagnosis via macOS networkQuality, which was a red herring during the P2P investigation (large RTT spikes were the WiFi/ISP, not NetBird).
3.2 KiB
3.2 KiB
NetBird Self-Hosted @ 192.168.42.127
在 Proxmox LXC (Ubuntu 24.04) 上自建 NetBird 的完整部署記錄與設定檔。
部署特色
- IP-only 部署：無需域名，純內網 LAN 使用
- HTTP 模式：使用 Caddy 作為反向代理統一 port 80
- 內建 IdP：使用 NetBird Server 內建的 OAuth2（Dex），無需額外 IdP
- LXC 相容：使用 crun 取代 runc 繞過 Proxmox 非特權容器限制
文件說明
| 文件 | 用途 |
|---|---|
| QUICKSTART.md | 快速部署步驟（適合複製貼上執行） |
| netbird-selfhosted-setup.md | 完整安裝指南（含原理說明） |
| npm-grpc-fix.md | 透過 Nginx Proxy Manager 對外公開時的 gRPC 修復 |
| setup-keys-and-pat.md | Setup Keys 概念、PAT 用法、以及 API 無法改名的繞道做法 |
| stun-port-conflict.md | STUN 3478 被 Headscale 佔用 → NetBird 改用 3479 的解法 |
| client-troubleshooting.md | 客戶端 P2P 失敗、bufferbloat、Force Relay 等坑 |
| SUMMARY.md | 部署摘要與疑難排解記錄 |
快速開始
# 瀏覽器開啟
open http://192.168.42.127
# 客戶端連線
netbird up --management-url http://192.168.42.127
架構
┌───────────────────────┐
│ 192.168.42.127 │
│ │
:80 ────▶│ Caddy (反向代理) │
│ ├── / ──▶│──▶ dashboard (Web UI)
│ ├── /api/* ──▶│──▶ netbird-server
│ ├── /oauth2/* ──▶│──▶ netbird-server
│ ├── /relay* ──▶│──▶ netbird-server
│ └── gRPC ──▶│──▶ netbird-server
:3478/udp ────────────────────────│──▶ netbird-server (STUN)
└───────────────────────┘
環境
| 項目 | 值 |
|---|---|
| 主機 | 192.168.42.127 |
| 系統 | Ubuntu 24.04 LTS |
| STUN port | 3479/udp (非標準 — 3478 被 Headscale 佔用) |
| 容器類型 | Proxmox LXC (非特權) |
| Docker | 29.4.0 |
| OCI Runtime | crun 1.20 |
| 設定目錄 | /opt/netbird/ |
服務清單
| 容器 | 映像 | 用途 |
|---|---|---|
netbird-caddy |
caddy:2 |
反向代理 (:80) |
netbird-dashboard |
netbirdio/dashboard:latest |
Web 管理介面 |
netbird-server |
netbirdio/netbird-server:latest |
管理 + Signal + Relay + STUN + IdP |
注意事項
- 無 TLS：僅適合內網，勿暴露至公網
- 無域名：使用 IP 作為 issuer，若 IP 變更需重建
- LXC 限制：必須使用 crun，不可使用預設 runc
- 首次啟動慢：需下載 GeoLite2 資料庫（約 60MB）