Collabora Online 로딩 시 검은 화면 또는 빈 문서 문제 해결

먼저 WebSocket 연결과 두 서버의 연결 상태를 확인하세요. Collabora Online 편집기가 검은 화면, 흰 페이지 또는 빈 문서 캔버스로 열리는 경우, 문서 UI 로딩이 완료되기 전에 오류가 발생하는 경우가 많습니다. 모든 파일에서 동일한 문제가 발생하는 경우, 브라우저-Collabora 경로, 리버스 프록시 및 Nextcloud-Collabora 연결을 먼저 점검하세요. 특정 파일에서만 문제가 발생하는 경우, 다른 문서를 테스트하고 해당 파일의 권한 및 형식을 확인한 후 서버 설정을 변경하세요.

다음 순서대로 진행하세요. 브라우저를 확인하고, Collabora의 검색 엔드포인트를 테스트하고, 통합 및 서버 로그를 읽은 다음, 문제의 원인이 되는 프록시 또는 WOPI 설정만 수정하세요. 브라우저 캐시를 재설정하면 오래된 자산 문제를 해결하는 데 도움이 될 수 있지만, 손상된 WebSocket이나 연결할 수 없는 WOPI 호스트 문제는 해결할 수 없습니다. 아래 인터페이스 이미지는 개략적인 예시이며, 정확한 레이블과 요청 경로는 브라우저, 클라우드 플랫폼, 프록시 및 Collabora 릴리스에 따라 다릅니다.

증상으로 빠른 진단

1. 문제가 브라우저 측 문제인지 서버 전체 문제인지 파악합니다.

먼저, 정상적으로 읽을 수 있는 다른 문서를 열고, 동일한 파일을 다른 브라우저나 시크릿 창에서 열어보세요. 다른 문서는 열리는데 특정 문서만 열리지 않는다면, 해당 사용자가 파일 플랫폼에서 파일을 다운로드하거나 미리 볼 수 있는지 확인하세요. 파일 손상, 지원되지 않는 형식, 공유 만료 또는 권한 부족은 편집기 문제처럼 보일 수 있지만, 리버스 프록시를 변경해도 파일 관련 문제는 해결되지 않습니다.

브라우저 측 점검을 위해 빈 문서를 다시 로드하기 전에 개발자 도구를 여세요. 크로뮴 기반 브라우저에서는 F12또는 키를 누르고, 네트워크를Ctrl+Shift+I 선택한 다음 , 로그 보존을 활성화하고 다시 로드하세요. , 또는 를 필터링하세요 . 또한 콘솔 탭에서 차단된 스크립트, 인증서 경고 또는 콘텐츠 보안 정책 오류가 있는지 확인하세요.wscoolbrowser

요청 실패는 /cool/…/wsWebSocket 핸드셰이크 또는 프록시 문제일 가능성이 높습니다. 502일반적으로 오류는 프록시가 업스트림에서 유효한 응답을 받지 못했음을 의미하며, 404오류는 경로가 라우팅되지 않았음을, 403거부된 호스트 또는 액세스 규칙을 나타낼 수 있습니다. 이러한 상태 코드는 문제 해결 범위를 좁히는 데 도움이 되지만, 정확한 원인을 파악하려면 해당 프록시 및 Collabora 로그를 함께 확인해야 합니다. 실패한 요청이 JavaScript 또는 CSS 파일인 경우 /browser, 프록시가 해당 정적 자산을 Collabora 서비스로 전달하는지 확인하십시오.

개인 정보 보호 모드에서 네트워크 요청이 성공하면 스크립트 또는 교차 사이트 요청을 차단하는 브라우저 확장 프로그램을 일시적으로 비활성화한 다음 클라우드 및 Collabora 호스트 이름에 대한 사이트 데이터만 삭제하십시오. 서버 구성을 변경하기 전에 다시 테스트하십시오. 네트워크 탭에서 동일한 요청이 여전히 실패하는 경우 캐시 삭제를 주요 해결 방법으로 사용하지 마십시오.

2. Collabora URL 및 검색 엔드포인트를 확인합니다.

Nextcloud 통합을 위해서는 Office 관리 설정에서 Collabora Online 서버 URL을 확인하십시오. 브라우저에서 접속 가능한 공용 URL에 올바른 호스트 이름과 포트 번호를 사용해야 합니다. Nextcloud의 최신 지침에 따르면 Collabora와 Nextcloud 서비스는 동일한 프로토콜(HTTPS)을 사용해야 합니다. 한 서비스는 HTTPS로 설정되어 있는데 http://다른 서비스는 다른 프로토콜로 접속하는 경우 와 같이 프로토콜이 일치하지 않으면 https://혼합 콘텐츠 요청이 차단되거나 콜백이 실패할 수 있습니다.

해당 클라이언트의 브라우저에서 `http:// discovery endpoint` https://office.example.com/hosting/discovery및 https://office.example.com/hosting/capabilities`http://discovery endpoint`를 엽니다. 예시 호스트 이름은 실제 호스트 이름으로 바꿔야 합니다. 검색 엔드포인트는 지원되는 문서 작업을 설명하는 XML을 반환해야 하며, 기능 엔드포인트는 Collabora 서버에서 응답을 반환해야 합니다. 브라우저 오류, 로그인 페이지, 프록시 관련 404 오류 또는 게이트웨이 오류가 발생하는 경우 공용 경로가 예상되는 Collabora 엔드포인트에 도달하지 못하고 있음을 의미합니다.

그런 다음 Nextcloud 호스트에서 테스트하십시오. 브라우저 테스트만으로는 서버 간 통신이 가능하다는 것을 입증할 수 없기 때문입니다.

curl -sS -o /dev/null -w "%{http_code}\n" https://office.example.com/hosting/discovery
curl -sS -o /dev/null -w "%{http_code}\n" https://office.example.com/hosting/capabilities

구성된 Collabora 호스트 이름으로 바꾸십시오 office.example.com. HTTP 응답이 성공적이면 연결 가능성을 확인하는 데 유용하지만, 시간 초과, DNS 오류, TLS 오류 또는 5xx 응답이 발생하면 해당 네트워크, 인증서, DNS 또는 프록시 계층에서 문제를 해결해야 합니다. Collabora 서버가 Nextcloud로 콜백해야 하는 설치 환경에서는 Collabora 호스트에서 Nextcloud 상태 URL도 테스트하십시오.

curl -fsS https://cloud.example.com/status.php

실제 Nextcloud 호스트 이름을 사용하십시오. 내장 CODE 설치는 별도의 공개 Collabora 호스트 이름 대신 내부 프록시 URL을 사용할 수 있으므로 독립 실행형 서버 예제를 그대로 적용하는 대신 해당 배포 지침을 따르십시오.

3. 웹소켓 경로 및 리버스 프록시를 확인합니다.

Collabora는 여러 경로를 통해 브라우저 자산과 문서 세션을 제공합니다. 리버스 프록시는 설치된 릴리스에서 예상하는 경로(편집기 자산, 검색 및 기능 엔드포인트, 문서 WebSocket 경로 포함)를 전달해야 합니다. 현재 Collabora 문서에서는 경로를 사용하고 있으며 /cool/…/ws, 이전 배포 환경에서는 레거시 경로에 대한 구성이 남아 있을 수 있습니다 . Nextcloud의 마이그레이션 문서에서는 경로가 에서 으로 , 에서 으로 /lool변경된 과거 경로를 구체적으로 언급하고 있습니다 .loleafletbrowserloolcool

프록시 구성에서 WebSocket 위치가 광범위한 캐치올 규칙보다 먼저 일치하는지, 프록시 소프트웨어에 필요한 업그레이드 헤더가 전달되는지, 업스트림이 실제 Collabora 서비스 및 포트를 가리키는지 확인하십시오. 또한 프록시가 예상되는 호스트 및 스키마 정보를 유지하고 장기 연결을 계속 열어 두도록 허용하는지 확인하십시오. TLS가 프록시에서 종료되는 경우 Collabora의 SSL 종료 설정이 해당 설계와 일치하는지 확인하십시오.

위의 짧은 코드 예시는 Nginx 스타일 프록시에 필요한 WebSocket 헤더의 예시일 뿐, 완전한 프록시 구성이 아닙니다. 이 코드를 단독으로 붙여넣거나 다른 릴리스의 지시문을 조합하여 사용하지 마십시오. 사용 중인 프록시 및 Collabora 버전에 맞는 Collabora 공식 리버스 프록시 가이드를 참조하여 전체 구성을 확인하십시오 . 프록시 파일을 편집한 후에는 서버를 다시 로드하기 전에 해당 서버의 configuration-test 명령어를 사용하여 구문을 검증하십시오.

4. WOPI 호스트 유효성 검사 및 서버 로그를 확인하십시오.

Collabora는 WOPI(웹 애플리케이션 개방형 플랫폼 인터페이스)를 사용하여 Nextcloud와 같은 연결된 스토리지 서비스에서 문서를 요청합니다. Collabora 서버는 WOPI 호스트를 허용해야 하며, 스토리지 서버는 Collabora 서비스에 연결할 수 있어야 합니다. Nextcloud에서 Office 설정과 WOPI 요청 허용 목록을 확인하세요. 예상되는 Collabora 서버 주소만 추가하고, 호스트 유효성 검사를 비활성화하거나 임의의 호스트를 허용하여 화면이 사라지는 일이 없도록 하세요.

문제가 재현되는 순간의 로그를 확인하세요. Docker 배포의 경우, Nextcloud의 문제 해결 가이드에 컨테이너 로그 확인 방법이 나와 있습니다. 이때 실제 컨테이너 이름 또는 ID를 사용하세요.

docker logs --tail 100 collabora

패키지 기반 설치의 경우 서비스 이름과 로그 대상 위치는 운영 체제 및 패키지 버전에 따라 다릅니다. 일반적인 systemd 검사는 다음과 같습니다.

sudo journalctl -u coolwsd -n 100 --no-pager

타임스탬프가 일치하는지 확인하고, 승인되지 않은 WOPI 호스트, CheckFileInfo요청 실패, TLS 검증 실패, 사용 불가능한 스토리지 또는 WebSocket 연결 실패와 관련된 오류를 찾아보세요. "허용 가능한 WOPI 호스트가 없습니다"라는 메시지는 일반적으로 통합을 위해 구성된 스토리지 호스트 이름이 Collabora에서 허용한 호스트와 일치하지 않음을 의미합니다. 관련 없는 도메인을 추가하는 대신 호스트 이름이나 허용 목록 항목을 수정하세요.

파일 플랫폼 로그에서 동일한 요청 시간을 확인하십시오. Collabora가 Nextcloud에 연결할 수 없는 경우 Collabora 호스트의 DNS 확인, 방화벽 규칙, 공용 또는 내부 경로, 그리고 서비스가 컨테이너 네트워크 내부에서 다르게 해석되는 호스트 이름을 통해 자체적으로 연결을 시도하는지 여부를 확인하십시오. Nextcloud 문제 해결 설명서에서는 양방향 연결을 확인하고 서버 로그를 사용하여 실패한 쪽을 식별할 것을 권장합니다.

5. 문서를 다시 테스트하고 필요한 부분만 수정하십시오.

경로, URL, 인증서 또는 허용 목록 항목을 수정한 후에는 배포 환경에 필요한 경우에만 프록시와 해당 서비스를 다시 로드하십시오. 개발자 도구를 다시 열고 파일을 다시 로드한 다음 이전에 실패했던 요청이 이제 완료되는지 확인하십시오. 문서의 페이지 또는 시트가 제대로 표시되고, 간단한 편집을 수행한 후 해당 편집 내용을 성공적으로 저장할 수 있어야 합니다. 빈 페이지가 사라지지만 저장할 수 없는 경우는 WOPI 또는 스토리지 연결이 아직 해결되지 않았음을 나타냅니다.

• 검색은 성공하지만 WebSocket 연결에 실패합니다. 프록시의 WebSocket 경로, 업그레이드 처리, 업스트림 주소 및 연결 시간 초과 문제를 집중적으로 살펴보세요.
• 브라우저에서는 Collabora에 접속할 수 있지만 Nextcloud에서는 접속할 수 없습니다. Nextcloud 호스트에서 DNS, 방화벽, TLS 신뢰 및 라우팅을 테스트해 보세요.
• Collabora에서 승인되지 않은 WOPI 호스트가 있다고 보고하는 경우, 통합 설정의 정확한 스토리지 호스트 이름을 WOPI 호스트 허용 목록과 비교하십시오.
• 업그레이드 후 기존 설치에서만 오류가 발생합니다. 프록시 경로를 설치된 릴리스 문서와 비교하고 필요한 경우 레거시 경로 /lool또는 기타 경로를 업데이트하십시오./loleaflet
• 연결 확인 후 하나의 파일만 오류가 발생하는 경우, 전역 설정을 변경하기 전에 파일 접근 권한을 확인하고 복사본이나 다른 지원되는 형식의 파일을 테스트해 보세요.

성공적인 해결책의 모습

정상적인 결과는 단순히 편집기 도구 모음이 나타나는 것 이상입니다. 문서 내용이 제대로 표시되고, 편집기 또는 WebSocket 요청 실패가 지속적으로 발생하지 않으며, 간단한 테스트 편집이 저장되고 새로 고침 후에도 유지되는 것을 의미합니다. 문제가 지속되는 경우, 브라우저의 네트워크/콘솔 로그에서 일부 정보를 삭제한 부분과 Nextcloud, 프록시, Collabora 로그를 함께 저장해 주세요. 로그에는 호스트 이름, 사용자 이름, 파일 식별자 또는 토큰이 포함될 수 있으므로 민감한 값은 삭제한 후 공유해 주시기 바랍니다.

현재 배포 환경에 따른 구체적인 단계는 Nextcloud Office 문제 해결 가이드 , Nextcloud Office 구성 참조 및 Collabora 마이그레이션 참고 사항을 참조하십시오 . ownCloud, 다른 WOPI 호스트, 내장 CODE 서비스 또는 컨테이너 플랫폼에 대한 정확한 확인 절차는 Nextcloud의 예시와 다를 수 있습니다.