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
|
||||
```
|
||||
Reference in New Issue
Block a user