Como fazer backup e restaurar arquivos de configuração do Collabora CODE com segurança

A versão 26.04.4.2 do Collabora Online Development Edition (CODE) foi lançada em 24 de setembro de 2026. Isso é importante para o planejamento de backups, pois a versão 26.04 também alterou partes do tratamento recomendado de caminhos de proxy reverso para URLs WebSocket mais recentes. Se você estiver se preparando para uma atualização, migração ou recuperação de desastres, fazer backup de apenas um arquivo XML pode não ser suficiente para reproduzir uma implantação funcional.

O núcleo verificado é simples: o arquivo de configuração principal do servidor da Collabora é o `.code` /etc/coolwsd/coolwsd.xml, inclusive dentro do contêiner oficial do CODE. A documentação oficial do Docker também explica como copiar esse arquivo para fora de um contêiner, copiá-lo de volta ou montá-lo a partir do host. As partes que variam são tudo o que está ao redor: variáveis ​​de ambiente do Docker, montagens de diretórios, chaves à prova de WOPI, terminação TLS e configuração de proxy reverso.

Este guia apresenta um processo conservador de backup e restauração tanto para instalações de pacotes nativos quanto para implantações do Docker. Ele separa intencionalmente o que é confirmado pela documentação da Collabora do que depende da sua própria implementação.

O que deve incluir um backup do Collabora CODE?

Verificado: /etc/coolwsd/coolwsd.xml este é o arquivo de configuração principal do Collabora Online. A Collabora documenta este caminho diretamente e descreve o arquivo como autoexplicativo para as opções de servidor disponíveis. Consulte o manual oficial do SDK do Collabora Online .

Dependente da implantação: uma recuperação completa também pode exigir a configuração usada para iniciar o serviço. Para o Docker, isso pode incluir o arquivo YAML do Compose, variáveis ​​de ambiente, montagens de diretórios, segredos e arquivos montados do host. Para uma instalação nativa, pode incluir um host virtual de proxy reverso e certificados, caso sejam gerenciados no mesmo servidor.

Ação: antes de criar um arquivo, anote se sua instância é uma instalação de pacote nativo ou uma implantação Docker/Compose. Não presuma que o mesmo procedimento de restauração se aplica a ambos.

Mal-entendidos comuns antes de começar

Fazer backup do arquivo coolwsd.xml não inclui os documentos do usuário.

O CODE normalmente se conecta a uma plataforma de armazenamento por meio do WOPI. Os documentos permanecem sob o controle dessa plataforma de armazenamento, como o Nextcloud ou outro host WOPI. Portanto, restaurar a configuração do CODE não restaura os documentos em si.

Ação: faça backup do host WOPI e do seu armazenamento de dados usando o procedimento de backup próprio do produto. Considere este backup do CODE como um backup de configuração de serviço.

Um contêiner Docker não é um backup.

Um contêiner pode ser recriado a partir de uma imagem. Configurações passadas por meio de variáveis ​​de ambiente ou montagens de diretórios podem residir fora do contêiner, enquanto edições feitas somente dentro do contêiner podem desaparecer quando o contêiner for substituído.

Ação: salve a definição de implantação e os arquivos montados no host, não apenas o sistema de arquivos do contêiner.

Copiar um arquivo coolwsd.xml antigo para substituir uma versão mais recente nem sempre é a forma mais segura de restauração.

As opções de configuração podem mudar entre as versões do CODE. As notas de versão atuais da Collabora mostram mudanças contínuas no servidor e no proxy na série 26.04, incluindo recomendações atualizadas de proxy para a URL WebSocket compacta. Consulte as notas de versão oficiais do CODE 26.04 .

Ação: registre a versão do código em todos os backups. Ao restaurar para uma versão diferente, compare o arquivo salvo com o padrão do novo pacote antes de substituí-lo completamente.

Etapa 1: Registre a versão instalada e o tipo de implantação.

Comece registrando informações suficientes para reproduzir o ambiente. Para uma implantação em contêiner, inspecione o contêiner em execução e sua imagem:

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

Se o seu contêiner usar um nome diferente, substitua-o collaborade acordo. A imagem oficial é publicada como collabora/code; o Docker Hub atualmente identifica a imagem 26.04.4.2 na linha de lançamento mais recente. Veja a imagem oficial do Collabora CODE no Docker Hub .

Para instalar um pacote nativo, anote a versão do pacote usando o gerenciador de pacotes que você utiliza. No Debian ou Ubuntu, por exemplo:

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

Ação: salve o resultado da versão no mesmo diretório de backup protegido que o arquivo de configuração.

Etapa 2: Faça backup da configuração principal e dos metadados de implantação.

Instalação de pacote nativo

Crie um diretório de backup somente para a raiz e arquive o /etc/coolwsddiretório completo, em vez de selecionar apenas o arquivo XML principal. Isso preserva quaisquer arquivos adicionais que seu pacote instalado ou personalização local tenha colocado lá.

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

Este comando altera deliberadamente o caminho /etcantes do arquivamento, de forma que o arquivo contenha um coolwsd/caminho relativo em vez de um caminho absoluto do sistema de arquivos.

Docker ou Docker Compose

A documentação da Collabora afirma que a imagem oficial contém /etc/coolwsd/coolwsd.xmlo seguinte conteúdo e que os administradores podem copiá-la, modificá-la, copiá-la de volta ou montá-la de fora do contêiner.

Se o arquivo ainda não estiver montado no host, copie-o:

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

Em seguida, registre como o contêiner foi configurado:

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

Importante: os comandos do ambiente podem conter senhas, credenciais do console de administração, nomes de host ou outros segredos. Mantenha esses arquivos legíveis apenas pelo usuário root e criptografe ou proteja de alguma outra forma as cópias externas.

Se você usa o Docker Compose, copie o arquivo Compose e quaisquer arquivos de ambiente ou segredos referenciados do host. Os locais desses arquivos são específicos para sua implantação, portanto, não existe um caminho universal que possa ser assumido com segurança.

Ação: confirme se seu backup inclui a fonte de dados confiável. Se coolwsd.xmlo sistema estiver montado via bind, faça backup do arquivo hosts. Se a configuração for fornecida por meio de variáveis ​​de ambiente, preserve a configuração do Compose/run que define essas variáveis.

Etapa 3: Inclua chaves de prova, configuração de proxy e TLS somente quando aplicável.

Esses componentes são importantes justamente porque não são idênticos em todas as instalações.

Chave de prova WOPI: A documentação da Collabora indica que as instalações RPM e DEB geram automaticamente o par de chaves de prova WOPI. Para o Docker, o par de chaves não é fornecido na imagem pública; quando utilizado, ele deve ser gerado e fornecido ao contêiner, geralmente por meio de um volume. O manual descreve coolconfig generate-proof-keycomo gerar a chave. Como a chave do Docker reside fora da imagem imutável, a perda da chave montada no host pode alterar a identidade usada para a assinatura de prova WOPI.

Ação: utilize a lista de montagens do contêiner para identificar a localização no host de qualquer montagem com chave de segurança e faça backup desse arquivo ou diretório no host de forma segura. Não crie um caminho se sua implantação não o utiliza.

Proxy reverso: Apache, Nginx, HAProxy, Traefik ou outro proxy pode armazenar o nome de host público, a terminação TLS, o roteamento WebSocket e as regras de encaminhamento de solicitações. No CODE 26.04, a Collabora atualizou as diretrizes de proxy para a URL WebSocket compacta mais recente, mantendo, ao mesmo tempo, uma alternativa legada em alguns casos.

Ação: faça backup da configuração exata do proxy que atende ao seu hostname do Collabora. O caminho do sistema de arquivos depende do seu sistema operacional e do proxy, portanto, identifique-o na configuração do proxy ativo em vez de copiar um caminho genérico de um tutorial.

Certificados TLS: faça backup deles somente se este host realmente os possuir. Se o TLS for encerrado em um balanceador de carga, controlador de entrada, CDN ou proxy reverso separado, o backup do certificado deve ser feito lá.

Passo 4: Verifique o backup antes de precisar dele.

Executar um tarcomando com sucesso não é suficiente. Verifique se o arquivo compactado pode ser listado e se o arquivo de configuração principal esperado está presente.

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

Criar um checksum para verificação fora do host:

cd /var/backups/collabora
sha256sum * > SHA256SUMS

Em seguida, copie o backup para um segundo local protegido usando seu sistema de backup normal. Não deixe a única cópia no mesmo host que você está protegendo.

Ação: teste a extração para um diretório temporário pelo menos uma vez. Um backup que você nunca abriu é apenas uma suposição.

Etapa 5: Restaure de forma conservadora e, em seguida, valide o serviço em execução.

Restaurar uma instalação nativa

É preferível instalar primeiro a mesma versão do CODE. Pare o serviço, extraia o arquivo para um diretório de preparação e compare a configuração salva com a configuração padrão recém-instalada:

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

Se as versões coincidirem e você pretender uma substituição completa, primeiro mantenha o diretório atualizado como uma cópia de reversão:

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

Se as versões forem diferentes, mescle as configurações que você realmente alterou em vez de substituir cegamente o novo arquivo. Isso evita descartar novos valores padrão ou elementos obrigatórios introduzidos pela versão mais recente.

Restaurar uma implantação do Docker

Recrie o contêiner a partir da versão da imagem gravada e do Docker Compose ou docker rundefinição original. Restaure a configuração de vinculação do host, as chaves de prova e outros arquivos externos para seus caminhos originais no host antes de iniciar o contêiner.

Se você manteve coolwsd.xmlo arquivo dentro do contêiner em vez de usá-lo como um ponto de montagem (bind mount), a abordagem documentada pela Collabora permite copiar o arquivo de volta. Na prática, um ponto de montagem no host é mais fácil de reproduzir, pois a configuração persiste mesmo após a substituição do contêiner.

Ação: restaure primeiro a definição de implantação e, em seguida, restaure os arquivos aos quais ela faz referência. Isso mantém as variáveis ​​de ambiente, os volumes e a configuração XML consistentes entre si.

Como confirmar se a restauração realmente funcionou

Não julgue o sucesso apenas pelo fato de o processo iniciar. Verifique o serviço a partir do mesmo caminho de rede usado pelos clientes.

Para uma instalação nativa:

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

Para Docker:

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

A Collabora documenta o /hosting/capabilitiesendpoint como uma forma de recuperar, entre outras informações, o nome e a versão do produto em execução. Por meio do seu URL público da Collabora, teste-o com:

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

Substitua o nome do host pelo seu. Além disso, abra um documento real do host WOPI e verifique se a edição, o salvamento e a reconexão funcionam corretamente pelo caminho normal do proxy reverso.

Ação: considere a restauração concluída somente após o ponto de extremidade de recursos responder e um documento real poder ser aberto e salvo.

Lista de verificação de backup prática

Recomendação final

O plano de recuperação mais confiável para o Collabora CODE não se baseia em um único arquivo copiado. Mantenha coolwsd.xmlo arquivo de configuração, a versão exata do CODE e a definição de implantação juntos como um conjunto recuperável. Adicione chaves de prova, regras de proxy e conteúdo TLS somente onde sua arquitetura realmente os utiliza. Para atualizações, restaure para a mesma versão sempre que possível; se você migrar para uma versão mais recente, compare e mescle as configurações em vez de sobrescrever os novos padrões sem revisão.

Em 6 de outubro de 2026, a versão atual do CODE, conforme indicado nas notas de lançamento oficiais da Collabora para a versão 26.04 e nos metadados da imagem Docker, era a 26.04.4.2. Consulte essas fontes oficiais novamente antes de uma futura migração, pois as versões das imagens, as recomendações de proxy e as opções de configuração continuam a evoluir.