timmy
b6138095f0
Dashboard's 'SSH Access is disabled' warning confuses new users who can clearly ssh into peers just fine. These are two different systems: Dashboard's SSH Access is NetBird's own in-daemon SSH tunnel server (accessed via Dashboard Connect button or 'netbird ssh'), while the regular ssh command uses the target machine's OpenSSH running on port 22 and has nothing to do with the Dashboard SSH toggle. Home-lab use cases rarely need the NetBird built-in SSH — regular OpenSSH over the NetBird overlay is sufficient. Doc explains when you would actually want it (browser-based terminal from Dashboard, credential offloading to NetBird identity, etc) and how to enable if needed.
3.6 KiB
3.6 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 等坑 |
| peer-deployment-ops.md | 在 LXC 用 Docker 部署客戶端、改名、Mac daemon 重啟 |
| groups-and-policies.md | Groups 與 Access Control Policies 概念、設計、API 操作 |
| network-routes.md | Subnet Router：讓遠端 peer 存取 LAN 上沒裝 NetBird 的裝置 |
| ssh-access.md | 一般 SSH vs NetBird 內建 SSH — 常見混淆點釐清 |
| 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）