SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

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

在 VPS 上自架 NetBird VPN 控制平面。本文涵蓋 v0.76.2 快速啟動腳本、TLS 與 DNS 設定、Setup Keys 自動化部署,並分析其與 Headscale 的架構差異,協助您評估自架效益。

自架 NetBird VPN 伺服器的優勢

自架 NetBird VPN 伺服器意味著將控制平面(Control Plane)部署在您擁有的 VPS 上。該組件負責維護節點清單、決定節點間的存取權限,並協助兩個節點在 NAT(網路位址轉譯)後建立連線。隧道本身仍採用 WireGuard 技術,流量直接在您的機器間加密傳輸。此舉的差異在於,沒有外部公司能掌握您的裝置清單或登入流程。請務必釐清這帶來的實際效益,因為託管式控制平面同樣無法取得加密您流量的密鑰,且 協調伺服器遭入侵時的實際影響 範圍,通常比多數人在閱讀前所預想的還要小。

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

若您的需求僅是將所有流量導向單一伺服器出口,網狀網路的架構將顯得過於複雜。在單一 VPS 上架設純 WireGuard VPN 或 使用 Tailscale 出口節點(Exit Node) 即可達成,且維護成本更低。若目標僅是存取單一私有網路,而非將多台機器互連,在 VPS 上部署 Tailscale 子網路由器(Subnet Router) 即可將該網段廣播至現有的 tailnet,無須建置下方所述的完整堆疊。

實際執行的元件

版面最近有所變更,多數較早的說明仍在介紹舊版架構。本節於 2026 年 10 月針對 v0.80.0,以及本指南鎖定的版本 v0.76.2 進行確認。快速入門指令碼預設會建立包含 3 個服務的 Compose 檔案。

  • netbird-server 提供管理 API、signal service、內嵌 STUN listener 的 relay,以及內嵌的 identity provider。較舊版本會將這些元件分成不同容器,且必須先自行建置獨立的 Zitadel 安裝。
  • dashboard 是管理員網頁主控台。
  • traefik 終止 TLS(transport layer security),並在首次啟動時向 Let's Encrypt 申請憑證。

另外還有 2 個服務。除非在提示中選擇啟用,否則這些服務會維持停用。NetBird Proxy service 會以公開主機名稱發布內部服務。CrowdSec 會過濾濫用流量。建立可運作的 mesh 不需要這 2 個服務,而且在小型主機上會增加記憶體用量。

如果你是從 單一 Docker 容器中的 wg-easy 遷移而來,元件數量會明顯增加。這換來的是存取政策、每位使用者各自的帳戶,以及彼此直接連線而非透過單一 gateway 的 peers。

開始前的必要條件

公開網域名稱不是選用項目。儀表板、API 與 relay 都透過 HTTPS 使用 443 埠,Traefik 也會使用 TLS-ALPN-01 challenge 從 Let's Encrypt 取得憑證。該 challenge 會在 443 埠回應,因此需要一個可從公開網際網路解析到此 VPS 的名稱。此流程不支援直接使用 IP 位址。

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

dig +short netbird.example.com

該指令必須輸出伺服器的位址。若 DNS 尚未傳播就執行安裝程式,憑證要求會在首次啟動時失敗。反覆驗證失敗也會觸發 Let's Encrypt 的速率限制,之後必須等待限制解除才能再次嘗試。

預設設定只需要讓網際網路可連線到 2 個埠:TCP 443,用於儀表板、API、signal、relay 流量及憑證 challenge;UDP 3478,用於 STUN。TCP 80 必須在本機保持可用,因為 Traefik 會繫結該埠,但不需要對公開網際網路開放。封鎖對外的 80 埠只會使 HTTP-to-HTTPS redirect 無法運作。

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)可讓對等端得知自身 NAT 指派的公開位址與埠,讓兩個對等端嘗試建立直接 tunnel。封鎖 UDP 3478 後,對等端仍可透過 TCP 443 上的 relay 連線,因此表面上不會出現明顯故障。無法找到直接路徑的對等端會顯示 Connection type: Relayed,其流量會經過你的 VPS,而不是直接在對等端之間傳輸。同一個 LAN 上的對等端仍可使用本機位址直接連線。

軟體方面需要安裝 Docker 與 Compose v2 plugin,另外還需要 jq 和 curl。此腳本會檢查 Docker、Compose 與 jq,缺少其中任何一項就會停止。腳本會直接使用 curl,不會檢查它是否存在,因此請先安裝。若 Docker 剛安裝在此伺服器上,請先完成 在 VPS 上讓 Docker Compose 正常運作。

略過內建反向代理時的埠

沒有 Traefik 時,整合式伺服器仍會在同一個 HTTP backend 上承載管理、signal 與 relay,因此埠清單幾乎不會增加。產生的 Compose 檔案會發布:

  • TCP 8080,儀表板,預設繫結至 127.0.0.1
  • TCP 8081,netbird-server,預設繫結至 127.0.0.1
  • UDP 3478,STUN,直接發布

你自行管理的 proxy 會在 TCP 443 終止 TLS,並轉送至這 2 個本機埠。STUN 不會經過 proxy,因此無論是否使用 proxy,UDP 3478 都必須在防火牆中保持開放。列出管理 gRPC、signal gRPC 與 relay 個別埠的指南,描述的是較舊的多容器架構。

只有在伺服器已為其他服務終止 TLS 時,才選擇此方式。否則,內建 Traefik 需要的規則較少,也較不容易設定錯誤。

使用快速入門指令碼安裝 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 到 4 會寫入設定片段,並由你自行完成整合;選項 5 會寫入 Compose 檔案、dashboard.env 和 config.yaml,並將設定文件輸出到終端機。若該主機已執行 proxy,這樣的設定是正確的;若是全新的主機,則不適用。選項 0 接著會要求輸入電子郵件地址,Traefik 會使用該地址向你的 Let's Encrypt 帳戶註冊。提示仍稱這是用於憑證通知的地址,但 Let's Encrypt 已於 June 4, 2025 停止寄送到期通知,因此續期問題會出現在 Traefik log 中,而不是收件匣。

首次安裝時,請不要啟用 NetBird Proxy service。它需要額外的 DNS 紀錄,也就是指向 netbird.example.com 的萬用字元 *.netbird.example.com CNAME;對一般 mesh 沒有作用。只有啟用 proxy 後才會出現 CrowdSec 提示,因此拒絕 proxy 也會略過 CrowdSec。兩者之後都可以再加入。

指令碼會在目前目錄寫入:docker-compose.yml、權限模式為 600 的 config.yaml,以及 dashboard.env。使用內建 Traefik 時,只有在啟用 NetBird Proxy 後,才會加入 traefik-dynamic.yaml 和 proxy.env。請將該目錄視為需要保留的狀態資料,因為 config.yaml 存放用於加密資料儲存區的金鑰。遺失該金鑰不是重新安裝可以修復的問題。

docker compose ps
docker compose logs -f netbird-server

每個服務都應讀取 running,而且伺服器 log 應停止反覆重新啟動。請另外監控憑證:

docker compose logs traefik | grep -i acme

ACME(automatic certificate management environment)是 Traefik 用來取得憑證的通訊協定。這裡的錯誤幾乎都與 DNS 或 443 埠遭封鎖有關。

建立第一個管理員帳號

開啟 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)伺服器無需使用。

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

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 是預先驗證 token,可在不需要互動操作的情況下註冊機器。請在 dashboard 的 Settings → Setup Keys 中建立 setup key。

setup key 有兩種類型。一次性 setup key 只會驗證一台機器,使用後即失效。可重複使用的 setup key 可註冊多台機器,也可選擇設定數量上限。兩種類型都可選擇設定到期時間,也都能在新 peer 加入時自動將其指派至群組,因此該群組的存取規則會在機器出現後立即套用。

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

--hostname 會設定 dashboard 中顯示的名稱。未設定時,peer 會使用機器自行回報的名稱;如果整個機器群組的項目都顯示為 ubuntu,將無助於辨識。

對於容器與短期使用的建置代理程式,建立 setup key 時請將其標記為 ephemeral。使用 ephemeral setup key 註冊的 peer,在離線超過 10 minutes 後會自動移除,避免已失效的項目留在 peer 清單中。

在規劃使用 setup key 前,請先了解一項限制:setup key 到期或遭撤銷後,只會停止新的註冊,不會中斷已使用該 setup key 完成註冊的機器。若要移除機器的存取權,必須移除該 peer。

是否仍需要獨立的身分識別提供者?

對於小型安裝,不需要。內建使用者儲存區可管理從儀表板建立的帳戶,幾位使用者已足夠。

如果你已經有外部身分識別提供者,且不想維護第二份使用者清單,就應使用該提供者。NetBird 接受任何支援 OIDC 的提供者。先在提供者中註冊 confidential OIDC client,再於 NetBird 儀表板中新增整合,填入名稱、client ID、client secret,以及必要時的 issuer。NetBird 會提供 redirect URL,讓你貼回提供者的設定中。系統提供 Google、Microsoft Entra ID、Okta、Zitadel、Keycloak、Authentik 和 Pocket ID 的命名整合;其他提供者則使用一般 OIDC 設定。如果你已經執行 Authentik 作為自架的單一登入服務,採用這個方式即可維持一份帳戶清單,不必分成兩份。

新增提供者後,本機登入仍可使用,所有已設定的提供者都會顯示在登入頁面。保留一個使用強密碼的本機管理員帳戶。如此一來,即使 OIDC 設定損壞,你仍有登入方式。

NetBird 或 Headscale:應該執行哪個控制平面?

兩者都能移除同一項相依性,也就是原本由用戶端連回的代管控制伺服器。但兩者的專案定位不同。

Headscale 重新實作 Tailscale 控制伺服器,而您仍使用官方 Tailscale 用戶端。它沒有官方 Web 主控台。您需使用 headscale 命令,搭配設定檔管理使用者與預先驗證金鑰。社群提供 Web 介面,但這些介面不屬於該專案。對於希望將狀態儲存在檔案中,並透過版本控制管理變更的人來說,這種方式較合適。

NetBird 整套產品都由自身提供:包括專用 client、專用 dashboard、內嵌的 identity provider,以及可在瀏覽器中編輯的存取政策。這會在 VPS 上增加更多組件;對於永遠不會開啟終端機的同事而言,交由他們操作也會容易得多。如果你實際上是在 NetBird 與託管式 Tailscale 之間評估,而不是拿它與 Headscale 比較,兩者底層都使用 WireGuard,因此NetBird 與 Tailscale 的比較會說明兩者真正的差異:誰負責執行 control plane、如何撰寫存取規則,以及 relay 如何承載網路流量。

如果您已投入使用 Tailscale 用戶端,或希望控制平面儘可能精簡,請選擇 Headscale。如果多人需要管理對等節點,且您希望直接取得主控台與 SSO,而不必自行組裝,請選擇 NetBird。在決定前,請先確認Tailscale 免費方案實際涵蓋的內容,因為符合條件且不具商業用途的群組,在 6 位使用者以內可免費使用代管控制平面,起始即提供不限數量的使用者裝置與 50 個標記資源,因此可能根本不需要自行執行控制平面。超過這個上限後,費用會依人數而非機器數量增加,因此計算 Tailscale 對您的群組收取的費用,即可將這個金額與 VPS 成本及維護此堆疊所需的工時進行比較。

這項服務需要多小的 VPS 才能執行?

文件記載的最低需求是 1 個 CPU 和 2 GB 記憶體。請購買 2 GB 的方案。

在資源有限的主機上,有 3 個項目可以安全省略。不要啟用 NetBird Proxy 服務。這項服務用於透過公開主機名稱發布內部服務,與對等端連線無關。略過 CrowdSec。安裝腳本只會在提供 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 與主伺服器上的共享密鑰必須完全相同,否則用戶端無法向 relay 完成驗證。

失效情況與可見現象

儀表板顯示憑證警告。 Traefik 未取得憑證。執行 docker compose logs traefik | grep -i acme。原因有兩種。可能是 dig +short netbird.example.com 尚未解析至這台 VPS,也可能是 TCP 443 在 Let's Encrypt 與容器之間的某處遭到關閉,通常是供應商的網路防火牆,而不是 ufw。挑戰會在 443 上回應,因此開放連接埠 80 無法解決問題。修正原因後再重試,不要持續循環重試,因為 Let's Encrypt 每個帳戶的每個主機名稱每小時只允許 5 次失敗的授權嘗試。超過限制後,必須等候額度恢復才能再次嘗試。

用戶端表示已連線,但儀表板是空的。 用戶端已向 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 會讓對等端得知自己的公開位址與連接埠。netbird status --detail 也會列出 Direct: false,以及每個對等端的 ICE(互動式連線建立)候選類型。這可顯示連線嘗試進行到哪個階段。在某些網路上,轉送是唯一可用的結果,這不代表發生錯誤。

對等端加入後無法連線至任何內容。 加入網狀網路不代表兩個對等端可以互相通訊。存取政策會決定是否允許通訊,而未套用任何政策的群組無法連線至任何內容。開始排查路由與防火牆前,先在儀表板檢查政策。

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 存放用來加密儲存區敏感資料的金鑰,因此沒有它的資料庫副本無法還原已加密的設定金鑰與 API token。

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 都應固定為特定版本。理由與固定安裝腳本版本相同:您需要知道目前執行的版本,並在升級發生問題時,能夠退回至指定版本。Client 會透過安裝它們時使用的套件管理員進行升級。

FAQ

我需要自行架設身分提供者,才能自架 NetBird 嗎?

不需要。目前的版本已內建使用者儲存區,因此您可以在瀏覽器中於 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 命令和設定檔管理它,沒有官方 Web 主控台,並且會驅動官方 Tailscale 用戶端。NetBird 在同一套堆疊中提供自有用戶端、管理主控台及身分提供者整合。Headscale 較容易執行,並將狀態保存在檔案中。NetBird 則較適合提供給不使用終端機的人員。

自架 NetBird 伺服器需要多大規模的 VPS?

文件記載的最低需求是 1 CPU 和 2 GB 記憶體,建議購買 2 GB 的方案。安裝期間請略過選用的 proxy 服務,這也會略過 CrowdSec 提示。在確實需要 PostgreSQL 之前,請維持使用預設的 SQLite 儲存區。

這篇文章對您有幫助嗎?