NetBird VPN 서버 직접 호스팅 및 VPS 구축 가이드

NetBird VPN 서버를 직접 호스팅할 때의 이점

NetBird VPN 서버를 직접 호스팅하면 제어 평면(control plane)을 사용자가 소유한 VPS에 둘 수 있습니다. 제어 평면은 피어 목록을 유지하고, 어떤 장치가 어디에 접속할 수 있는지 결정하며, NAT(network address translation) 환경 뒤에 있는 두 피어가 서로를 찾을 수 있도록 돕는 역할을 합니다. 터널 자체는 여전히 WireGuard를 사용하며, 장치 간에 직접 암호화됩니다. 달라지는 점은 외부 기업이 사용자의 장치 목록이나 로그인 흐름을 보관하지 않는다는 것입니다.

NetBird는 이미 알고 있을 법한 두 가지 개념 사이에 위치합니다. 이는 메시 오버레이(mesh overlay) 방식이므로, 모든 트래픽을 하나의 게이트웨이로 보내는 대신 피어들이 서로 직접 연결됩니다. 또한 처음부터 끝까지 직접 호스팅이 가능하며, 이는 Headscale, 직접 호스팅하는 Tailscale 제어 서버와 비교되는 지점입니다. 단일 게이트웨이 터널만 운영해 보았다면, 먼저 일반 WireGuard와 메시 오버레이의 차이를 읽어보시기 바랍니다. 해당 개념을 이해해야 이 페이지의 나머지 내용을 유용하게 활용할 수 있습니다.

만약 모든 트래픽이 나가는 단일 서버를 원한다면, 메시 방식은 작업 규모에 비해 너무 복잡합니다. 단일 VPS에서의 일반 WireGuard VPN이나 Tailscale exit node를 사용하는 것이 훨씬 적은 운영 부담으로 동일한 기능을 수행합니다.

실제 실행되는 스택 구성

최근 레이아웃이 변경되어 기존의 많은 가이드가 구식 정보를 담고 있습니다. 2026년 8월 기준, v0.76.2 릴리스부터 퀵스타트 스크립트는 기본적으로 3개의 서비스가 포함된 Compose 파일을 생성합니다.

• netbird-server는 관리 API, 신호(signal) 서비스, 내장 STUN 리스너가 포함된 릴레이, 그리고 내장 ID 공급자를 담당합니다. 이전 릴리스에서는 이들이 별도의 컨테이너였으며, ID 공급자는 먼저 빌드해야 하는 별도의 Zitadel 설치본이었습니다.
• dashboard은 관리자 웹 콘솔입니다.
• traefik은 TLS(전송 계층 보안)를 종료하며, 최초 시작 시 Let's Encrypt에 인증서를 요청합니다.

프롬프트에서 승인하지 않는 한 기본적으로 꺼져 있는 서비스가 2개 더 있습니다. NetBird Proxy 서비스는 내부 서비스를 공용 호스트명으로 게시하며, CrowdSec은 악성 트래픽을 필터링합니다. 둘 다 작동하는 메시 네트워크를 구축하는 데 필수적이지 않으며, 소형 장비에서는 메모리를 소모합니다.

단일 Docker 컨테이너 기반의 wg-easy에서 전환하는 경우, 구성 요소 수가 늘어난 것처럼 보일 수 있습니다. 하지만 이를 통해 접근 정책, 사용자별 계정, 그리고 하나의 게이트웨이를 거치지 않고 피어끼리 직접 연결되는 기능을 얻게 됩니다.

시작하기 전에 필요한 사항

공용 도메인 이름은 필수입니다. 대시보드, API, 릴레이는 모두 443 포트에서 HTTPS를 사용하며, Traefik은 HTTP 챌린지를 통해 Let's Encrypt에서 인증서를 발급받습니다. 이를 위해서는 공용 인터넷에서 해당 VPS로 연결되는 도메인 이름이 필요합니다. 단순히 IP 주소만으로는 이 과정을 진행할 수 없습니다.

VPS의 공용 IPv4 주소를 가리키는 A 레코드를 하나 생성하고, netbird.example.com 명령을 실행하여 도메인이 정상적으로 연결될 때까지 기다리십시오.

dig +short netbird.example.com

위 명령은 서버의 주소를 출력해야 합니다. DNS가 전파되기 전에 설치 프로그램을 실행하면 첫 시작 시 인증서 요청이 실패합니다. 검증 실패가 반복되면 Let's Encrypt의 속도 제한(rate limit)에 걸려 1시간 동안 재시도를 할 수 없게 됩니다.

인터넷에서 다음 세 가지 포트에 접근할 수 있어야 합니다. 인증서 챌린지 및 HTTPS 리다이렉트를 위한 TCP 80, 대시보드·API·시그널·릴레이 트래픽을 위한 TCP 443, 그리고 STUN을 위한 UDP 3478입니다.

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)은 피어가 자신의 NAT가 할당한 공용 주소와 포트를 파악하여 피어 간 직접 터널을 생성할 수 있게 하는 기술입니다. UDP 3478 포트를 차단해도 피어들은 TCP 443의 릴레이를 통해 연결되므로 겉으로는 문제가 없어 보입니다. 하지만 모든 피어에서 Connection type: Relayed 상태가 나타나며, 모든 트래픽이 피어 간 직접 통신이 아닌 VPS를 거치게 됩니다.

소프트웨어 측면에서는 Compose v2 플러그인이 포함된 Docker와 jq, curl가 필요합니다. 설치 스크립트는 이들의 설치 여부를 확인하며, 하나라도 누락되면 중단됩니다. 서버에 Docker를 처음 설치한다면 먼저 VPS에서 Docker Compose 설정하기를 진행하십시오.

퀵스타트 스크립트로 NetBird 서버 설치하기

문서화된 한 줄짜리 명령어는 최신 릴리스를 셸로 바로 파이프합니다.

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

대신 버전을 고정하십시오. latest은 계속 변경되므로, 2주 간격으로 같은 명령어를 실행하면 서로 다른 버전이 설치되며 디스크 어디에도 어떤 버전이 설정을 작성했는지 기록되지 않습니다. 태그가 지정된 릴리스를 다운로드하여 내용을 확인한 뒤 실행하십시오.

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 서비스 사용을 거부하십시오. 이 서비스는 proxy.netbird.example.com와 와일드카드 *.proxy.netbird.example.com이라는 두 개의 DNS 레코드를 추가로 요구하며, 단순 메시(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-server 컨테이너에 내장된 ID 공급자가 관리하는 NetBird 자체 사용자 저장소에 생성됩니다. 외부 서비스는 관여하지 않습니다. 이는 1년 전 NetBird를 직접 호스팅하던 방식에서 가장 크게 바뀐 점입니다. 당시에는 설치를 시작하기 전에 Zitadel이나 Keycloak을 먼저 구축하고 4개의 OIDC(OpenID Connect) 값을 setup.env에 복사해 넣어야 했습니다.

설정 페이지 대신 브라우저 인증서 경고가 나타난다면 인증서가 발급되지 않은 것입니다. 이 문제를 먼저 해결하십시오. 대시보드는 동일한 호스트네임을 통해 API와 통신하므로, 잘못된 인증서가 적용된 상태에서는 알 수 없는 오류가 발생하며 정상적으로 작동하지 않습니다.

첫 번째 피어 연결하기

메시 네트워크에 포함하고 싶다면 VPS 자체를 포함하여, 모든 Linux 머신에 클라이언트를 설치합니다.

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

Debian 및 Ubuntu에서 해당 스크립트는 NetBird의 패키지 저장소를 구성한 뒤 apt를 통해 클라이언트를 설치하므로, 결과적으로 패키지 관리자가 설치를 관리하게 됩니다. 스크립트를 셸로 바로 전달하는 방식이 꺼려진다면 curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh으로 먼저 저장한 뒤 내용을 확인하고 sh install.sh로 실행하십시오. 어떤 방식이든 설치 결과를 확인합니다.

apt-cache policy netbird

netbird은 명령줄 클라이언트이자 데몬입니다. netbird-ui는 데스크톱 트레이 앱이며, 헤드리스 서버에서는 사용할 필요가 없습니다.

이제 클라이언트가 서버를 가리키도록 설정합니다.

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: 라인, 그리고 오버레이 범위 내의 NetBird IP:가 출력되어야 합니다. wt0은 NetBird가 생성하는 WireGuard 인터페이스이며, 동일한 주소를 가지고 있어야 합니다.

설정 키를 사용하여 두 번째 머신을 무인으로 연결하기

브라우저가 없거나 사용자가 직접 조작할 수 없는 환경에서는 브라우저 로그인을 사용할 수 없습니다. 설정 키(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분 이상 지속되면 자동으로 삭제되므로, 피어 목록에 죽은 항목이 쌓이지 않게 관리할 수 있습니다.

설정 키를 활용하기 전에 이해해야 할 한 가지 제한 사항이 있습니다. 키를 만료시키거나 삭제하면 새로운 등록은 차단되지만, 이미 해당 키로 등록된 머신들의 연결이 끊기지는 않습니다. 머신의 접근 권한을 제거하려면 해당 피어 자체를 삭제해야 합니다.

별도의 ID 공급자가 여전히 필요한가요?

소규모 설치 환경이라면 필요하지 않습니다. 내장된 사용자 저장소가 대시보드에서 생성된 계정을 처리하며, 소수의 인원에게는 이것으로 충분합니다.

이미 외부 ID 공급자를 사용 중이고 사용자 목록을 이중으로 관리하고 싶지 않다면 외부 ID 공급자가 필요합니다. NetBird는 OIDC를 지원하는 모든 공급자를 수용합니다. 공급자에 confidential OIDC 클라이언트를 등록한 다음, NetBird 대시보드에서 이름(name), 클라이언트 ID(client ID), 클라이언트 시크릿(client secret), 발행자(issuer) 등 4가지 값을 입력하여 추가하십시오. NetBird가 제공하는 리다이렉트 URL을 공급자 설정에 붙여넣으면 됩니다. Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik, Pocket ID에 대해서는 전용 통합 설정이 존재하며, 그 외의 서비스는 일반 OIDC로 등록할 수 있습니다. 이미 자체 호스팅 SSO로 Authentik을 운영 중이라면, 이 방식을 통해 계정 목록을 하나로 통합하여 관리할 수 있습니다.

공급자를 추가한 후에도 로컬 로그인은 계속 사용할 수 있으며, 설정된 모든 공급자가 로그인 페이지에 표시됩니다. 강력한 암호를 설정한 로컬 관리자 계정을 하나 유지하십시오. OIDC 설정에 문제가 생기더라도 해당 계정을 통해 시스템에 접근할 수 있습니다.

NetBird와 Headscale: 어떤 컨트롤 플레인을 운영해야 할까?

두 프로젝트 모두 클라이언트가 외부로 통신해야 하는 호스팅된 컨트롤 서버에 대한 의존성을 제거한다는 점은 같습니다. 하지만 두 프로젝트의 성격은 다릅니다.

Headscale은 Tailscale 컨트롤 서버를 재구현한 것으로, 공식 Tailscale 클라이언트를 그대로 사용합니다. 공식 웹 콘솔은 제공하지 않습니다. 사용자 및 사전 인증 키는 설정 파일을 대상으로 headscale 명령을 사용하여 관리합니다. 커뮤니티에서 만든 웹 인터페이스가 존재하지만, 이는 프로젝트의 일부가 아닙니다. 상태를 파일로 관리하고 변경 사항을 버전 관리 시스템으로 추적하려는 사용자에게 적합합니다.

NetBird는 자체 클라이언트, 자체 대시보드, 내장 ID 공급자, 브라우저에서 편집 가능한 접근 정책 등 제품 전체를 제공합니다. VPS에서 관리해야 할 구성 요소가 더 많지만, 터미널을 사용하지 않는 동료에게 업무를 위임할 때는 훨씬 수월합니다.

이미 Tailscale 클라이언트를 사용 중이거나 가장 가벼운 컨트롤 플레인을 원한다면 Headscale을 선택하십시오. 여러 사람이 피어를 관리해야 하고, 별도의 조립 과정 없이 콘솔과 SSO를 사용하고 싶다면 NetBird를 선택하십시오.

이 서비스를 운영하기 위한 최소 VPS 사양은 어느 정도입니까?

문서화된 최소 사양은 1 CPU와 2 GB 메모리입니다. 사용자 관리가 로컬에서 이루어지게 되면서, 과거 Zitadel 전체 배포가 필요했던 시절의 2 GB~4 GB 요구 사양과 달리 현재 NetBird의 자체 권장 사양은 1 GB RAM 수준까지 낮아졌습니다. 2 GB 사양을 구매하십시오. 여유 공간이 있어야 기존 이미지가 디스크에 남아 있는 상태에서 업그레이드를 통해 새 이미지를 내려받을 수 있습니다.

소규모 장비에서는 다음 세 가지를 제외해도 안전합니다. 내부 서비스를 공개 호스트네임으로 게시하는 용도이며 피어 연결과는 무관한 NetBird Proxy 서비스는 제외하십시오. CrowdSec은 첫날부터 설치하기보다 나중에 노출된 장비에 추가하는 것이 좋습니다. 기본 SQLite 저장소를 netbird_data 볼륨에 유지하고, 배포를 여러 장비로 분산하거나 실제 동시 접속 부하가 발생할 때 PostgreSQL로 이전하십시오. 이는 나중에 수행할 수 있는 마이그레이션으로 문서화되어 있습니다.

릴레이(relay)는 제외할 수 없는 유일한 구성 요소입니다. NAT가 목적지마다 서로 다른 포트를 할당하는 두 피어는 직접 터널을 생성할 수 없으므로, 릴레이만이 유일한 연결 경로가 됩니다. 릴레이를 비활성화해도 메모리 절약 효과는 미미하며, 추적하기 어려운 연결 오류를 유발합니다.

한 대의 장비로 부족해지면 릴레이를 가장 먼저 분리하십시오. 독립형 릴레이는 NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET 및 NB_ENABLE_STUN를 사용하여 실행됩니다. 공유 비밀값(shared secret)은 릴레이와 메인 서버에서 동일해야 하며, 그렇지 않으면 클라이언트 인증이 실패합니다.

실패 유형 및 확인 사항

대시보드에 인증서 경고가 표시됩니다. Traefik이 인증서를 획득하지 못했습니다. docker compose logs traefik | grep -i acme를 실행하십시오. 원인은 두 가지입니다. dig +short netbird.example.com이 아직 이 VPS를 가리키지 않거나, Let's Encrypt와 컨테이너 사이 어딘가에서 TCP 80 포트가 닫혀 있는 경우입니다. 후자는 보통 ufw 내부가 아니라 제공업체의 네트워크 방화벽에서 발생합니다. 검증 실패 시 속도 제한(rate limit)이 적용되어 한 시간 동안 재시도가 차단되므로, 반복해서 시도하기 전에 원인을 먼저 해결하십시오.

클라이언트는 연결되었다고 하지만 대시보드가 비어 있습니다. --management-url 설정이 누락되어 클라이언트가 NetBird의 호스팅 서비스에 등록되었습니다. 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 연결만 가능하며, 이 경우 정상적인 상태일 수 있습니다.

피어가 참여했지만 아무것도 연결할 수 없습니다. 메쉬 네트워크에 포함되었다고 해서 모든 피어 간 통신이 가능한 것은 아닙니다. 접근 정책(Access policies)에 따라 결정되며, 정책이 할당되지 않은 그룹은 아무것도 연결할 수 없습니다. 라우팅이나 방화벽을 디버깅하기 전에 대시보드에서 정책을 먼저 확인하십시오.

netbird status에서 데몬 문제가 보고됩니다. 서비스가 실행 중이지 않은 상태입니다. 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 볼륨입니다. 이 둘을 함께 백업하십시오. 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는 프로젝트 디렉터리 이름을 볼륨 이름 앞에 접두사로 붙입니다. 따라서 netbird_data로 문서화된 볼륨은 보통 netbird_netbird_data으로 나타납니다. 먼저 docker volume ls을 실행하여 출력되는 이름을 확인하십시오. 그렇지 않으면 위의 docker run 명령이 빈 볼륨을 생성하고 아무것도 아카이빙하지 않은 채 종료될 수 있습니다. 아카이브는 VPS 외부에 보관하십시오. 이미 백업 도구를 사용 중이라면 restic 또는 BorgBackup을 사용하여 외부 저장소로 전송할 수 있습니다.

서버 업그레이드는 이미지를 내려받고 컨테이너를 다시 생성하는 과정으로 진행됩니다.

docker compose pull
docker compose up -d
docker compose ps

이 과정을 수행하기 전에 docker compose config | grep image:를 실행하십시오. latest으로 표시된 모든 태그는 특정 버전으로 고정해야 합니다. 설치 스크립트를 고정한 이유와 마찬가지로, 현재 실행 중인 버전을 명확히 파악하고 업그레이드 시 문제가 발생할 경우 이전 버전으로 즉시 복구하기 위함입니다. 클라이언트는 해당 패키지를 설치한 패키지 관리자를 통해 업그레이드합니다.

FAQ

NetBird를 직접 호스팅하려면 자체 ID 공급자가 필요한가요?

아니요. 현재 릴리스에는 내장 사용자 저장소가 포함되어 있습니다. 따라서 https://netbird.example.com에서 브라우저를 통해 첫 번째 관리자 계정을 생성한 다음, 대시보드에서 사용자를 추가하면 됩니다. 외부 OIDC 공급자는 선택 사항이며, 나중에 이름, client ID, client secret, issuer라는 네 가지 값을 사용하여 추가할 수 있습니다. NetBird를 배포하기 전에 Zitadel이나 Keycloak을 먼저 배포하라고 안내하는 가이드는 더 이상 필요하지 않은 설정을 설명하고 있으며, 이를 따르면 운영해야 할 서비스만 하나 더 늘어날 뿐입니다.

모든 피어(peer)가 Connection type: Relayed로 표시되는 이유는 무엇인가요?

직접 연결이 형성되지 않아 트래픽이 VPS의 릴레이를 거치고 있기 때문입니다. 일반적인 원인은 피어가 자신의 공인 IP 주소와 포트를 확인하는 데 사용하는 STUN 포트인 UDP 3478이 차단된 경우입니다. VPS 방화벽과 제공업체의 별도 네트워크 방화벽에서 해당 포트를 개방한 다음, netbird status --detail을 다시 실행하고 Direct: 줄을 확인하십시오. 목적지마다 다른 포트를 할당하는 NAT 네트워크 환경에서는 릴레이 연결이 유일한 결과이며, 설정이 잘못된 것이 아닙니다.

클라이언트는 연결되었는데 대시보드에 피어가 보이지 않습니다. 어떻게 된 일인가요?

클라이언트가 서버가 아닌 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은 제어 평면(control plane) 역할만 수행합니다. headscale 명령과 설정 파일로 관리하며 공식 웹 콘솔이 없고, 공식 Tailscale 클라이언트를 사용합니다. 반면 NetBird는 자체 클라이언트, 관리자 대시보드, ID 공급자 통합 기능을 하나의 스택으로 제공합니다. Headscale은 운영 리소스가 적고 상태를 파일로 관리합니다. NetBird는 터미널 사용에 익숙하지 않은 사용자에게 제공하기가 더 쉽습니다.

직접 호스팅하는 NetBird 서버에는 어느 정도 크기의 VPS가 필요한가요?

문서상 최소 사양은 CPU 1개와 메모리 2 GB이며, 2 GB를 선택하는 것이 좋습니다. 최근 릴리스에서는 ID 공급자가 별도 배포 방식에서 내장 방식으로 변경되어 실질적인 최소 사양은 약 1 GB까지 낮아졌습니다. 설치 과정에서 선택 사항인 프록시와 CrowdSec 서비스를 제외하고, PostgreSQL이 반드시 필요한 상황이 되기 전까지는 기본 SQLite 저장소를 사용하십시오.