가이드

작성자 Matt Connor 2026-08-13 · 업데이트됨 2026-08-16

VPS에서 UniFi 컨트롤러 설치 및 운영 가이드

Q: UniFi 컨트롤러는 자동 백업 파일을 어디에 저장합니까?

여기에서 사용하는 컨테이너 이미지에서는 /config/data/backup/autobackup에 저장됩니다. 이 경로는 호스트의 데이터 경로와 data/backup/autobackup으로 매핑되며, 버전과 타임스탬프가 포함된 .unf 파일 형태로 생성됩니다. 일부 초기 설치 시에는 autobackup 디렉터리가 존재하지 않을 수 있습니다. 이 경우 예약된 백업이 오류 보고 없이 아무것도 기록하지 않으므로, 일정을 설정한 다음 날 해당 디렉터리를 확인하고 비어 있다면 직접 생성하십시오. .unf에는 사이트 설정과 관리자 계정 정보가 포함되어 있으므로 반드시 VPS 외부로 복사해 두어야 합니다.

VPS에 UniFi Network Application을 호스팅하는 방법을 설명합니다. RAM 권장 사양, Docker와 MongoDB 설정, set-inform을 이용한 Layer 3 어돕션, 그리고 보안을 위해 차단해야 할 필수 포트 정보를 상세히 다룹니다.

VPS에서 UniFi 컨트롤러가 수행하는 역할

VPS상의 UniFi 컨트롤러는 관리 대상 사이트가 오프라인 상태가 되어도 계속 연결 가능한 단일 관리 서버입니다. 이 소프트웨어는 Ubiquiti의 UniFi Network Application으로, MongoDB 데이터베이스를 기반으로 동작하는 Java 프로그램입니다. 이 프로그램은 액세스 포인트와 스위치를 구성하고, 통계 데이터를 저장하며, 관리자 인터페이스를 제공합니다. 클라이언트의 네트워크 트래픽은 처리하지 않습니다.

마지막 지점이 컨트롤러의 위치를 결정합니다. 컨트롤러를 관리 대상 사무실 내부의 장비에 두면, 네트워크가 중단되는 즉시 네트워크를 진단할 도구도 함께 잃게 됩니다. 반면 고정된 공인 IP 주소를 가진 VPS에 두면, 컨트롤러는 계속 실행되면서 데이터를 수집하고 여러 사이트의 장치를 한곳에서 관리(adopt)할 수 있습니다. 이 서비스는 높은 연산 성능보다는 안정적인 가동 시간(uptime)이 중요합니다.

컨트롤러가 오프라인 상태가 되어도, 이미 설정이 적용된 액세스 포인트와 스위치는 트래픽을 정상적으로 전달합니다. 다만 대시보드와 통계 데이터는 확인할 수 없으며, 게스트 포털 로그인이나 컨트롤러를 RADIUS 서버로 사용하는 경우의 RADIUS(remote authentication dial-in user service)와 같이 컨트롤러가 실시간으로 필요한 기능은 사용할 수 없습니다. 클라이언트의 연결은 그대로 유지됩니다.

UniFi 컨트롤러에는 RAM이 얼마나 필요한가?

2 GB가 최소 사양이며 4 GB를 권장합니다. 한 서버에서 Java와 MongoDB라는 두 가지 메모리 소비자가 독립적으로 자원을 점유합니다.

Java 힙은 MEM_LIMIT에 의해 제한되며, 컨테이너 이미지는 기본적으로 1024 MB로 설정합니다. 나머지 절반은 MongoDB가 차지합니다. MongoDB의 WiredTiger 스토리지 엔진은 1 GB를 초과하는 RAM의 절반 또는 256 MB 중 더 큰 값을 캐시 크기로 잡습니다. 2 GB VPS 환경에서는 대략 512 MB의 캐시와 1 GB의 힙, JVM의 비힙(non-heap) 메모리, 그리고 운영체제 점유분이 합쳐집니다. 평소에는 문제가 없으나 부하가 몰리는 날에는 커널의 OOM(out-of-memory) 킬러가 두 프로세스 중 하나를 강제 종료합니다. 원인 불명의 재시작이 발생하면 dmesg -T | grep -i 'killed process'을 실행하여 해당 현상이 발생했는지 확인하십시오. 2 GB RAM을 사용 중이라면 스왑 파일을 추가해야 합니다.

CPU와 디스크 요구 사항은 높지 않습니다. vCPU 1~2개로 수십 대의 장치를 관리할 수 있습니다. 디스크는 20 GB로 시작하여 추이를 지켜보십시오. 데이터베이스 크기는 클라이언트 수와 통계 보관 기간에 따라 증가합니다. 컨트롤러만 단독으로 운영하면 4 GB 서버의 자원이 대부분 남습니다. 다른 서비스를 함께 운영할 계획이라면 해당 서비스의 요구 사양을 우선 고려하십시오. PhotoPrism과 Immich는 RAM 최소 요구 사양이 매우 다르며 두 서비스 모두 컨트롤러보다 더 많은 메모리를 요구합니다.

저가형 플랜에서 간과하기 쉬운 중요한 CPU 기능이 하나 있습니다.

grep -m1 -o avx /proc/cpuinfo

MongoDB 5.0 이상 버전은 x86_64 하드웨어에서 AVX(advanced vector extensions)를 지원해야 합니다. 위 명령어를 실행했을 때 아무런 결과가 출력되지 않으면, CPU가 지원하지 않는 명령어를 바이너리가 실행하려 하기 때문에 mongod가 시작 즉시 종료되고 컨테이너가 무한 재시작 루프에 빠집니다. 주로 구형 Intel Celeron이나 Pentium 호스트, 또는 게스트 OS에 CPU 플래그를 숨기는 하이퍼바이저 환경에서 발생합니다. MongoDB 4.4는 AVX를 요구하지 않으므로 유일한 대안이 될 수 있으나, 해당 버전은 업스트림에서 더 이상 패치를 제공하지 않습니다. 더 최신 CPU를 탑재한 호스트로 이전하는 것이 올바른 해결책입니다. ARM VPS에서는 AVX가 x86 명령어 세트이므로 이 문제가 발생하지 않으며, 두 이미지 모두 arm64 빌드를 제공합니다. 두 아키텍처 사이에서 고민 중이라면 ARM과 x86 VPS 플랜의 차이점을 가격 외적인 측면에서도 고려해야 합니다.

Docker Compose를 사용하여 UniFi Network Application 설치하기

Docker는 애플리케이션이 지원하는 특정 버전의 MongoDB를 고정하여 사용할 수 있게 해주므로, 배포판에서 제공하는 버전을 그대로 사용하는 것보다 예기치 않은 오류가 적습니다. 서버에 아직 Docker가 설치되지 않았다면 먼저 VPS에 Docker 설치하기를 진행하십시오.

mkdir -p ~/unifi/config ~/unifi/db
cd ~/unifi

애플리케이션이 로그인하려면 MongoDB에 사용자가 먼저 생성되어 있어야 합니다. 공식 MongoDB 이미지는 첫 실행 시 /docker-entrypoint-initdb.d에 있는 모든 스크립트를 실행합니다. 이 내용을 ~/unifi/init-mongo.sh로 저장하십시오:

#!/bin/bash
if which mongosh > /dev/null 2>&1; then
  mongo_init_bin='mongosh'
else
  mongo_init_bin='mongo'
fi
"${mongo_init_bin}" <<EOF
use ${MONGO_AUTHSOURCE}
db.auth("${MONGO_INITDB_ROOT_USERNAME}", "${MONGO_INITDB_ROOT_PASSWORD}")
db.createUser({
  user: "${MONGO_USER}",
  pwd: "${MONGO_PASS}",
  roles: [
    "clusterMonitor",
    { db: "${MONGO_DBNAME}", role: "dbOwner" },
    { db: "${MONGO_DBNAME}_stat", role: "dbOwner" },
    { db: "${MONGO_DBNAME}_audit", role: "dbOwner" },
    { db: "${MONGO_DBNAME}_restore", role: "dbOwner" }
  ]
})
EOF

이 스크립트는 데이터베이스 디렉터리가 비어 있을 때만 단 한 번 실행됩니다. 잘못된 비밀번호로 스택을 시작하면 사용자가 잘못된 비밀번호로 생성되며, 이후 compose 파일을 수정해도 스크립트는 다시 실행되지 않으므로 아무런 변화가 없습니다. 이 경우 애플리케이션 컨테이너는 MongoDB 인증 실패 로그를 출력하고 웹 인터페이스는 나타나지 않습니다. 새로 설치하는 상황이라면 스택을 중지하고 ~/unifi/db을 삭제한 뒤 다시 시작하는 것이 해결 방법입니다.

그런 다음 ~/unifi/compose.yaml을 작성하십시오:

services:
  unifi-db:
    image: docker.io/mongo:8.0
    container_name: unifi-db
    environment:
      - MONGO_INITDB_ROOT_USERNAME=root
      - MONGO_INITDB_ROOT_PASSWORD=change-this-root-password
      - MONGO_USER=unifi
      - MONGO_PASS=change-this-unifi-password
      - MONGO_DBNAME=unifi
      - MONGO_AUTHSOURCE=admin
    volumes:
      - ./db:/data/db
      - ./init-mongo.sh:/docker-entrypoint-initdb.d/init-mongo.sh:ro
    restart: unless-stopped

  unifi-network-application:
    image: lscr.io/linuxserver/unifi-network-application:10.5.67-ls141
    container_name: unifi-network-application
    depends_on:
      - unifi-db
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - MONGO_USER=unifi
      - MONGO_PASS=change-this-unifi-password
      - MONGO_HOST=unifi-db
      - MONGO_PORT=27017
      - MONGO_DBNAME=unifi
      - MONGO_AUTHSOURCE=admin
      - MEM_LIMIT=1024
      - MEM_STARTUP=1024
    volumes:
      - ./config:/config
    ports:
      - "8080:8080"
      - "3478:3478/udp"
      - "127.0.0.1:8443:8443"
    restart: unless-stopped

두 이미지 태그는 의도적으로 고정되어 있습니다. 10.5.67-ls141는 2026년 8월 기준 최신 애플리케이션 릴리스였으므로, 설치 시점에 이미지 릴리스 목록을 확인하여 최신 버전을 고정하십시오. 데이터베이스 태그는 더욱 중요합니다. MongoDB는 메이저 버전 간 데이터 파일을 자동으로 업그레이드하지 않으므로, mongo:latest을 사용하면 언젠가 새로운 메이저 버전이 내려받아져 기존 파일을 열지 못하고 재시작을 반복하게 됩니다. 메이저 버전을 고정하고 필요할 때 의도적으로 업데이트하십시오. UniFi Network 8.1 이상 버전은 MongoDB 3.6부터 7.0까지 지원하며, 9.0 버전부터는 MongoDB 8.0 지원이 추가되었습니다.

PUID와 PGID는 호스트의 실제 사용자와 일치해야 합니다. 그렇지 않으면 ./config 하위의 파일들이 쓰기 권한이 없는 사용자 소유로 생성됩니다. id을 실행하여 본인의 값을 확인하십시오. 컨테이너 이미지에서 PUID와 PGID가 작동하는 방식에서 설정 불일치 시 발생하는 문제를 다룹니다.

스택을 시작하고 로그를 확인하십시오:

docker compose up -d
docker compose ps
docker compose logs -f unifi-network-application

docker compose ps을 실행했을 때 두 컨테이너 모두 running 상태여야 합니다. unifi-db이 restarting 상태에서 멈춰 있다면 위에서 언급한 AVX 문제이거나 ./db의 권한 문제일 가능성이 큽니다. 로그가 안정되면 두 리스너를 확인하십시오:

curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8443/
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/inform

어떤 HTTP 상태 코드라도 출력된다면 리스너가 바인딩되어 응답하고 있다는 의미입니다. Connection refused이 출력된다면 애플리케이션이 여전히 시작 중이거나(첫 실행 시 소형 VPS에서는 1~2분 소요), 아예 시작되지 않은 것입니다.

관리자 인터페이스를 외부 노출 없이 접속하기

위 파일의 127.0.0.1에는 포트 8443이 게시되어 있으므로, VPS 외부에서는 관리자 인터페이스에 접근할 수 없습니다. 설정 마법사를 실행하려면 SSH를 통해 해당 포트를 포워딩하십시오.

ssh -L 8443:127.0.0.1:8443 you@vps.example.com

해당 세션을 열어둔 상태에서 https://127.0.0.1:8443로 접속하십시오. 인증서가 자체 서명된 방식이므로 브라우저에서 한 번 경고가 나타납니다. 관리자 계정을 생성하고 사이트 이름을 지정한 뒤, 장치 채택(device adoption)은 일단 건너뛰십시오.

SSH 터널은 관리자가 한 명일 때 적합합니다. 팀 단위로 운영한다면 VPS에 사설 주소를 부여하고 해당 인터페이스에 바인딩하십시오. 직접 구축한 VPS의 WireGuard VPN이나 Tailscale 서브넷 라우터를 사용하면 팀원들만 접근 가능한 주소를 얻을 수 있습니다. 게시된 포트를 WireGuard의 경우 10.8.0.1:8443:8443으로, 또는 Tailscale이 할당한 주소로 변경하십시오. 한 가지 주의할 점은 Docker는 존재하지 않는 주소에는 포트를 게시할 수 없다는 것입니다. 따라서 컨테이너가 시작되기 전에 터널 인터페이스가 먼저 활성화되어야 하며, 그렇지 않으면 컨테이너가 바인딩 오류로 실패합니다.

원격 UniFi 장치가 채택되지 않는 이유

UniFi 장치는 기본적으로 로컬 네트워크에서 UDP 포트 10001을 통해 브로드캐스트를 수행하여 컨트롤러를 찾습니다. 브로드캐스트는 LAN을 벗어나지 못하므로, 다른 도시에 있는 사무실의 장치는 VPS에 있는 컨트롤러를 발견할 수 없습니다. 이것이 Layer 3 채택이며, 대부분의 사용자가 여기서 막히게 됩니다. 장치와 컨트롤러 모두 정상입니다. 다만 장치에 어디를 바라봐야 할지 알려주는 설정이 없을 뿐입니다.

먼저 컨트롤러에 어떤 주소를 전달할지 알려주어야 합니다. 컨트롤러의 Settings 내 System 섹션에 override 옵션이 포함된 inform host 설정이 있습니다. 이를 VPS의 공인 호스트 이름이나 IP로 설정하십시오. 이 설정이 없으면 컨트롤러는 자신의 인터페이스에서 확인되는 주소를 알리는데, Docker 브리지 네트워크 내부에서는 172.18.0.3과 같은 사설 주소가 됩니다. 장치는 해당 주소를 수신하지만 라우팅할 수 없어 다시 검색 상태로 돌아갑니다.

그다음 장치에 해당 주소를 지정하십시오. 원격 LAN에 있는 장치에 SSH로 접속합니다. 공장 초기화 상태의 장치는 사용자 이름 ubnt과 비밀번호 ubnt를 사용합니다.

ssh ubnt@192.168.1.20
set-inform http://vps.example.com:8080/inform

최신 장치 펌웨어는 셸 대신 메뉴로 진입합니다. 동일한 내용을 단일 명령어로 실행하십시오.

ssh ubnt@192.168.1.20 mca-cli-op set-inform http://vps.example.com:8080/inform

이제 장치가 컨트롤러에 채택 가능한 상태로 나타납니다. Adopt를 클릭하면 상태가 Adopting으로 변경됩니다. 여기서 모두가 당황하는 부분이 있습니다. 보통 set-inform을 두 번 실행해야 합니다. 장치가 프로비저닝 상태로 재시작되면서 컨트롤러가 아직 교체하지 못한, 장치 자체 설정에 저장된 inform URL로 되돌아가기 때문입니다. 상태가 Adopting일 때 명령어를 다시 실행하면 인계가 완료됩니다. 장치에서 info을 입력하여 현재 유지하고 있는 inform URL과 상태를 확인하십시오.

장치가 이전에 다른 컨트롤러에 의해 채택된 적이 있다면 set-inform만으로는 완료되지 않습니다. 이전 컨트롤러의 자격 증명을 여전히 가지고 있기 때문입니다. 리셋 버튼을 사용하거나 이전 자격 증명을 사용하여 SSH로 set-default을 실행하여 먼저 공장 초기화를 수행하십시오.

장치 수가 많다면 대신 DHCP를 사용하십시오. DHCP(Dynamic Host Configuration Protocol) 옵션 43은 공급업체별 값을 전달하며, UniFi 장치는 하위 옵션 2에서 inform URL을 읽어옵니다. Linux 시스템에서 16진수 문자열을 생성하십시오.

URL="http://vps.example.com:8080/inform"
HEX=$(printf '%s' "$URL" | od -An -tx1 | tr -d ' \n')
printf '02%02x%s\n' "${#URL}" "$HEX"

http://192.168.3.10:8080/inform의 경우 31바이트 문자열이 021f687474703a2f2f3139322e3136382e332e31303a383038302f696e666f726d를 출력합니다. 이 결과를 라우터의 DHCP 옵션 43 필드에 16진수 값으로 붙여넣으십시오. 해당 네트워크에서 부팅되는 모든 장치는 SSH 작업 없이도 임대 정보를 통해 컨트롤러 주소를 학습합니다. 구형 가이드에는 하위 옵션 1인 0104과 뒤에 이어지는 IPv4 주소의 4바이트 16진수 값이 표시되어 있으며, 장치는 여전히 해당 형식을 허용합니다.

해당 사이트에서 DNS를 운영 중이라면 세 번째 방법이 있습니다. UniFi 장치는 부팅 시 unifi 호스트 이름을 확인하려고 시도하므로, unifi에 대한 A 레코드를 VPS 주소로 지정하면 장치별 작업 없이도 채택이 가능합니다. 이 방법은 장치가 실제로 사용하는 리졸버를 직접 제어할 수 있는 경우에만 유효합니다.

개방해야 할 UniFi 포트와 비공개로 유지해야 할 포트

원격 사이트에서 접근 가능해야 하는 포트는 단 두 개뿐입니다.

TCP 8080은 inform 채널이며, 채택된 모든 장치가 이 포트로 연결됩니다. 내부 페이로드는 장치 채택 시 컨트롤러가 부여한 키로 AES 암호화되므로, 일반적인 설정에서는 평문 HTTP를 사용합니다.
UDP 3478은 STUN(session traversal utilities for NAT)이며, 장치가 컨트롤러로 돌아오는 경로를 유지하는 데 사용합니다.

그 외의 모든 포트는 VPS에서 닫아두어야 합니다.

TCP 8443은 관리자 인터페이스입니다. 이 포트는 절대 공개해서는 안 됩니다. 컨트롤러가 관리하는 모든 사이트의 설정이 단일 비밀번호 뒤에 보호되어 있습니다.
UDP 10001과 UDP 1900은 브로드캐스트 검색용입니다. 브로드캐스트는 인터넷을 넘어 전달되지 않으므로, 이 포트를 열어도 아무런 효과가 없습니다.
TCP 8880과 TCP 8843은 게스트 포털 리다이렉트용입니다. 게스트 포털을 운영하는 경우에만 여십시오.
TCP 6789는 모바일 속도 테스트용이며, UDP 5514는 원격 syslog용입니다. 필요할 때만 추가하십시오.
TCP 27117은 MongoDB용입니다. 위 compose 파일에서 데이터베이스는 포트를 전혀 게시하지 않으므로, 내부 Docker 네트워크에서만 존재합니다. 이 상태를 유지하십시오.

사이트가 고정 공인 IP 주소를 사용하는 경우, 해당 주소만 허용하십시오:

sudo ufw allow OpenSSH
sudo ufw allow proto tcp from 203.0.113.4 to any port 8080
sudo ufw allow proto udp from 203.0.113.4 to any port 3478
sudo ufw enable
sudo ufw status verbose

VPS 방화벽을 위한 ufw 기초에서는 해당 규칙들이 전제로 하는 기본 거부(default deny) 설정을 다룹니다.

여기서 많은 사용자가 빠지는 함정이 있습니다. Docker가 게시한 포트는 ufw를 우회합니다. 포트를 게시하면 NAT 및 포워딩 규칙이 iptables에 직접 작성되며, 해당 트래픽은 ufw가 관리하는 INPUT 체인이 아닌 Docker 자체 체인에서 필터링됩니다. 따라서 ufw deny 8443가 ufw status에서 올바르게 설정된 것처럼 보여도 포트는 전 세계에 열려 있을 수 있습니다. VPS 내부가 아닌 다른 기기에서 테스트하십시오:

nc -vz vps.example.com 8443

연결 거부나 타임아웃이 발생해야 정상입니다. 연결이 성공한다면 ufw 설정과 관계없이 포트가 공개된 것입니다. 확실한 해결책은 이미 compose 파일에 적용된 방식입니다. 포트를 127.0.0.1 또는 터널 주소에 게시하여 Docker가 공인 인터페이스에 바인딩하지 않도록 하십시오. DOCKER-USER 체인의 규칙을 사용하는 방법도 있지만, 바인딩 방식이 더 간단하며 규칙 순서 오류로 인해 설정이 무력화될 위험이 없습니다.

Ubiquiti에서 제공하는 설치 프로그램은 어떤가요?

Ubiquiti는 Network Application을 위한 Debian 패키지를 배포합니다. 이 패키지는 정상적으로 작동하지만, 최신 Ubuntu 환경에서는 배포판에서 더 이상 지원하지 않는 MongoDB 관련 문제가 발생합니다. Ubuntu 22.04 및 24.04에는 MongoDB 서버 패키지가 포함되어 있지 않으므로, 사용자가 직접 MongoDB 저장소를 추가하고 버전을 수동으로 맞춰야 합니다. 위에서 설명한 컨테이너 방식은 이러한 버전 매칭을 고정된 태그 하나로 해결하므로 이 가이드에서는 해당 방식을 권장합니다.

Ubiquiti의 최신 자가 호스팅 제품인 UniFi OS Server는 Podman 컨테이너에서 UniFi 애플리케이션을 실행하며, 하드웨어 콘솔과 동일한 UniFi OS 환경을 제공합니다. 2026년 8월 기준으로 이 제품은 x86_64 아키텍처의 Ubuntu 22.04 또는 24.04, slirp4netns이 포함된 Podman 4.3.1 이상 버전을 요구합니다. 최소 사양은 2 vCPU와 4 GB RAM이며, 권장 사양은 4 vCPU와 8 GB RAM입니다. 설치 프로그램은 Ubiquiti 다운로드 페이지에서 무료 계정으로 로그인해야 접근할 수 있으므로, 가이드에 바로 붙여넣을 수 있는 고정된 URL은 없습니다. 이 설치 프로그램은 uosserver라는 시스템 사용자를 생성하고 해당 사용자 권한으로 컨테이너를 실행합니다. 제조사가 제공하는 패키징 방식을 선호한다면 이 방법을 선택하십시오. 버전을 직접 고정하고 서버를 다른 용도로도 자유롭게 활용하고 싶다면 컨테이너 스택 방식을 선택하십시오.

UniFi 백업 저장 위치 및 외부 반출 방법

컨트롤러는 설정(Settings)의 백업 섹션에서 지정한 일정에 따라 자체 백업을 수행하며, 보관할 백업 파일의 개수도 해당 섹션에서 설정합니다. 파일은 컨테이너 내부의 /config/data/backup/autobackup에 저장되며, 호스트에서는 ~/unifi/config/data/backup/autobackup 경로에 위치합니다. 파일명은 autobackup_10.5.67_20260813_1200_1755086400004.unf와 같은 형식을 따릅니다.

백업 파일이 실제로 생성되었는지 확인하십시오:

ls -l ~/unifi/config/data/backup/autobackup

백업 일정을 설정한 지 하루가 지났음에도 디렉터리가 비어 있다면, 이는 컨테이너를 새로 설치했을 때 발생하는 알려진 문제입니다. 애플리케이션은 autobackup 디렉터리가 이미 존재할 것으로 예상하지만 이를 직접 생성하지 않기 때문에, 예약된 작업이 아무런 파일도 기록하지 못하고 실패하게 됩니다. 컨테이너를 실행하는 사용자와 동일한 권한으로 해당 디렉터리를 직접 생성한 뒤 다음 실행 주기를 기다리십시오:

mkdir -p ~/unifi/config/data/backup/autobackup
docker compose restart unifi-network-application

.unf 파일에는 사이트 구성 정보와 관리자 계정이 포함되어 있으므로, 암호화 키와 같이 취급해야 합니다. 관리 중인 다른 장비로 복사본을 가져와 안전하게 보관하십시오:

rsync -av you@vps.example.com:~/unifi/config/data/backup/autobackup/ ~/unifi-backups/

복구는 한 단계로 완료됩니다. 새로 설치한 경우 설정 마법사의 첫 페이지에서 백업 파일로 복구하는 옵션을 제공하며, 실행 중인 컨트롤러는 동일한 설정 페이지에서 복구를 수행할 수 있습니다. 동일한 버전 또는 더 최신 버전으로 복구하십시오. 현재 실행 중인 애플리케이션보다 더 최신 버전에서 생성된 백업 파일은 복구가 거부되므로, 백업 파일과 함께 버전 번호를 기록해 두는 것이 좋습니다.

컨트롤러 업그레이드 시 발생할 수 있는 문제

업그레이드 전에는 항상 수동으로 백업을 생성하고 파일을 다운로드하십시오. 그 후 다음 사항을 확인하십시오.

docker compose pull
docker compose up -d
docker compose logs -f unifi-network-application

가장 먼저 문제가 발생하는 부분은 데이터베이스입니다. 애플리케이션을 수정하면서 동시에 mongo 태그를 새로운 메이저 버전으로 변경하는 것은 컨트롤러가 시작되지 않게 만드는 가장 빠른 방법입니다. MongoDB는 단계적 업그레이드 과정 없이 다른 메이저 버전의 데이터 파일을 열 수 없기 때문입니다. 애플리케이션을 먼저 단독으로 업그레이드하십시오. MongoDB는 별도로, 한 번에 한 메이저 버전씩, 최신 백업을 확보한 상태에서 업그레이드하십시오.

다음은 메모리 문제입니다. 더 큰 릴리스는 더 큰 힙 메모리를 요구합니다. 애플리케이션이 시작된 후 몇 분 동안 실행되다가 종료된다면 MEM_LIMIT 및 MEM_STARTUP 값을 1536 또는 2048로 높이고 재시작하십시오. 호스트에서 dmesg -T | grep -i 'killed process' 명령을 실행하면 커널에 의해 프로세스가 종료되었는지 확인할 수 있습니다.

장치 펌웨어는 사람들이 간과하기 쉬운 위험 요소입니다. 컨트롤러가 업그레이드된 후에는 연결된 장치들에 대한 펌웨어 업그레이드를 제안합니다. 동일한 세션에서 이를 수락하지 마십시오. 장치 업그레이드와 컨트롤러 업그레이드가 겹치고 둘 사이의 연결이 끊어지면, 장치가 절반만 프로비저닝된 상태로 남을 수 있습니다. 이 경우 다른 건물에 있는 하드웨어에 SSH로 접속하여 set-inform를 수행해야 하는 상황이 발생합니다.

업그레이드 작업 자체는 생각보다 위험하지 않습니다. 컨트롤러가 재시작되는 동안에도 장치들은 트래픽을 계속 전달하므로 사용자는 아무런 변화를 느끼지 못합니다. 다만 컨트롤러가 게스트 포털이나 RADIUS를 제공하는 경우 해당 서비스는 중단되므로, 사용자가 없는 시간을 선택하십시오. 새벽 3시에 조용히 중단된 컨트롤러를 파악하는 것은 중요하므로, Uptime Kuma 상태 모니터를 8080 포트에 연결하여 알림을 받도록 설정하십시오.

정직한 대안: Ubiquiti 호스팅 콘솔

Ubiquiti는 동일한 역할을 서비스 형태로 판매합니다. 2026년 8월 기준으로 공식 UniFi Cloud Console은 월 29달러부터 시작하며 최대 500대의 UniFi 장치를 관리할 수 있고, Ubiquiti가 업데이트와 백업을 직접 수행합니다. 방금 설치한 자가 호스팅 애플리케이션은 무료이며 구독료가 발생하지 않습니다.

단일 사이트를 관리하며 패치 작업보다 비용 지불을 선호한다면 호스팅 콘솔을 선택하십시오. 여러 사이트를 관리하거나, 직접 제어하는 네트워크 내부에 컨트롤러를 두고 다른 서비스와 서버를 공유하고 싶다면 VPS를 선택하십시오. 소규모 환경에서는 비용 차이가 분명하지만, 고려해야 할 요소는 비용뿐만이 아닙니다. 호스팅 콘솔은 타인의 가동 시간에 의존하는 것이며, VPS는 디스크가 가득 차는 상황을 포함하여 모든 운영 책임을 사용자가 직접 집니다. 어차피 서버를 운영해야 한다면, 다음으로 VPS에서 실행할 수 있는 다른 서비스 목록을 읽어보시기 바랍니다.

FAQ

UniFi 장비가 VPS의 컨트롤러에 어댑트(adopt)되지 않는 이유는 무엇입니까?

장비는 UDP 10001 포트로 브로드캐스트를 보내 컨트롤러를 탐색합니다. 브로드캐스트는 로컬 네트워크를 벗어날 수 없으므로 원격지의 장비는 공인 인터넷에 있는 컨트롤러를 찾지 못합니다. 컨트롤러의 시스템 설정에서 inform host override를 VPS 호스트명으로 지정한 뒤, 장비에서 ssh ubnt@<device-ip>를 실행하고 이어서 set-inform http://vps.example.com:8080/inform을 입력하여 컨트롤러를 가리키게 하십시오. 장비가 Adopting 상태에서 멈춰 있다면 해당 상태에서 set-inform을 다시 실행하십시오. 이전에 다른 컨트롤러에 어댑트된 적이 있다면, 이전 컨트롤러의 자격 증명이 남아 있으므로 먼저 공장 초기화를 수행해야 합니다.

자가 호스팅 UniFi 컨트롤러에는 어느 정도의 RAM이 필요합니까?

2 GB가 최소 사양이며 4 GB 정도면 원활하게 동작합니다. 이 애플리케이션은 Java와 MongoDB로 구성되며 각각 메모리를 점유합니다. 컨테이너 이미지는 기본적으로 Java 힙을 1024 MB로 제한하며, MongoDB의 WiredTiger 캐시는 1 GB를 초과하는 RAM의 절반을 사용합니다. x86_64 환경에서는 grep -m1 -o avx /proc/cpuinfo을 통해 CPU가 AVX를 지원하는지 확인하십시오. MongoDB 5.0 이상 버전은 AVX가 없으면 실행되지 않아 데이터베이스 컨테이너가 무한 재시작 루프에 빠지기 때문입니다.

8443 포트를 인터넷에 공개해야 합니까?

아니요. 8443 포트는 관리자 인터페이스이며 컨트롤러가 관리하는 모든 사이트의 설정이 포함되어 있습니다. 127.0.0.1를 통해 게시하고 ssh -L 8443:127.0.0.1:8443 you@vps.example.com으로 접속하거나, WireGuard 또는 Tailscale 주소에 바인딩하십시오. 각 사이트에서 접근 가능해야 하는 포트는 TCP 8080과 UDP 3478뿐이며, 사이트의 공인 IP가 고정되어 있다면 해당 IP로 접근을 제한할 수 있습니다. Docker로 게시된 포트는 ufw의 필터링을 거치지 않는다는 점을 유의하십시오. 따라서 ufw status의 상태만 믿지 말고 외부 장비에서 직접 테스트해야 합니다.

VPS 컨트롤러가 다운되면 네트워크가 중단됩니까?

아니요. 이미 어댑트된 액세스 포인트와 스위치는 컨트롤러가 이전에 푸시한 설정을 사용하여 트래픽을 계속 전달하므로 클라이언트 연결과 Wi-Fi는 정상적으로 유지됩니다. 중단되는 기능은 관리 기능뿐입니다. 대시보드와 통계 수집 기능이 비활성화되며, 게스트 포털 인증이나 컨트롤러가 RADIUS 서버 역할을 하는 경우의 RADIUS 인증 등 컨트롤러가 실시간으로 제공하는 기능도 사용할 수 없게 됩니다.

UniFi 컨트롤러는 자동 백업 파일을 어디에 저장합니까?

여기에서 사용하는 컨테이너 이미지에서는 /config/data/backup/autobackup에 저장됩니다. 이 경로는 호스트의 데이터 경로와 data/backup/autobackup으로 매핑되며, 버전과 타임스탬프가 포함된 .unf 파일 형태로 생성됩니다. 일부 초기 설치 시에는 autobackup 디렉터리가 존재하지 않을 수 있습니다. 이 경우 예약된 백업이 오류 보고 없이 아무것도 기록하지 않으므로, 일정을 설정한 다음 날 해당 디렉터리를 확인하고 비어 있다면 직접 생성하십시오. .unf에는 사이트 설정과 관리자 계정 정보가 포함되어 있으므로 반드시 VPS 외부로 복사해 두어야 합니다.

#unifi#ubiquiti#network-management#docker #self-hosting