Nginx 환경에서 Collabora Online을 구성하는 방법

제대로 작동하는 리버스 프록시의 역할

Nginx 뒤에 Collabora Online을 안정적으로 배포하면 사용자는 편집기에 대한 공용 HTTPS 주소를 하나 확보하는 동시에 Collabora 서비스는 사설 네트워크에서 운영할 수 있습니다. 편집기는 브라우저 자산을 로드하고, 오피스 기능을 검색하고, 연결된 스토리지 플랫폼을 통해 문서를 열고, 편집 중에 WebSocket 연결을 유지해야 합니다. Nginx 구문 검사만으로는 이러한 경로가 제대로 작동하는지 보장할 수 없습니다.

이 예제는 독립형 Collabora 서버 또는 CODE 컨테이너가 9980번 포트에서 수신 대기하고, Nginx가 서비스를 제공하며 office.example.com, TLS 연결이 Nginx에서 종료된다고 가정합니다. 호스트 이름과 인증서 경로는 실제 환경에 맞게 변경하십시오. 백엔드 주소는 127.0.0.1:9980Nginx와 Collabora가 동일한 호스트를 공유하고 서비스가 루프백 인터페이스에 바인딩된 경우에만 적용됩니다. 별도의 컨테이너를 사용하는 경우, 사설 Docker 네트워크에서 Collabora 서비스 이름(예: `/cobb/collabora.php`)을 사용하십시오 http://collabora:9980.

Nginx를 변경하기 전에

공용 DNS 이름이 프록시로 확인되는지, TLS 인증서가 해당 이름을 정확히 포함하는지, 그리고 Nginx가 내부 주소로 Collabora에 연결할 수 있는지 확인하십시오. Docker를 사용하는 경우 두 서비스를 사용자 정의 네트워크에 연결하고 Collabora 포트를 공개적으로 노출하지 마십시오. Nginx가 호스트에서 실행되는 경우 컨테이너 포트를 루프백 인터페이스에 바인딩하십시오(예: `/etc/npm-float`) 127.0.0.1:9980:9980. 방화벽은 Collabora 백엔드 포트가 아닌, 서비스를 제공하려는 공용 웹 포트를 노출해야 합니다.

TLS 구성 방식을 하나 선택하십시오. 아래 구성은 브라우저에서 Nginx까지는 TLS를 사용하고, Collabora까지는 신뢰할 수 있는 프라이빗 홉을 통해 일반 HTTP를 사용합니다. 이는 TLS 종료 방식입니다. 프록시와 Collabora 간에도 암호화가 필요한 정책이 있는 경우, 업스트림에는 HTTPS를 사용하고 Nginx가 백엔드 인증서를 신뢰하도록 구성하십시오. 스키마만 변경하지 마십시오 . 서버 측 TLS 설정이 실제 Collabora 리스너 설정과 일치해야 합니다. Collabora는 Nginx 리버스 프록시 가이드 와 25.04 SDK 설명서proxy_pass 에서 두 가지 프록시 구성 방식을 모두 설명합니다 .

Collabora의 프록시 인식 TLS 옵션을 설정합니다.

TLS 종료를 위해 Collabora 서비스 coolwsd에 ` ssl.enable=false--TLS ssl.termination=true...coolwsd.xmlextra_params

이 설정은 프록시에서 백엔드로의 연결이 HTTP를 사용하더라도 외부 연결이 프록시에 의해 보호된다는 것을 Collabora에 알려줍니다. 이 설정은 공개 인증서를 설치하거나 DNS를 구성하거나 스토리지 서버가 Collabora를 사용하도록 승인하는 것은 아닙니다. 스토리지 플랫폼에 따라 WOPI 호스트 허용 목록 또는 통합 설정을 별도로 구성하십시오.

편집기 경로가 전달되도록 Nginx를 구성합니다.

Nginx는 검색 및 브라우저 리소스를 전달하고 대화형 편집에 사용되는 WebSocket 업그레이드를 유지해야 합니다. 다음은 단일 서버 예시입니다. 가상 호스트 내부가 아닌 메인 서버와 같은 mapNginx 컨텍스트에서 정의하십시오.httpnginx.conf

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

Nginx에 포함된 사이트 구성에 서버 블록을 추가하세요. 이는 TLS 인증서가 이미 설치되어 있고 프록시와 Collabora 간의 연결이 HTTP라고 가정합니다.

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

    ssl_certificate     /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
    }
}

로 시작하는 경로는 /cool주요 WebSocket 및 편집기 요청을 전달하며, /lool호환성을 위해 기존 경로도 포함합니다. Nginx의 WebSocket 프록시는 HTTP/1.1 업그레이드 헤더를 필요로 하는데 , 이는 Upgrade및 Connection헤더가 홉별 헤더이기 때문입니다. 긴 읽기 시간 제한은 일반적인 짧은 프록시 시간 제한으로 인해 활성 편집 연결이 끊어지는 것을 방지하는 데 도움이 됩니다. Nginx WebSocket 프록시 문서 및 프록시 모듈 참조를 확인하세요 .

업스트림에서 HTTPS를 사용하려면 백엔드 URL을 변경하고 https://Nginx의 업스트림 인증서 검증 및 신뢰할 수 있는 인증서 체인을 적절하게 구성하십시오. 인증서 검증을 영구적인 해결 방법으로 비활성화하지 마십시오. Nginx가 다른 컨테이너에 있는 경우 루프백 주소를 Collabora 서비스 이름으로 바꾸십시오. 127.0.0.1프록시 컨테이너 내부에서는 해당 프록시 컨테이너를 가리키도록 설정해야 합니다.

전용 호스트 이름 대신 URI 접두사(예: `/`)를 사용하는 경우 /collabora/, 구성 및 Collabora에서 생성된 검색 URL에 추가적인 경로 처리가 필요합니다. 플랫폼에서 하위 경로 배포를 명시적으로 지원하지 않는 한, 전용 호스트 이름부터 시작하십시오. 루트에서 요청을 전달하는 서버 블록은 검색에서 생성된 URL이 접두사 아래에서 자동으로 작동하도록 만들지 않습니다.

각 레이어를 다시 로드하고 확인하십시오.

Nginx 설정을 적용하기 전에 유효성을 검사하고, 적용 후 서비스를 다시 시작하십시오.

sudo nginx -t
sudo systemctl reload nginx

구문 검사에 실패하면 먼저 오류가 보고된 파일과 줄을 수정하십시오. 재로드가 성공하면 Nginx가 구성을 수락한 것이지 백엔드, 인증서 또는 WebSocket 경로가 작동하는 것은 아닙니다. DNS 및 인증서 유효성을 별도로 확인한 다음 공개 호스트 이름을 통해 두 Collabora 엔드포인트에 요청하십시오.

curl -fsS https://office.example.com/hosting/discovery | head
curl -fsS https://office.example.com/hosting/capabilities

검색 엔드포인트는 Nginx 404 페이지나 로그인 페이지가 아닌 XML을 반환해야 합니다. 기능 요청 시에는 Collabora의 응답이 반환되어야 합니다. 검색 XML의 편집기 URL을 검사해 보세요. 컨테이너 이름이나 내부 전용 주소가 아닌 공개 HTTPS 호스트 이름과 접근 가능한 경로를 사용해야 합니다. 아래 샘플 이미지는 확인해야 할 응답 유형을 보여줍니다. 표시된 값은 예시일 뿐 실제 서버 출력값이 아닙니다.

마지막으로, 문서 플랫폼을 https://office.example.comCollabora 서버로 설정하여 테스트 문서를 열어보세요. 편집기가 로드되고 입력, 저장, 문서 다시 열기 동안 응답성을 유지하는 것이 성공의 지표입니다. 브라우저 개발자 도구에서 WebSocket 요청이 /cool/성공적으로 업그레이드되었는지 확인하고, HTTP 상태 코드가 101 Switching Protocols예상되는 WebSocket 핸드셰이크 결과인지 확인하세요. 예시로 표시된 상태 코드를 서버가 이 검사를 통과했다는 증거로 간주해서는 안 됩니다.

실패를 그 증상으로 파악하세요.

• 502 Bad Gateway: Nginx가 업스트림에 연결할 수 없습니다. 서비스 이름, 포트, 컨테이너 네트워크, 리스너 및 로그를 확인하십시오. 컨테이너가 분리되어 있는 경우 프록시 컨테이너의 루프백 주소를 사용하지 마십시오.
• 검색 또는 브라우저 자산에서 404 오류 발생 시: 요청이 올바른 가상 호스트에 도달하고, 의도치 않은 URI 재작성 없이 해당 위치가 경로를 전달하는지 확인하십시오. 백엔드 URL뿐만 아니라 공개 URL도 테스트하십시오.
• 편집기가 로드되지만 멈추거나 연결이 끊어지는 경우: 요청을 검사하십시오 /cool/.../ws. 업그레이드 헤더 누락, HTTP/1.0 업스트림 연결, 짧은 시간 초과 또는 연결을 버퍼링하는 프록시로 인해 편집이 중단될 수 있습니다. 문서가 활성화된 동안 요청이 업그레이드되고 연결된 상태로 유지되는지 확인하십시오.
• 승인되지 않은 WOPI 호스트: 프록시는 정상일 수 있지만 Collabora에서 스토리지 플랫폼 연결을 거부할 수 있습니다. 실제 WOPI 호스트 이름이 Collabora의 허용 목록 및 플랫폼 커넥터 구성과 일치하는지 확인하십시오. 백엔드를 공용 인터넷에 개방하는 방식으로 이 문제를 해결하지 마십시오.
• 혼합 콘텐츠 또는 인증서 경고: 공개 편집기 URL과 검색에 사용되는 URL이 HTTPS를 사용하고 인증서가 호스트 이름과 일치하는지 확인하십시오. Nginx에서 TLS를 종료하는 경우 Collabora의 TLS 종료 설정도 확인하십시오.

이러한 검사를 통과하면 Collabora 백엔드를 비공개로 유지하고, 구성 요소를 업그레이드할 때 Nginx 및 Collabora 로그를 모두 모니터링하십시오. 이 단일 업스트림 예제에서는 고가용성, 로드 밸런싱 또는 문서별 세션 선호도를 구성하지 않습니다. 여러 Collabora 복제본을 사용하는 경우, 관련 Collabora 컨트롤러 또는 로드 밸런서의 배포 지침을 따르고 프로덕션 트래픽을 라우팅하기 전에 문서 선호도를 테스트하십시오.

출처 및 버전 정보

구성 세부 정보는 2026년 10월 6일에 Collabora의 프록시 문서 및 25.04 SDK 설명서, 그리고 Nginx의 WebSocket 및 프록시 모듈 참조 자료를 기준으로 확인되었습니다. 패키지 및 컨테이너 옵션은 Collabora 릴리스에 따라 다를 수 있으므로 적용하기 전에 실행 중인 버전의 설정 이름을 확인하십시오. 이 문서는 특정 스토리지 플랫폼을 가정하거나 실제 배포 환경을 증명하는 것은 아닙니다.