Collabora Online을 ownCloud Infinite Scale과 통합하는 방법

Collabora Online과 ownCloud Infinite Scale(oCIS)의 통합은 ownCloud Classic에서 사용하는 설정과는 다른 WOPI 통합입니다. WOPI(Web Application Open Platform Interface)는 온라인 오피스 제품군이 스토리지 플랫폼에서 파일을 요청하고, 브라우저에서 편집한 후 결과를 다시 저장할 수 있도록 하는 프로토콜입니다.

이러한 차이점은 현재 Infinite Scale 배포에서 내장된 협업 서비스를 oCIS와 Collabora 간의 연결 다리로 사용하기 때문에 중요합니다. 기존 ownCloud Classic Collabora 앱을 설치하고 서버 URL을 지정하는 방식이 아닙니다. 오피스 애플리케이션은 협업 및 앱 레지스트리 서비스를 통해 등록됩니다. 공식 ownCloud WOPI 문서에는 Collabora가 지원되는 오피스 애플리케이션으로 명시되어 있으며, 협업 서비스 문서에는 서비스 및 필요한 설정에 대한 설명이 포함되어 있습니다.

2026년 10월 현재, ownCloud의 공식 GitHub 릴리스에는 2026년 8월 10일에 출시된 Infinite Scale 8.2.0이 포함되어 있습니다. 프로젝트의 배포 예제는 독립적으로 변경될 수 있으므로, 롤링 이미지가 적합하다고 가정하기보다는 테스트를 거친 프로덕션 태그를 사용하는 것이 좋습니다. 공식 oCIS 전체 배포 예제는 현재 26.04.3.1.1환경 파일에 Collabora CODE 태그를 사용할 것을 권장합니다. 버전을 고정하기 전에 공식 Infinite Scale 릴리스 와 공식 배포 예제 환경 파일을 확인하십시오.

먼저, 세 가지 종착점을 이해하십시오.

일반적으로 프로덕션 통합에는 세 가지 논리적 최종 지점이 포함됩니다.

확인됨: COLLABORATION_APP_ADDR Collabora URL이며, COLLABORATION_WOPI_SRC오피스 애플리케이션에서 사용하는 WOPI 소스를 식별합니다. 환경에 따라 다름: Collabora와 협업 서비스가 신뢰할 수 있는 컨테이너 네트워크를 공유하는 경우 WOPI 소스가 별도의 공용 호스트 이름일 필요는 없습니다. 현재 공식 Compose 예제는 http://collaboration:9300내부적으로 사용합니다. 분리된 배포 환경에서는 라우팅된 HTTPS WOPI 호스트 이름이 필요할 수 있습니다.

유용한 조치: 구성 값을 복사하기 전에 토폴로지를 결정하세요. 모든 구성 요소가 하나의 공식 Compose 스택에서 실행되는 경우 해당 예제를 참조하세요. Collabora가 다른 호스트 또는 Kubernetes 클러스터에 있는 경우 각 측에서 실제로 확인하고 연결할 수 있는 DNS 이름을 기록해 두세요.

1단계: DNS, HTTPS 및 Collabora 검색 확인

oCIS 구성을 변경하기 전에 ownCloud 및 Collabora 이름이 올바르게 확인되는지, 그리고 Collabora가 검색 엔드포인트를 노출하는지 확인하십시오. Collabora는 WOPI 기능을 통해 정보를 제공합니다 /hosting/discovery. 기본적인 확인 방법은 다음과 같습니다.

dig +short cloud.example.com
dig +short office.example.com

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

office.example.com검색 엔드포인트에서 XML을 수신해야 합니다. TLS가 리버스 프록시에서 종료되는 경우, oCIS 호스트 또는 컨테이너 네트워크 관점에서 제시된 인증서가 유효한지 확인하십시오 .

/hosting/discovery캡션: Infinite Scale 내에서 WOPI 등록을 디버깅하기 전에 이름 확인 및 Collabora 엔드포인트를 확인하십시오.

흔히 발생하는 오해: 브라우저에서 Collabora 랜딩 페이지가 보이는 것이 WOPI 통합이 작동한다는 것을 증명하는 것은 아닙니다. 웹 엔드포인트에 접근 가능하다는 것을 보여줄 뿐입니다. 협업 서비스 또한 Collabora에 접근할 수 있어야 하고, Collabora 역시 WOPI 소스에 접근할 수 있어야 합니다.

유용한 조치: 관련 서비스와 동일한 네트워크 네임스페이스에서 연결 테스트를 실행하세요. 예를 들어 Docker를 사용하는 경우 협업 컨테이너 내부에서 실행할 수 있습니다.

2단계: 무한 확장 협업 서비스 구성

일반적인 관리 모드 설정에서는 협업 서비스가 자동으로 시작되지 않습니다 ocis server. ownCloud 설명서에 따르면 관리자는 여러 오피스 제품에 대해 협업 서비스 인스턴스를 여러 개 실행할 수 있으므로 협업 서비스를 명시적으로 시작해야 합니다.

Collabora의 중요 설정은 다음과 같습니다.

COLLABORATION_APP_NAME=CollaboraOnline
COLLABORATION_APP_PRODUCT=Collabora
COLLABORATION_APP_ADDR=https://office.example.com
COLLABORATION_WOPI_SRC=http://collaboration:9300
OCIS_URL=https://cloud.example.com

위의 WOPI 소스는 현재 공식 Compose 예제에서 사용되는 토폴로지와 정확히 일치합니다. Collabora와 협업 서비스는 동일한 Docker 네트워크를 공유합니다. Collabora 서버가 외부에 있는 경우 내부 URL을 Collabora가 접근할 수 있는 주소로 바꾸십시오.

이 서비스는 Infinite Scale의 게이트웨이 및 앱 제공자 인프라에 의존합니다. 컨테이너 분할 배포의 경우, ownCloud 문서에서는 생성된 비밀 키가 서비스 간에 필요하므로 oCIS 구성을 협업 컨테이너와 공유해야 한다고 명시적으로 경고합니다. 최신 Collabora Compose 정의를 참조하십시오 .

캡션: 협업 서비스 프로세스는 의도한 Collabora 주소와 WOPI 소스로 시작해야 합니다. 실제 서비스 로그를 사용하여 배포 환경에서 해당 값이 올바른지 확인하십시오.

유용한 조치:collabora.yml 배포를 수동으로 구축한 경우, 이전 cs3org/wopiserver 튜토리얼의 설정을 복사하는 대신 공식 환경과 비교해 보세요 .

3단계: WOPI 호스트 및 브라우저 임베딩을 위한 Collabora 구성

Collabora는 WOPI 호스트를 신뢰해야 하며 ownCloud 웹 페이지 내에서 렌더링이 허용되어야 합니다. 공식 oCIS Compose 예제는 역방향 프록시에서 TLS를 종료하고 net.frame_ancestorsoCIS 도메인으로 설정하는 Collabora 옵션을 전달합니다. 또한 Collabora를 시작하기 전에 WOPI 인증 키를 생성합니다.

공식 예시에서 Collabora 측 관련 값은 다음과 같습니다.

DONT_GEN_SSL_CERT=YES

extra_params:
  --o:ssl.enable=...
  --o:ssl.ssl_verification=...
  --o:ssl.termination=true
  --o:welcome.enable=false
  --o:net.frame_ancestors=cloud.example.com

정확한 SSL 플래그는 TLS 종료 위치에 따라 달라집니다. 권장되는 인터넷 연결 설정은 인증서 검증이 활성화된 HTTPS입니다. 예제의 INSECURE=true옵션은 자체 서명 인증서를 사용하는 로컬 설정용이며, ownCloud의 배포 가이드에서는 공용 서버의 경우 해당 옵션을 제거하거나 false로 설정하도록 명시적으로 안내하고 있습니다.

캡션: 접근 가능한 Collabora 엔드포인트는 필수 조건 중 하나입니다. 프로덕션 배포 환경에서는 다른 구성 요소에서 신뢰하는 인증서를 사용하여 HTTPS를 통해 해당 엔드포인트를 노출해야 합니다.

유용한 조치: 문서 로딩 시 빈 iframe이 표시되거나 CSP 오류가 발생하는 경우, 브라우저 개발자 도구와 리버스 프록시 헤더를 검사하십시오. 페이지 로딩을 위해 인증서 검증이나 콘텐츠 보안 제한을 일괄적으로 비활성화하지 마십시오.

4단계: 등기소 파일 형식 및 테스트 편집

Infinite Scale의 앱 레지스트리 서비스는 각 MIME 유형을 열 수 있는 애플리케이션을 결정합니다. 설정에서 MIME 유형, 확장자, 아이콘, 기본 애플리케이션, 그리고 사용자가 해당 유형의 파일을 새로 생성할 수 있는지 여부를 정의할 수 있습니다. 이러한 필드에 대한 자세한 설명은 공식 앱 레지스트리 문서를 참조하십시오.

핵심 사항은 레지스트리에서 사용하는 앱 이름이 실제로 등록한 협업 제공업체와 일치해야 한다는 것입니다. 현재 공식 Collabora 배포 예제에서는 제품 이름 CollaboraOnline으로 COLLABORATION_APP_NAME와 를 사용합니다 Collabora. 배포 버전을 확인하지 않고 이전 예제에서 복사한 이름을 혼합해서 사용하지 마십시오.

시작 후 ownCloud 웹에 로그인하고 지원되는 오피스 문서를 엽니다. 정상적인 절차는 다음과 같습니다.

• ownCloud Web은 문서의 MIME 유형에 따라 등록된 오피스 애플리케이션을 선택합니다.
• 협업 서비스는 WOPI 발사 정보를 생성합니다.
• Collabora가 브라우저에 로드되어 WOPI를 통해 파일을 요청합니다.
• 수정 사항은 동일한 통합 과정을 통해 Infinite Scale에 다시 기록됩니다.

캡션: 마지막 테스트는 ownCloud Web에서 실제 오피스 문서를 열고, Collabora에서 편집한 다음, 문서를 닫고 저장된 버전이 Infinite Scale에서 다시 표시되는지 확인하는 것입니다.

유용한 방법: 임시 테스트 문서에 작은 변경 사항을 적용하고 편집기를 닫은 다음 파일을 다시 열어 변경 사항이 유지되었는지 확인합니다. 단순히 편집기를 로드하는 페이지는 완전한 쓰기 경로 테스트가 아닙니다.

사용자 지정 토폴로지가 필요하지 않은 경우 공식 Compose 예제를 사용하십시오.

일반적인 Docker 배포의 경우, 위험 부담이 가장 적은 방법은 ownCloud에서 제공하는 ocis_full예제를 사용하는 것입니다. 이 예제에는 Infinite Scale, 협업 서비스인 Collabora, 그리고 Traefik이 포함되어 있습니다. 공식 가이드에 따르면 배포에는 oCIS와 Collabora에 대한 도메인이 필요하며, WOPI 구성 요소도 스택의 일부로 설명되어 있습니다. 자세한 내용은 공식 배포 가이드를 참조하십시오 .

일반적인 운영 환경 설정 파일에는 다음과 같은 개념적 값이 포함됩니다.

OCIS_DOCKER_IMAGE=owncloud/ocis
OCIS_DOCKER_TAG=<tested-production-version>
OCIS_DOMAIN=cloud.example.com

COLLABORA=:collabora.yml
COLLABORA_DOCKER_TAG=<tested-collabora-version>
COLLABORA_DOMAIN=office.example.com

INSECURE=false

그런 다음 다음과 같이 스택을 시작합니다.

docker compose pull
docker compose up -d
docker compose ps

확인됨: 현재 공식 리버스 프록시 예제는 Collabora/Collabora에서 요구하는 대로 HTTPS 진입점에서 인코딩된 슬래시, 물음표 및 퍼센트 문자를 사용할 수 있도록 지원합니다. 환경 종속성: Traefik 대신 Nginx, HAProxy, 인그레스 컨트롤러 또는 클라우드 로드 밸런서를 사용하는 경우 해당 플랫폼에서 필요한 URL 처리, WebSocket/프록시 동작, 인증서 및 타임아웃을 재현해야 합니다.

유용한 조치: Traefik 레이블을 다른 프록시의 라우팅 요구 사항으로 문자 그대로 변환하지 마십시오. 레이블을 사용하여 라우팅 요구 사항을 파악한 다음, 해당 프록시의 문서화된 구문을 사용하여 요구 사항을 구현하십시오.

문제 해결 참조

알려진 사실, 배치 상황에 따라 달라지는 사항, 그리고 추측을 피해야 할 사항

알려진 사실: Infinite Scale은 WOPI를 통해 Collabora를 지원하며, 내장된 협업 서비스가 현재 브리지 역할을 하고, 공식 전체 배포판은 작동 참조 아키텍처를 제공합니다.

환경에 따라 다릅니다. WOPI 엔드포인트가 내부 컨테이너 URL인지 공용 호스트 이름인지, TLS가 어디에서 종료되는지, 어떤 프록시를 사용하는지, 그리고 Collabora가 oCIS와 동일한 네트워크에서 실행되는지 여부에 따라 달라집니다.

오해하지 마십시오. ownCloud Classic용 지침이 Infinite Scale에도 동일하게 적용됩니다. Collabora/richdocuments 앱을 설치하거나 Classic 관리자 UI를 통해 구성하라는 Classic 설명서는 다른 제품 아키텍처를 설명하고 있습니다.

따라서 가장 안정적인 통합 워크플로는 다음과 같습니다. 공식 Infinite Scale 배포 모델에서 시작하여 네트워크 및 TLS 연결 가능성을 확인하고, 협업 서비스를 구성하고, Collabora가 WOPI 호스트를 신뢰하고 연결할 수 있는지 확인하고, 관련 MIME 유형을 등록한 다음, 마지막으로 실제 문서를 열고 저장하는 기능을 테스트합니다.