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 等坑 |
| peer-deployment-ops.md | 在 LXC 用 Docker 部署客戶端、改名、Mac daemon 重啟 |
| groups-and-policies.md | Groups 與 Access Control Policies 概念、設計、API 操作 |
| network-routes.md | Subnet Router（home-lan）與 Exit Nodes（exit-ct100、exit-virmach-lax） |
| ssh-access.md | 一般 SSH vs NetBird 內建 SSH — 常見混淆點釐清 |
| caddy-netbird-diagram.html | Caddy 反向代理架構的視覺化示意圖（瀏覽器開啟） |
| SUMMARY.md | 部署摘要與疑難排解記錄 |
快速開始
# 瀏覽器開啟
open http://192.168.42.127
# 客戶端連線
netbird up --management-url http://192.168.42.127
架構
互動 / 動畫版：caddy-netbird-diagram.html（用瀏覽器開）
┌───────────────────────┐
│ 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）