如何自架 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 acmeACME(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 netbirdnetbird 是命令列客戶端與背景服務(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 -dCompose 會在 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 儲存區。