Collabora Online에서 발생하는 "이건 정말 민망하네요" 연결 오류 해결 방법

Collabora Online에서 "죄송하지만 문서에 연결할 수 없습니다." 라는 메시지 는 문제의 원인이 아니라 증상입니다. 이 메시지는 편집기 셸이 로드된 후 문서 세션이 완료되지 않을 때 나타납니다. 현재 배포 환경에서는 Collabora 설정을 임의로 변경하는 대신 WOPI 경로에서 어떤 연결이 실패하는지 파악하는 것이 가장 빠른 해결 방법입니다.

이 가이드는 최신 Nextcloud 35 관리 문서와 Collabora Online 25.04 SDK 가이드라인을 참조 자료로 사용합니다. 동일한 문제 해결 논리가 ownCloud 및 사용자 지정 WOPI 통합에도 적용되지만, 정확한 설정 이름은 플랫폼 및 릴리스에 따라 다를 수 있습니다.

일반적으로 이러한 Collabora 연결 오류의 원인은 무엇입니까?

정상적인 브라우저 세션은 여러 경로에 따라 달라집니다. 사용자의 브라우저는 스토리지 서버와 Collabora 모두에 연결되어야 하고, 스토리지 서버도 Collabora에 연결되어야 하며, Collabora도 스토리지 서버에 연결되어야 합니다. 또한 프로토콜과 인증서가 호환되어야 하고, 리버스 프록시는 Collabora의 HTTP 및 WebSocket 경로를 올바르게 전달해야 합니다. Nextcloud의 공식 문제 해결 페이지에는 이러한 양방향 연결 요구 사항이 명시적으로 나와 있습니다.

즉, 모든 상황에 적용되는 단 하나의 정답은 없습니다. 첫 번째 실패한 테스트를 기준으로 복구 경로를 선택하십시오.

1. Collabora 검색 및 기능 엔드포인트를 확인합니다.

먼저 통합에 실제로 사용되는 Collabora 공개 URL부터 시작하세요. 브라우저와 스토리지 서버에서 다음 엔드포인트를 엽니다.

https://office.example.com/hosting/discovery
https://office.example.com/hosting/capabilities

Nextcloud의 최신 문제 해결 문서에서는 두 가지 테스트를 모두 권장합니다. 검색 엔드포인트는 XML을 반환해야 하며, 기능 엔드포인트는 Collabora 기능 데이터를 반환해야 합니다. 시간 초과, 인증서 경고, 404 오류, 프록시 관련 오류 페이지 또는 리디렉션 루프가 발생하는 경우 WOPI 설정을 변경하기 전에 네트워크 또는 리버스 프록시 문제를 해결해야 합니다.

먼저 Collabora의 공개 검색 및 기능 URL을 확인하십시오. 두 URL 모두 통합에 사용되는 동일한 호스트 이름을 통해 접근 가능해야 합니다.

엔드포인트 관련 공식적인 지침은 Nextcloud Office 문제 해결 및 Collabora Online 25.04 SDK 설명서를 참조하십시오 .

2. 브라우저뿐만 아니라 네트워크의 네 방향 모두를 테스트하십시오.

office.example.com흔히 저지르는 실수 중 하나 는 Collabora가 데스크톱 브라우저에서 열리기 때문에 스토리지 서버에서도 파일을 가져올 수 있다고 생각하는 것입니다 . 이는 보장되지 않습니다. 실제 호스트 또는 컨테이너에서 테스트해 보세요.

# From the Nextcloud/storage server
curl -fsS https://office.example.com/hosting/discovery >/dev/null && echo OK

# From the Collabora host/container
curl -fsS https://cloud.example.com/status.php

# Then inspect Collabora logs
docker logs --tail 100 collabora

Docker, Kubernetes 또는 사설 네트워크 내부에서 공용 호스트 이름이 다르게 해석되는 경우, 내부 DNS를 수정하거나, 적절한 호스트 매핑을 추가하거나, 공용 엔드포인트를 통해 라우팅할지 결정해야 합니다. 규모가 커지면 내부 DNS 설정이 일반적으로 더 깔끔합니다. hosts 파일에 항목을 추가하는 것은 소규모 정적 설치에는 빠르지만 유지 관리가 더 어려워집니다.

서버 자체에서 연결성 테스트를 실행한 다음 Collabora 로그를 사용하여 네트워크 오류와 WOPI 신뢰 오류를 구분하십시오.

3. WebSockets 또는 Collabora 경로가 누락된 경우 리버스 프록시를 수정하십시오.

Collabora는 일반적인 정적 웹 애플리케이션이 아닙니다. Collabora의 리버스 프록시는 브라우저 자산, 검색/기능, 문서 트래픽 및 WebSocket에 대한 경로가 필요합니다. Collabora SDK 설명서의 Nginx 예제에서는 WebSocket 경로 및 관련 트래픽 을 전달 /browser합니다 ./hosting/discovery/hosting/capabilities/cool/.../ws/cool/lool

WebSocket 경로의 경우 프록시는 호스트를 유지하고 HTTP 업그레이드를 전달해야 합니다. 간소화된 Nginx 패턴은 다음과 같습니다.

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 $host;
    proxy_read_timeout 36000s;
}

TLS 종료 방식이 다른 경우 이 내용을 그대로 복사하지 마십시오. Collabora는 종단 간 TLS 및 SSL 종료에 대한 별도의 패턴을 문서화하고 있습니다. TLS가 Nginx에서 종료되고 백엔드 연결이 HTTP인 경우 Collabora의 내부 SSL 설정은 해당 설계와 일치해야 합니다. 모든 곳에서 HTTPS를 사용하는 것이 이해하기 더 간단하지만, 프록시에서 TLS를 종료하면 컨테이너 내부의 인증서 처리 부담은 줄어들지만 구성 경계가 하나 더 추가됩니다.

올바른 리버스 프록시는 Collabora HTTP 경로를 전달하고 문서 세션에 대한 WebSocket 업그레이드를 유지해야 합니다.

4. 프로토콜, 인증서 및 호스트 이름의 일관성을 확인합니다.

Nextcloud의 최신 Office 구성 문서에 따르면 Collabora Online 서버는 Nextcloud 설치와 동일한 프로토콜을 사용해야 하며, HTTPS 사용을 권장합니다. 하지만 실제로 공용 HTTP/HTTPS 혼합 구성은 콘텐츠 차단, 잘못된 리디렉션 대상 지정 또는 백엔드 인증서 유효성 검사 실패와 같은 문제를 야기할 수 있습니다.

다음 항목들을 함께 확인하십시오:

• Collabora 스토리지 플랫폼에 저장된 URL은 사용자가 접속하는 정확한 공개 URL입니다.
• 해당 호스트 이름으로 제공되는 인증서는 해당 호스트 이름에 대해 유효하며 스토리지 서버에서 신뢰받고 있습니다.
• Collabora는 스토리지 서버의 HTTPS 인증서를 검증할 수 있습니다.
• 리버스 프록시가 원래 호스트와 스키마를 올바르게 전달합니다.
• 구성된 Collabora 호스트 이름에서 WOPI가 예상하지 않는 다른 호스트 이름으로의 리디렉션은 없습니다.

자체 서명 인증서는 모든 구성 요소가 명시적으로 신뢰하도록 설정되어 있다면 연구실 환경에서는 허용될 수 있지만, 이러한 편의성은 이식성을 저해하고 향후 업그레이드 또는 컨테이너 재구축 실패를 야기하는 경우가 많습니다. 프로덕션 환경에서는 공개적으로 신뢰받는 인증서 또는 조직에서 신뢰하는 인증서 체인을 사용하는 것이 더 안전한 선택입니다.

5. WOPI 허용 목록을 비활성화하는 대신 올바르게 수정합니다.

검색이 정상적으로 작동하고 Collabora 로그에 "대상과 일치하는 허용 가능한 WOPI 호스트가 없습니다"와 같은 메시지가 표시되면 Unauthorized WOPI host문제는 기본 연결 문제에서 신뢰 구성 문제로 넘어간 것입니다. Nextcloud의 공식 문제 해결 문서에서는 이러한 경우 컨테이너 로그를 확인하도록 명시적으로 안내하고 있습니다.

스토리지 측면에서 Nextcloud는 WOPI 요청 허용 목록 설정을 사용하여 WOPI 요청을 Collabora 서버의 IP 주소로 제한하는 것을 권장합니다 . Collabora 측에서는 허용된 WOPI 스토리지 호스트가 Collabora가 실제로 수신하는 스토리지 URL과 일치해야 합니다. 여러 스토리지 도메인을 사용하는 경우 Collabora의 최신 SDK 문서에서 WOPI 별칭 그룹을 확인할 수 있습니다.

Collabora 서버 URL과 WOPI 허용 목록을 실제 배포 환경과 일치시키세요. 유효성 검사를 끄는 대신 신뢰할 수 있는 항목 수를 제한적으로 설정하세요.

현재 서버 URL 및 WOPI 허용 목록에 대한 지침은 Nextcloud Office 구성을 참조하세요 . ownCloud Infinite Scale을 사용하는 경우 해당 협업 서비스는 COLLABORATION_APP_ADDR오피스 앱 URL과 COLLABORATION_WOPI_SRC외부에서 접근 가능한 WOPI 소스에 대해 다음 주소를 사용합니다. ownCloud 협업 서비스 설명서를 참조하세요 .

별도의 Collabora 서버 대신 내장된 CODE를 사용해야 하는 경우는 언제일까요?

소규모 Nextcloud 설치의 경우, 내장된 CODE 서버는 외부에서 관리해야 하는 구성 요소 수를 줄여줍니다. 하지만 그 대신 Nextcloud 인스턴스가 브라우저에서 사용하는 호스트 이름을 통해 자체적으로 접근할 수 있어야 한다는 단점이 있습니다. Nextcloud의 문제 해결 문서에서는 이 점을 명확히 지적하며, 내장된 CODE 서버가 연결에 실패할 경우 호스트 이름을 올바르게 확인하도록 권장합니다.

독립적인 확장이 필요하거나, 여러 스토리지 인스턴스에 대한 중앙 집중식 서비스가 필요하거나, 리소스 경계가 명확한 프로덕션 아키텍처가 필요한 경우 별도의 Collabora 서버를 사용하는 것이 일반적으로 더 적합합니다. 하지만 이렇게 하면 DNS, 프록시, 인증서, 방화벽 및 WOPI 신뢰 구성이 추가되므로 운영 부담이 더 커집니다.

하지 말아야 할 일

• WOPI 유효성 검사를 비활성화하는 것을 첫 번째 해결책으로 삼지 마십시오. 이는 실제 호스트 이름 불일치를 숨길 수 있으며 보안 경계를 약화시킵니다.
• 프록시가 제대로 작동하지 않는다고 해서 9980번 포트를 직접 노출하지 마십시오. 직접 노출이 의도적이고 보안이 강화된 설계가 아닌 이상, 프록시 문제를 해결해야 합니다.
• Collabora 홈페이지에서 200 응답을 받았다고 해서 문서 편집이 정상적으로 작동한다고 단정짓지 마십시오. 검색, 기능, WOPI 파일 접근 및 WebSockets는 각각 별개의 경로입니다.
• 여러 계층을 한 번에 변경하지 마십시오. 변경 후에는 반드시 테스트를 수행하여 DNS, TLS, 프록싱 또는 WOPI 트러스트 중 어느 것이 실제 원인인지 확인하십시오.

최종 확인 체크리스트

변경 사항을 적용한 후에는 다음 순서대로 시스템을 확인하십시오.

1. 브라우저에서 엽니다 /hosting/discovery./hosting/capabilities
2. 스토리지 서버에서 동일한 엔드포인트를 가져옵니다.
3. Collabora 서버에서 스토리지 서버 상태 URL을 가져옵니다.
4. Collabora와 스토리지 로그를 동시에 확인하면서 문서를 엽니다.
5. 브라우저가 Collabora WebSocket 연결을 반복적으로 끊지 않고 제대로 설정하는지 확인하십시오.
6. 공동 편집이 필요한 경우, 두 번째 사용자가 테스트 문서를 열고 편집할 수 있는지 확인하십시오.

6가지 검사가 모두 성공하면 일반적인 "이런, 난감한 상황이 발생했네요"라는 메시지가 더 이상 연결 실패를 가리지 않게 됩니다. 만약 메시지가 계속 표시된다면, 문서 열기 시도 한 번에 대한 정확한 Collabora 로그 라인과 브라우저 네트워크 오류 기록을 캡처해 두세요. 이 두 가지 증거가 일반적인 UI 메시지 자체보다 훨씬 유용합니다.