프록시를 통해 Collabora의 WebSocket 연결을 복원합니다.

Collabora Online에서 소켓 연결이 예기치 않게 종료되었다는 오류가 발생하면 먼저 브라우저의 WebSocket 요청이 coolwsd리버스 프록시를 거쳐 전송되는지 확인하십시오. 프록시 경로를 Collabora 버전에 맞게 조정하고, WebSocket 업그레이드 및 URL 경로를 유지한 다음, 브라우저의 네트워크 패널과 서버 로그를 모니터링하면서 문서 하나를 테스트하십시오. Apache 환경에서 CODE 26.04로 업그레이드한 후 문제가 발생한 경우, ProxyPass먼저 Apache 규칙을 확인하십시오. Collabora 26.04 릴리스 노트에는 간소화된 WebSocket URL에 대한 변경 사항이 언급되어 있습니다.

WebSocket은 문서가 열려 있는 동안 Collabora가 브라우저와 서버 간에 사용하는 장시간 지속되는 양방향 연결입니다. 리버스 프록시는 공개 요청을 수락하여 Collabora로 전달하는 서비스입니다. 오류 메시지는 해당 연결을 가리키지만, 프록시가 원인임을 입증하는 것은 아닙니다. WOPI 호스트 거부, 잘못된 공개 URL, TLS 불일치 또는 잘못된 백엔드 설정 또한 세션을 중단시킬 수 있습니다.

변경하기 전에 먼저 경로를 확인하세요.

Collabora 버전 또는 이미지 태그, 프록시 소프트웨어, 공개 Collabora 호스트 이름, 그리고 TLS 연결이 프록시에서 종료되는지 아니면 Collabora에서 종료되는지 여부를 기록해 두십시오. 배포를 변경하지 않고 서비스 이름과 현재 이미지를 확인하십시오.

docker compose ps collabora
docker compose images collabora

Compose 파일에 있는 서비스 이름으로 바꾸세요 collabora. Compose를 사용하지 않는 컨테이너의 경우, 컨테이너와 이미지를 식별하기 위해 `<service name>` docker ps과 `<service name>`을 사용하세요. 태그가 지난주에 테스트했던 버전과 동일한 버전을 가리킨다 docker inspect고 가정하지 마세요 .latest

1. 웹소켓 핸드셰이크가 어디에서 멈추는지 확인하세요.

브라우저에서 개발자 도구를 열고 네트워크를 선택한 다음 WS 또는 WebSocket 으로 필터링 하고 문서를 다시 열어보세요. wss://공개 페이지가 HTTPS인 경우 요청 URL을 사용해야 합니다. 실패한 요청을 선택하고 상태, URL 경로 및 응답 헤더를 기록해 두세요. 핸드셰이크가 성공하면 일반적으로 해당 101 Switching Protocols문서 세션이 활성화되어 있는 동안 연결이 유지됩니다.

• WebSocket 요청이 나타나지 않습니다. 서버 규칙을 수정하기 전에 통합 앱의 Collabora URL, 브라우저 콘솔, DNS 및 리디렉션 또는 혼합 콘텐츠 오류를 확인하십시오.
• 요청이 400 또는 404 오류를 반환하는 경우, 요청된 경로를 프록시가 전달하는 경로 및 설치된 Collabora 버전에서 지원하는 경로와 비교하십시오. coolwsd"잘못되었거나 알 수 없는 요청"이라는 400 오류는 요청이 Collabora에서 허용하지 않는 경로로 도달했음을 의미할 수 있습니다.
• 요청이 502 또는 504 오류를 반환합니다. 프록시가 구성된 Collabora 업스트림에 연결할 수 있는지, 그리고 주소와 포트가 올바른 컨테이너 또는 호스트를 가리키는지 확인하십시오.
• 요청이 101 응답 코드를 반환한 후 연결이 종료됩니다. 프록시, 로드 밸런싱, 방화벽 및 클라이언트 네트워크 유휴 시간 초과 설정을 확인하십시오. WebSocket 연결은 수명이 길기 때문에 유휴 연결을 너무 빨리 닫는 중간 장치는 그렇지 않았다면 성공적으로 연결되었을 연결을 방해할 수 있습니다.

2. 프록시 규칙을 Collabora 버전과 비교하십시오.

사용 중인 프록시 소프트웨어 및 버전에 맞는 Collabora의 최신 리버스 프록시 설정을 사용하십시오 . WebSocket 경로가 WebSocket으로 처리되는지, 프록시가 업그레이드 헤더를 전달하는지, 경로와 인코딩된 쿼리 문자열을 리디렉션하거나 재작성하지 않고 그대로 유지하는지 확인하십시오. 또한 프록시는 Collabora에 구성된 외부 서버 이름 및 TLS 종료 설정과 일관되게 공개 호스트와 스키마를 전송해야 합니다.

Nginx의 경우 Collabora의 최신 예제에서 WebSocket 관련 위치와 HTTP/1.1, Upgrade및 Connection포워딩 지시문을 검토하십시오. Apache의 경우 ProxyPass최신 예제와 규칙 및 순서를 비교하십시오. 설치된 버전에서 요구하는 사항을 확인하지 않고 이전 일치 항목을 변경 없이 붙여넣지 마십시오 /cool/…/ws.

CODE 26.04 버전에서는 이 버전 확인이 중요합니다. 2026년 6월 8일에 게시된 Collabora 릴리스 노트에는 더 간결해진 WebSocket URL에 대한 설명과 함께 Apache 리버스 프록시 사용자가 ProxyPass이에 맞춰 설정을 조정해야 한다는 내용이 포함되어 있습니다. 26.04 버전에서는 기존 URL에 대한 대체 동작이 추가되었으므로 일부 빌드에서는 이전 규칙이 여전히 작동할 수 있습니다. Collabora의 26.04 WebSocket 문제 해결 보고서 에서 이 후속 조치를 확인할 수 있습니다. 이 대체 기능은 현재 프록시 구성을 설치된 버전과 일치시키는 것을 대체하는 것이 아닙니다. CODE 26.04 릴리스 노트 와 업데이트된 SDK 예제를 함께 참조하십시오.

3. 실패 사례 하나를 포착하고, 그 실패 사례 하나에 초점을 맞춰 변화를 시도하십시오.

문서를 다시 시도하기 전에 짧은 로그 스트림을 시작합니다. Docker의 --since옵션은 초기 출력을 제한하는 반면, --follow새 줄을 스트림으로 출력합니다. Docker Compose 로그 참조를 확인하세요 .

docker compose logs --since=2m --follow collabora

테스트 시간을 기록하고 Collabora 및 프록시 로그에서 동일한 요청을 찾습니다. 브라우저가 프록시가 잘못된 백엔드로 라우팅하는 경로를 요청하는 경우, Collabora의 버전 일치 예제를 사용하여 해당 WebSocket 경로만 업데이트합니다. 요청이 Collabora에 도달했지만 호스트, 오리진 또는 스키마가 거부된 경우, 공개 호스트 이름과 포트를 구성된 서버 이름 및 전달된 헤더와 비교합니다. 로그에 WOPI 호스트 거부 또는 파일 정보 요청 실패가 표시되는 경우, 통합 서버의 허용 호스트와 Collabora 컨테이너에서 해당 서버에 연결할 수 있는지 확인합니다. 이는 브라우저 WebSocket 핸드셰이크와는 별개의 단계입니다.

프록시 자체의 구문 검사 명령으로 구성을 검증한 후 프록시를 다시 로드하십시오. TLS 종료, 호스트 허용 목록 및 URL 재작성 규칙을 동시에 변경하지 마십시오. 테스트당 하나의 원인만 변경해야 다음 결과를 해석할 수 있습니다. TLS 검증을 비활성화하거나 모든 WOPI 호스트를 허용하는 등의 편법을 사용하지 마십시오.

4. 브라우저에서 문서로 수정 사항이 적용되었는지 확인합니다.

동일한 문서를 다시 시도하십시오. 개발자 도구에서 WebSocket 요청이 응답을 반환 101 Switching Protocols하고 연결된 상태를 유지하는지 확인하십시오. 문서 로딩이 완료되고 연결이 유지되며 간단한 편집 후 성공적으로 저장되는지 확인하십시오. WOPI 파일 액세스 또는 저장이 여전히 실패하는 경우 연결 상태만으로는 충분하지 않습니다.

핸드셰이크가 여전히 실패하는 경우, 브라우저 요청 경로, 프록시 액세스/오류 라인, 그리고 coolwsd동일한 타임스탬프의 로그 항목을 비교하십시오. 이 세 가지 항목을 비교하면 브라우저, 프록시, Collabora 경로 또는 WOPI 호스트 중 어느 부분을 추가로 조사해야 하는지 알 수 있습니다. 도움을 요청할 때는 브라우저 세부 정보와 로그에서 액세스 토큰, 문서 식별자, 사용자 이름 및 개인 호스트 이름을 삭제하십시오.