# 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
```