Collabora 빈 문서의 오류 발생 원인을 추적합니다.

먼저 빈 화면이 특정 파일에만 발생하는지 아니면 모든 파일에 발생하는지 확인한 다음, 브라우저의 네트워크 및 콘솔 패널과 Collabora 및 스토리지 플랫폼 로그를 함께 검사하십시오. 빈 화면은 증상일 뿐 진단은 아닙니다. 편집기가 로드되는 동안 문서 연결, WOPI 인증 또는 내장 리소스에 문제가 발생했을 수 있습니다.

1. 문제가 파일, 브라우저 또는 서비스 중 어느 것에 있는지 판단하십시오.

동일한 애플리케이션에서 정상적으로 작동하는 문서를 연 다음, 문제가 발생하는 파일을 다른 지원되는 브라우저나 시크릿 모드에서 열어보세요. 진단 중에는 원본 파일을 편집하지 마십시오. 하나의 파일에서 오류가 발생하는 경우 파일 형식, 내용 또는 권한 문제일 가능성이 높으며, 여러 파일에서 오류가 발생하는 경우 공유 서비스 또는 네트워크 변경 사항 때문일 수 있습니다.

개인 정보 보호 모드는 테스트용이지 해결책이 아닙니다. 개인 정보 보호 모드에서 문제가 해결된다면, 확장 프로그램을 하나씩 비활성화하거나 동기화되지 않은 작업이 없는지 확인한 후 해당 출처의 사이트 데이터를 삭제하세요. 모든 브라우저 데이터를 삭제하면 사용자가 로그아웃되고 관련 없는 사이트 상태가 제거될 수 있습니다.

2. 설정을 변경하기 전에 실패한 요청을 찾으세요.

Chrome 또는 Chromium에서 개발자 도구( F12 또는 Ctrl+Shift+I )를 열고 네트워크를 선택한 다음 로그 보존을 활성화 하고 페이지를 새로 고침합니다. WS (WebSocket) 를 필터링 하고 오류를 검사합니다. Chrome 개발자 도구의 네트워크 참조에서 요청 필터 및 상태 세부 정보를 확인할 수 있습니다. 콘솔에서 CSP, 인증서, 혼합 콘텐츠 또는 JavaScript 오류를 확인합니다.

일반적인 대리 공식을 적용하기보다는 증거를 해석하십시오.

• 에디터 자산 또는 /browser/경로에서 404 오류가 발생하는 경우: 리버스 프록시가 현재 Collabora 경로를 올바른 상위 서버로 전달하는지 확인하십시오.
• 502 오류, 타임아웃 또는 즉시 종료되는 WebSocket 연결: 상위 엔드포인트 연결 가능성, 프록시 로그, WebSocket 처리 및 요청 경로를 확인하십시오. 연결 가능한 /hosting/discovery엔드포인트는 기본적인 HTTP 액세스만 증명할 뿐이며, 에디터의 실제 연결이 작동한다는 것을 증명하는 것은 아닙니다.
• 로그에 403 오류 또는 "승인되지 않은 WOPI 호스트" 오류가 발생하는 경우, WOPI URL에 명시된 스토리지 호스트가 Collabora에서 허용된 WOPI 호스트 목록에 있는지 확인하십시오.
• CSP 또는 인증서 오류: 정확한 임베딩 출처 또는 인증서 체인을 수정하십시오. 화면이 로드되도록 브라우저 보안을 비활성화하거나 콘텐츠 보안 정책(CSP)을 광범위하게 완화하지 마십시오.

WebSocket 요청의 목표는 핸드셰이크 성공입니다. 표시되는 상태 코드는 HTTP 버전과 프록시 경로에 따라 달라지므로, 단일한 예상 상태 코드를 보편적인 기준으로 삼아서는 안 됩니다.

3. 오류가 발생한 레이어에 맞는 수정 방법을 적용합니다.

양방향 및 URL 스키마를 모두 확인하십시오.

Nextcloud의 최신 문제 해결 지침에 따르면 사용자의 브라우저는 HTTP(S)를 통해 두 서버 모두에 접속해야 하며, Nextcloud는 Collabora에, Collabora는 Nextcloud에 접속해야 합니다. 또한 두 서비스 모두 동일한 프로토콜을 사용해야 합니다. 브라우저에서 Collabora의 공개 주소( https://office.example.com/hosting/discovery및 ) 에 접속하여 테스트하십시오 https://office.example.com/hosting/capabilities. Nextcloud 호스트에서는 다음 명령어를 사용하십시오.

curl -fsS https://office.example.com/hosting/discovery -o /dev/null

curl -fsS https://office.example.com/hosting/capabilities -o /dev/null

예시 호스트 이름을 실제 Collabora URL로 바꾸세요. 이러한 검사는 HTTP 연결 가능성을 확인하는 것이며, 편집 성공 여부를 확인하는 것은 아닙니다. 서버 연결은 성공했지만 브라우저 연결에 실패하는 경우, 공용 DNS, TLS, 방화벽 또는 프록시 노출 여부를 확인하세요. Nextcloud Office 문제 해결 가이드 에는 이러한 연결 검사 항목이 나와 있으며, 두 애플리케이션의 로그를 모두 검토하는 것이 좋습니다.

요청에 프록시 라우팅 문제가 관련된 경우에만 프록시 라우팅을 수정하십시오.

정적 편집기 리소스가 404 오류를 반환하거나 라이브 연결에서 502 오류가 발생하는 경우, 리버스 프록시 경로를 Collabora의 공식 프록시 설정 과 비교 하십시오. 프록시가 필요한 Collabora 경로를 올바른 업스트림으로 전송하고 브라우저에서 사용하는 WebSocket 연결을 지원하는지 확인하십시오. 배포 환경에서 요구하는 외부 호스트 및 HTTPS 정보를 유지해야 합니다. 다른 프록시, URL 접두사 또는 Collabora 릴리스에 대한 구성을 복사하기 전에 해당 구성의 전제 조건을 반드시 확인하십시오. 전용 Collabora 호스트 이름을 사용하는 것이 디버깅에 더 편리한 경우가 많습니다. 경로 기반 라우팅은 일관된 접두사 처리가 필요합니다.

WOPI 허용 목록을 열지 않고 수정합니다.

WOPI는 Collabora가 스토리지 플랫폼을 통해 문서를 가져오고 저장하는 데 사용하는 프로토콜입니다. WOPI 호스트는 일반적으로 Collabora 호스트 이름이 아니라 Nextcloud 또는 다른 스토리지 호스트 이름입니다. 로그에 오류 메시지가 표시되면 Collabora의 WOPI 호스트 구성에 정확한 스토리지 호스트를 추가하거나 수정하고, 스토리지 플랫폼의 WOPI 요청 허용 목록에 Collabora 서버 주소가 포함되어 있는지 확인하십시오. Nextcloud는 Office 구성 지침No acceptable WOPI hosts found 에서 WOPI 요청을 예상되는 Collabora IP 주소로 제한하고 Collabora가 예상되는 호스트를 신뢰하도록 구성할 것을 권장합니다 .

특정 신뢰 호스트를 추가하는 것이 호스트 유효성 검사를 비활성화하거나 광범위한 도메인을 허용하는 것보다 안전합니다. 현재 설정을 기록하고 관련 항목만 변경한 다음 배포에 필요한 경우에만 서비스를 다시 시작하거나 재로드하십시오. Docker를 사용하는 경우, Collabora의 최근 출력에서 ​​` docker logs --since=10m <collabora-container>--colabora_log` 명령어를 사용하여 확인할 수 있습니다. 여기서 `--colabora_log`는 실제 컨테이너 이름으로 바꿔야 합니다. 패키지 또는 Kubernetes 설치의 경우, 해당 서비스 또는 Pod 로그를 사용하십시오.

4. 상태 엔드포인트뿐만 아니라 편집기 자체도 확인하십시오.

동일한 문서를 다시 로드합니다. 자산이 로드되고, 라이브 연결이 유지되고, 콘텐츠가 표시되고, 콘솔 오류가 사라지는지 확인합니다. 문제가 동일한 경우 다른 문서와 다른 사용자를 대상으로 테스트합니다. 간단한 테스트 편집을 저장하고 다시 열어 읽기 및 저장이 제대로 되는지 확인합니다.

빈 캔버스가 계속 나타나지만 요청은 성공하는 경우, 서버 로그에서 문서 변환 오류 또는 파일 관련 오류를 확인하고 동일한 형식의 다른 파일과 비교해 보세요. Collabora, 브라우저 또는 프록시 업데이트 직후 문제가 발생한 경우, 여러 변수를 한 번에 변경하기보다는 유지 관리 기간에 제어된 롤백 또는 버전별 프록시 변경을 테스트해 보세요. 브라우저 캐시 삭제는 오래된 클라이언트 자산이 문제의 원인일 때만 유용하며, 차단된 경로 또는 거부된 WOPI 요청을 복구할 수는 없습니다.