timmy
d026ce4ba9
Gitea's markdown renderer displays keycap emojis (1️⃣, 2️⃣) as broken boxes. Strip all decorative emojis from doc files for cleaner rendering.
246 lines
4.8 KiB
Markdown
246 lines
4.8 KiB
Markdown
# 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: 開始使用
|
||
|
||
### Web 管理介面
|
||
|
||
瀏覽器開啟：**http://192.168.42.127**
|
||
|
||
首次登入會引導你建立管理員帳號。
|
||
|
||
### 客戶端連線
|
||
|
||
安裝 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
|
||
```
|