Nextcloud를 자체 호스팅 Collabora CODE 컨테이너에 연결하기

Nextcloud를 자체 호스팅 Collabora Online Development Edition(CODE) 컨테이너에 연결하려면 CODE를 별도의 호스트 이름에서 실행하고 HTTPS 뒤에 배치한 다음 Nextcloud Office에 해당 공개 URL을 입력해야 합니다. 또한 CODE 컨테이너에서 Nextcloud 사이트의 오리진을 WOPI 호스트로 허용해야 합니다. 아래 예시에서 Nextcloud는 cloud.example.com이고 Collabora는 입니다 office.example.com. 두 호스트 이름을 실제 호스트 이름으로 바꾸십시오.

시작하기 전에 무엇을 준비해야 할까요?

Nextcloud가 정상적으로 설치되어 있어야 하고, CODE 컨테이너를 실행할 수 있는 Docker 호스트, Nextcloud 및 Collabora 호스트 이름에 대한 DNS 레코드, 그리고 두 공개 사이트 모두에 유효한 HTTPS 인증서가 필요합니다. Nextcloud 호스트와 Collabora 서버는 네트워크를 통해 서로 연결될 수 있어야 합니다. 전용 Collabora 서버는 내장된 CODE 옵션보다 용량을 향상시키기 위한 것이지만, 아직 개발 버전이므로 대규모 또는 비즈니스 핵심 환경에 사용하기 전에 Collabora의 최신 약관 및 릴리스 지침을 확인하십시오.

이 가이드에서는 리버스 프록시가 Docker 호스트에서 실행되고 HTTPS 트래픽을 office.example.com컨테이너의 로컬 포트로 전달하는 상황을 가정합니다. 프록시가 다른 컨테이너 또는 다른 머신에서 실행되는 경우 루프백 포트 매핑을 그대로 복사하지 마십시오. 프록시가 접근할 수 있는 프라이빗 Docker 네트워크 또는 프라이빗 호스트 주소를 사용하고, 백엔드가 공개적으로 노출되지 않도록 방화벽을 설정하십시오.

1. CODE 컨테이너를 시작합니다.

먼저 이미지를 다운로드하고 컨테이너를 시작하세요. 별칭 설정에서 Nextcloud의 공개 오리진(프로토콜 및 포트 포함)을 사용하세요. Collabora URL은 입력하지 마세요. Nextcloud의 Docker 설치 예제는 이 패턴을 사용합니다.

docker pull collabora/code
docker run -t -d -p 127.0.0.1:9980:9980 \
  -e 'aliasgroup1=https://cloud.example.com:443' \
  --restart always \
  --cap-add MKNOD \
  collabora/code

루프백 바인딩은 포트 9980이 Docker 호스트(예: 동일 호스트의 리버스 프록시)에서만 접근 가능하다는 것을 의미합니다. 프록시는 컨테이너 포트를 비공개로 유지하면서 브라우저와 Nextcloud에 공개 HTTPS 엔드포인트를 제공합니다. Nextcloud가 표준 포트가 아닌 다른 포트를 사용하거나 다른 공개 호스트 이름을 통해 제공되는 경우, 별칭을 사용자가 실제로 사용하는 원본 호스트 이름과 일치시켜야 합니다. Nextcloud 인스턴스가 여러 개인 경우, 임의의 도메인을 광범위하게 허용하는 대신 Collabora에서 제공하는 공식 구문을 사용하여 각 허용된 WOPI 호스트를 구성해야 합니다.

위 명령어는 Nextcloud 35 관리 설명서의 Docker 예제를 따릅니다. 실제 운영 환경에서 사용하기 전에 최신 CODE 이미지 문서를 검토하고 유지 관리 프로세스에 맞는 릴리스/태그 업데이트 정책을 선택하십시오. 릴리스가 게시됨에 따라 기본 이미지 참조가 변경될 수 있으므로 업데이트 계획을 수립하고 컨테이너를 모니터링하며 업그레이드 후 문서 편집을 다시 테스트하십시오.

2. 컨테이너를 HTTPS 리버스 프록시 뒤에 배치합니다.

기존 프록시를 구성하여 https://office.example.comCODE 서비스로 요청을 전달하고 처리하도록 설정하세요 127.0.0.1:9980. 프록시 소프트웨어에는 Collabora의 현재 리버스 프록시 구성을 사용하십시오. 프록시는 필수 경로를 유지하고 WebSocket 업그레이드를 지원해야 합니다. 에디터의 브라우저 세션은 이러한 경로에 의존합니다. Nextcloud Docker 예제에는 WebSocket 엔드포인트를 포함하여 /browser, /hosting/discovery, /hosting/capabilities, 에 대한 경로가 포함되어 있습니다 /cool. 일부 통합은 호환성 /lool경로도 사용합니다.

홈페이지 로딩이 성공했다고 해서 프록시 설정이 완료된 것으로 간주해서는 안 됩니다. 일반 HTTPS 요청은 처리하지만 WebSocket 연결 업그레이드에 실패하는 프록시는 편집기 프레임을 표시한 후 로딩 중이거나 연결이 끊어진 상태로 남아 있을 수 있습니다. Collabora 호스트 이름에 유효한 공개 인증서를 사용하십시오. 프록시가 유일한 진입점 역할을 하도록 설정한 경우, 9980번 포트를 공용 인터넷에 개방하지 않도록 유지하십시오.

3. Nextcloud Office를 활성화하고 서버 URL을 입력합니다.

Nextcloud에서 앱을 열고 Nextcloud Office ( 통합 기능)를 설치하거나 활성화합니다 richdocuments. 그런 다음 관리 설정 → Office를 열고 외부 Collabora 서버 옵션을 선택한 후 를 입력합니다 . 설정을 저장합니다. Nextcloud 서버와 사용자의 브라우저가 동일한 외부 Collabora 엔드포인트를 확인해야 하므로 https://office.example.com공개 URL을 사용해야 합니다 .localhost:9980

Nextcloud 관리 설명서에 따르면 구성된 서버 URL은 Collabora 설치와 동일한 프로토콜을 사용해야 하며 HTTPS를 권장합니다. 저장 후 Nextcloud에 연결 또는 검색 상태가 표시될 수 있습니다. 인증서, DNS 또는 WOPI 문제가 보고되면 파일을 열기 전에 해당 문제를 해결하십시오.

4. WOPI 경로를 확인하고 테스트 문서를 엽니다.

WOPI는 Nextcloud가 Collabora에 문서에 대한 제어된 액세스 권한을 부여하는 데 사용하는 프로토콜입니다. Nextcloud Office 관리 설정에서 WOPI 요청 허용 목록을 검토 하고 Collabora 서비스가 Nextcloud에 접속하는 IP 주소로만 요청을 제한하십시오. 또한 Collabora가 의도한 WOPI 호스트만 허용하도록 구성하십시오. 컨테이너, NAT 또는 역방향 프록시가 관련된 경우 정확한 주소가 다를 수 있으므로 추측하지 말고 Nextcloud 로그에서 실제로 확인되는 소스 주소를 사용하십시오.

정상 작동 여부를 확인하려면 일반 Nextcloud 사용자 계정으로 로그인하여 간단한 DOCX 또는 ODT 파일을 생성하거나 업로드한 후, 파일 메뉴에서 해당 파일을 엽니다. 편집기가 제대로 로드되는지 확인하고, 간단한 변경 작업을 수행한 후 저장 표시가 나타날 때까지 기다립니다. 그런 다음 문서를 닫았다가 다시 열어 변경 사항이 유지되는지 확인합니다. 배포 환경에 중요한 모든 파일 형식과 사용자 그룹을 대상으로 테스트를 진행하십시오. DOCX 파일 테스트가 성공했다고 해서 모든 파일 형식이나 권한 경로가 올바르게 구성되었다는 의미는 아닙니다.

에디터가 열리지 않을 경우 무엇을 확인해야 할까요?

• 검색 또는 연결 오류:office.example.com Nextcloud 서버와 브라우저에서 주소가 제대로 확인되는지, 인증서가 유효한지, 프록시가 /hosting/discoveryCODE로 요청을 보내는지 확인하십시오 .
• 무한 로딩 또는 편집기 연결 끊김 현상: 리버스 프록시의 WebSocket 업그레이드 처리 및 /cool라우팅 설정을 확인하세요. 프록시 및 컨테이너 로그에서 거부된 요청을 검토하십시오.
• WOPI 호스트가 거부되었습니다. 구성된 aliasgroup1호스트와 스키마 및 포트를 포함한 정확한 Nextcloud 공개 오리진을 비교하십시오. Nextcloud에서 볼 수 있는 Collabora 소스 IP와 Nextcloud의 WOPI 허용 목록을 비교하여 확인하십시오.
• 호스트에서는 작동하지만 Nextcloud에서는 작동하지 않습니다. Nextcloud 서버에서 Collabora 공개 URL로의 연결을 테스트해 보세요. 컨테이너의 내부 호스트 이름이나 Docker 호스트의 localhost 주소는 모든 컨테이너에서 자동으로 접근 가능한 것은 아닙니다.
• 인증서 경고: 인증서 체인 또는 호스트 이름 불일치를 수정하십시오. 인증서 확인을 비활성화하면 원인이 숨겨지고 연결이 약화될 수 있습니다.

진단을 위해 공식 Nextcloud Docker 설치 예제 , Office 및 WOPI 구성 지침 , 그리고 Collabora의 CODE Docker 이미지 및 역방향 프록시 문서 와 구성을 비교해 보세요 . 이러한 참조 자료는 버전이 지정되어 있으며 변경될 수 있습니다. 여기에 제시된 명령은 2026년 10월 10일에 제공되는 Nextcloud 35 관리 예제를 기준으로 합니다.