Collabora 코드를 TLS 종료를 사용하여 Nginx 뒤에서 실행

Collabora CODE를 HTTPS 뒤에 배치한 후 문서 로딩이 지연될 수 있습니다. 이는 프록시와 CODE가 TLS 종료 위치를 다르게 인식하거나 프록시가 WebSocket 트래픽을 차단하기 때문입니다. Nginx에서 공개 인증서를 제공하고, 비공개 CODE 리스너로 포워딩하며, WebSocket 경로를 전달하도록 구성하십시오. CODE 설정은 다음 ssl.enable=false과 같습니다 ssl.termination=true.

이 예제에서는 Docker 호스트에서 Nginx를 사용합니다. 다른 컨테이너에서 프록시를 사용하려면 Docker의 프라이빗 네트워크를 사용하십시오. 버전별 옵션은 Collabora의 프록시 설정 및 CODE Docker 이미지 가이드를 참조하십시오.

SSL 종료 변경 사항을 이해하세요

TLS 종료는 Nginx가 브라우저의 HTTPS 연결 및 인증서를 처리하는 동안 CODE가 그 뒤에서 9980번 포트를 사용하여 HTTP 연결을 사용하는 것을 의미합니다. 해당 리스너는 비공개로 유지해야 합니다. 단일 호스트의 루프백 인터페이스에 바인딩하거나, 비공개 Docker 네트워크를 사용하십시오. 프록시에서 CODE로의 트래픽이 신뢰할 수 없는 네트워크를 통과하는 경우, 해당 링크를 TLS 또는 터널로 보호하십시오.

용기와 증명서를 준비하세요.

1. 공개 호스트 이름을 선택합니다. Nginx 프록시를 가리키는 DNS 레코드를 생성합니다 office.example.com. 해당 호스트 이름에 대한 인증서를 발급받고, 인증서 체인과 개인 키를 프록시에 설치합니다.
2. CODE의 포트는 비공개로 유지하세요. Docker 호스트에 Nginx가 직접 설치된 경우, 컨테이너 포트는 루프백 인터페이스에만 공개하세요. Compose에서 관련 매핑은 다음과 같습니다 . 방화벽 및 네트워크 설계에서 명시적으로 제한하지 않는 한 모든 호스트 인터페이스에 127.0.0.1:9980:9980포트를 공개하지 마세요 .9980:9980
3. CODE의 TLS 모드를 설정합니다. Compose 서비스에서 CODE 구성에 두 가지 옵션을 추가합니다. 아래 예시에서는 이미지 변수를 사용하여 검토 및 테스트한 특정 태그를 지정할 수 있습니다.

services:
  collabora:
    image: ${COLLABORA_CODE_IMAGE}
    restart: unless-stopped
    ports:
      - "127.0.0.1:9980:9980"
    environment:
      extra_params: "--o:ssl.enable=false --o:ssl.termination=true"

테스트를 거쳐 고정된 이미지 태그로 설정하세요 COLLABORA_CODE_IMAGE. WOPI 호스트 허용 목록과 인증 설정을 유지하세요. TLS 종료는 이러한 설정을 대체하지 않습니다. Nginx가 다른 Docker 서비스인 경우 호스트 포트 매핑을 생략하고 http://collabora:9980공유 사설 네트워크로 프록시하세요.

Nginx가 TLS 및 프록시 CODE 트래픽을 종료하도록 구성합니다.

4. HTTPS 가상 호스트를 추가합니다. 공개 Collabora 호스트 이름에 대한 Nginx 서버 블록 내에 다음 위치를 입력합니다. 예시 호스트 이름과 인증서 경로는 실제 경로로 바꿔야 합니다. 이 구성은 루트 수준의 Collabora URL에 대한 것이며, .과 같은 경로 아래에 마운트된 URL에는 적용되지 않습니다 /office/.

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 $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    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 "Upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 36000s;
    }
    location ^~ /cool/adminws {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 36000s;
    }
    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

편집기 자산, 검색 및 기능 경로를 전달합니다. 해당 /cool/.../ws위치 에는 Nginx가 WebSocket 터널링을 수행할 수 있도록 HTTP/1.1 및 Upgrade 헤더가 필요합니다. 읽기 시간 초과가 길어지면 편집 세션이 계속 열려 있게 됩니다. Nginx의 WebSocket 프록싱 문서를/cool/adminws 참조하세요 .

변경 사항을 적용하고 버전별 동작을 확인하세요.

5. Nginx를 다시 로드하기 전에 유효성을 검사하십시오. 명령어를 실행하십시오 nginx -t. Nginx에서 구성 테스트가 성공했다고 보고하는 경우에만 계속 진행하십시오. 그런 다음 시스템의 일반 서비스 명령어를 사용하여 Nginx를 다시 로드하십시오.
6. CODE 컨테이너를 다시 생성합니다. 명령어를 사용하여 Compose 변경 사항을 적용합니다 docker compose up -d collabora. 컨테이너 로그에서 시작 오류를 확인하고 활성 구성에 두 가지 SSL 옵션이 모두 포함되어 있는지 확인합니다.

버전 관련 정보를 드리자면, Collabora 저장소는 2026년 7월 22일에 coolwsd --probeCODE 26.04.2.2 이상 버전의 내장 상태 확인 기능이 프록시에서 TLS 연결이 종료되는 경우에도 9980번 포트에서 HTTPS 연결을 확인할 수 있다는 보고서를 기록했습니다. 이로 인해 컨테이너가 비정상으로 표시되더라도 공용 엔드포인트는 정상적으로 응답할 수 있습니다. 이미지 태그에 대한 문제 기록을 검토하고 , 상태 확인만으로 TLS 오류를 판단하기 전에 공용 엔드포인트와 편집 세션을 테스트해 보시기 바랍니다. 다른 모니터링 도구로 대체되지 않는 한 상태 확인 기록을 유지하십시오.

HTTPS 검색 및 실제 편집 세션을 검증합니다.

https://office.example.com/hosting/discovery브라우저 또는 다른 방법을 통해 요청하십시오 curl. 해당 요청은 공개 HTTPS 호스트 이름을 사용하는 URL과 함께 HTTPS를 통해 WOPI 검색 XML을 반환해야 합니다. 인증서 경고는 호스트 이름 또는 인증서 문제를 나타내고, HTTP URL은 TLS 모드 또는 전달 체계 불일치를 나타내며, 502 오류는 프록시가 CODE에 연결할 수 없음을 나타냅니다.

다음으로, 연결된 WOPI 호스트에서 테스트 문서를 열고 편집이 정상적으로 작동하는지 확인합니다. 브라우저 개발자 도구에서 /cool/.../ws요청이 WebSocket 연결을 설정해야 합니다. 검색은 성공했지만 편집이 멈추는 경우 WebSocket 위치와 헤더를 확인하십시오. 통합 설정에서 WOPI 호스트를 허용하고 해당 호스트를 가리키는지 확인합니다 https://office.example.com.

설정이 성공적으로 완료되었습니다. 인증서가 신뢰할 수 있게 되었고, 검색 시 HTTPS를 사용하며, 9980번 포트는 비공개로 유지되고, 테스트 문서가 WebSocket을 통해 열리고 편집됩니다.