如何自架 NetBird VPN 伺服器：VPS 部署教學

自架 NetBird VPN 伺服器的優勢

自架 NetBird VPN 伺服器能將控制平面（Control Plane）託管於您自有的 VPS 上：此組件負責維護節點清單、決定節點間的存取權限，並協助兩個節點在 NAT（網路位址轉譯）後方建立連線。隧道本身仍採用 WireGuard 技術，在您的機器之間進行端對端加密。此架構的改變在於，沒有任何外部公司能掌握您的裝置清單或登入流程。

NetBird 的定位介於您可能已熟悉的兩種技術之間。它是一種網狀覆蓋網路（Mesh Overlay），節點間可直接連線，無須將所有流量經由單一閘道轉發。它同時支援完整的端對端自架，這使其與 Headscale（自架 Tailscale 控制伺服器） 類似。若您過去僅使用過單一閘道隧道，請先閱讀 純 WireGuard 與網狀覆蓋網路的差異，因為該概念模型是理解本頁後續內容的基礎。

若您的需求僅是將所有流量導向單一出口伺服器，網狀網路的架構將顯得過於複雜。在單一 VPS 上架設純 WireGuard VPN 或 使用 Tailscale 節點作為出口節點，皆能以更輕量的配置達成目標。

實際運作的堆疊架構

佈局近期已變更，大多數舊版教學文件描述的是舊架構。截至 2026 年 8 月，在 v0.76.2 版本中，快速啟動腳本預設會寫入包含三個服務的 Compose 檔案。

• netbird-server 承載管理 API、訊號服務、內建 STUN 監聽器的轉送服務（relay）以及內建的身分識別提供者。在舊版本中，這些是獨立的容器，且身分識別提供者必須先自行建置獨立的 Zitadel 安裝。
• dashboard 是管理員網頁控制台。
• traefik 負責終止 TLS (transport layer security)，並在首次啟動時向 Let's Encrypt 申請憑證。

另外還有兩個服務，除非您在提示中選擇確認，否則預設為關閉。NetBird Proxy 服務負責將內部服務發佈至公開主機名稱。CrowdSec 則用於過濾惡意流量。建置可運作的網狀網路（mesh）並不需要這兩者，且兩者都會在小型伺服器上佔用記憶體。

如果您是從 單一 Docker 容器的 wg-easy 遷移過來，這意味著組件數量有所增加。您獲得的好處是存取控制原則、個別使用者帳號，以及讓節點直接相互連線，而非透過單一閘道轉送。

開始前的準備工作

公開網域名稱是必要條件。儀表板、API 與轉送服務（relay）皆透過 443 埠的 HTTPS 運作，且 Traefik 需透過 HTTP challenge 向 Let's Encrypt 申請憑證，這要求網域名稱必須能從公網解析至此 VPS。單純使用 IP 位址無法完成此流程。

請建立一筆 A 記錄，netbird.example.com 指向該 VPS 的公開 IPv4 位址，並在執行任何操作前等待 DNS 生效。

dig +short netbird.example.com

上述指令必須正確顯示伺服器的 IP 位址。若在 DNS 傳播完成前執行安裝程式，首次啟動時的憑證申請將會失敗；若重複失敗，將觸發 Let's Encrypt 的速率限制，導致您必須等待一小時後才能再次嘗試。

必須確保以下三個埠可從網際網路存取：TCP 80 用於憑證驗證與 HTTPS 重新導向、TCP 443 用於儀表板、API、訊號與轉送流量，以及 UDP 3478 用於 STUN。

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw reload
sudo ufw status

請務必在雲端服務供應商的網路防火牆中開啟這些埠。這通常是 VPS 控制面板中的獨立設定，也是許多伺服器即便自身 ufw status 設定正確，卻仍無法連線的主因。

STUN (session traversal utilities for NAT) 是讓對等節點（peer）得知其 NAT 所分配的公開位址與埠號的機制，藉此嘗試建立直接通道。若封鎖 UDP 3478，對等節點仍會透過 TCP 443 上的轉送服務連線，表面上看起來運作正常。但實際上，所有節點都會顯示 Connection type: Relayed，導致所有流量皆經過您的 VPS，而非點對點傳輸。

軟體需求方面，您需要安裝 Docker 並包含 Compose v2 外掛，此外還需 jq 與 curl。安裝腳本會檢查上述所有項目，若有缺失將會停止執行。若此伺服器尚未安裝 Docker，請先參考 在 VPS 上設定 Docker Compose。

使用快速啟動腳本安裝 NetBird 伺服器

官方文件提供的單行指令會直接將最新版本導向至 shell 執行：

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

請改用鎖定版本的方式。latest 會隨時間變動，導致相隔兩週執行的相同指令會產生兩種不同的安裝結果，且磁碟上沒有任何紀錄能說明是哪一個版本寫入了您的設定。請下載標記過的發行版本，閱讀內容後再執行。

mkdir -p ~/netbird
cd ~/netbird
curl -fsSL -o getting-started.sh \
  https://github.com/netbirdio/netbird/releases/download/v0.76.2/getting-started.sh
less getting-started.sh
bash getting-started.sh

腳本會先詢問網域名稱：

Enter the domain you want to use for NetBird (e.g. netbird.my-domain.com):

接著詢問 TLS 的處理方式：

Which reverse proxy will you use?
  [0] Traefik (recommended - automatic TLS, included in Docker Compose)
  [1] Existing Traefik (labels for external Traefik instance)
  [2] Nginx (generates config template)
  [3] Nginx Proxy Manager (generates config + instructions)
  [4] External Caddy (generates Caddyfile snippet)
  [5] Other/Manual (displays setup documentation)
Enter choice [0-5] (default: 0):

請選擇 [0]。選項 2 到 5 會寫入設定片段並將後續連接工作留給您處理；這對於已經運行反向代理的伺服器是正確的，但對於全新的伺服器則不適用。選項 0 則會要求輸入 Let's Encrypt 的電子郵件地址，用於接收憑證過期通知。

首次安裝時，請拒絕安裝 NetBird Proxy 服務。它需要額外兩個 DNS 紀錄：proxy.netbird.example.com 與萬用字元 *.proxy.netbird.example.com，且對於單純的 mesh 網路並無幫助。同樣地，也請拒絕安裝 CrowdSec。這兩者皆可在日後視需求加入。

腳本會將檔案寫入當前目錄：docker-compose.yml、權限為 600 的 config.yaml、dashboard.env，以及選擇內建 Traefik 時產生的 traefik-dynamic.yaml。請將該目錄視為必須保留的狀態資料，因為 config.yaml 存放著加密儲存資料的金鑰。一旦遺失，重新安裝也無法修復。

docker compose ps
docker compose logs -f netbird-server

每個服務都應讀取 running，且伺服器日誌應趨於穩定，而非陷入重啟迴圈。請另外監控憑證狀態：

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) 是 Traefik 用於取得憑證的協定。此處若發生錯誤，通常是因為 DNS 設定問題或 80 埠未開啟。

建立第一個管理員帳號

開啟 https://netbird.example.com。全新安裝時，系統會導向設定頁面而非登入表單。輸入電子郵件地址、名稱與密碼，接著點擊 Create Account。該帳號即成為第一個管理員，隨後頁面會重新導向至登入表單。

此帳號儲存於 NetBird 內建的使用者儲存庫中，由 netbird-server 容器內嵌的身分識別提供者（Identity Provider）驅動，無需任何外部服務。這是自架版 NetBird 與一年前相比最大的變更；當時若要完成安裝，必須先架設 Zitadel 或 Keycloak，並將四個 OIDC (OpenID Connect) 數值複製到 setup.env 才能啟動。

若瀏覽器顯示憑證警告而非設定頁面，代表憑證未成功簽發。請務必在進行後續步驟前修復此問題，因為儀表板會透過相同的主機名稱與 API 通訊，若憑證異常，將導致連線失敗並產生難以排查的錯誤。

加入您的第一個節點

在任何 Linux 機器上安裝客戶端，若您希望將 VPS 本身納入網狀網路（mesh），也可以在該 VPS 上安裝：

curl -fsSL https://pkgs.netbird.io/install.sh | sh

在 Debian 與 Ubuntu 上，該腳本會設定 NetBird 的軟體套件庫，並透過 apt 安裝客戶端，因此軟體套件管理員會接管後續的維護。若您不希望直接將腳本導向至 shell 執行，請先使用 curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh 儲存檔案，並在執行 sh install.sh 前先行閱讀。無論採取何種方式，請確認安裝結果：

apt-cache policy netbird

netbird 是命令列客戶端與背景程式（daemon）。netbird-ui 是桌面系統匣應用程式，無頭伺服器（headless server）無需使用。

現在將客戶端指向您的伺服器：

sudo netbird up --management-url https://netbird.example.com

若省略 --management-url，客戶端會預設向 NetBird 的託管服務註冊，因為這是編譯時的預設值。該指令仍會執行成功，機器也會取得位址，但您的自架儀表板將保持空白。這是初學者最常遇到的陷阱。

該指令會顯示一個 URL，請在瀏覽器中開啟以完成登入。完成後：

netbird status
ip addr show wt0

從 netbird status 讀取四行資訊：Management: Connected、Signal: Connected、一行回報所有可用中繼節點的 Relays:，以及一個位於覆蓋網路（overlay）範圍內的 NetBird IP:。wt0 是 NetBird 建立的 WireGuard 介面，該介面應具備相同的位址。

使用 setup key 進行第二台機器的無人值守加入

若機器沒有瀏覽器且無人操作，則無法使用瀏覽器登入。setup key 是一種預先驗證權杖，可在無需互動步驟的情況下註冊機器。請在儀表板的 Setup Keys 頁面中建立此金鑰。

金鑰分為兩種。一次性金鑰僅能驗證一台機器，使用後即失效。可重複使用金鑰則可註冊多台機器，並可選擇設定註冊上限。兩者皆需設定過期時間，且皆可將新節點自動指派至特定群組，讓該群組的存取規則在機器出現時立即生效。

sudo netbird up --setup-key <SETUP-KEY> \
  --management-url https://netbird.example.com \
  --hostname build-runner-01

--hostname 可設定儀表板上顯示的名稱。若未設定，節點將會使用機器本身的名稱；若有一堆名稱皆為 ubuntu 的項目，將無法識別。

對於容器與短暫存在的建置代理程式，請在建立金鑰時將其標記為 ephemeral。使用 ephemeral 金鑰註冊的節點在離線超過 10 分鐘後會自動移除，這能避免節點清單中出現無效項目。

在規劃使用 setup key 前，請務必了解一項限制：過期或刪除金鑰僅會停止新的註冊，不會中斷已使用該金鑰註冊的機器。若要撤銷機器的存取權，必須移除該節點。

您是否仍需要獨立的身分提供者？

對於小型安裝而言，並不需要。內建的使用者儲存庫可處理從儀表板建立的帳號，這對少數使用者來說已足夠。

若您已有現成的身分提供者，且不想維護第二份使用者清單，則建議使用外部身分提供者。NetBird 支援任何採用 OIDC 協定的提供者。請在您的提供者中註冊一個機密型（confidential）OIDC 用戶端，接著在 NetBird 儀表板中填入四項數值：名稱、client ID、client secret 與 issuer。NetBird 會提供一組重新導向 URL，請將其貼回至提供者設定中。系統已針對 Google、Microsoft Entra ID、Okta、Zitadel、Keycloak、Authentik 與 Pocket ID 提供整合選項，其他服務則可透過通用 OIDC 方式設定。如果您已經部署了 Authentik 作為自架單一登入服務，這就是維持單一帳號清單的最佳途徑。

新增提供者後，本機登入功能依然有效，且所有已設定的提供者都會顯示在登入頁面上。請務必保留一個具備強密碼的本機管理員帳號。如此一來，即使 OIDC 設定發生錯誤，您仍有管道可以進入系統。

NetBird 或 Headscale：該執行哪種控制平面？

兩者皆移除了相同的依賴項目，即用戶端原本必須連線回報的託管控制伺服器。但這兩個專案的架構並不相同。

Headscale 重新實作了 Tailscale 控制伺服器，讓您能繼續使用官方的 Tailscale 用戶端。該專案並未提供官方網頁控制台。您需透過 headscale 指令針對設定檔來管理使用者與預先驗證金鑰。雖然社群開發了網頁介面，但它們並非專案的一部分。這適合偏好將狀態存於檔案中，並透過版本控制系統管理變更的使用者。

NetBird 則提供完整產品：包含自有的用戶端、儀表板、內建身分提供者，以及可在瀏覽器中編輯的存取原則。這意味著您的 VPS 上會有更多運作中的組件，但對於不習慣操作終端機的同事來說，這套方案的管理負擔遠低於前者。

若您已深度使用 Tailscale 用戶端，或希望控制平面越精簡越好，請選擇 Headscale。若有多人需要管理節點，且您希望在無需自行組裝的情況下擁有控制台與 SSO 功能，請選擇 NetBird。

此服務最小需要多小的 VPS？

文件記載的最低需求為 1 CPU 與 2 GB 記憶體。由於使用者管理已改為本地化，NetBird 官方說明目前的記憶體下限約為 1 GB；相較之下，舊架構因包含完整的 Zitadel 部署，需要 2 GB 至 4 GB。建議購買 2 GB 的規格。額外的空間能確保在升級時，系統能在舊映像檔尚未移除前下載新的映像檔。

在小型主機上，有三項功能可以捨棄。請拒絕安裝 NetBird Proxy 服務，該服務僅用於將內部服務發布至公開網域名稱，與節點間的連線無關。請拒絕安裝 CrowdSec，這類工具建議在日後有需要時再加入，而非第一天就部署。請保留 netbird_data 磁碟區中的預設 SQLite 儲存庫，僅在將部署分散至多台機器或遇到實際併發需求時，再遷移至 PostgreSQL；文件已說明這是一項日後可執行的遷移作業。

Relay 是唯一不能捨棄的元件。若兩個節點的 NAT 會為每個目的地分配不同的連接埠，它們將無法建立直接通道，此時 Relay 是讓它們連線的唯一途徑。停用 Relay 節省的記憶體極少，卻會導致難以追蹤的連線中斷問題。

當單台主機不敷使用時，Relay 是首個應移出的元件。獨立的 Relay 執行時需設定 NB_LISTEN_ADDRESS、NB_EXPOSED_ADDRESS、NB_AUTH_SECRET 與 NB_ENABLE_STUN。Relay 與主伺服器上的共用密鑰（shared secret）必須完全一致，否則用戶端將無法通過驗證。

故障模式與現象說明

儀表板顯示憑證警告。 Traefik 未能取得憑證。請執行 docker compose logs traefik | grep -i acme。原因有二：一是 dig +short netbird.example.com 尚未指向此 VPS，二是 TCP 80 埠在 Let's Encrypt 與容器之間被阻擋，通常是供應商的網路防火牆而非 ufw 所致。請先排除原因再重試，因為驗證失敗會觸發速率限制，導致您在一小時內無法再次嘗試。

客戶端顯示已連線，但儀表板為空。 客戶端註冊到了 NetBird 的託管服務，因為缺少了 --management-url。請執行 netbird status --detail 並查看 Management: 行，該行會顯示實際連線的伺服器名稱。若看到 Management: Connected to https://api.netbird.io:443，代表連線到了雲端服務。請執行 sudo netbird down，然後再次執行 sudo netbird up --management-url https://netbird.example.com。

所有節點均顯示 Connection type: Relayed。 這代表無法建立直接通道，所有流量皆須經過您的 VPS，導致延遲增加。請檢查 VPS 防火牆與供應商防火牆的 UDP 3478 埠，因為 STUN 是讓節點獲取自身公用 IP 與埠的關鍵。netbird status --detail 也會輸出 Direct: false 以及每個節點的 ICE (interactive connectivity establishment) 候選類型，藉此判斷連線嘗試的進度。在某些網路環境下，relayed 是唯一可行的結果，這並不代表系統有誤。

節點加入後無法存取任何資源。 加入網狀網路並不代表節點間即可通訊。存取政策決定了通訊權限，未綁定政策的群組將無法存取任何資源。在開始除錯路由與防火牆之前，請先檢查儀表板中的政策設定。

netbird status 回報 daemon 問題。 服務未執行。請使用 sudo netbird service status 與 sudo netbird service start。客戶端日誌位於 /var/log/netbird/client.log。若遇到無法定位的問題，netbird debug bundle --anonymize --system-info 可將日誌、狀態、路由、DNS 設定與防火牆狀態收集至單一封存檔中。

備份與升級

整個安裝僅需依賴兩項內容：存放 docker-compose.yml 與 config.yaml 的目錄，以及存放資料庫與加密金鑰的 Docker volume。請務必將兩者一併備份。config.yaml 內含用於加密儲存資料的金鑰，若缺少此檔案，備份的資料庫將無法還原為可讀取的內容。

docker volume ls
docker compose down
sudo tar czf netbird-config.tgz -C ~ netbird
docker run --rm -v netbird_netbird_data:/data -v "$PWD":/backup \
  alpine tar czf /backup/netbird-data.tgz -C /data .
docker compose up -d

Compose 會在 volume 名稱前加上專案目錄作為前綴，因此文件中標示為 netbird_data 的 volume，實際名稱通常為 netbird_netbird_data。請先執行 docker volume ls 並使用其顯示的名稱，否則上述的 docker run 指令會因靜默建立空的 volume 而導致備份失敗。請將備份檔存放在 VPS 之外。若您已有備份工具，可使用 restic 或 BorgBackup 處理異地備份。

升級伺服器的方式為拉取映像檔並重新建立容器：

docker compose pull
docker compose up -d
docker compose ps

在執行升級前，請先執行 docker compose config | grep image:。任何標記為 latest 的 tag 都應鎖定特定版本，理由與鎖定安裝腳本相同：您需要明確掌握執行中的版本，並在升級發生異常時有版本可供回溯。客戶端程式則透過當初安裝時所使用的套件管理工具進行升級。

FAQ

自架 NetBird 是否需要自備身份提供者（Identity Provider）？

不需要。目前的版本已內建使用者儲存庫，您可以在瀏覽器 https://netbird.example.com 建立第一個管理員帳號，隨後即可從儀表板新增使用者。外部 OIDC 提供者為選用項目，日後可透過四項數值隨時加入：名稱、client ID、client secret 與 issuer。若教學文件要求在 NetBird 之前先部署 Zitadel 或 Keycloak，該設定方式已不再必要，且會導致您需額外維護一項服務。

為何所有節點都顯示 Connection type: Relayed？

因為無法建立直接連線，流量正透過您 VPS 上的中繼伺服器（relay）傳輸。常見原因是 UDP 3478 埠被封鎖，這是節點用來偵測自身公開位址與埠號的 STUN 埠。請在 VPS 防火牆及服務供應商的網路防火牆上開啟該埠，接著再次執行 netbird status --detail 並查看 Direct: 行。若網路的 NAT 會針對不同目的地指派不同埠號，則 relayed 即為唯一可能的結果，並非設定錯誤。

客戶端已連線，但儀表板未顯示任何節點，發生了什麼事？

客戶端註冊到了 NetBird 的託管服務，而非您的伺服器，這是因為遺漏了 --management-url 參數。netbird status --detail 會在 Management: 行顯示目前連線的伺服器，若數值為 https://api.netbird.io:443 則代表連線錯誤。請執行 sudo netbird down，接著執行 sudo netbird up --management-url https://netbird.example.com，節點即會出現在您的儀表板中。

自架 NetBird 與 Headscale 有何不同？

兩者皆可取代託管控制伺服器，改為自行運作。Headscale 僅提供控制平面：您需透過 headscale 指令與設定檔進行管理，且沒有官方網頁控制台，並驅動官方的 Tailscale 客戶端。NetBird 則在同一套堆疊中提供專屬客戶端、管理儀表板與身份提供者整合。Headscale 運作資源需求較低且以檔案儲存狀態；NetBird 則更適合提供給不熟悉終端機操作的使用者。

自架 NetBird 伺服器需要多大規格的 VPS？

官方文件建議的最低規格為 1 CPU 與 2 GB 記憶體，請準備 2 GB 記憶體。由於身份提供者現已內建而非獨立部署，近期版本的實際運作門檻已降至約 1 GB。安裝時可選擇不啟用選配的 proxy 與 CrowdSec 服務，並維持預設的 SQLite 儲存庫，直到您確實有使用 PostgreSQL 的需求為止。