WebSocket 연결을 깨뜨리지 않고 Collabora를 Nginx 뒤에 설치하는 방법

Collabora를 Nginx의 전용 HTTPS 호스트 이름에 배치하고, 편집기 및 검색 경로를 로 포워딩하며 coolwsd, 라이브 소켓 경로에 WebSocket 업그레이드 헤더를 명시적으로 전달하십시오. 단일 호스트의 경우 Nginx는 공용 TLS를 종료하고 개인 인터페이스를 통해 Collabora로 HTTP 요청을 보낼 수 있습니다. Nginx와 Collabora가 서로 다른 컨테이너에서 실행되는 경우, 공유 네트워크에서 대신 Collabora 서비스 이름을 사용하십시오 127.0.0.1.

이 예제는 사용자가 인증서를 열고 https://office.example.comNginx가 인증서를 처리한다고 가정합니다. Collabora의 기본 수신 포트는 9980입니다. 배포 환경에서 접근 가능한 포트를 사용하십시오. `/collabora.com`과 같은 URL 접두사는 https://example.com/collabora/경로 및 서비스 루트 설정이 일치해야 하므로 이 루트 호스트 구성은 변경 없이 적용되지 않습니다.

1. 업스트림 및 WebSocket 연결 맵을 정의합니다.

Nginx 컨텍스트에 Collabora의 업스트림 이름과 클라이언트가 WebSocket을 요청할 때만 http연결 헤더를 설정하는 맵을 추가합니다 . 이 블록은 모든 블록 외부에 배치해야 합니다. Nginx가 다른 경로로 Collabora에 연결하는 경우 주소를 변경하십시오.upgradeserver

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream coolwsd {
    server 127.0.0.1:9980;
}

Nginx 자체가 컨테이너인 경우, 127.0.0.1업스트림은 Collabora 컨테이너가 아닌 해당 Nginx 컨테이너를 가리킵니다. 공유 Docker 네트워크에서는 업스트림을 server collabora:9980;해당 네트워크에서 확인되는 서비스 이름을 사용하여 지정할 수 있습니다.

2. HTTPS 가상 호스트 및 Collabora 경로를 추가합니다.

server`/ `에 대한 HTTPS 블록 내에서 office.example.com브라우저 자산, 검색 엔드포인트, WebSocket 연결 및 나머지 Collabora 경로를 전달합니다. 위치는 Collabora의 프록시 지침을 따릅니다. Nginx가 WebSocket 헤더를 올바르게 적용하도록 특정 소켓 위치는 더 넓은 cool`/` 경로 위에 유지해야 합니다.lool

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/private-key.pem;

    location ^~ /browser {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ^~ /cool/adminws {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

호스트에 맞는 인증서 경로로 교체하십시오. 관리 콘솔을 사용하지 않는 설치 환경이라면 /cool/adminws문서 편집에 해당 위치가 필요하지 않을 수 있지만, 기본 /cool/.../ws경로는 필수적입니다. proxy_read_timeout여기서 1시간은 예시일 뿐이며, 모든 경우에 적용되는 요구 사항은 아닙니다. Nginx의 기본 프록시 읽기 시간 초과는 연속 읽기 간 60초입니다. 세션에 필요한 유휴 시간보다 긴 값을 선택하거나, 지원되는 경우 적절한 WebSocket ping 트래픽을 활용하십시오.

3. Collabora의 TLS 모드를 프록시 홉에 맞게 설정합니다.

Nginx에서 Collabora로 연결되는 프라이빗 홉이 HTTP를 사용하더라도 사용자는 HTTPS를 통해 Collabora에 접속해야 합니다. TLS 종료 구성에서는 coolwsd프록시를 TLS 종료자로 처리하도록 설정하십시오. 즉, 내부 리스너에서는 SSL을 비활성화하고 SSL 종료를 활성화해야 합니다. 패키지 또는 컨테이너 이미지에서 지원하는 방법을 통해 이러한 설정을 적용한 다음, Collabora 설명서에 따라 Collabora를 재시작/재로드하십시오.

신뢰할 수 있는 사설 네트워크에서만 HTTP 업스트림을 사용하고 포트 9980에 대한 공용 액세스를 차단하십시오. Nginx와 Collabora 간에 암호화가 필요한 정책이 있는 경우 HTTPS 업스트림을 사용하고 인증서 확인을 올바르게 구성하십시오. 인증서 불일치를 숨기기 위해 확인을 비활성화하지 마십시오. Collabora의 프록시 설정 문서에서는 프록시에서의 SSL과 프록시와 Nginx 간의 SSL을 구분합니다 coolwsd.

또한 스토리지 통합에서 Collabora URL을 공개 HTTPS 호스트 이름으로 설정하십시오. Nextcloud의 관리 설명서에 따르면 브라우저와 두 서버 모두 HTTP(S)를 통해 서로 통신할 수 있어야 하며, 외부 프로토콜도 일치해야 합니다. WOPI 허용 목록을 예상되는 스토리지 호스트와 Collabora 주소로 제한하십시오. 프록시 라우팅 오류를 해결하기 위해 허용 목록을 광범위하게 완화하지 마십시오.

4. 양쪽에서 구성을 테스트합니다.

Nginx를 다시 로드하기 전에 구문을 확인하세요.

sudo nginx -t
sudo systemctl reload nginx

Nginx가 컨테이너에서 실행되는 경우 해당 컨테이너의 유효성 검사 및 재로드 절차를 사용하십시오. Nextcloud 호스트에서 실제 호스트 이름을 사용하여 공개 Collabora 엔드포인트를 테스트하십시오.

curl -fsS https://office.example.com/hosting/discovery -o /dev/null
curl -fsS https://office.example.com/hosting/capabilities -o /dev/null

사용자 브라우저에서도 해당 HTTPS URL을 열어보세요. 연결 가능성을 확인하는 방법이지만, 검색 응답이 성공적이라고 해서 문서 편집이 제대로 작동하는 것은 아닙니다. 문서를 열고 브라우저의 네트워크 패널을 사용하여 자산이 로드되고 /cool/.../ws연결이 유지되는지 확인하세요. HTTP/1.1 WebSocket 연결이 성공적으로 이루어지면 일반적으로 다음과 같은 메시지가 표시됩니다 101 Switching Protocols. 정확한 표시는 브라우저와 전송 방식에 따라 다를 수 있습니다. 이 표준 설정이 Firefox에서는 작동하지만 Chromium에서는 실패하는 경우 요청 메서드와 프로토콜을 검사하세요. Collabora 25.04 버전에 대한 문제 보고서에서 Chromium WebSocket이 HTTP/2를 사용하여 연결 CONNECT되고 405 오류를 수신하는 문제가 보고되었으며, 2026년 10월 9일 확인 결과 해당 보고서는 여전히 열려 있습니다. 이는 특정 버전에서만 발생하는 문제이며, 모든 경우에 공통적으로 나타나는 현상은 아닙니다. HTTP/2 설정을 변경하기 전에 Collabora, Nginx 및 브라우저 버전을 비교하세요. Collabora 문제 12155를 참조하세요 .

검색에 실패하면 Nginx의 오류 로그를 확인하고 업스트림 호스트 이름, 포트 및 프로토콜을 점검하십시오. 검색은 되지만 편집에 연결할 수 없는 경우 WebSocket 경로, 헤더, 시간 초과 및 Collabora 로그를 확인하십시오. WOPI 인증 오류는 스토리지 호스트 허용 목록과 관련이 있습니다. Nextcloud Office 문제 해결 가이드에서는 브라우저, Nextcloud 및 Collabora에서 연결 가능성을 확인한 다음 두 서버의 로그를 검토할 것을 권장합니다.

Nginx WebSocket 프록싱 가이드에서는 `idle timeout` 및 `idle timeout` 매개변수를 명시적으로 전달해야 하는 이유와 유휴 시간 초과 동작이 중요한 이유를 설명합니다 Upgrade. 지시문 동작에 대한 자세한 내용은 Nginx 프록시 모듈 참조를 확인하세요 . 모든 검사를 통과하면 테스트 문서를 열고, 편집하고, 저장한 후 다시 열어 새 경로를 사용자에게 제공하기 전에 검토하세요.Connection