Initial commit: NetBird self-hosted deployment documentation
This commit is contained in:
245
QUICKSTART.md
Normal file
245
QUICKSTART.md
Normal file
@@ -0,0 +1,245 @@
|
|||||||
|
# NetBird 快速部署指南
|
||||||
|
|
||||||
|
> 目標：在 Proxmox LXC (Ubuntu 24.04) 上部署 NetBird，使用 IP 直接存取（無域名、無 TLS）。
|
||||||
|
|
||||||
|
## 先決條件
|
||||||
|
|
||||||
|
- Proxmox LXC / Ubuntu 24.04
|
||||||
|
- root 權限
|
||||||
|
- 網際網路存取
|
||||||
|
- 內網 IP (例：`192.168.42.127`)
|
||||||
|
|
||||||
|
> ⚠️ 以下步驟中的 `192.168.42.127` 請換成你的實際 IP。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: 安裝前置套件
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apt-get update
|
||||||
|
apt-get install -y curl jq ca-certificates gnupg openssl
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 2: 安裝 Docker
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsSL https://get.docker.com | sh
|
||||||
|
systemctl start docker
|
||||||
|
systemctl enable docker
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 3: 安裝 crun（LXC 必須）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -sL "https://github.com/containers/crun/releases/download/1.20/crun-1.20-linux-amd64" \
|
||||||
|
-o /usr/local/bin/crun
|
||||||
|
chmod +x /usr/local/bin/crun
|
||||||
|
|
||||||
|
cat > /etc/docker/daemon.json << 'EOF'
|
||||||
|
{
|
||||||
|
"runtimes": {
|
||||||
|
"crun": {
|
||||||
|
"path": "/usr/local/bin/crun"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"default-runtime": "crun"
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
|
||||||
|
systemctl restart docker
|
||||||
|
docker run --rm hello-world # 驗證
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 4: 建立設定目錄與產生金鑰
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p /opt/netbird && cd /opt/netbird
|
||||||
|
|
||||||
|
RELAY_SECRET=$(openssl rand -base64 32 | sed 's/=//g')
|
||||||
|
ENCRYPTION_KEY=$(openssl rand -base64 32)
|
||||||
|
SERVER_IP=192.168.42.127 # 改成你的 IP
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 5: 建立設定檔
|
||||||
|
|
||||||
|
### docker-compose.yml
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > /opt/netbird/docker-compose.yml << 'EOF'
|
||||||
|
services:
|
||||||
|
caddy:
|
||||||
|
image: caddy:2
|
||||||
|
container_name: netbird-caddy
|
||||||
|
restart: unless-stopped
|
||||||
|
networks: [netbird]
|
||||||
|
ports:
|
||||||
|
- "80:80"
|
||||||
|
volumes:
|
||||||
|
- ./Caddyfile:/etc/caddy/Caddyfile:ro
|
||||||
|
|
||||||
|
dashboard:
|
||||||
|
image: netbirdio/dashboard:latest
|
||||||
|
container_name: netbird-dashboard
|
||||||
|
restart: unless-stopped
|
||||||
|
networks: [netbird]
|
||||||
|
env_file:
|
||||||
|
- ./dashboard.env
|
||||||
|
|
||||||
|
netbird-server:
|
||||||
|
image: netbirdio/netbird-server:latest
|
||||||
|
container_name: netbird-server
|
||||||
|
restart: unless-stopped
|
||||||
|
networks: [netbird]
|
||||||
|
ports:
|
||||||
|
- "3478:3478/udp"
|
||||||
|
volumes:
|
||||||
|
- netbird_data:/var/lib/netbird
|
||||||
|
- ./config.yaml:/etc/netbird/config.yaml
|
||||||
|
command: ["--config", "/etc/netbird/config.yaml"]
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
netbird_data:
|
||||||
|
|
||||||
|
networks:
|
||||||
|
netbird:
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
### Caddyfile
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > /opt/netbird/Caddyfile << 'EOF'
|
||||||
|
:80 {
|
||||||
|
@grpc header Content-Type application/grpc*
|
||||||
|
reverse_proxy @grpc h2c://netbird-server:80
|
||||||
|
|
||||||
|
@backend path /relay* /ws-proxy/* /api/* /oauth2/*
|
||||||
|
reverse_proxy @backend netbird-server:80
|
||||||
|
|
||||||
|
reverse_proxy /* netbird-dashboard:80
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
### config.yaml
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > /opt/netbird/config.yaml << EOF
|
||||||
|
server:
|
||||||
|
listenAddress: ":80"
|
||||||
|
exposedAddress: "http://${SERVER_IP}:80"
|
||||||
|
stunPorts:
|
||||||
|
- 3478
|
||||||
|
metricsPort: 9090
|
||||||
|
healthcheckAddress: ":9000"
|
||||||
|
logLevel: "info"
|
||||||
|
logFile: "console"
|
||||||
|
|
||||||
|
authSecret: "${RELAY_SECRET}"
|
||||||
|
dataDir: "/var/lib/netbird"
|
||||||
|
|
||||||
|
auth:
|
||||||
|
issuer: "http://${SERVER_IP}/oauth2"
|
||||||
|
signKeyRefreshEnabled: true
|
||||||
|
dashboardRedirectURIs:
|
||||||
|
- "http://${SERVER_IP}/nb-auth"
|
||||||
|
- "http://${SERVER_IP}/nb-silent-auth"
|
||||||
|
cliRedirectURIs:
|
||||||
|
- "http://localhost:53000/"
|
||||||
|
|
||||||
|
reverseProxy:
|
||||||
|
trustedHTTPProxies:
|
||||||
|
- "0.0.0.0/0"
|
||||||
|
|
||||||
|
store:
|
||||||
|
engine: "sqlite"
|
||||||
|
encryptionKey: "${ENCRYPTION_KEY}"
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
### dashboard.env
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > /opt/netbird/dashboard.env << EOF
|
||||||
|
NETBIRD_MGMT_API_ENDPOINT=http://${SERVER_IP}
|
||||||
|
NETBIRD_MGMT_GRPC_API_ENDPOINT=http://${SERVER_IP}
|
||||||
|
AUTH_AUDIENCE=netbird-dashboard
|
||||||
|
AUTH_CLIENT_ID=netbird-dashboard
|
||||||
|
AUTH_CLIENT_SECRET=
|
||||||
|
AUTH_AUTHORITY=http://${SERVER_IP}/oauth2
|
||||||
|
USE_AUTH0=false
|
||||||
|
AUTH_SUPPORTED_SCOPES=openid profile email groups
|
||||||
|
AUTH_REDIRECT_URI=/nb-auth
|
||||||
|
AUTH_SILENT_REDIRECT_URI=/nb-silent-auth
|
||||||
|
NGINX_SSL_PORT=443
|
||||||
|
LETSENCRYPT_DOMAIN=none
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 6: 啟動服務
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /opt/netbird
|
||||||
|
docker compose pull
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
> ⏳ 首次啟動需等待約 2-5 分鐘下載 GeoLite2 地理資料庫（約 60MB）。
|
||||||
|
|
||||||
|
## Step 7: 驗證
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 檢查容器狀態
|
||||||
|
docker ps
|
||||||
|
|
||||||
|
# 測試 Dashboard
|
||||||
|
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/
|
||||||
|
# 預期: 200
|
||||||
|
|
||||||
|
# 測試 OAuth2 端點（伺服器就緒的指標）
|
||||||
|
curl -s http://127.0.0.1/oauth2/.well-known/openid-configuration | jq .issuer
|
||||||
|
# 預期: "http://192.168.42.127/oauth2"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 8: 開始使用
|
||||||
|
|
||||||
|
### 1️⃣ Web 管理介面
|
||||||
|
|
||||||
|
瀏覽器開啟：**http://192.168.42.127**
|
||||||
|
|
||||||
|
首次登入會引導你建立管理員帳號。
|
||||||
|
|
||||||
|
### 2️⃣ 客戶端連線
|
||||||
|
|
||||||
|
安裝 NetBird 客戶端後執行：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
netbird up --management-url http://192.168.42.127
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 疑難排解
|
||||||
|
|
||||||
|
### Docker 容器啟動失敗
|
||||||
|
|
||||||
|
```
|
||||||
|
OCI runtime create failed: runc create failed: ... permission denied
|
||||||
|
```
|
||||||
|
|
||||||
|
**原因**：Proxmox LXC 容器 `/proc/sys` 限制。
|
||||||
|
**解決**：確認已執行 Step 3 設定 crun。
|
||||||
|
|
||||||
|
### 伺服器啟動後無回應 (502 Bad Gateway)
|
||||||
|
|
||||||
|
**原因**：正在下載 GeoLite2 資料庫。
|
||||||
|
**檢查**：`docker compose logs -f netbird-server`
|
||||||
|
**處理**：耐心等待，視網速需 2-5 分鐘。
|
||||||
|
|
||||||
|
### 完全重置
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /opt/netbird
|
||||||
|
docker compose down --volumes
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
76
README.md
Normal file
76
README.md
Normal file
@@ -0,0 +1,76 @@
|
|||||||
|
# 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](./QUICKSTART.md) | 快速部署步驟（適合複製貼上執行） |
|
||||||
|
| [netbird-selfhosted-setup.md](./netbird-selfhosted-setup.md) | 完整安裝指南（含原理說明） |
|
||||||
|
| [SUMMARY.md](./SUMMARY.md) | 部署摘要與疑難排解記錄 |
|
||||||
|
|
||||||
|
## 🚀 快速開始
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 瀏覽器開啟
|
||||||
|
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 |
|
||||||
|
| 容器類型 | 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）
|
||||||
|
|
||||||
|
## 🔗 相關連結
|
||||||
|
|
||||||
|
- [NetBird 官方文件](https://docs.netbird.io/selfhosted/selfhosted-quickstart)
|
||||||
|
- [NetBird GitHub](https://github.com/netbirdio/netbird)
|
||||||
|
- [crun](https://github.com/containers/crun)
|
||||||
142
SUMMARY.md
Normal file
142
SUMMARY.md
Normal file
@@ -0,0 +1,142 @@
|
|||||||
|
# NetBird 部署摘要
|
||||||
|
|
||||||
|
## 部署結果
|
||||||
|
|
||||||
|
✅ **NetBird Self-Hosted 成功部署於 `192.168.42.127`**
|
||||||
|
|
||||||
|
- 部署日期：2026-04-17
|
||||||
|
- 存取方式：`http://192.168.42.127`
|
||||||
|
- 部署模式：HTTP-only（無 TLS）、IP-only（無域名）
|
||||||
|
|
||||||
|
## 部署時的關鍵決策
|
||||||
|
|
||||||
|
### 1. 為何不用官方 `getting-started.sh` 腳本？
|
||||||
|
|
||||||
|
官方腳本是互動式的（讀取 `/dev/tty`），且預設選項需要公網域名與 Let's Encrypt。本次為內網 IP 部署，手動產生設定檔更直接。
|
||||||
|
|
||||||
|
腳本原始碼中支援 `NETBIRD_DOMAIN=use-ip` 模式（line 308），會自動偵測 IP 並切換為 HTTP、port 80、`rel://` relay 協定。本次部署採用了相同的邏輯但以手動設定檔實現。
|
||||||
|
|
||||||
|
### 2. 為何選 Caddy 而非 Traefik 作為反向代理？
|
||||||
|
|
||||||
|
- Traefik 內建 Let's Encrypt ACME，但無域名時會反覆嘗試失敗
|
||||||
|
- Caddy 設定檔更精簡（約 10 行），純 HTTP 路由對本場景足夠
|
||||||
|
- 兩者都能正確處理 gRPC (h2c) 後端
|
||||||
|
|
||||||
|
### 3. 為何需要 crun 取代 runc？
|
||||||
|
|
||||||
|
**遇到的錯誤**：
|
||||||
|
|
||||||
|
```
|
||||||
|
OCI runtime create failed: runc create failed: unable to start container process:
|
||||||
|
error during container init: open sysctl net.ipv4.ip_unprivileged_port_start file:
|
||||||
|
reopen fd 8: permission denied
|
||||||
|
```
|
||||||
|
|
||||||
|
**根因分析**：
|
||||||
|
- Proxmox 非特權 LXC 將 `/proc/sys` 掛載為唯讀（`ro`）
|
||||||
|
- runc 1.2+ 為防止 TOCTOU 攻擊，會用「reopen fd」機制存取 sysctl 檔案
|
||||||
|
- 此機制在 LXC 的 `/proc` mount namespace 限制下失敗
|
||||||
|
|
||||||
|
**嘗試但無效的方法**：
|
||||||
|
- `--privileged` flag
|
||||||
|
- `--security-opt apparmor=unconfined --security-opt seccomp=unconfined`
|
||||||
|
- `mount -o remount,rw /proc/sys`
|
||||||
|
- apt 安裝的 crun 1.14.1（OCI spec 太舊，Docker 不接受）
|
||||||
|
|
||||||
|
**最終解法**：
|
||||||
|
下載 GitHub 最新 crun binary (1.20)，並設為 Docker 預設 runtime。
|
||||||
|
|
||||||
|
## 安裝步驟摘要
|
||||||
|
|
||||||
|
```
|
||||||
|
1. apt 安裝前置套件 (curl, jq, openssl) ← 約 1 分鐘
|
||||||
|
2. 安裝 Docker Engine ← 約 2 分鐘（網速慢）
|
||||||
|
3. 下載 crun binary，設定為 Docker 預設 runtime ← 約 30 秒
|
||||||
|
4. 建立 /opt/netbird/ 下四個設定檔 ← 約 30 秒
|
||||||
|
5. docker compose pull + up -d ← 約 1 分鐘
|
||||||
|
6. 等待 netbird-server 下載 GeoLite2 資料庫 ← 約 2-5 分鐘
|
||||||
|
```
|
||||||
|
|
||||||
|
總耗時約 10 分鐘（含 GeoIP 下載）。
|
||||||
|
|
||||||
|
## 服務驗證
|
||||||
|
|
||||||
|
所有服務已驗證正常運作：
|
||||||
|
|
||||||
|
| 端點 | 狀態 | 說明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `http://192.168.42.127/` | ✅ 200 | Dashboard Web UI |
|
||||||
|
| `http://192.168.42.127/oauth2/.well-known/openid-configuration` | ✅ 200 | OIDC Discovery |
|
||||||
|
| STUN `:3478/udp` | ✅ | NAT 穿透 |
|
||||||
|
| 內部 gRPC (Signal + Management) | ✅ | h2c via Caddy |
|
||||||
|
|
||||||
|
## 疑難排解記錄
|
||||||
|
|
||||||
|
| 問題 | 原因 | 解法 |
|
||||||
|
|------|------|------|
|
||||||
|
| 初次 apt install 卡住 | 背景執行的 apt 行程未結束就被觸發第二個，導致 lock 競爭 | 清除 `/var/lib/dpkg/lock*` 與 `/var/lib/apt/lists/lock`，重啟 apt |
|
||||||
|
| `curl: command not found` | apt 仍在安裝中 | 等待安裝完成 |
|
||||||
|
| 所有 Docker 容器啟動失敗 | LXC `/proc/sys` 唯讀 + runc 1.3 的 reopen fd 機制 | 改用 crun 1.20 |
|
||||||
|
| Docker Compose `crun` runtime 未知 | `/etc/docker/daemon.json` 設定未生效 | `systemctl restart docker` |
|
||||||
|
| apt 的 crun 1.14.1 報 `unknown version specified` | crun 的 OCI spec 1.0.0 與 Docker 29.4 不相容 | 從 GitHub 下載 crun 1.20 |
|
||||||
|
| 502 Bad Gateway（所有 API 端點） | netbird-server 下載 GeoLite2 中，尚未開始監聽 port 80 | 等待 2-5 分鐘 |
|
||||||
|
|
||||||
|
## 檔案位置
|
||||||
|
|
||||||
|
### 本機（/Users/timmy/dev/42_127/）
|
||||||
|
|
||||||
|
```
|
||||||
|
├── README.md ← 專案總覽
|
||||||
|
├── QUICKSTART.md ← 快速部署步驟
|
||||||
|
├── SUMMARY.md ← 本檔（部署摘要）
|
||||||
|
└── netbird-selfhosted-setup.md ← 完整安裝指南
|
||||||
|
```
|
||||||
|
|
||||||
|
### 遠端伺服器（192.168.42.127:/opt/netbird/）
|
||||||
|
|
||||||
|
```
|
||||||
|
├── docker-compose.yml ← 服務編排
|
||||||
|
├── Caddyfile ← 反向代理路由
|
||||||
|
├── config.yaml ← NetBird Server 設定
|
||||||
|
└── dashboard.env ← Dashboard 環境變數
|
||||||
|
```
|
||||||
|
|
||||||
|
### Docker Volume
|
||||||
|
|
||||||
|
- `netbird_netbird_data`：NetBird SQLite 資料庫與 GeoIP 資料
|
||||||
|
|
||||||
|
## 後續維運
|
||||||
|
|
||||||
|
### 日常指令
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ssh root@192.168.42.127
|
||||||
|
cd /opt/netbird
|
||||||
|
|
||||||
|
# 查看日誌
|
||||||
|
docker compose logs -f
|
||||||
|
|
||||||
|
# 重啟
|
||||||
|
docker compose restart
|
||||||
|
|
||||||
|
# 更新映像
|
||||||
|
docker compose pull && docker compose up -d
|
||||||
|
|
||||||
|
# 備份資料庫
|
||||||
|
docker compose exec netbird-server sqlite3 /var/lib/netbird/store.db ".backup /tmp/backup.db"
|
||||||
|
docker cp netbird-server:/tmp/backup.db ./backup-$(date +%F).db
|
||||||
|
```
|
||||||
|
|
||||||
|
### 可能的擴展
|
||||||
|
|
||||||
|
- **加上 TLS**：若之後取得域名，可切換為 Traefik + Let's Encrypt（或本機自簽憑證）
|
||||||
|
- **外部 IdP**：需支援 OIDC 的 IdP（如 Authentik、Keycloak、Google）可取代內建 Dex
|
||||||
|
- **高可用性**：SQLite 不支援叢集，需改用 PostgreSQL；Relay 可獨立部署
|
||||||
|
- **監控**：已暴露 `metricsPort: 9090` 的 Prometheus 指標
|
||||||
|
|
||||||
|
## 參考資料
|
||||||
|
|
||||||
|
- 官方文件：https://docs.netbird.io/selfhosted/selfhosted-quickstart
|
||||||
|
- Getting Started 腳本：https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh
|
||||||
|
- crun release：https://github.com/containers/crun/releases
|
||||||
|
- Proxmox LXC Docker 相容性：https://pve.proxmox.com/wiki/Linux_Container#_features
|
||||||
302
netbird-selfhosted-setup.md
Normal file
302
netbird-selfhosted-setup.md
Normal file
@@ -0,0 +1,302 @@
|
|||||||
|
# NetBird Self-Hosted 安裝指南
|
||||||
|
|
||||||
|
> 環境：Proxmox LXC (CT127) / Ubuntu 24.04 / 內網 IP-only (無域名)
|
||||||
|
|
||||||
|
## 環境資訊
|
||||||
|
|
||||||
|
| 項目 | 值 |
|
||||||
|
|------|-----|
|
||||||
|
| 主機 | 192.168.42.127 |
|
||||||
|
| 系統 | Ubuntu 24.04 LTS (Noble Numbat) |
|
||||||
|
| 核心 | 6.8.12-16-pve (Proxmox VE) |
|
||||||
|
| 容器類型 | LXC (非特權) |
|
||||||
|
|
||||||
|
## 1. 安裝前置套件
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apt-get update
|
||||||
|
apt-get install -y curl jq ca-certificates gnupg openssl
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. 安裝 Docker
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsSL https://get.docker.com | sh
|
||||||
|
systemctl start docker
|
||||||
|
systemctl enable docker
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. 解決 LXC 容器中 Docker 無法啟動的問題
|
||||||
|
|
||||||
|
Proxmox LXC 容器中 `/proc/sys` 被掛載為唯讀，導致 runc 1.3+ 嘗試存取 `net.ipv4.ip_unprivileged_port_start` sysctl 時失敗：
|
||||||
|
|
||||||
|
```
|
||||||
|
OCI runtime create failed: runc create failed: unable to start container process:
|
||||||
|
error during container init: open sysctl net.ipv4.ip_unprivileged_port_start file:
|
||||||
|
reopen fd 8: permission denied
|
||||||
|
```
|
||||||
|
|
||||||
|
**解決方案：以 crun 取代 runc 作為 OCI runtime**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 下載 crun 1.20
|
||||||
|
curl -sL "https://github.com/containers/crun/releases/download/1.20/crun-1.20-linux-amd64" \
|
||||||
|
-o /usr/local/bin/crun
|
||||||
|
chmod +x /usr/local/bin/crun
|
||||||
|
|
||||||
|
# 設定 Docker 使用 crun
|
||||||
|
cat > /etc/docker/daemon.json << 'EOF'
|
||||||
|
{
|
||||||
|
"runtimes": {
|
||||||
|
"crun": {
|
||||||
|
"path": "/usr/local/bin/crun"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"default-runtime": "crun"
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
|
||||||
|
systemctl restart docker
|
||||||
|
|
||||||
|
# 驗證
|
||||||
|
docker run --rm hello-world
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. 建立 NetBird 設定檔
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p /opt/netbird
|
||||||
|
cd /opt/netbird
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.1 產生金鑰
|
||||||
|
|
||||||
|
```bash
|
||||||
|
RELAY_SECRET=$(openssl rand -base64 32 | sed 's/=//g')
|
||||||
|
ENCRYPTION_KEY=$(openssl rand -base64 32)
|
||||||
|
|
||||||
|
echo "RELAY_SECRET=$RELAY_SECRET"
|
||||||
|
echo "ENCRYPTION_KEY=$ENCRYPTION_KEY"
|
||||||
|
```
|
||||||
|
|
||||||
|
> 記下這兩個值，下方設定檔需要用到。
|
||||||
|
|
||||||
|
### 4.2 docker-compose.yml
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
caddy:
|
||||||
|
image: caddy:2
|
||||||
|
container_name: netbird-caddy
|
||||||
|
restart: unless-stopped
|
||||||
|
networks: [netbird]
|
||||||
|
ports:
|
||||||
|
- "80:80"
|
||||||
|
volumes:
|
||||||
|
- ./Caddyfile:/etc/caddy/Caddyfile:ro
|
||||||
|
logging:
|
||||||
|
driver: "json-file"
|
||||||
|
options:
|
||||||
|
max-size: "500m"
|
||||||
|
max-file: "2"
|
||||||
|
|
||||||
|
dashboard:
|
||||||
|
image: netbirdio/dashboard:latest
|
||||||
|
container_name: netbird-dashboard
|
||||||
|
restart: unless-stopped
|
||||||
|
networks: [netbird]
|
||||||
|
env_file:
|
||||||
|
- ./dashboard.env
|
||||||
|
logging:
|
||||||
|
driver: "json-file"
|
||||||
|
options:
|
||||||
|
max-size: "500m"
|
||||||
|
max-file: "2"
|
||||||
|
|
||||||
|
netbird-server:
|
||||||
|
image: netbirdio/netbird-server:latest
|
||||||
|
container_name: netbird-server
|
||||||
|
restart: unless-stopped
|
||||||
|
networks: [netbird]
|
||||||
|
ports:
|
||||||
|
- "3478:3478/udp"
|
||||||
|
volumes:
|
||||||
|
- netbird_data:/var/lib/netbird
|
||||||
|
- ./config.yaml:/etc/netbird/config.yaml
|
||||||
|
command: ["--config", "/etc/netbird/config.yaml"]
|
||||||
|
logging:
|
||||||
|
driver: "json-file"
|
||||||
|
options:
|
||||||
|
max-size: "500m"
|
||||||
|
max-file: "2"
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
netbird_data:
|
||||||
|
|
||||||
|
networks:
|
||||||
|
netbird:
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 Caddyfile
|
||||||
|
|
||||||
|
Caddy 作為反向代理，將所有服務統一在 port 80：
|
||||||
|
|
||||||
|
```
|
||||||
|
:80 {
|
||||||
|
@grpc header Content-Type application/grpc*
|
||||||
|
reverse_proxy @grpc h2c://netbird-server:80
|
||||||
|
|
||||||
|
@backend path /relay* /ws-proxy/* /api/* /oauth2/*
|
||||||
|
reverse_proxy @backend netbird-server:80
|
||||||
|
|
||||||
|
reverse_proxy /* netbird-dashboard:80
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.4 config.yaml
|
||||||
|
|
||||||
|
將 `<RELAY_SECRET>` 和 `<ENCRYPTION_KEY>` 替換為步驟 4.1 產生的值：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
server:
|
||||||
|
listenAddress: ":80"
|
||||||
|
exposedAddress: "http://192.168.42.127:80"
|
||||||
|
stunPorts:
|
||||||
|
- 3478
|
||||||
|
metricsPort: 9090
|
||||||
|
healthcheckAddress: ":9000"
|
||||||
|
logLevel: "info"
|
||||||
|
logFile: "console"
|
||||||
|
|
||||||
|
authSecret: "<RELAY_SECRET>"
|
||||||
|
dataDir: "/var/lib/netbird"
|
||||||
|
|
||||||
|
auth:
|
||||||
|
issuer: "http://192.168.42.127/oauth2"
|
||||||
|
signKeyRefreshEnabled: true
|
||||||
|
dashboardRedirectURIs:
|
||||||
|
- "http://192.168.42.127/nb-auth"
|
||||||
|
- "http://192.168.42.127/nb-silent-auth"
|
||||||
|
cliRedirectURIs:
|
||||||
|
- "http://localhost:53000/"
|
||||||
|
|
||||||
|
reverseProxy:
|
||||||
|
trustedHTTPProxies:
|
||||||
|
- "0.0.0.0/0"
|
||||||
|
|
||||||
|
store:
|
||||||
|
engine: "sqlite"
|
||||||
|
encryptionKey: "<ENCRYPTION_KEY>"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.5 dashboard.env
|
||||||
|
|
||||||
|
```env
|
||||||
|
NETBIRD_MGMT_API_ENDPOINT=http://192.168.42.127
|
||||||
|
NETBIRD_MGMT_GRPC_API_ENDPOINT=http://192.168.42.127
|
||||||
|
AUTH_AUDIENCE=netbird-dashboard
|
||||||
|
AUTH_CLIENT_ID=netbird-dashboard
|
||||||
|
AUTH_CLIENT_SECRET=
|
||||||
|
AUTH_AUTHORITY=http://192.168.42.127/oauth2
|
||||||
|
USE_AUTH0=false
|
||||||
|
AUTH_SUPPORTED_SCOPES=openid profile email groups
|
||||||
|
AUTH_REDIRECT_URI=/nb-auth
|
||||||
|
AUTH_SILENT_REDIRECT_URI=/nb-silent-auth
|
||||||
|
NGINX_SSL_PORT=443
|
||||||
|
LETSENCRYPT_DOMAIN=none
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. 啟動服務
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /opt/netbird
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
首次啟動時 netbird-server 會下載 GeoLite2 地理位置資料庫（約 60MB），視網路速度可能需要數分鐘。
|
||||||
|
|
||||||
|
驗證所有容器正常運行：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker ps
|
||||||
|
```
|
||||||
|
|
||||||
|
預期輸出三個容器皆為 `Up` 狀態：
|
||||||
|
|
||||||
|
```
|
||||||
|
NAMES STATUS PORTS
|
||||||
|
netbird-caddy Up 0.0.0.0:80->80/tcp
|
||||||
|
netbird-dashboard Up 80/tcp, 443/tcp
|
||||||
|
netbird-server Up 0.0.0.0:3478->3478/udp
|
||||||
|
```
|
||||||
|
|
||||||
|
驗證 OAuth2 端點：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s http://127.0.0.1/oauth2/.well-known/openid-configuration | jq .issuer
|
||||||
|
# 預期輸出: "http://192.168.42.127/oauth2"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. 使用方式
|
||||||
|
|
||||||
|
### Web 管理介面
|
||||||
|
|
||||||
|
瀏覽器打開 `http://192.168.42.127`，完成首次設定（建立管理員帳號）。
|
||||||
|
|
||||||
|
### 客戶端連線
|
||||||
|
|
||||||
|
```bash
|
||||||
|
netbird up --management-url http://192.168.42.127
|
||||||
|
```
|
||||||
|
|
||||||
|
## 服務架構
|
||||||
|
|
||||||
|
```
|
||||||
|
Client Request (:80)
|
||||||
|
|
|
||||||
|
Caddy (反向代理)
|
||||||
|
|
|
||||||
|
+-- / --> netbird-dashboard (Web UI)
|
||||||
|
+-- /api/* /oauth2/* --> netbird-server (管理 API + 內建 IdP)
|
||||||
|
+-- /relay* /ws-proxy/* --> netbird-server (Relay + WebSocket)
|
||||||
|
+-- gRPC (Content-Type 判斷) --> netbird-server (Signal + Management gRPC)
|
||||||
|
|
||||||
|
STUN (:3478/udp) --> netbird-server
|
||||||
|
```
|
||||||
|
|
||||||
|
## 開放端口
|
||||||
|
|
||||||
|
| 端口 | 協定 | 用途 |
|
||||||
|
|------|------|------|
|
||||||
|
| 80 | TCP | Dashboard + API + Signal + Relay |
|
||||||
|
| 3478 | UDP | STUN (NAT 穿透) |
|
||||||
|
|
||||||
|
## 常用維運指令
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /opt/netbird
|
||||||
|
|
||||||
|
# 查看日誌
|
||||||
|
docker compose logs -f netbird-server
|
||||||
|
docker compose logs -f --tail=50
|
||||||
|
|
||||||
|
# 重啟服務
|
||||||
|
docker compose restart
|
||||||
|
|
||||||
|
# 停止服務
|
||||||
|
docker compose down
|
||||||
|
|
||||||
|
# 更新映像
|
||||||
|
docker compose pull
|
||||||
|
docker compose up -d
|
||||||
|
|
||||||
|
# 完全重置（刪除所有資料）
|
||||||
|
docker compose down --volumes
|
||||||
|
```
|
||||||
|
|
||||||
|
## 注意事項
|
||||||
|
|
||||||
|
- 此為 HTTP-only 內網部署，無 TLS 加密，不適合暴露至公網
|
||||||
|
- 如需公網存取，應配置域名並啟用 HTTPS（使用 Traefik + Let's Encrypt）
|
||||||
|
- Proxmox LXC 容器需使用 crun 替代 runc，否則 Docker 容器無法啟動
|
||||||
|
- 設定檔位於 `/opt/netbird/`，資料儲存在 Docker volume `netbird_netbird_data`
|
||||||
Reference in New Issue
Block a user