Collabora Online에서 발생하는 "소켓 연결이 예기치 않게 종료되었습니다" 오류 해결: WebSocket 및 프록시 확인

Collabora Online은 언뜻 보기에 정상적으로 작동하는 것처럼 보일 수 있지만, 편집기가 실제 WebSocket 연결을 시도하는 순간 오류가 발생할 수 있습니다. 흔히 나타나는 증상은 문서 로딩이 시작된 후 소켓 연결이 예기치 않게 종료되었다는 메시지가 표시되고, 때로는 wss://브라우저에서 요청 실패 오류가 함께 발생하는 것입니다. 2026 버전에서는 다른 설정을 변경하기 전에 이 문제를 먼저 확인해야 하는 특정 이유가 있습니다. 26.04 브랜치에서 더 간결한 WebSocket URL이 도입되었는데, 기존의 리버스 프록시 규칙이 이 URL과 충돌할 수 있기 때문입니다.

Collabora의 공식 CODE 26.04 릴리스 노트에 따르면 2026년 6월 8일에 출시된 CODE 26.04.1 버전에서는 Apache2 리버스 프록시 사용자가 새로운 간소화된 WebSocket URL에 맞게 ProxyPass 규칙을 변경해야 했습니다. 이후 26.04.2.x 릴리스 노트에서는 새 경로를 사용할 수 없는 경우 CODE가 기존 URL로 대체될 수 있으며, 관리자에게 현재 프록시 권장 사항을 안내하는 감사 경고를 출력한다고 명시하고 있습니다. Collabora Online 엔터프라이즈 버전 26.04도 2026년 현재 최신 버전이므로, 관리자는 이전 24.04 또는 25.04 버전 가이드에서 복사한 프록시 구성을 최신 공급업체 문서와 비교한 후 문제를 단순한 네트워크 오류로 간주해야 합니다.

오류가 실제로 의미하는 바는 무엇일까요?

이 메시지는 단일한 근본 원인을 명시하지 않습니다. 이는 브라우저와 Collabora 간의 WebSocket 연결이 성공적으로 업그레이드되지 않았거나, 연결은 되었지만 예기치 않게 종료되었음을 의미합니다. 이러한 차이점은 해결 방법이 다르기 때문에 중요합니다.

1. 26.04 업그레이드 이후에 오류가 발생했는지 확인하십시오.

25.04 또는 이전 버전의 CODE 이미지에서 26.04로 업그레이드한 직후 문제가 발생했다면, 리버스 프록시를 가장 먼저 의심해 봐야 합니다. 이는 추측이 아닙니다. Collabora는 26.04 릴리스 노트에 간소화된 WebSocket URL 변경 사항을 명시했으며, 공식 프로젝트 이슈에서도 26.04.1로 업그레이드 후 Apache 프록시 규칙을 수정하기 전까지 WebSocket 연결이 실패하는 문제가 보고되었습니다.

단순히 이전 버전으로 다운그레이드하고 기존 프록시를 그대로 두는 방식으로 문제를 해결하지 마십시오. 롤백은 임시 복구 조치일 수 있지만, 근본적인 해결책은 실행하려는 버전에 맞춰 프록시를 업데이트하는 것입니다. Apache의 경우, 26.04 이전 버전의 프록시 설정이 아닌 현재 Collabora Online 프록시 설정을 사용하십시오. Collabora의 26.04 WebSocket 문제 기록에는 Apache 규칙을 업데이트하여 문제가 해결된 사례가 나와 있습니다.

2. HTTP는 작동하지만 WebSocket은 작동하지 않는 경우를 증명하십시오.

먼저 일반적인 Collabora 엔드포인트를 테스트하십시오.

curl -I https://office.example.com/hosting/discovery
curl -I https://office.example.com/hosting/capabilities

성공적인 응답은 DNS, TLS, 프런트엔드 프록시 및 Collabora 서비스의 일부에 접근 가능함을 증명합니다. 하지만 문서 편집 기능이 작동한다는 것을 보장하는 것은 아닙니다 . 편집기는 /cool/다른 프록시 요구 사항을 가진 WebSocket 경로에 의존합니다.

다음으로 브라우저 개발자 도구를 열고 오류를 재현한 다음 WS 필터를 사용하여 네트워크 패널을 검사하십시오. WebSocket 핸드셰이크가 성공하면 일반적으로 HTTP 연결이 업그레이드됩니다. RFC 6455는 업그레이드가 성공했을 때 서버 응답을 HTTP 상태 코드 101로 정의합니다. 만약 400, 404, 405, 502 오류가 발생하거나 요청이 즉시 실패하는 경우, 해당 타임스탬프를 리버스 프록시 및 coolwsd 로그와 비교하십시오.

3. Nginx WebSocket 경로 및 헤더를 수정합니다.

Nginx의 경우 중요한 속성은 간단합니다. 요청은 Collabora /cool/경로에 도달해야 하고, 프록시는 일반적인 WebSocket Upgrade 흐름을 위해 HTTP/1.1을 사용해야 하며, Upgrade및 Connection헤더가 전달되어야 하고, 원래 호스트가 유지되어야 하며, 읽기 시간 제한은 편집 세션에 충분히 길어야 합니다.

Collabora SDK 매뉴얼에는 오랫동안 Upgrade, Connection, Host, 그리고 긴 를 포함하는 전용 WebSocket 위치가 표시되어 왔습니다 proxy_read_timeout. Collabora 프로젝트의 공식 문서 문제에서도 더 넓은 경로에 WebSocket 헤더가 필요하다고 언급했습니다 /cool. 보수적인 26.04 호환 패턴은 다음과 같습니다.

location ^~ /cool/ {
    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-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 3600s;
}

기존에 운영 중인 프로덕션 환경 구성에 이 내용을 붙여넣기 전에 업스트림 주소, TLS 모델, 경로 처리 및 기존 보안 제어를 반드시 수정해야 합니다. 올바른 방법은 현재 Collabora의 경로 및 헤더 요구 사항을 충족하면서 토폴로지를 유지하는 것입니다.

타임아웃 값이 중요한 이유

WebSocket 편집 세션은 장시간 지속됩니다. Collabora 프로젝트의 현재 Helm 값은 이 점을 명시적으로 설명하고 있으며, 번들로 제공되는 Nginx 프록시에 대해 긴 프록시 타임아웃을 사용합니다. 만약 엣지 로드 밸런서, Kubernetes 인그레스, CDN, 방화벽 또는 리버스 프록시가 애플리케이션이 예상하는 시간보다 빨리 유휴 연결을 닫는 경우, 사용자는 한동안 정상적으로 편집하다가 일정한 간격으로 연결이 끊어질 수 있습니다.

오류가 매번 거의 같은 시간(초) 후에 발생하는 경우, Nginx의 타임아웃만 늘리는 대신 경로상의 모든 중간 단계를 점검해야 합니다. 가장 짧은 타임아웃 값이 우선합니다.

4. TLS 종료를 일관되게 유지하십시오.

일반적인 배포 방식에서는 HTTPS 트래픽이 Nginx, Apache, HAProxy, Traefik 또는 인그레스 컨트롤러에서 종료되고 일반 HTTP 트래픽이 Collabora의 9980번 포트로 전달됩니다. 이러한 구성에서 Collabora의 공식 설정은 백엔드에서 TLS 트래픽이 프록시에서 종료된다는 사실을 알도록 요구합니다. SDK 매뉴얼은 이 모델에 대한 ssl.enable=false자세한 내용을 제공합니다 .ssl.termination=true

Docker 배포의 경우, 이는 일반적으로 Collabora의 추가 매개변수를 통해 표현됩니다.

--o:ssl.enable=false --o:ssl.termination=true

TLS 연결이 상위 네트워크에서 완전히 종료된 경우에만 이 설정을 사용하십시오. 프록시가 HTTPS를 통해 Collabora에 연결하는 경우, 두 가지 모델을 혼합하지 말고 해당 토폴로지를 일관되게 구성하십시오. 두 모델이 일치하지 않으면 잘못된 스키마, 잘못된 WebSocket URL, 인증서 오류 또는 업그레이드를 중단시키는 리디렉션이 발생할 수 있습니다.

5. coolwsd 로그에서 호스트 및 오리진 불일치를 확인하세요.

Collabora는 WebSocket 오리진을 검증합니다. 로그에 Rejecting WebSocket upgrade오리진과 예상 호스트가 뒤따르는 문구가 포함되어 있는 경우, 임의로 허용 헤더를 추가하기보다는 외부 호스트 이름/포트 관계를 수정해야 합니다. Collabora 공식 이슈 트래커에는 구성된 서버 이름이 :443명시적인 포트 없이 브라우저 오리진과 일치하지 않는 예시가 문서화되어 있습니다.

유용한 명령어는 설치 환경에 따라 다릅니다.

docker logs collabora --tail 200
journalctl -u coolwsd --since "10 minutes ago"
nginx -t
apachectl configtest

WS 요청 실패와 동시에 발생하는 첫 번째 오류를 찾아보세요. 업그레이드 거부, 잘못된 URI 구문, 예상치 못한 호스트 또는 업스트림을 사용할 수 없음과 같은 메시지는 일반적인 브라우저 팝업보다 더 유용한 조치를 취할 수 있는 정보입니다.

6. 크로뮴 기반 브라우저에서만 오류가 발생하는 경우 HTTP/2 또는 HTTP/3 처리 방식을 점검하십시오.

이는 비교적 드문 경우이지만, 서버를 재구축하기 전에 확인해 볼 가치가 있습니다. Collabora 프로젝트는 프록시가 HTTP/2 CONNECT WebSocket 요청을 coolwsd로 직접 전달하여 405 Method Not Allowed 오류를 수신한 Chromium 관련 사례를 보고한 바 있습니다. 또 다른 문제에서는 특정 프록시 경로에서 HTTP/3/QUIC 관련 문서 로딩 실패가 기록되어 있습니다. 이러한 보고는 HTTP/2 또는 HTTP/3를 항상 비활성화해야 한다는 의미가 아니라, 중간 매개체가 클라이언트 동작을 Collabora가 지원하는 WebSocket 연결로 변환해야 한다는 것을 의미합니다.

동일한 계정과 문서에서 Firefox는 정상적으로 작동하지만 Chrome은 작동하지 않는 경우, 프록시에서 프로토콜과 상태 코드를 캡처하십시오. 환경에 호환되는 대안이 없는 경우를 제외하고는, 최신 프로토콜을 전역적으로 비활성화하는 것보다 프록시/인그레스 동작을 수정하는 것이 좋습니다.

7. 구성 유효성 검사 후 재시작하십시오.

먼저 프록시의 구문 테스트를 수행한 다음, 반복적인 재시작을 하지 말고 새로 고침하십시오.

sudo nginx -t && sudo systemctl reload nginx
sudo apachectl configtest && sudo systemctl reload apache2

컨테이너의 경우, 자체 환경이나 coolwsd설정을 변경했을 때만 Collabora 서비스를 재시작하십시오. 프록시 설정만 변경한 경우에는 일반적으로 프록시를 다시 로드하기만 하면 됩니다.

수정 사항을 직접 확인하는 방법

단일 문서 열기 성공 여부에 의존하는 대신, 간략한 검증 절차를 사용하십시오.

• 동일한 공용 호스트 이름을 통해 사용자가 액세스할 수 있는지 /hosting/discovery확인 하십시오 ./hosting/capabilities
• 문서를 열고 브라우저의 웹 서비스 요청이 4xx/5xx 오류를 반환하는 대신 성공적으로 업그레이드되는지 확인하십시오.
• 몇 가지 수정 사항을 입력하고, 이전 오류 발생 간격보다 더 오래 기다린 후 연결이 안정적인지 확인하십시오.
• 문서를 저장하고 닫은 다음 다시 열어 WOPI 왕복이 정상적으로 이루어지는지 확인하십시오.
• coolwsd 및 프록시 로그에서 WebSocket 업그레이드 거부, URI 구문 분석 오류 또는 반복적인 재연결 루프가 있는지 확인하십시오.
• 배포 환경에 로드 밸런서 또는 인그레스가 있는 경우, 9980번 포트에 직접 연결하는 대신 실제 프로덕션 경로를 통해 테스트를 반복하십시오.

어떤 해결책을 선택해야 할까요?

26.04 버전으로 업그레이드했고 Apache를 사용하는 경우, Collabora에서 해당 변경 사항을 명시적으로 문서화했으므로 프록시 규칙을 업데이트하는 것이 최우선 과제입니다. 연결이 일정 시간 후에 끊어지는 경우, 모든 네트워크 홉의 타임아웃 설정을 확인하십시오. 모든 브라우저에서 연결이 즉시 끊어지는 경우, /cool/라우팅, 업그레이드 헤더, 호스트/출처 일관성 및 TLS 종료를 확인하십시오. 특정 브라우저 제품군에서만 문제가 발생하는 경우, Collabora 자체를 변경하기 전에 HTTP 프로토콜 처리 방식을 비교해 보십시오.

핵심은 "소켓 연결이 예기치 않게 종료되었습니다"라는 메시지를 Collabora 애플리케이션 충돌로 간주하지 않는 것입니다. 많은 배포 환경에서 편집기, 검색 엔드포인트 및 WOPI 호스트는 정상적으로 작동하지만, 역방향 프록시가 실시간 편집에 가장 중요한 연결 유형인 장시간 유지되는 WebSocket 연결을 제대로 처리하지 못하는 경우가 있습니다.

공식 참고 자료

• Collabora CODE 26.04 릴리스 노트
• Collabora Online 26.04 릴리스 노트
• Collabora Online SDK 프록시 설정
• CollaboraOnline/온라인 이슈 #15918: 26.04 업그레이드 후 WebSocket 오류 발생
• CollaboraOnline/온라인 이슈 #13751: 프록시 문서의 WebSocket 헤더
• Collabora Online Helm 프록시 타임아웃 기본값
• RFC 6455: 웹소켓 프로토콜