Collabora Online에서 "WOPI 호스트 권한 없음" 오류를 해결하는 방법 (코드)

가장 빠르고 확실한 해결 방법은 Collabora Online CODE가 스토리지 플랫폼에서 전송하는 WOPI 소스 URL에 나타나는 정확한 호스트 이름과 포트를 신뢰하도록 설정하는 것입니다. Nextcloud 서버가 하나뿐인 경우, CODE 호스트 허용 목록에 해당 Nextcloud 호스트 이름을 추가하고 컨테이너를 다시 생성한 후 테스트하십시오. 여러 Nextcloud 인스턴스를 운영하는 경우, 각 인스턴스를 명시적으로 허용해야 합니다. 모든 호스트에 대한 WOPI 액세스를 열어서 오류를 해결하지 마십시오.

"WOPI 호스트 권한 없음" 오류는 일반적으로 Collabora가 WOPI 요청에 지정된 스토리지 호스트를 거부했음을 의미합니다. 이 오류 자체만으로는 사용자 암호, 문서 권한, TLS 인증서 또는 리버스 프록시에 문제가 있음을 입증하는 것은 아닙니다. 이러한 요소들도 다른 연결 실패의 원인이 될 수 있으므로 설정을 변경하기 전에 Collabora 로그를 사용하여 구체적인 원인을 확인하십시오.

배포 환경에 맞는 변경 사항을 선택하세요.

아래 예시는 Nextcloud https://cloud.example.com와 Collabora가 https://office.example.com각각 에 설치되어 있다고 가정합니다. 이름과 포트 번호는 사용자의 설치 환경에 맞게 변경하십시오. Nextcloud의 Docker 설정 가이드에서는 aliasgroup1단일 스토리지 호스트에 대해 를 사용하며, 두 번째 Nextcloud 호스트에 대한 별칭 그룹을 추가하는 방법을 설명합니다. Collabora의 WOPI 구성은 호스트 이름과 포트를 기준으로 호스트 일치를 정의하며, 별칭은 동일한 스토리지 호스트의 대체 이름을 나타냅니다.

1. Collabora가 거부한 호스트를 확인하세요.

CODE 컨테이너 로그부터 확인하세요. Docker Compose 배포 환경에서는 다음 명령을 실행하세요.

docker compose logs --since=10m collabora

collaboraCompose 파일에서 서비스 이름으로 바꾸세요 . 일반 Docker를 사용하는 경우 `<service_name>`을 사용합니다 docker logs --since 10m CONTAINER_NAME. 문서 열기 시도 실패 메시지 근처에서 `<service_name>`과 같은 메시지를 찾아보세요 No acceptable WOPI hosts found matching the target host [cloud.example.com] in config. 괄호로 묶인 호스트 이름이 힌트입니다. Collabora 서버의 공개 호스트 이름이 아닌, 거기에 표시된 스토리지 호스트를 추가하세요.

로그에 WOPI URL의 호스트와 포트가 표시되면 기록해 두십시오. 이를 구성된 항목과 비교하십시오. 요청이 cloud.example.com:443내부 컨테이너 이름(예: )에 대한 항목과 일치하지 않을 수 있습니다 nextcloud. 두 이름이 동일한 머신으로 확인되더라도 마찬가지입니다. 리버스 프록시, 스플릿 호라이즌 DNS 및 여러 공용 URL로 인해 이러한 불일치를 놓치기 쉽습니다.

로그에 DNS 조회 실패, 연결 거부 또는 인증서 오류와 같은 다른 오류가 표시되는 경우 WOPI 호스트 목록을 확장하는 대신 해당 문제를 해결하십시오.

2. CODE의 신뢰할 수 있는 WOPI 호스트 설정을 업데이트합니다.

하나의 Nextcloud 호스트에 서비스를 제공하는 Docker Compose 설치의 경우, 서비스의 관련 부분은 다음과 같습니다.

services:
  collabora:
    image: collabora/code
    environment:
      - aliasgroup1=https://cloud.example.com:443

기존 서비스 옵션, 시크릿, 볼륨, 포트 및 리버스 프록시 설정은 그대로 유지하세요. 예시에는 허용 목록 항목만 나와 있으며, 전체 프로덕션 Compose 파일이 아닙니다. 사용 중인 CODE 버전에서 지원하는 설정 스타일을 사용하고, 변경 후 렌더링된 구성 또는 시작 구성을 확인하세요. 컨테이너 이미지 및 구성 인터페이스는 시간이 지남에 따라 변경될 수 있습니다.

단일 호스트의 경우, 광범위한 정규 표현식보다 정확한 호스트 항목을 입력하는 것이 감사가 더 쉽습니다. 설치가 domain환경 변수에 의존하는 경우, 이미지에 대해 문서화된 이스케이프 규칙을 확인하고 표현식이 의도한 스토리지 호스트 이름과만 일치하는지 확인하십시오. 이스케이프되지 않은 와일드카드나 관련 없는 하위 도메인과 일치하는 상위 도메인 패턴을 복사하지 마십시오.

여러 개의 Nextcloud 인스턴스를 사용하는 경우, 사용 중인 CODE 릴리스에서 지원하는 메커니즘을 이용하여 각 독립적인 호스트에 대해 별도의 그룹을 추가하십시오. 예를 들어, Nextcloud의 Docker 통합 가이드에서는 aliasgroup2두 번째 클라우드 호스트 이름에 대한 추가 항목을 보여줍니다. 하나의 Nextcloud 서버에 내부 이름과 공용 이름처럼 여러 이름으로 접속해야 하는 경우에만 별칭을 추가하십시오. 마이그레이션 후 이전 호스트 이름을 삭제할 수 있도록 이러한 이름 목록을 기록해 두는 것이 좋습니다.

3. 컨테이너를 다시 생성하고 Nextcloud의 별도 허용 목록을 확인하세요.

Compose 파일을 편집한 후, 새 환경이 적용되도록 서비스를 다시 생성하십시오.

docker compose up -d --force-recreate collabora

올바른 서비스 이름을 사용하십시오. 그런 다음 컨테이너가 정상적으로 시작되고 예상 호스트가 시작 구성 또는 로그에 나타나는지 확인하십시오. 전체 환경 덤프를 지원 요청에 붙여넣지 마십시오. 암호나 기타 기밀 정보가 노출될 수 있습니다.

Nextcloud에는 Office 관리 설정에 "WOPI 요청 허용 목록"이라는 별도의 설정이 있습니다. 이 목록은 Nextcloud에 WOPI 요청을 보낼 수 있는 IP 주소를 제한합니다. Collabora에서는 예상되는 Collabora 서버 주소로 제한하는 것을 권장합니다. Nextcloud에서 이 경고가 표시되면, 프록시 또는 컨테이너 네트워크가 관련된 경우 다를 수 있는 Nextcloud가 실제로 요청에 대해 확인하는 주소를 추가하십시오. 이 확인은 CODE 호스트 항목과 별도로 관리해야 합니다. CODE는 스토리지 호스트 이름을 신뢰하는 반면, Nextcloud의 허용 목록은 요청하는 서버의 IP 주소와 관련이 있습니다.

리버스 프록시를 사용하는 경우, Nextcloud가 WOPI 링크에 게시하는 호스트 이름이 CODE에서 신뢰하도록 구성된 호스트 이름과 동일한지 확인하십시오. Nextcloud 오피스 서버 URL과 리버스 프록시의 공용 호스트 구성을 확인하세요. WOPI URL에 있는 스토리지 호스트가 아닌 경우, 오피스 호스트 이름을 WOPI 스토리지 허용 목록에 추가하지 마십시오.

4. 연결이 완전히 되었는지 확인하십시오.

먼저 브라우저와 Nextcloud 서버에서 Collabora 서비스 엔드포인트를 확인하세요. 예시 호스트 이름을 사용자의 Office URL로 바꾸세요.

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

이러한 검사는 엔드포인트가 응답하는지 확인하는 것이며, WOPI 문서 요청이 승인될 것이라는 것을 증명하는 것은 아닙니다. 다음으로, CODE가 Nextcloud에서 제공하는 동일한 호스트를 사용하여 Nextcloud에 연결할 수 있는지 확인하십시오. 예를 들어 다음과 같습니다.

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

마지막으로 테스트 문서를 열고 CODE와 Nextcloud 로그를 동시에 확인하세요. 성공적인 결과는 편집기가 로드되고, "허용 가능한 WOPI 호스트가 없습니다"라는 메시지가 사라지고, 간단한 변경 사항을 저장하는 것이 정상적으로 작동하는 것입니다. 문제가 발생한 사용자와 동일한 공유 및 편집 권한을 가진 일반 사용자 계정으로 테스트하세요.

주요 옵션들의 비교

정확한 호스트 하나 대 정규 표현식

단일 클라우드 배포 환경에서는 의도한 포트 번호가 포함된 정확한 호스트 이름을 사용하는 것이 일반적으로 가장 적합합니다. 이렇게 하면 검토가 쉽고 의도치 않은 일치 항목을 줄일 수 있습니다. 의도적으로 관리하는 호스트 이름 집합이 특정 패턴을 공유하는 경우에는 정규 표현식을 사용할 수 있지만, 감사가 어렵고 너무 광범위하게 작성하면 의도치 않은 하위 도메인까지 승인될 수 있습니다. 검증된 요구 사항을 충족하는 가장 구체적인 표현식을 사용하십시오.

하나의 CODE 인스턴스와 여러 개의 인스턴스

공유 CODE 서비스를 사용하면 유지 관리해야 할 서비스 수를 줄일 수 있으며, 명시적 그룹을 통해 여러 Nextcloud 인스턴스를 지원할 수 있습니다. 팀에서 더 강력한 구성 격리 또는 독립적인 유지 관리 기간이 필요한 경우 개별 CODE 인스턴스를 사용하는 것이 적합할 수 있습니다. 하지만 이 경우 패치, 모니터링 및 라우팅에 필요한 인프라가 더 많아진다는 단점이 있습니다. 두 옵션 모두 WOPI 호스트 이름 불일치 문제를 자동으로 해결하지는 않으며, 각 인스턴스는 올바른 스토리지 호스트를 신뢰해야 합니다.

컨테이너 환경 설정과 XML 편집 비교

Docker CODE 배포의 경우, 이미지에서 지원하는 구성 인터페이스를 사용하고 해당 구성을 Compose 또는 다른 배포 소스에 저장하세요. 이렇게 하면 컨테이너가 다시 생성될 때 변경 사항을 반복 적용할 수 있습니다. coolwsd.xml관리형 패키지나 의도적인 사용자 지정 배포의 경우 직접 편집하는 것이 유용할 수 있지만, 실행 중인 컨테이너 내부에서 생성된 파일을 편집하는 것은 불안정하며 컨테이너 교체 또는 업그레이드 시 변경 내용이 손실될 수 있습니다. 사용 중인 패키지, Helm 차트 또는 이미지에 대한 정확한 지침을 따르세요.

흔히 저지르는 실수들을 피하는 방법

• office.example.com거부된 WOPI 스토리지 호스트가 다음과 같을 때 허용합니다 cloud.example.com.
• WOPI URL에 공용 DNS 이름이 포함된 경우 개인 컨테이너 이름을 입력하거나, 그 반대의 경우.
• Nextcloud WOPI IP 허용 목록이 비어 있는 경우와 CODE의 호스트 구성이 동일한 제어라고 가정합니다.
• 편집기가 로드되도록 하려면 광범위한 와일드카드를 추가하거나 호스트 유효성 검사를 비활성화해야 합니다.
• 프록시, TLS 및 WOPI 규칙을 한꺼번에 변경하면 결과 진단이 더 어려워집니다.
• 문서 인증이 제대로 작동한다는 증거로 검색 엔드포인트만 테스트합니다.

다른 해결책을 사용해야 하는 경우

요청 간에 거부된 호스트가 변경되는 경우, 새 호스트 이름을 추가하기 전에 Nextcloud의 정규 URL, 신뢰할 수 있는 프록시 헤더 및 대체 웹 루트를 확인하십시오. 모든 호스트 이름이 일치하지만 오류가 계속 발생하는 경우, 활성 CODE 구성을 편집한 파일 또는 환경 설정과 비교하고 컨테이너가 다시 생성되었는지 확인하십시오. Kubernetes 또는 Helm의 경우, 실행 중인 Pod가 아닌 차트 값 또는 관리되는 구성 소스를 편집하십시오. 로그에 인증서, 방화벽, WebSocket 또는 DNS 오류가 표시되는 경우, 해당 서버 로그 및 네트워크 검사를 사용하여 해당 계층의 문제를 해결하십시오.

이 단계는 2026년 10월 6일에 제공되는 Nextcloud 35 관리 설명서와 Collabora에서 게시한 WOPI 구성 스키마를 따릅니다. 특정 구성 키는 배포 방법 및 이미지 버전에 따라 다를 수 있으므로 변경 사항을 적용하기 전에 설치된 릴리스의 설명서를 참조하여 확인하십시오.

공식 참고 자료

• Nextcloud Office 문제 해결 및 연결 상태 점검
• Nextcloud의 Collabora용 Docker 예제(WOPI 호스트 설정 포함)
• Nextcloud Office 구성 및 WOPI IP 허용 목록 안내
• Collabora Online에서 공개한 coolwsd.xml 구성 스키마
• Collabora Online 프록시 설정 문서