Collabora CODE 설정 파일을 안전하게 백업하고 복원하는 방법

Collabora Online Development Edition(CODE) 26.04.4.2 버전이 2026년 9월 24일에 출시되었습니다. 이 버전은 백업 계획 수립에 중요한데, 26.04 릴리스 라인에서 최신 WebSocket URL에 대한 권장 리버스 프록시 경로 처리 방식이 일부 변경되었기 때문입니다. 업그레이드, 마이그레이션 또는 재해 복구를 준비하는 경우, XML 파일 하나만 백업하는 것으로는 정상적인 배포 환경을 재현하기에 충분하지 않을 수 있습니다.

검증된 핵심 부분은 간단합니다. Collabora의 메인 서버 구성 파일은 /etc/coolwsd/coolwsd.xml공식 CODE 컨테이너 내부에 포함되어 있습니다. 공식 Docker 문서에서는 해당 파일을 컨테이너 밖으로 복사하거나, 다시 컨테이너 안으로 복사하거나, 호스트에서 바인드 마운트하는 방법도 지원합니다. 달라지는 부분은 그 주변의 모든 것, 즉 Docker 환경 변수, 바인드 마운트, WOPI 인증 키, TLS 종료 및 리버스 프록시 구성입니다.

이 가이드는 네이티브 패키지 설치와 Docker 배포 모두에 대한 보수적인 백업 및 복원 프로세스를 보여줍니다. Collabora 문서에서 확인된 내용과 사용자의 배포 환경에 따라 달라지는 내용을 의도적으로 구분하여 설명합니다.

Collabora CODE 백업에는 무엇이 포함되어야 할까요?

확인됨: /etc/coolwsd/coolwsd.xml 이 파일은 Collabora Online의 기본 구성 파일입니다. Collabora는 이 경로를 직접 문서화하고 있으며, 사용 가능한 서버 옵션에 대한 설명이 파일에 포함되어 있다고 명시하고 있습니다. 자세한 내용은 Collabora Online SDK 공식 설명서를 참조하십시오 .

배포 환경에 따라 다릅니다. 완벽한 복구를 위해서는 서비스를 시작하는 데 사용된 구성 파일이 필요할 수 있습니다. Docker의 경우 Compose YAML 파일, 환경 변수, 바인드 마운트, 시크릿, 호스트에서 마운트된 파일 등이 포함될 수 있습니다. 네이티브 설치의 경우, 동일 서버에서 관리되는 경우 역방향 프록시 가상 호스트와 인증서도 포함될 수 있습니다.

조치: 아카이브를 생성하기 전에 인스턴스가 네이티브 패키지 설치인지 Docker/Compose 배포인지 기록해 두십시오. 두 경우 모두 동일한 복원 절차가 적용된다고 가정하지 마십시오.

시작하기 전에 흔히 발생하는 오해

coolwsd.xml 파일을 백업해도 사용자 문서는 백업되지 않습니다.

CODE는 일반적으로 WOPI를 통해 스토리지 플랫폼에 연결됩니다. 문서는 Nextcloud 또는 다른 WOPI 호스트와 같은 해당 스토리지 플랫폼의 제어 하에 유지됩니다. 따라서 CODE 구성을 복원해도 문서 자체는 복원되지 않습니다.

조치: WOPI 호스트와 해당 데이터 저장소를 해당 제품의 백업 절차에 따라 백업하십시오. 이 CODE 백업을 서비스 구성 백업으로 처리하십시오.

Docker 컨테이너는 백업이 아닙니다.

컨테이너는 이미지로부터 다시 생성할 수 있습니다. 환경 변수나 바인드 마운트를 통해 전달된 구성은 컨테이너 외부에 존재할 수 있지만, 컨테이너 내부에서만 이루어진 편집 내용은 컨테이너가 교체될 때 사라질 수 있습니다.

조치: 컨테이너 파일 시스템뿐만 아니라 배포 정의 및 호스트 마운트된 파일도 저장하십시오.

이전 coolwsd.xml 파일을 최신 버전으로 복사하는 것이 항상 가장 안전한 복원 방법은 아닙니다.

구성 옵션은 CODE 릴리스 버전에 따라 변경될 수 있습니다. Collabora의 최신 릴리스 노트에는 26.04 시리즈에서 지속적으로 변경되는 서버 및 프록시 관련 내용과 함께 간소화된 WebSocket URL에 대한 업데이트된 프록시 권장 사항이 나와 있습니다. 자세한 내용은 공식 CODE 26.04 릴리스 노트를 참조하십시오 .

조치: 모든 백업에 코드 버전을 기록하십시오. 다른 버전으로 복원할 때는 저장된 파일을 새 패키지의 기본 파일과 비교한 후 전체를 교체하십시오.

1단계: 설치된 버전 및 배포 유형을 기록합니다.

먼저 환경을 재현하는 데 필요한 정보를 충분히 기록하십시오. 컨테이너 배포의 경우 실행 중인 컨테이너와 해당 이미지를 검사하십시오.

docker ps --filter name=collabora
docker inspect collabora --format '{{.Config.Image}}'
docker inspect collabora --format '{{json .Mounts}}'

컨테이너 이름이 다른 경우, collabora그에 맞게 변경하십시오. 공식 이미지는 다음과 같이 게시됩니다 collabora/code. Docker Hub에서는 현재 최신 릴리스 라인에서 26.04.4.2 이미지를 식별합니다. Docker Hub에서 Collabora CODE 공식 이미지를 참조하십시오 .

네이티브 패키지 설치의 경우, 실제로 사용하는 패키지 관리자를 통해 패키지 버전을 기록해 두세요. 예를 들어, 데비안이나 우분투에서는 다음과 같습니다.

dpkg-query -W 'coolwsd*' 'collaboraoffice*' 2>/dev/null

조치: 버전 출력 결과를 구성 아카이브와 동일한 보호된 백업 디렉터리에 저장합니다.

2단계: 핵심 구성 및 배포 메타데이터 백업

네이티브 패키지 설치

루트 디렉토리만 백업하는 디렉토리를 생성하고, /etc/coolwsd메인 XML 파일만 선택하는 대신 전체 디렉토리를 아카이브하십시오. 이렇게 하면 설치된 패키지나 로컬 사용자 지정으로 인해 해당 디렉토리에 추가된 파일도 보존됩니다.

sudo install -d -m 700 /var/backups/collabora
sudo tar -C /etc -czpf \
  /var/backups/collabora/coolwsd-etc-$(date +%F).tar.gz \
  coolwsd

이 명령은 의도적으로 /etc아카이빙 전에 경로를 변경하므로 아카이브에는 coolwsd/절대 파일 시스템 경로 대신 상대 경로가 포함됩니다.

도커 또는 도커 컴포즈

Collabora의 문서에 따르면 공식 이미지에는 해당 파일이 포함되어 /etc/coolwsd/coolwsd.xml있으며 관리자는 컨테이너 외부에서 해당 파일을 복사, 수정, 다시 복사하거나 마운트할 수 있습니다.

호스트에서 해당 파일이 바인드 마운트되어 있지 않으면 파일을 복사하십시오.

sudo install -d -m 700 /var/backups/collabora
docker cp collabora:/etc/coolwsd/coolwsd.xml \
  /var/backups/collabora/coolwsd.xml

다음으로 컨테이너가 어떻게 구성되었는지 캡처합니다.

docker inspect collabora --format '{{json .Config.Env}}' \
  > /var/backups/collabora/container-env.json

docker inspect collabora --format '{{json .Mounts}}' \
  > /var/backups/collabora/container-mounts.json

중요: 환경 변수 출력에는 암호, 관리자 콘솔 자격 증명, 호스트 이름 또는 기타 비밀 정보가 포함될 수 있습니다. 이러한 파일은 루트 사용자만 읽을 수 있도록 유지하고, 호스트 외부에 복사본을 저장할 경우 암호화하거나 다른 방법으로 보호하십시오.

Docker Compose를 사용하는 경우, 실제 Compose 파일과 참조된 환경 변수 또는 비밀 파일들을 호스트에서 복사해야 합니다. 이러한 파일들의 위치는 배포 환경에 따라 다르므로, 안전하게 가정할 수 있는 보편적인 경로는 없습니다.

조치: 백업에 원본 파일이 포함되어 있는지 확인하십시오. coolwsd.xml바인드 마운트된 경우 호스트 파일을 백업하십시오. 환경 변수를 통해 구성이 제공되는 경우 해당 변수를 정의하는 Compose/실행 구성을 보존하십시오.

3단계: 증명 키, 프록시 구성 및 TLS는 필요한 경우에만 포함합니다.

이러한 구성 요소는 모든 설치 환경에서 동일하지 않기 때문에 중요합니다.

WOPI 증명 키: Collabora 문서에 따르면 RPM 및 DEB 설치 시 WOPI 증명 키 쌍이 자동으로 생성됩니다. Docker의 경우, 키 쌍은 공개 이미지에 포함되어 있지 않으므로, 사용할 때는 직접 생성하여 컨테이너에 제공해야 합니다(일반적으로 볼륨을 통해). coolconfig generate-proof-key키 생성 방법은 매뉴얼을 참조하십시오. Docker 키는 변경 불가능한 이미지 외부에 저장되므로 호스트 측에 마운트된 키를 분실하면 WOPI 증명 서명에 사용되는 ID가 변경될 수 있습니다.

조치: 컨테이너의 마운트 목록을 사용하여 인증 키 마운트의 호스트 위치를 확인하고 해당 호스트 측 파일 또는 디렉터리를 안전하게 백업하십시오. 배포 환경에서 사용하지 않는 경로를 임의로 만들지 마십시오.

리버스 프록시: Apache, Nginx, HAProxy, Traefik 또는 다른 프록시가 공용 호스트 이름, TLS 종료, WebSocket 라우팅 및 요청 전달 규칙을 보유할 수 있습니다. Collabora는 CODE 26.04에서 새로운 간소화된 WebSocket URL에 대한 프록시 지침을 업데이트했으며, 일부 경우에는 기존 방식을 유지합니다.

조치: Collabora 호스트 이름을 제공하는 정확한 프록시 구성을 백업하십시오. 파일 시스템 경로는 운영 체제 및 프록시에 따라 다르므로 튜토리얼에서 제공하는 일반적인 경로를 복사하는 대신 활성 프록시 구성에서 해당 경로를 확인하십시오.

TLS 인증서: 해당 호스트가 인증서를 실제로 소유하고 있는 경우에만 백업하십시오. TLS 연결이 로드 밸런서, 인그레스 컨트롤러, CDN 또는 별도의 리버스 프록시에서 종료되는 경우, 인증서 백업은 해당 위치에 저장해야 합니다.

4단계: 사용하기 전에 백업을 확인하십시오

명령 실행이 성공하는 것만 tar으로는 충분하지 않습니다. 아카이브 목록을 확인할 수 있는지, 그리고 예상되는 주요 구성 파일이 있는지 테스트하십시오.

sudo tar -tzf /var/backups/collabora/coolwsd-etc-$(date +%F).tar.gz \
  | grep 'coolwsd/coolwsd.xml'

호스트 외부 검증을 위한 체크섬을 생성합니다.

cd /var/backups/collabora
sha256sum * > SHA256SUMS

그런 다음 평소 사용하는 백업 시스템을 이용하여 백업 파일을 두 번째 안전한 위치로 복사하십시오. 보호하려는 호스트에 백업 사본 하나만 남겨두지 마십시오.

조치: 최소 한 번은 임시 디렉터리로 압축 해제 테스트를 해보세요. 한 번도 열어보지 않은 백업 파일은 단지 추측일 뿐입니다.

5단계: 안전하게 복원한 후 실행 중인 서비스를 검증합니다.

기본 설치 복원

먼저 동일한 CODE 릴리스를 설치하는 것이 좋습니다. 서비스를 중지하고 아카이브를 스테이징 디렉터리에 압축 해제한 다음 저장된 구성을 새로 설치된 기본 구성과 비교하십시오.

sudo systemctl stop coolwsd
sudo mkdir -p /root/collabora-restore
sudo tar -xzf /var/backups/collabora/coolwsd-etc-YYYY-MM-DD.tar.gz \
  -C /root/collabora-restore

sudo diff -u \
  /etc/coolwsd/coolwsd.xml \
  /root/collabora-restore/coolwsd/coolwsd.xml

버전이 일치하고 전체 교체를 진행하려는 경우, 먼저 새 디렉터리를 롤백 복사본으로 보관하십시오.

sudo cp -a /etc/coolwsd /etc/coolwsd.pre-restore
sudo cp -a /root/collabora-restore/coolwsd/. /etc/coolwsd/
sudo systemctl start coolwsd

버전이 다른 경우, 새 파일을 무턱대고 덮어쓰지 말고 실제로 변경한 설정을 병합하세요. 이렇게 하면 최신 릴리스에서 도입된 새로운 기본값이나 필수 요소가 손실되는 것을 방지할 수 있습니다.

Docker 배포 복원

기록된 이미지 버전과 원래 Docker Compose 또는 docker run정의를 사용하여 컨테이너를 다시 생성합니다. 컨테이너를 시작하기 전에 호스트 바인드 마운트된 구성, 인증 키 및 기타 외부 파일을 원래 호스트 경로로 복원합니다.

coolwsd.xml컨테이너 내부에 파일을 의도적으로 유지하고 바인드 마운트로 사용하지 않은 경우 , Collabora에서 제공하는 공식 방법에 따라 파일을 다시 복사할 수 있습니다. 하지만 실제로는 호스트 바인드 마운트를 사용하는 것이 컨테이너를 교체해도 구성이 유지되므로 재현이 더 쉽습니다.

조치: 먼저 배포 정의를 복원한 다음, 해당 정의에서 참조하는 파일을 복원하십시오. 이렇게 하면 환경 변수, 볼륨 및 XML 구성이 서로 일관성을 유지합니다.

복원 작업이 실제로 성공했는지 확인하는 방법

프로세스가 시작되었는지 여부만으로 성공 여부를 판단하지 마십시오. 클라이언트가 사용하는 동일한 네트워크 경로에서 서비스를 확인하십시오.

네이티브 설치의 경우:

sudo systemctl status coolwsd --no-pager
sudo journalctl -u coolwsd -n 100 --no-pager

Docker의 경우:

docker ps --filter name=collabora
docker logs --tail 100 collabora

Collabora 문서에는 해당 /hosting/capabilities엔드포인트를 통해 실행 중인 제품 이름과 버전을 비롯한 여러 정보를 가져올 수 있다고 나와 있습니다. 공개 Collabora URL을 통해 다음 명령으로 테스트해 보세요.

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

호스트 이름을 본인의 이름으로 바꾸십시오. 또한 WOPI 호스트에서 실제 문서를 열고 일반적인 리버스 프록시 경로를 통해 편집, 저장 및 재연결이 제대로 작동하는지 확인하십시오.

조치: 복원 작업은 기능 엔드포인트에서 응답이 오고 실제 문서를 열고 저장할 수 있게 된 후에만 완료된 것으로 간주합니다.

실용적인 백업 체크리스트

최종 권고

Collabora CODE 복구 계획 중 가장 신뢰할 수 있는 방법은 단일 파일을 복사하는 것이 아닙니다. coolwsd.xml정확한 CODE 버전과 배포 정의를 하나의 복구 가능한 세트로 함께 보관하십시오. 아키텍처에서 실제로 필요한 경우에만 증명 키, 프록시 규칙 및 TLS 자료를 추가하십시오. 업그레이드 시에는 가능한 한 동일한 릴리스로 복원하십시오. 최신 릴리스로 이동하는 경우, 검토 없이 새 기본값을 덮어쓰기보다는 구성을 비교하고 병합하십시오.

2026년 10월 6일 현재, Collabora의 공식 26.04 릴리스 노트 및 Docker 이미지 메타데이터에 따르면 CODE 26.04.4.2가 최신 릴리스입니다. 이미지 버전, 프록시 권장 사항 및 구성 옵션은 지속적으로 변경될 수 있으므로 향후 마이그레이션 전에 공식 자료를 다시 확인하십시오.