netbird-selfhosted/QUICKSTART.md

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: 安裝前置套件

apt-get update
apt-get install -y curl jq ca-certificates gnupg openssl

Step 2: 安裝 Docker

curl -fsSL https://get.docker.com | sh
systemctl start docker
systemctl enable docker

Step 3: 安裝 crun（LXC 必須）

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: 建立設定目錄與產生金鑰

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

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

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

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

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: 啟動服務

cd /opt/netbird
docker compose pull
docker compose up -d

首次啟動需等待約 2-5 分鐘下載 GeoLite2 地理資料庫（約 60MB）。

Step 7: 驗證

# 檢查容器狀態
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 客戶端後執行：

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 分鐘。

完全重置

cd /opt/netbird
docker compose down --volumes
docker compose up -d