Collabora Online 클러스터를 여러 노드로 설정하는 방법

Collabora Online 클러스터는 단순히 coolwsd라운드 로빈 로드 밸런서 뒤에 있는 여러 대의 정상 서버로만 구성된 것이 아닙니다. 공동 편집 기능은 동일한 문서에 대한 요청을 동일한 Collabora 노드로 전송하는 데 의존합니다. WOPISrc이러한 이유로 Collabora의 Kubernetes 차트는 WOPI 문서 식별자(<code>@collabora.com</code>)를 사용한 라우팅을 설명합니다. 이 가이드에서는 Kubernetes에서 유지 관리되는 Collabora Helm 차트를 구체적인 멀티 노드 설정으로 사용하고, 다른 인그레스 컨트롤러를 사용하거나 Kubernetes가 아닌 환경에 배포할 경우 변경해야 하는 사항을 설명합니다.

확인됨: Collabora의 차트는 여러 복제본을 지원하며 문서별 선호도를 설명합니다 WOPISrc. 배포 환경에 따라 인그레스 어노테이션, TLS 종료, 리소스 요청, 세션 컨트롤러 사용 여부 등이 달라질 수 있습니다. 모든 로드 밸런서나 "스티키 세션" 설정이 문서 선호도를 유지한다고 가정해서는 안 됩니다 . 컨트롤러별 동작을 확인하고 사용자를 클러스터로 이동하기 전에 테스트하십시오.

클러스터의 기능과 한계는 무엇일까요?

일반적인 다중 복제 배포 방식에서 각 Collabora 노드는 문서를 제공할 수 있으며, 프록시는 각 문서에 대한 요청을 하나의 노드로 전송합니다. 이렇게 하면 여러 문서가 노드 풀 전체에 분산됩니다. 하지만 이는 모든 노드가 동일한 실시간 편집 프로세스를 공유하거나, 실행 중인 문서가 해당 노드의 작동이 중단되더라도 다른 노드로 원활하게 이동할 수 있다는 것을 의미하지는 않습니다.

Collabora는 Kubernetes용 COOL 컨트롤러에 대한 문서도 제공하며, 이 컨트롤러는 다른 세션 관리 방식을 제공합니다. 라우팅 및 구성은 독립형 복제 풀과 다릅니다. 이 문서에서는 더 간단한 WOPI 소스 선호도 모델을 구성합니다. 해당 릴리스에 맞는 컨트롤러를 배포하고 구성하지 않은 경우에는 컨트롤러별 라우트 토큰 설정과 함께 사용하지 마십시오.

조치: 용량 및 노드 이중화를 위한 기본 복제 Collabora 서비스가 필요한지, 아니면 세션 인식 기능을 갖춘 컨트롤러 관리형 설정이 필요한지 결정하십시오. 후자는 추가 구성 요소와 버전별 구성이 필요합니다. 해당 방식을 고려 중인 경우 Collabora 온라인 컨트롤러 개요를 검토하십시오.

배포하기 전에

• 정상 작동하는 Kubernetes 클러스터, Helm, 공개 Collabora 호스트 이름에 대한 DNS, 그리고 TLS를 지원하는 인그레스 또는 리버스 프록시가 필요합니다.
• Nextcloud와 같은 WOPI 통합은 개별 Pod 주소 대신 단일 공용 Collabora 호스트 이름을 사용하도록 구성됩니다.
• 차트 collabora.aliasgroups구성에 입력된 Collabora에서 허용된 WOPI 호스트 또는 호스트들입니다.
• 문서 워크로드에 충분한 CPU 및 메모리가 있으며, Pod 상태, 인그레스 로그 및 리소스 사용량을 검사할 수 있는 방법도 필요합니다.
• 초기 배포를 위한 유지 관리 기간과 두 개의 별도 사용자 계정이 포함된 테스트 문서가 제공됩니다.

전용 Collabora Online 서비스는 Nextcloud에 내장된 CODE 서버와는 다릅니다. Nextcloud는 내장 옵션을 개인 사용자 또는 소규모 팀을 대상으로 하며 전용 서버처럼 고급 확장 기능을 제공하지 않는다고 설명합니다. 조치: 다중 노드 Collabora 풀이 필요한 경우 전용 서비스를 계획하고 배포 환경에 적합한 라이선스 및 지원 모델을 확인하십시오. Nextcloud Office 설치 가이드를 참조하세요 .

1단계: 라우팅 모델을 선택합니다.

문서화된 독립형 모델은 WOPISrcWOPI 요청에서 문서를 식별하는 데 사용되는 해시 값을 기반으로 작동합니다. 하나의 문서에 대한 요청은 동일한 Pod에 도달해야 하며, 서로 다른 문서에 대한 요청은 여러 Pod에 분산될 수 있습니다. 일반적인 라운드 로빈 규칙은 이러한 요구 사항을 충족하지 못합니다.

조치: 차트 문서에서 지원하는 인그레스 구현(예: 문서에 제공된 NGINX 또는 HAProxy 인그레스 예제)을 사용하거나, 클러스터에서 적절한 인그레스 컨트롤러를 사용할 수 없는 경우 차트의 네임스페이스 내 리버스 프록시를 사용하십시오. 다른 프록시를 사용하는 경우 일반 HTTP 요청과 장기 WebSocket 연결 모두에 대해 WOPI 소스를 통해 요청을 일관되게 라우팅할 수 있는지 확인하십시오.

2단계: 차트를 검토하고 버전을 선택합니다.

차트와 그 값은 시간이 지남에 따라 변경될 수 있습니다. 설치하기 전에 이전 릴리스용으로 작성된 구성을 복사하는 대신 최신 공식 차트 README 파일과 값을 확인하십시오. 아래 예시는 2026년 10월 6일에 검토된 Collabora 차트 문서에 따른 것입니다. 설치 시점에 적용되는 최신 정보는 저장소의 최신 릴리스 노트와 값을 참조하십시오.

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions
helm show values collabora/collabora-online

조치: 변경 관리 정책에 맞는 차트 버전을 선택하고 해당 차트에서 배포되는 Collabora 이미지 버전을 기록하십시오. 반복적인 업그레이드를 위해 차트 버전을 고정하십시오. 프로덕션 환경에서 검토되지 않은 유동적인 버전에 의존하지 마십시오. 차트 설정 가이드는 Collabora Online for Kubernetes README를 참조하십시오 .

3단계: 세 개의 복제본에 대한 값을 준비합니다.

이 예제는 NGINX 인그레스 컨트롤러, 인그레스에서의 TLS 종료, 그리고 외부 WOPI 호스트를 가정합니다 cloud.example.com. 두 호스트 이름은 실제 환경에 맞게 변경하십시오. TLS 종료 위치가 다르거나 HAProxy를 사용하는 경우, 해당 컨트롤러의 문서화된 구성을 사용하십시오.

replicaCount: 3

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: --o:ssl.enable=false --o:ssl.termination=true

위의 해시 어노테이션과 타임아웃 값은 차트의 NGINX 예시에 나와 있습니다. 이 extra_params줄은 리버스 프록시가 TLS를 종료하고 HTTP를 통해 Collabora에 연결하는 경우에만 적합합니다. TLS 토폴로지가 다른 경우 이 줄을 변경하지 않고 그대로 사용하지 마십시오. 인그레스 TLS 시크릿과 호스트는 사용하는 인증서 관리자와 로컬 차트 값에 따라 구성해야 합니다. 이 예시에서는 공급자별 설정은 생략되어 있습니다.

조치: 이 내용을 저장하고 my_values.yaml, 인그레스에 필요한 TLS 구성을 추가한 다음, 모든 키를 선택한 차트 릴리스의 키와 비교하십시오 values.yaml. DNS, TLS, 통합의 Collabora URL 및 프록시 라우팅에서 Collabora 공개 호스트 이름을 일관되게 유지하십시오.

4단계: Collabora 릴리스를 설치합니다.

지정된 네임스페이스에 설치하십시오. <chart-version>2단계에서 선택한 버전으로 교체하십시오. 여기 있는 꺾쇠괄호는 설명용 자리 표시자이므로 그대로 입력해서는 안 됩니다.

helm install --create-namespace   --namespace collabora   collabora-online collabora/collabora-online   --version <chart-version>   -f my_values.yaml

기존 릴리스의 경우, 릴리스의 마이그레이션 노트와 변경 사항을 확인한 후 계획된 Helm 업그레이드를 사용하십시오. 첫 번째 스케일링 변경과 동시에 주요 이미지 또는 차트 업데이트를 배포하지 마십시오. 한 번에 하나의 변수만 변경하면 오류를 더 쉽게 분리할 수 있습니다.

조치: 릴리스를 검사하고 모든 복제본이 준비될 때까지 기다립니다.

helm status collabora-online -n collabora
kubectl get pods,svc,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

원하는 복제본이 3개라고 해서 3개의 노드가 정상적으로 트래픽을 처리하고 있다는 것을 보장하는 것은 아닙니다. 준비 상태, 최근 재시작, 스케줄링 및 인그레스 엔드포인트를 확인하십시오. Pod가 여전히 대기 중인 경우, 사용 가능한 클러스터 용량과 차트 값의 리소스 요청 및 제한 사항을 확인하십시오.

5단계: WOPI 애플리케이션을 연결합니다.

파일 플랫폼의 오피스 통합 설정에서 Collabora 서버 URL을 공개 엔드포인트(예: )로 설정하십시오 https://office.example.com. 통합 자체가 클러스터 내에서 실행되고 설계에서 프라이빗 라우팅이 명시적으로 지원되지 않는 한, 애플리케이션을 Pod IP 또는 Kubernetes 전용 서비스 이름으로 지정하지 마십시오.

`hostname`은 aliasgroups문서를 저장하고 제공하는 WOPI 호스트를 식별해야 하며, Collabora 호스트 이름이 아닙니다. 호스트 이름이 일치하지 않으면 Collabora Pod와 Ingress가 정상인 경우에도 WOPI 호스트 유효성 검사에 실패할 수 있습니다.

조치: 통합 구성에 동일한 Collabora 공개 URL을 입력하고 저장한 다음 연결 또는 검색 확인이 성공하는지 확인합니다. 실패하는 경우 복제본 수를 변경하기 전에 애플리케이션의 WOPI 허용 목록, Collabora의 별칭 그룹, DNS, TLS 및 프록시 헤더를 확인하십시오.

6단계: 문서 친화성 및 협업 기능 테스트

테스트 문서를 열고 인그레스 또는 프록시 로그를 검사하여 어떤 백엔드가 해당 문서를 제공하는지 확인합니다. 그런 다음 두 번째 사용자 세션에서 동일한 문서를 열고 두 사용자 모두 문서를 편집하고 서로의 변경 사항을 볼 수 있는지 확인합니다. 다른 문서를 열고 로드 밸런서가 해당 문서를 다른 정상적인 파드로 전송할 수 있는지 확인합니다. 이 테스트는 랜딩 페이지가 HTTP 200 응답을 반환하는지 여부뿐만 아니라 라우팅 및 협업 기능에 대한 것입니다.

조치: WOPI 소스 해시가 존재하고 WebSocket 업그레이드를 포함하여 동일한 문서에 대해 생성된 요청에 일관되게 적용되는지 확인하십시오. 사용자가 서로의 편집 내용을 볼 수 없는 경우, WOPI 호스트 또는 브라우저 캐시를 조사하기 전에 동일한 문서에 대한 백엔드 선택 항목을 비교하십시오.

7단계: 노드 상태 관리 및 노드 손실 테스트

준비 상태 검사는 상태가 불량하거나 시작 중인 Pod가 서비스에 접속하지 못하도록 해야 합니다. 차트에는 시작, 준비 상태 및 활성 상태 프로브 설정이 포함되어 있지만 정확한 동작 및 타이밍은 선택한 차트 버전과 클러스터에 따라 달라집니다. Pod를 사용할 수 없게 되면 해당 Pod에서 실행 중인 문서 작업이 중단될 수 있으므로, 기본적인 어피니티 풀을 실시간 세션 복제라고 설명해서는 안 됩니다.

조치: 테스트 환경에서 활성 편집 세션 중에 서비스 중인 Pod 하나를 제거하고 클라이언트 동작 및 프록시 라우팅을 관찰한 다음 문서를 다시 열고 정상적인 Pod에 연결되는지 확인하십시오. 승인된 유지 관리 계획 없이 활성 프로덕션 문서에 대해 이 테스트를 수행하지 마십시오. 세션 연속성을 더욱 엄격하게 유지하려면 COOL 컨트롤러와 버전별 라우트 토큰 설정을 평가하십시오.

8단계: 신중하게 모니터링, 조정 및 업그레이드하십시오.

Pod 재시작, CPU 및 메모리 사용량, 요청 및 WebSocket 오류, 인그레스 지연 시간, 문서 로딩 또는 재연결에 대한 사용자 보고 등을 추적하세요. Collabora 차트 문서에는 Kubernetes 모니터링 지침이 포함되어 있습니다. 예제 수치를 복사하는 대신 관찰된 워크로드를 기반으로 리소스를 설정하세요. 문서 크기, 동시 세션, 글꼴 및 편집 패턴은 모두 용량에 영향을 미칩니다.

Collabora는 클라이언트가 일관된 버전별 웹 자산을 받을 수 있도록 로드 밸런싱된 모든 노드에서 동일한 버전을 실행하는 것을 권장합니다. 업그레이드 시에는 차트에서 지원하는 롤아웃 전략을 사용하고, 준비 상태 및 로그를 모니터링하며, 변경 완료를 선언하기 전에 여러 사용자가 문서를 열어 테스트하십시오.

조치: 차트 버전, 이미지 버전, 값 파일 및 테스트 결과를 변경 기록에 함께 보관하십시오. 업그레이드 일정을 예약하고, 모든 복제본이 의도한 버전으로 수렴하는지 확인하고, 차트에서 지원하는 롤백 동작과 호환되는 롤백 계획을 유지하십시오.

흔히 잘못 알려진 사실들을 확인해 보세요

• "세 개의 복제본이 자동으로 작동 가능한 클러스터를 생성합니다." 복제본만으로는 문서 선호도를 구성할 수 없습니다. WOPI 소스의 인그레스 해시 또는 컨트롤러가 의도한 세션 라우팅을 제공하는지 확인하십시오.
• "사용자 IP를 기반으로 하는 고정 세션이면 충분합니다." 하지만 Collabora의 독립형 Kubernetes 풀 차트에서는 그렇게 설명하지 않습니다. 하나의 문서를 공동 작업하는 사용자는 서로 다른 장치나 네트워크에서 접속하더라도 동일한 노드에 연결되어야 합니다. 문서 기반 선호도를 구성하고 두 명의 사용자로 테스트해 보세요.
• "정상적인 홈페이지는 클러스터가 준비되었음을 증명합니다." 하지만 이는 단지 하나의 HTTP 요청이 성공적으로 반환되었음을 증명할 뿐입니다. 문서 열기 및 공동 편집, WebSocket 업그레이드, 그리고 파드 사용 불가 시 동작 등을 테스트해 보세요.
• "노드를 추가하면 노드 손실 시에도 활성 세션이 유지됩니다." 기본 WOPI 소스 선호도 풀은 문서를 노드로 라우팅하지만, 메모리 내 편집 프로세스가 복제되는지는 확인하지 않습니다. 제어된 테스트에서 예상되는 복구 동작을 확인하거나 컨트롤러의 별도 세션 관리 기능을 평가하십시오.

Kubernetes 환경이 아닌 경우 아키텍처 원칙은 동일하지만 Kubernetes 차트 명령 및 인그레스 어노테이션은 적용되지 않습니다. Collabora 버전 및 로드 밸런서에 맞는 프록시 구성을 사용하고, 장기 WebSocket 연결이 지원되는지 확인하며, WOPI 소스를 사용하여 문서별 라우팅을 구현하십시오. Collabora Online SDK 설명서에는 로드 밸런싱 및 WOPISrc어피니티 요구 사항에 대한 내용이 설명되어 있습니다. 사용 중인 릴리스의 설명서에서 해당 섹션을 확인하십시오.