Nextcloud Hub Talk 고성능 백엔드(HPB) 설정 안내서

1. 서론

Nextcloud 관리자 설정 페이지에서 “고성능 백엔드가 구성되지 않았습니다(No High-performance backend configured)“라는 메시지를 마주하는 것은 시스템의 치명적인 오류를 의미하는 것이 아니다. 오히려 이는 Nextcloud 개발팀이 사용자의 경험을 관리하고, Talk 애플리케이션의 아키텍처적 한계를 명확히 알리기 위해 의도적으로 추가한 전략적 경고에 해당한다.1 이 경고는 Talk 버전 20.1.2 업데이트에서 처음 도입되었으며, 그 목적은 고성능 백엔드(High-Performance Backend, 이하 HPB) 없이는 화상 통화가 2-3명의 소규모 인원으로 제한된다는 사실을 관리자에게 명확히 인지시키는 데 있다.2

기본 설정 상태의 Nextcloud Talk는 P2P(Peer-to-Peer) 메시(mesh) 네트워크 방식으로 동작한다. 이 구조에서는 통화에 참여하는 모든 참가자가 자신의 오디오 및 비디오 스트림을 다른 모든 참가자에게 개별적으로 전송해야 한다. 예를 들어, 5명이 통화에 참여할 경우 각 참가자는 4개의 업로드 스트림을 동시에 유지해야 한다. 이는 참가자 수의 증가에 따라 요구되는 업로드 대역폭이 기하급수적으로 늘어나는 결과를 초래하며, 일반적인 가정이나 소규모 사무실의 인터넷 환경에서는 순식간에 한계에 도달하게 된다.3 이러한 구조적 한계로 인해 사용자들이 다자간 통화에서 심각한 품질 저하를 겪고, 결과적으로 Nextcloud Talk를 비효율적인 솔루션으로 오해하는 상황이 빈번하게 발생했다. 개발팀은 이러한 부정적인 인식을 바로잡고 제품의 명성을 보호하기 위해 HPB의 필요성을 알리는 경고를 시스템에 내장하기로 결정한 것이다.3

HPB를 구성하는 것은 이 P2P 메시 아키텍처를 중앙 집중식 허브-앤-스포크(Hub-and-Spoke) 모델로 전환하는 과정이다. HPB가 도입되면 각 참가자는 자신의 미디어 스트림을 서버로 단 한 번만 전송하면 된다. 그러면 서버가 이 스트림을 받아 다른 모든 참가자에게 효율적으로 분배하는 역할을 맡는다.4 이 방식은 각 클라이언트의 CPU 사용률과 업로드 대역폭 부담을 극적으로 감소시켜, 수십 명 이상이 참여하는 대규모 화상 통화도 안정적으로 운영할 수 있는 기반을 마련한다.7

따라서 이 보고서의 목표는 단순히 관리자 페이지의 경고 메시지를 제거하는 것을 넘어, Nextcloud Talk의 잠재력을 최대한 발휘하여 안정적이고 확장 가능한 자체 호스팅 커뮤니케이션 플랫폼을 구축하는 데 필요한 모든 기술적 절차와 심층적인 지식을 제공하는 것이다. 이 과정을 통해 관리자는 단순한 오류 해결이 아닌, 시스템의 근본적인 성능 업그레이드를 수행하게 될 것이다.

2. 부: 고성능 백엔드(HPB)의 핵심 구성 요소 이해

Nextcloud Talk HPB는 단일 소프트웨어가 아닌, 여러 전문화된 서비스가 유기적으로 협력하여 구성되는 일종의 마이크로서비스 생태계다.8 각 구성 요소의 역할과 상호작용을 정확히 이해하는 것은 성공적인 설치와 효율적인 문제 해결의 전제 조건이다. HPB의 아키텍처를 구성하는 핵심 요소는 다음과 같다.

2.1 시그널링 서버 (Signaling Server - spreed-signaling): 통화 연결의 지휘자

시그널링 서버는 HPB의 두뇌와 같은 역할을 수행하며, 화상 통화의 ’항공 교통 관제사’에 비유할 수 있다. 이 서버는 실제 오디오나 비디오 미디어 데이터를 직접 처리하지 않는다. 대신, 통화 연결을 설정하고 관리하는 데 필요한 모든 제어 정보, 즉 메타데이터를 교환하는 책임을 진다.4 여기에는 참가자들의 IP 주소와 포트 번호, 사용 가능한 코덱 정보, 통화 참여 및 이탈과 같은 세션 제어 메시지가 포함된다. 시그널링 서버는 이러한 실시간 정보 교환을 위해 웹소켓(WebSocket) 프로토콜을 사용하여 클라이언트와 지속적인 연결을 유지한다.8 성공적인 작동을 위해 시그널링 서버는 미디어 게이트웨이 역할을 하는 Janus와 메시지 배포를 위한 NATS 서버에 의존하므로, 이들 구성 요소 간의 상호 연결성을 이해하는 것이 중요하다.10

2.2 STUN (Session Traversal Utilities for NAT) 서버: 공인 IP 주소 탐색기

STUN 서버는 단순하지만 필수적인 기능을 수행한다. 대부분의 클라이언트 장치는 공유기나 방화벽과 같은 NAT(Network Address Translation) 환경 내에 위치하여 사설 IP 주소를 사용한다. STUN 서버의 역할은 이러한 클라이언트가 외부 인터넷에서 자신을 식별할 수 있는 공인 IP 주소와 포트 번호를 발견하도록 돕는 것이다.4 클라이언트는 STUN 서버에 간단한 요청을 보내고, STUN 서버는 그 요청이 도달한 소스 IP 주소와 포트를 응답으로 돌려준다. 이 정보는 클라이언트 간의 직접적인 P2P 연결을 시도하는 첫 번째 단계에서 사용된다. Nextcloud는 기본적으로 stun.nextcloud.com:443이라는 STUN 서버를 제공하며, coturn과 같은 대부분의 TURN 서버 구현체는 STUN 기능을 내장하고 있어 별도의 STUN 서버 없이도 운영이 가능하다.5

2.3 TURN (Traversal Using Relays around NAT) 서버: 네트워크 제약을 우회하는 데이터 중계기

STUN을 통한 공인 IP 주소 확인만으로는 모든 네트워크 환경에서 P2P 연결을 보장할 수 없다. 특히, 양쪽 클라이언트가 모두 엄격한 방화벽 뒤에 있거나 대칭형(Symmetric) NAT 환경에 있는 경우 직접적인 통신 경로 설정이 불가능하다. 이때 TURN 서버가 최후의 보루 역할을 한다.4

TURN 서버는 미디어 데이터 중계기(Relay)로 작동한다. P2P 연결에 실패한 클라이언트들은 각자의 미디어 스트림을 TURN 서버로 전송한다. 그러면 TURN 서버가 이 스트림들을 수신하여 상대방 클라이언트에게 전달해 줌으로써 통신을 가능하게 만든다.14 이는 통화 연결의 신뢰성을 극대화하는 매우 중요한 기능으로, 어떤 네트워크 환경에 있는 사용자라도 통화에 참여할 수 있도록 보장한다. Nextcloud 환경에서는 coturn이 사실상의 표준 오픈소스 TURN 서버로 널리 사용되고 있다.13

이처럼 HPB는 시그널링, STUN, TURN이라는 세 가지 핵심 서비스가 각자의 역할을 수행하며 긴밀하게 협력하는 분산 시스템이다. 설치 과정에서 발생하는 문제들은 대부분 이들 서비스 간의 통신 설정 오류(예: 방화벽 포트 차단, 잘못된 주소 설정, 시크릿 키 불일치 등)에서 비롯된다. 따라서 각 구성 요소의 역할을 명확히 인지하고, 이들 간의 데이터 흐름을 머릿속에 그리는 것이 전체 시스템을 성공적으로 구축하는 열쇠가 된다.

3. 부: 설치 방법론: Docker 기반 간편 설치 vs. 수동 고급 설치

HPB를 설치하는 데에는 크게 두 가지 접근 방식이 존재한다. 하나는 Docker 컨테이너를 이용한 간소화된 방식이며, 다른 하나는 각 구성 요소를 직접 컴파일하고 설정하는 수동 방식이다. 어떤 방식을 선택할지는 관리자의 기술 숙련도, 서버 환경의 제약 조건, 그리고 요구되는 시스템 제어 수준에 따라 달라진다.

3.1 접근 방식 비교 분석

Docker 기반 설치 (권장): 이 방식은 Nextcloud AIO(All-in-One) 팀에서 제공하는 사전 구성된 Docker 이미지를 사용하는 것으로, 대부분의 사용자에게 강력히 권장된다. 이 이미지 안에는 시그널링 서버뿐만 아니라 Janus, NATS와 같은 복잡한 종속성들이 모두 포함되어 있고 최적화된 상태로 패키징되어 있다.4 관리자는 몇 가지 환경 변수 설정과 Docker 명령어 실행만으로 전체 HPB 스택을 구동할 수 있어, 설치 과정의 복잡성이 대폭 감소하고 설정 오류의 가능성도 현저히 낮아진다.

수동 설치 (고급 사용자용): 이 방식은 Docker를 사용할 수 없는 환경이거나, 각 서비스의 모든 설정을 세밀하게 제어해야 하는 특별한 요구사항이 있는 전문가를 위한 경로다. coturn, Janus, NATS, spreed-signaling 서버를 각각 소스 코드로부터 컴파일하거나 패키지로 설치하고, 서비스 데몬을 수동으로 관리하며, 모든 설정 파일을 직접 편집해야 한다.10 이 방법은 최고의 유연성을 제공하지만, 상당한 수준의 리눅스 시스템 관리 지식과 문제 해결 능력을 요구한다.

다음 표는 두 설치 방식의 주요 특징을 비교하여 관리자가 자신의 환경에 가장 적합한 결정을 내릴 수 있도록 돕는다.

표 1: 설치 방법론 비교

이 비교를 통해 명확히 알 수 있듯이, 특별한 이유가 없는 한 Docker 기반 설치 방식이 시간과 노력을 절약하고 안정성을 확보하는 가장 효율적인 경로다. 이어지는 3부에서는 이 권장 방식을, 4부에서는 고급 사용자를 위한 수동 설치 방식을 상세히 다룬다.

4. 부: Docker를 이용한 고성능 백엔드 설치 (권장 방식)

Docker를 이용한 설치는 HPB 구성의 복잡성을 크게 줄여주는 가장 효율적인 방법이다. 이 절차는 사전 준비, 보안 키 생성, 컨테이너 실행, 그리고 리버스 프록시 설정의 네 단계로 구성된다.

4.1 사전 준비: Docker, 도메인, 방화벽

본격적인 설치에 앞서 다음과 같은 준비가 필요하다.

• Docker 설치: 서버에 Docker 엔진이 설치되어 있어야 한다. 공식 Docker 문서를 참조하여 운영체제에 맞는 최신 버전을 설치하라. 여기서 중요한 점은, Snap 패키지를 통해 설치된 Docker는 예기치 않은 문제를 일으킬 수 있으므로 사용을 피해야 한다는 것이다. sudo docker info | grep "Docker Root Dir" | grep "/var/snap/docker/" 명령어로 확인 후, 해당된다면 Snap 버전을 제거하고 공식적인 방법으로 재설치해야 한다.21

• DNS 및 도메인 설정: 시그널링 서버를 위한 전용 서브도메인을 준비해야 한다. 예를 들어, Nextcloud 도메인이 cloud.example.com이라면 talk.example.com과 같은 서브도메인을 생성하고, 해당 도메인의 A 레코드가 서버의 공인 IP 주소를 가리키도록 DNS 설정을 완료해야 한다.22

• 방화벽 설정: HPB 컨테이너 내부에서 실행될 TURN 서버가 외부 클라이언트와 통신할 수 있도록 방화벽에서 특정 포트를 개방해야 한다. 포트 3478에 대해 TCP 및 UDP 프로토콜의 인바운드 트래픽을 허용하도록 규칙을 추가해야 한다.8

4.2 보안 시크릿 키 생성

HPB 컨테이너는 Nextcloud 및 내부 서비스 간의 인증을 위해 세 가지 종류의 보안 비밀 키를 필요로 한다: TURN_SECRET, SIGNALING_SECRET, INTERNAL_SECRET.4 이 키들은 추측이 불가능하도록 충분한 엔트로피를 가진 무작위 문자열이어야 한다.

openssl 도구를 사용하여 다음과 같이 강력한 16진수 문자열 키를 생성할 수 있다.

# 아래 명령어를 세 번 실행하여 각각의 시크릿 키를 생성하고 안전한 곳에 기록해 두어라.
openssl rand -hex 32

이 명령어를 실행할 때마다 64자의 무작위 16진수 문자열이 생성된다. 세 개의 고유한 키를 생성하여 다음 단계에서 사용할 준비를 하라.

4.3 AIO Talk Docker 컨테이너 실행

모든 준비가 완료되었다면, 이제 Docker 명령어를 사용하여 HPB 컨테이너를 실행할 차례다. 아래 명령어는 공식 문서에서 제공하는 표준 실행 명령어이며, 각 옵션에 대한 설명이 포함되어 있다.4

< >로 표시된 부분은 자신의 환경에 맞게 수정해야 한다.

docker run \
--name=nextcloud-talk-hpb \
--restart=always \
--detach \
-e NC_DOMAIN="<your_nextcloud_domain>" \
-e TALK_PORT=3478 \
-e TURN_SECRET="<your_turn_secret>" \
-e SIGNALING_SECRET="<your_signaling_secret>" \
-e INTERNAL_SECRET="<your_internal_secret>" \
-p <your_host_port>:8081 \
ghcr.io/nextcloud-releases/aio-talk:latest

• --name=nextcloud-talk-hpb: 컨테이너의 이름을 지정한다.

• --restart=always: 서버가 재부팅되거나 컨테이너가 예기치 않게 종료될 경우 자동으로 다시 시작하도록 설정한다.

• --detach: 컨테이너를 백그라운드에서 실행한다.

• -e NC_DOMAIN: Nextcloud가 설치된 주 도메인을 지정한다 (예: cloud.example.com).

• -e TALK_PORT: 외부에서 접근할 TURN 포트를 지정한다. 3.1 단계에서 방화벽에 개방한 3478 포트를 사용한다.

• -e TURN_SECRET: 3.2 단계에서 생성한 TURN 서버용 시크릿 키를 입력한다.

• -e SIGNALING_SECRET: 3.2 단계에서 생성한 시그널링 서버용 시크릿 키를 입력한다.

• -e INTERNAL_SECRET: 3.2 단계에서 생성한 내부 통신용 시크릿 키를 입력한다.

• -p <your_host_port>:8081: 컨테이너 내부의 8081 포트를 호스트 서버의 특정 포트(<your_host_port>)에 연결한다. 예를 들어, -p 8080:8081과 같이 설정할 수 있다. 이 포트는 리버스 프록시가 내부적으로 통신하는 데 사용된다.

• ghcr.io/nextcloud-releases/aio-talk:latest: 사용할 Docker 이미지의 주소다.

4.4 리버스 프록시 설정

Docker 컨테이너는 내부 포트(예: 8081)에서 HTTP 서비스로 실행된다. 외부의 암호화된 HTTPS 및 WSS(WebSocket Secure) 트래픽을 안전하게 수신하여 이 내부 컨테이너로 전달하는 역할은 리버스 프록시가 담당한다. 이 설정은 HPB 구축 과정에서 가장 흔한 실패 지점 중 하나이므로 정확한 설정이 매우 중요하다. 시그널링 서버는 지속적인 양방향 통신을 위해 웹소켓 연결을 요구하므로, 리버스 프록시는 일반적인 HTTP 요청 프록시뿐만 아니라 웹소켓 ’업그레이드’를 지원하도록 설정되어야 한다.8

4.4.1 Nginx 설정 예시

talk.example.com 서브도메인에 대한 Nginx 설정 파일에 다음 server 블록을 추가하거나 수정하라. 이 설정은 SSL/TLS 암호화를 처리하고 웹소켓 연결을 올바르게 프록시한다.8

server {
listen 443 ssl http2;
server_name talk.example.com;

# SSL/TLS 인증서 경로 설정
ssl_certificate /path/to/your/fullchain.pem;
ssl_certificate_key /path/to/your/privkey.pem;
include /path/to/your/options-ssl-nginx.conf;
ssl_dhparam /path/to/your/ssl-dhparams.pem;

location / {
proxy_pass http://127.0.0.1:<your_host_port>; # 3.3 단계에서 설정한 호스트 포트
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

# 웹소켓 지원을 위한 필수 헤더
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}

4.4.2 Apache 설정 예시

Apache를 사용하는 경우, mod_proxy와 mod_proxy_wstunnel 모듈이 활성화되어 있는지 확인해야 한다 (sudo a2enmod proxy proxy_wstunnel). 그 후 talk.example.com에 대한 <VirtualHost> 설정을 다음과 같이 구성하라.8

<VirtualHost *:443>
ServerName talk.example.com

# SSL/TLS 설정
SSLEngine on
SSLCertificateFile /path/to/your/fullchain.pem
SSLCertificateKeyFile /path/to/your/privkey.pem
# 기타 SSL 관련 보안 설정 추가

# 웹소켓 터널링을 위한 Rewrite 규칙
RewriteEngine On
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://127.0.0.1:<your_host_port>/$1 [P,L]

# 일반 HTTP 요청 프록시
ProxyPass / http://127.0.0.1:<your_host_port>/
ProxyPassReverse / http://127.0.0.1:<your_host_port>/
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
</VirtualHost>

이러한 리버스 프록시 설정을 완료하고 서비스를 재시작하면, Docker 기반의 HPB 설치가 완료된다.

5. 부: 수동 설치를 통한 고성능 백엔드 구축 (고급 사용자용)

이 섹션은 Docker를 사용하지 않거나 시스템의 모든 구성 요소를 완벽하게 제어하고자 하는 숙련된 시스템 관리자를 위한 것이다. 이 과정은 coturn TURN 서버, 시그널링 서버의 여러 종속성(NATS, Janus), 그리고 시그널링 서버 자체를 개별적으로 설치하고 설정하는 복잡한 작업을 포함한다.

5.1 TURN 서버 (coturn) 설치 및 설정

coturn은 HPB의 핵심 구성 요소 중 하나로, 안정적인 미디어 릴레이를 담당한다.

5.1.1 설치

Debian 또는 Ubuntu 기반 시스템에서는 apt 패키지 관리자를 통해 간단히 설치할 수 있다.13

sudo apt update
sudo apt install coturn

5.1.2 서비스 활성화

설치 후 coturn 서비스가 시스템 부팅 시 자동으로 시작되도록 설정해야 한다. /etc/default/coturn 파일을 열고 TURNSERVER_ENABLED=1 줄의 주석을 제거하거나 값을 1로 설정한다.15

# /etc/default/coturn 파일 수정
sudo nano /etc/default/coturn
# 아래 내용으로 수정
TURNSERVER_ENABLED=1

이후 다음 명령어로 서비스를 시작하고 활성화한다.

sudo systemctl start coturn
sudo systemctl enable coturn

5.1.3 turnserver.conf 설정

coturn의 핵심 설정은 /etc/turnserver.conf 파일에서 이루어진다. 아래는 Nextcloud Talk와 연동하기 위한 필수 설정 항목들이다.

# TURN 서버가 수신 대기할 포트. 기본값은 3478.
listening-port=3478

# 보안 강화를 위한 필수 옵션
fingerprint
lt-cred-mech

# Nextcloud와 공유할 인증 방식 및 시크릿 키
use-auth-secret
static-auth-secret=<your_turn_secret>

# Nextcloud 도메인과 일치시키는 것이 좋음
realm=cloud.example.com

# 서버가 NAT 환경 뒤에 있을 경우, 서버의 공인 IP 주소를 명시해야 함
# external-ip=YOUR_PUBLIC_IP

# 과도한 로그 생성을 방지하고 시스템 로그로 출력을 전환
syslog
no-stdout-log

# 보안 강화를 위해 내부 네트워크로의 릴레이를 차단
# 0.0.0.0/8, 10.0.0.0/8, 127.0.0.0/8, 172.16.0.0/12 등 사설 IP 대역 차단
denied-peer-ip=0.0.0.0-0.255.255.255
denied-peer-ip=10.0.0.0-10.255.255.255
denied-peer-ip=127.0.0.0-127.255.255.255
denied-peer-ip=172.16.0.0-172.31.255.255
#... 기타 필요한 사설 대역 추가

static-auth-secret에 사용할 강력한 시크릿 키는 openssl rand -hex 32 명령어로 생성하라.13

external-ip 설정은 서버가 공유기나 클라우드 플랫폼의 NAT 뒤에 있을 때 필수적이다.13

denied-peer-ip 설정은 TURN 서버가 악의적인 내부 네트워크 스캔에 악용되는 것을 방지하는 중요한 보안 조치다.24 설정 변경 후에는 sudo systemctl restart coturn 명령어로 서비스를 재시작해야 한다.

다음 표는 HPB 구성 요소들이 요구하는 방화벽 포트를 종합적으로 정리한 것이다. 이 정보를 바탕으로 방화벽 규칙을 정확하게 설정해야 한다.

표 2: HPB 구성 요소를 위한 필수 방화벽 포트

5.2 시그널링 서버 종속성 설치

시그널링 서버는 NATS 메시징 서버와 Janus WebRTC 게이트웨이라는 두 가지 핵심 종속성을 필요로 한다.

5.2.1 NATS 서버

NATS는 시그널링 서버 인스턴스 간의 메시지를 안정적으로 전달하는 경량 메시징 시스템이다.11 가장 간단한 설치 방법은 Docker를 이용하는 것이다.10

docker run -d --name nats-server -p 4222:4222 --restart=always nats:latest

5.2.2 Janus WebRTC 게이트웨이

Janus는 실제 WebRTC 미디어 스트림을 처리하는 미디어 게이트웨이 역할을 한다.9

apt를 통해 설치하고, 시그널링 서버와 연동하기 위해 몇 가지 설정을 변경해야 한다.10

sudo apt install janus

설치 후 /etc/janus/janus.jcfg 파일을 열어 다음 항목을 수정하거나 추가하라.

# /etc/janus/janus.jcfg
...
full_trickle = true
turn_rest_api_key = "<your_janus_api_key>"
...

turn_rest_api_key는 openssl rand -hex 16과 같은 명령어로 생성하여 입력한다. 이 키는 시그널링 서버가 TURN 서버를 제어할 때 사용된다.

5.3 시그널링 서버 컴파일 및 설정

5.3.1 빌드 및 설치

먼저 시그널링 서버를 빌드하는 데 필요한 도구들을 설치한다.10

sudo apt install git golang-go make protobuf-compiler

그 다음, 공식 GitHub 저장소에서 소스 코드를 복제하고 빌드한다.11

git clone https://github.com/strukturag/nextcloud-spreed-signaling.git
cd nextcloud-spreed-signaling
make build

빌드가 성공하면 bin/signaling 실행 파일이 생성된다.

5.3.2 server.conf 설정

설정 파일 템플릿을 복사하고 필요한 값을 채워 넣는다.

sudo mkdir -p /etc/signaling
sudo cp server.conf.in /etc/signaling/server.conf
sudo nano /etc/signaling/server.conf

server.conf 파일에서 수정해야 할 주요 항목은 다음과 같다.10

[http]
listen = 127.0.0.1:8080 # 리버스 프록시와 통신할 내부 주소 및 포트

[sessions]
hashkey = <your_hash_key>
blockkey = <your_block_key>

[backend]
backends = backend1

[backend1]
url = https://cloud.example.com # Nextcloud 주소
secret = <your_nextcloud_secret> # Nextcloud와 공유할 시크릿

[nats]
url = nats://127.0.0.1:4222 # NATS 서버 주소

[mcu]
type = janus
url = ws://127.0.0.1:8188 # Janus 웹소켓 주소

[turn]
apikey = <your_janus_api_key> # Janus에서 설정한 API 키
secret = <your_turn_secret> # coturn에서 설정한 static-auth-secret
servers = turn:your.turn.server:3478?transport=udp,turn:your.turn.server:3478?transport=tcp

hashkey, blockkey, nextcloud_secret은 모두 openssl rand -hex 16과 같은 명령어로 생성한 강력한 무작위 키여야 한다.

5.4 Systemd 서비스를 통한 백그라운드 실행

시그널링 서버를 안정적으로 운영하기 위해 Systemd 서비스로 등록한다. /etc/systemd/system/signaling.service 파일을 생성하고 다음 내용을 입력하라.11

[Unit]
Description=Nextcloud Talk Signaling Server
After=network.target


Type=simple
User=www-data # 또는 전용 사용자
Group=www-data # 또는 전용 그룹
ExecStart=/path/to/nextcloud-spreed-signaling/bin/signaling --config /etc/signaling/server.conf
Restart=always

[Install]
WantedBy=multi-user.target

ExecStart의 경로는 실제 signaling 바이너리 위치에 맞게 수정해야 한다. 이후 다음 명령어로 서비스를 활성화하고 시작한다.

sudo systemctl daemon-reload
sudo systemctl enable signaling
sudo systemctl start signaling

마지막으로, 3.4절에서 설명한 것과 동일한 원리로 시그널링 서버(127.0.0.1:8080)에 대한 리버스 프록시 설정을 완료해야 한다.

6. 부: Nextcloud 관리자 설정 연동 및 최종 활성화

HPB 인프라 구축이 완료되었다면, 마지막 단계는 Nextcloud가 이 새로운 백엔드를 인식하고 사용하도록 설정하는 것이다. 이 작업은 Nextcloud 관리자 설정 페이지에서 이루어지며, 각 입력 필드에 정확한 값을 입력하는 것이 매우 중요하다.

6.1 STUN/TURN 서버 정보 입력

먼저, Nextcloud 관리자 계정으로 로그인한 후 설정 > 관리 > Talk 메뉴로 이동한다.

6.1.1 STUN 서버 설정

STUN 서버 섹션에서, 직접 구축한 TURN 서버의 주소를 입력한다. coturn 서버는 STUN 기능을 포함하고 있으므로 별도의 STUN 서버 주소를 사용할 필요가 없다.27

• STUN 서버: turn.example.com:3478 (자신의 TURN 서버 도메인과 포트로 변경)

6.1.2 TURN 서버 설정

TURN 서버 섹션에서 HPB 구성 과정에서 설정한 coturn 서버의 정보를 입력한다. 여기서 입력 형식에 특히 주의해야 한다. 서버 주소 앞에 turn://과 같은 프로토콜 접두사를 붙이지 않아야 한다.27

• 서버: turn.example.com:3478 (프로토콜 없이 도메인과 포트만 입력)

• TURN 서버 비밀번호: coturn의 turnserver.conf 파일에 설정한 static-auth-secret 값을 그대로 복사하여 붙여넣는다.

• 프로토콜: 드롭다운 메뉴에서 UDP 및 TCP를 선택한다.

이 간단해 보이는 입력 단계는 전체 시스템의 성패를 좌우할 수 있다. 예를 들어, 서버 주소 필드에 불필요한 프로토콜 접두사를 추가하는 작은 실수는 Nextcloud가 TURN 서버와 통신하는 것을 완전히 차단하여 연결 실패를 유발할 수 있다. 이는 복잡한 백엔드 인프라가 완벽하게 구축되었더라도, 최종적으로 애플리케이션과 연결되는 인터페이스에서의 사소한 설정 오류 하나가 전체 시스템을 무용지물로 만들 수 있음을 보여준다.

6.2 고성능 백엔드(시그널링 서버) URL 및 공유 비밀 입력

마지막으로, 시그널링 서버 정보를 입력하여 HPB를 최종 활성화한다.

• 고성능 백엔드 URL: 리버스 프록시를 통해 외부로 노출되는 시그널링 서버의 전체 HTTPS 주소를 입력한다. 예를 들어, https://talk.example.com/과 같다.4 리버스 프록시 설정에 따라

/standalone-signaling/과 같은 특정 경로가 포함될 수도 있다.20

• 공유 비밀번호: 시그널링 서버와 Nextcloud가 서로를 인증하는 데 사용하는 공유 비밀번호를 입력한다.

• Docker 설치의 경우: 3.2 단계에서 생성한 SIGNALING_SECRET 값을 입력한다.

• 수동 설치의 경우: 4.3 단계의 server.conf 파일에 설정한 [backend1] 섹션의 secret 값을 입력한다.

모든 값을 정확하게 입력한 후 페이지 하단의 변경 사항 저장 버튼을 클릭하면, Nextcloud는 입력된 정보를 바탕으로 백엔드 서버와의 연결을 자동으로 테스트한다. 잠시 후 각 설정 항목 옆에 녹색 체크 표시가 나타나면 모든 연동이 성공적으로 완료된 것이다. 이로써 Nextcloud Talk는 이제 HPB를 통해 확장 가능한 다중 사용자 화상 통화 기능을 완벽하게 지원하게 된다.

7. 부: 전체 시스템 검증 및 문제 해결

HPB 설정이 완료된 후에는 모든 구성 요소가 정상적으로 작동하는지 체계적으로 검증하는 과정이 필수적이다. 이 단계는 잠재적인 문제를 조기에 발견하고 해결하는 데 도움을 준다.

7.1 명령줄 도구를 이용한 서버 연결성 테스트

가장 먼저 각 서버의 기본적인 접근성을 확인한다.

7.1.1 시그널링 서버 검증

외부에서 리버스 프록시를 통해 시그널링 서버에 접근할 수 있는지 확인한다. curl 명령어를 사용하여 API의 ‘welcome’ 엔드포인트를 호출한다.

curl https://talk.example.com/api/v1/welcome

성공적으로 연결되면 다음과 같은 JSON 응답을 받게 된다.4

{"nextcloud-spreed-signaling":"Welcome","version":"..."}

만약 연결 오류, 타임아웃, 또는 HTML 오류 페이지가 반환된다면, 문제는 리버스 프록시 설정, 시그널링 서버 프로세스의 실행 상태, 또는 방화벽 규칙에 있을 가능성이 높다.

7.1.2 TURN 서버 검증

coturn 패키지에 포함된 turnutils_uclient 유틸리티는 TURN 서버의 기능을 테스트하는 데 매우 유용하다. Nextcloud 서버나 클라이언트가 아닌, 외부의 다른 서버에서 이 명령어를 실행하여 공용 인터넷을 통한 접근성을 테스트해야 한다.27

turnutils_uclient -p 3478 -W "your_static_auth_secret" -v turn.example.com

• -p 3478: TURN 서버 포트

• -W "...": turnserver.conf에 설정된 static-auth-secret 값

• -v: 상세 정보 출력

• turn.example.com: TURN 서버의 도메인

명령 실행 결과 “Total lost packets 0“과 “Average round trip delay“와 같은 성공적인 통계가 출력되면 TURN 서버가 정상적으로 작동하고 있는 것이다. 여기서 실패한다면 coturn 설정(external-ip 등)이나 방화벽의 3478 포트(TCP/UDP) 규칙을 재점검해야 한다.

7.2 Nextcloud 관리자 페이지 상태 확인

명령줄 테스트가 성공했다면, Nextcloud 관리자 페이지(설정 > 관리 > Talk)로 돌아가서 최종 확인을 한다. 5부에서 입력한 TURN 서버와 고성능 백엔드 설정 항목 옆에 녹색 체크 표시(✅)가 나타나는지 확인하라.14 만약 빨간색 X 표시나 오류 메시지가 표시된다면, 이는 Nextcloud 서버가 백엔드 서비스와 통신하는 데 실패했음을 의미한다. 이 경우 URL, 포트, 공유 비밀번호 값이 정확한지 다시 한번 확인해야 한다.

7.3 주요 서비스 로그 확인 방법

문제가 지속될 경우, 각 서비스의 로그 파일을 확인하는 것이 가장 확실한 해결 방법이다.

• coturn 서버 로그:

sudo journalctl -u coturn -f 14

• 시그널링 서버 로그 (수동 설치):

sudo journalctl -u signaling -f 20

• HPB Docker 컨테이너 로그:

sudo docker logs -f nextcloud-talk-hpb

• 리버스 프록시 로그 (Nginx 예시):

sudo tail -f /var/log/nginx/error.log

sudo tail -f /var/log/nginx/access.log

로그는 서비스 시작 오류, 인증 실패, 연결 거부 등 문제의 근본 원인에 대한 구체적인 단서를 제공한다.

7.4 일반적인 오류 시나리오 및 해결 방안

• 시나리오 1: 2명까지는 통화가 되지만 3명 이상 참여 시 연결이 불안정하거나 실패한다.

• 원인: HPB가 작동하지 않고 시스템이 P2P 방식으로 대체 작동하는 전형적인 증상이다.

• 해결: 시그널링 서버가 실행 중인지, 리버스 프록시 설정이 올바른지 확인하라. 6.1의 curl 테스트를 통해 시그널링 서버의 접근성을 먼저 검증해야 한다.

• 시나리오 2: 외부 네트워크에 있는 사용자 간의 1:1 통화도 실패한다.

• 원인: TURN 서버가 제 기능을 하지 못하고 있을 가능성이 높다. P2P 연결이 불가능한 상황에서 미디어 릴레이가 이루어지지 않는 것이다.

• 해결: 6.1의 turnutils_uclient 테스트를 외부 서버에서 실행하여 TURN 서버의 공용 접근성을 확인하라. 방화벽에서 3478 포트(TCP/UDP)가 모두 개방되었는지, turnserver.conf의 external-ip가 정확한지 재점검하라.

• 시나리오 3: Nextcloud 관리자 페이지에서 HPB 설정에 빨간색 X가 표시된다.

• 원인: Nextcloud 서버가 시그널링 서버 URL에 도달할 수 없거나 인증에 실패했다.

• 해결: 관리자 페이지에 입력된 HPB URL이 정확한지 확인하라. Nextcloud 서버의 셸에서 curl 명령어로 해당 URL에 접속을 시도해 보라. 또한, Nextcloud에 입력한 ’공유 비밀번호’와 시그널링 서버 설정 파일의 비밀번호가 일치하는지 확인하라.

• 시나리오 4: 브라우저 개발자 콘솔에 ‘WebSocket connection failed’ 오류가 나타난다.

• 원인: 리버스 프록시가 웹소켓 트래픽을 제대로 처리하지 못하고 있다.

• 해결: 3.4절의 리버스 프록시 설정을 다시 검토하라. Nginx의 경우 Upgrade 및 Connection 헤더 설정이 누락되지 않았는지, Apache의 경우 mod_proxy_wstunnel 모듈이 활성화되고 RewriteRule이 올바르게 작성되었는지 확인해야 한다.

8. 결론

이 보고서에서 제시된 절차를 성공적으로 완수함으로써, 관리자는 Nextcloud Talk 인스턴스를 단순한 소규모 채팅 도구에서 다수의 사용자가 안정적으로 참여할 수 있는 강력하고 확장 가능한 자체 호스팅 커뮤니케이션 플랫폼으로 탈바꿈시켰다.7 “고성능 백엔드가 구성되지 않았습니다“라는 경고는 이제 사라졌으며, 이는 단순히 UI의 경고 메시지 하나를 제거한 것을 넘어 시스템의 근본적인 아키텍처를 개선했음을 의미한다.

P2P 메시 방식의 한계를 극복하고 중앙 집중식 허브-앤-스포크 모델을 도입함으로써, 이제 각 사용자는 과도한 네트워크 및 CPU 부담 없이 다자간 화상 회의에 원활하게 참여할 수 있다. 이는 조직의 협업 효율성을 높이고, 원격 근무 환경에서의 커뮤니케이션을 강화하는 데 결정적인 역할을 할 것이다.

무엇보다 이 모든 과정은 자체 서버 인프라 내에서 이루어졌다. 이는 Nextcloud의 핵심 철학인 ’데이터 주권’을 실현하는 중요한 성과다. 외부 상용 서비스에 의존하지 않고 모든 민감한 대화와 공유 파일을 자체적으로 통제함으로써, 조직은 최고 수준의 보안과 프라이버시를 유지할 수 있다.31 초기 설정 과정의 복잡성은 강력하고, 안전하며, 독립적인 커뮤니케이션 솔루션을 소유하게 되는 장기적인 가치에 비하면 충분히 감수할 만한 투자다. 이제 귀사의 Nextcloud Hub는 진정한 의미의 올인원 협업 플랫폼으로 거듭났다.

9. 참고 자료

1. 30.0.4에서 30.0.5로 업그레이드 - 새로운 오류 경고: “고성능 백엔드 없음…” : r/NextCloud, https://www.reddit.com/r/NextCloud/comments/1i3egfy/upgrade_from_3004_to_3005_new_error_warning_no/?tl=ko
2. Upgrade from 30.0.4 to 30.0.5 - New Error Warning: “No High Performance Backend…..” : r/NextCloud - Reddit, https://www.reddit.com/r/NextCloud/comments/1i3egfy/upgrade_from_3004_to_3005_new_error_warning_no/
3. Hide “No High-performance backend configured” message · Issue #14142 · nextcloud/spreed - GitHub, https://github.com/nextcloud/spreed/issues/14142
4. Quick install - Nextcloud Talk API documentation - Read the Docs, https://nextcloud-talk.readthedocs.io/en/latest/quick-install/
5. What’s the future of Talk and the HPB? - Talk (spreed) - Nextcloud community, https://help.nextcloud.com/t/whats-the-future-of-talk-and-the-hpb/228081
6. Talk, High-performance backend on truenas scale - ℹ️ Support - Nextcloud community, https://help.nextcloud.com/t/talk-high-performance-backend-on-truenas-scale/218575
7. I set up the “high performance backend” for Nextcloud Talk and it’s pretty cool! - LowEndTalk, https://lowendtalk.com/discussion/203384/i-set-up-the-high-performance-backend-for-nextcloud-talk-and-its-pretty-cool
8. How to configure talk HPB with Docker · nextcloud-snap/nextcloud-snap Wiki - GitHub, https://github.com/nextcloud-snap/nextcloud-snap/wiki/How-to-configure-talk-HPB-with-Docker
9. Installation of Nextcloud Talk High Performance Backend, https://portal.nextcloud.com/article/Nextcloud-Talk/High-Performance-Backend/Installation-of-Nextcloud-Talk-High-Performance-Backend
10. Setup Signaling server (High-performance backend) for Nextcloud Talk - Najigram.com, https://najigram.com/2024/01/setup-signaling-server-high-performance-backend-for-nextcloud-talk/
11. schklom/nextcloud-spreed-signaling-strukturag - Docker Image, https://hub.docker.com/r/schklom/nextcloud-spreed-signaling-strukturag
12. Setup nextcloud-spreed-signaling standalone server on Ubuntu | morph027_blog, https://morph027.gitlab.io/blog/nextcloud-spreed-signaling/
13. coturn TURN server - Synapse - GitHub Pages, https://matrix-org.github.io/synapse/latest/setup/turn/coturn.html
14. NextCloud Talk - coturn server - hope for some basic trouble-shooting help · MichaIng DietPi · Discussion #6417 - GitHub, https://github.com/MichaIng/DietPi/discussions/6417
15. How to setup and configure TURN server using coTURN? - Metered Video, https://www.metered.ca/blog/coturn/
16. coturn/coturn: coturn TURN server project - GitHub, https://github.com/coturn/coturn
17. How to set up and configure your own TURN server using Coturn | GabrielTanner, https://gabrieltanner.org/blog/turn-server/
18. Want to be sure that my CoTURN server works properly, need help about testing : r/WebRTC, https://www.reddit.com/r/WebRTC/comments/12l4l3x/want_to_be_sure_that_my_coturn_server_works/
19. HowTo: Setup Nextcloud Talk with TURN server, https://help.nextcloud.com/t/howto-setup-nextcloud-talk-with-turn-server/30794
20. Complete Guide on How to Setup a Nextcloud Spreed Signaling …, https://kaamoscreations.com/blog/how-to-setup-nextcloud-spreed-signaling-server-ie-talk-high-performance-backend-debian-bookworm-12
21. nextcloud/all-in-one: The official Nextcloud installation method. Provides easy deployment and maintenance with most features included in this one Nextcloud instance. - GitHub, https://github.com/nextcloud/all-in-one
22. How to install the High-Performance backend for Nextcloud Talk? - GitHub Pages, https://szaimen.github.io/Nextcloud-NAS-Guide/docs/hpb
23. Signaling server behind Apache - Appliances (Docker, Snappy, VM, NCP, AIO), https://help.nextcloud.com/t/signaling-server-behind-apache/101249
24. coTURN - Nextcloud Talk API documentation - Read the Docs, https://nextcloud-talk.readthedocs.io/en/latest/coturn/
25. strukturag/nextcloud-spreed-signaling: Standalone … - GitHub, https://github.com/strukturag/nextcloud-spreed-signaling
26. Talk + external signaling server (HPB) - only working with mobile app, https://help.nextcloud.com/t/talk-external-signaling-server-hpb-only-working-with-mobile-app/103122
27. TURN server configuration - Nextcloud Talk API documentation - Read the Docs, https://nextcloud-talk.readthedocs.io/en/latest/TURN/
28. Can someone explain how Nextcloud Talk is supposed to work? - ℹ️ Support, https://help.nextcloud.com/t/can-someone-explain-how-nextcloud-talk-is-supposed-to-work/152867
29. Create STUN/TURN server for Talk - Unix Server Tech Knowledge Base, https://kb.unixservertech.com/software/nextcloud/stun
30. Install coturn for nextcloud STUN and TURN services - jason schaefer . com, https://jasonschaefer.com/install-coturn-for-nextcloud-stun-and-turn-services/
31. Calls, chat and video conferencing with Nextcloud Talk, https://nextcloud.com/talk/