Backup y restauración de Confluence con acs2md — space get, space check y space restore, paso a paso

Confluence Cloud conserva una papelera y un historial de versiones. No conserva una copia que te pertenezca, y el día en que se elimina un espacio, un movimiento masivo manda un subárbol a la papelera o alguien sobrescribe un runbook minutos antes de una llamada de incidente, la papelera y el historial son justo lo que no puedes alcanzar. Desde la versión 1.0.12, acs2md cierra ese hueco con tres comandos: space get toma una copia de seguridad nativa y restaurable, space check demuestra que la copia está al día, y space restore devuelve páginas, carpetas o un espacio entero a Confluence después de mostrarte el plan.

Esta guía recorre el ciclo completo sobre un espacio real, tal como lo ejecutaría un operador: instalar y licenciar la herramienta, tomar la primera copia, programar la verificación, ensayar una recuperación en un espacio de pruebas, restaurar de verdad y archivar la evidencia que pedirá una revisión de gobernanza o de seguridad. Todos los comandos corresponden a acs2md v1.0.12; el manual de acs2md tiene la referencia completa de flags donde esta guía resume.

Qué cambió en acs2md v1.0.12, y por qué importa para la gobernanza

Hasta v1.0.12, acs2md era una herramienta de exportación. Convertía espacios a Markdown y, con space get, guardaba los cuerpos de página en su formato nativo ADF o storage. Eso es una copia de continuidad, pero no una copia de seguridad que puedas restaurar, porque las páginas de Confluence son más que cuerpos: tienen adjuntos, etiquetas, propiedades de contenido en las que las aplicaciones guardan su estado, una posición en un árbol de carpetas y una versión. v1.0.12 añade todo eso:

• space get escribe una copia de seguridad restaurable. Junto a los cuerpos guarda .backup-manifest.json, que registra el ID, el título, el estado, el padre, la posición, la versión y un SHA-256 del archivo de cada página, el nombre, el tipo, la descripción y la página de inicio del espacio, y cada carpeta de Confluence bajo la que están las páginas. Los adjuntos van a attachments/<page-id>/; las etiquetas y propiedades de contenido, al manifiesto. Las páginas y adjuntos sin cambios se omiten en la siguiente ejecución.
• space check compara la copia con el espacio en vivo, página a página, e informa de lo que se editó, renombró, movió, envió a la papelera, archivó, eliminó o añadió desde entonces. --fail-on-drift convierte una ejecución programada en una alerta; -f json te da un registro que conservar.
• space restore devuelve el espacio, empezando por los padres: las páginas y carpetas que Confluence perdió (--mode missing, el valor por defecto), las páginas editadas desde entonces (--mode changed) o ambas (--mode all). --create-space reconstruye un espacio eliminado o lo clona con una clave nueva. El progreso se guarda tras cada página, así que una restauración interrumpida se reanuda donde se detuvo.
• Una restauración nunca elimina, envía a la papelera, archiva ni mueve nada, y --dry-run muestra el plan sin escribir. Una propiedad en la que una aplicación guarda estado se conserva salvo que pases --overwrite-properties.

Para un programa de gobernanza, esta es la diferencia entre “exportamos Confluence” y “podemos demostrar una copia verificada y una recuperación probada”. ISO/IEC 27001:2022 pide exactamente eso en los controles A.8.13 (copias de seguridad de la información) y A.5.30 (preparación de las TIC para la continuidad de negocio); los criterios de disponibilidad de SOC 2 quieren procesos de copia y procedimientos de recuperación probados (A1.3); el artículo 21(2)(c) de NIS 2 nombra la gestión de copias de seguridad y la recuperación ante desastres sin rodeos. La página de continuidad de negocio para Confluence en climakers.com relaciona la evidencia con cada marco. Climakers no está certificado bajo ninguno de ellos; las herramientas producen los artefactos en los que se apoyan tus propios controles y auditores.

Paso 1 — Instalar, licenciar y comprobar el puesto de trabajo

Sigue Instalación y configuración inicial para el paquete firmado de macOS o el archivo de Linux. Una tarea de copia de seguridad quiere un plan que permita ejecuciones desatendidas: el plan CI/CD Automation está hecho para pipelines, y Professional o Small Team encajan en el puesto de un operador. Compáralos en la tienda de Climakers; todos los planes empiezan con una prueba gratuita de 14 días.

# Activa la licencia de tu pedido y confirma el puesto de extremo a extremo
acs2md license activate --license-key TU_CLAVE_DE_LICENCIA
acs2md doctor

doctor comprueba la configuración, las credenciales de Confluence, la conectividad con la API, la licencia, el identificador de máquina y, desde v1.0.12, dos filas que conviene leer antes de una copia: HTTP request timeout (cada petición tiene ahora un plazo, diez minutos por defecto, así que una conexión bloqueada ya no deja colgada una tarea nocturna) y Latest version, que te avisa cuando hay una versión más reciente. Mantén las credenciales en variables de entorno en vez de en el archivo de configuración cuando la tarea se ejecute desde un planificador; la página de Configuración lista ACS2MD_CONFLUENCE_DOMAIN, ACS2MD_CONFLUENCE_USERNAME y ACS2MD_CONFLUENCE_API_TOKEN.

Paso 2 — Localiza el espacio y mira lo que vas a respaldar

Nunca programes una tarea contra un espacio que no has inspeccionado.

acs2md space list
acs2md space pages by-key DEVOPS

space pages muestra el árbol de páginas. Fíjate en cuántas páginas están bajo carpetas de Confluence: en un espacio real, más de un tercio lo estaban, y sin el árbol de carpetas una restauración las habría aplanado. El manifiesto registra ese árbol, que es una de las razones por las que la copia es nativa y no Markdown.

Paso 3 — Toma la primera copia de seguridad restaurable

acs2md space get by-key DEVOPS --output-dir /backups --log-file /backups/DEVOPS.log

La clave del espacio se añade al directorio de salida, así que esto escribe en /backups/DEVOPS/. Lo que queda ahí:

Dos valores por defecto cambiaron en v1.0.12 y conviene conocerlos. space get guarda ahora en formato storage en lugar de ADF, porque storage se refiere a los adjuntos y a las páginas por nombre, lo que sobrevive a una restauración que les da ID nuevos; pasa --format atlas_doc_format si necesitas ADF, y un directorio que ya contiene una copia conserva su formato. Y la primera ejecución de v1.0.12 sobre una copia tomada por una versión anterior descarga cada página una vez más para completar el manifiesto; las siguientes vuelven a omitir las páginas sin cambios.

Los adjuntos, las etiquetas y las propiedades de contenido cuestan cada uno llamadas adicionales a la API. Están activados por defecto porque una copia sin ellos no es restaurable; --include-attachments=false, --include-labels=false y --include-properties=false existen para los pipelines que solo quieren cuerpos.

Mantén /backups en almacenamiento que controles y conserves, fuera del inquilino de Atlassian. Ese es el sentido del ejercicio.

Paso 4 — Verifica la copia cada noche con space check

Una copia que nadie comprueba es una esperanza, no un control. space check compara la copia con el espacio en vivo y te dice, página a página, qué difiere:

acs2md space check by-key DEVOPS --backup-dir /backups --fail-on-drift -f json > /backups/DEVOPS.check.json

El informe clasifica cada página en un estado:

Las carpetas y el nombre y la página de inicio del espacio también se comparan. --fail-on-drift hace que el comando termine con un código distinto de cero cuando algo difiere, que es lo que un planificador o una tarea de CI necesita para levantar una alerta; el archivo JSON es el registro que conservas. --deep compara también los cuerpos de página, además de las versiones, a cambio de una llamada a la API por página.

El patrón práctico es: copia, y después comprobación, cada noche. space get recoge los cambios; space check justo después confirma que la copia está al día, y cualquier otro día te dice qué pasó en el espacio desde la última copia buena, antes de que nadie escriba nada. La página Comprobar frente a una copia de seguridad documenta los estados y la forma del JSON.

Paso 5 — Ensaya la recuperación en un espacio de pruebas

Una restauración no probada es el hueco que encuentran la mayoría de las auditorías. space restore --create-space te permite ensayar sin tocar el original: restaura la copia en un espacio con una clave nueva y después compara esa copia con la copia de seguridad.

# Ensayo: reconstruye la copia como DEVOPS-DR, con todo lo que contiene
acs2md space restore by-key DEVOPS-DR --backup-dir /backups/DEVOPS --create-space --mode all --yes

# Demuéstralo: compara el espacio de pruebas con la copia de la que salió
acs2md space check by-key DEVOPS-DR --backup-dir /backups/DEVOPS --all -f json > /backups/DEVOPS-DR.test.json

space check reconoce las páginas restauradas: una página recreada tiene un ID nuevo, y la comprobación la asocia a su original a través del archivo de progreso de la restauración, así que el informe del ensayo dice ok para cada página que volvió. El .restore-state.json que queda en el directorio de la copia registra qué se restauró y cuándo.

Dos cuidados antes de hacer esto cada trimestre. El ensayo deja el archivo de progreso apuntando a DEVOPS-DR, así que una restauración real en DEVOPS más adelante necesita --reset-state. Y una restauración nunca elimina nada, tampoco un espacio de pruebas, así que retira DEVOPS-DR a mano en Confluence después.

Paso 6 — Restaura de verdad: páginas, un subárbol o un espacio entero

Cuando algo se pierde de verdad, la secuencia es siempre la misma: mira el plan y después ejecútalo.

# ¿Qué volvería? No cambies nada.
acs2md space restore by-key DEVOPS --backup-dir /backups/DEVOPS --dry-run

# Devuelve lo que Confluence ya no tiene (páginas y carpetas en la papelera, archivadas o purgadas)
acs2md space restore by-key DEVOPS --backup-dir /backups/DEVOPS

# Revierte también las páginas editadas desde la copia
acs2md space restore by-key DEVOPS --backup-dir /backups/DEVOPS --mode changed

# Ambas cosas, sin intervención
acs2md space restore by-key DEVOPS --backup-dir /backups/DEVOPS --mode all --yes

El plan va primero:

♻️  Restore from /backups/DEVOPS (manifest, storage, last updated 2026-10-31 02:00)
   Into:  DevOps (DEVOPS)
   Mode:  missing
   Plan:  create 1 folder, create 3 pages

┌────────┬────────┬────────────┬───────────────┬─────────┐
│ DO     │ KIND   │ ID         │ TITLE         │ WHY     │
├────────┼────────┼────────────┼───────────────┼─────────┤
│ create │ page   │ 3134096561 │ Release Guide │ trashed │
│ create │ folder │ 5989695572 │ Operations    │ missing │
│ create │ page   │ 3134096562 │ Chapter 1     │ trashed │
│ create │ page   │ 3134096563 │ Runbook       │ missing │
└────────┴────────┴────────────┴───────────────┴─────────┘

Restore 4 item(s)? [y/N]

Conviene saber cómo se comporta una restauración antes de aprobar un plan:

• Primero los padres. Una página va bajo su padre respaldado, o bajo la página o carpeta que la restauración acaba de crear para ella. Las carpetas también vuelven.
• A una página que sigue vigente en el espacio se le restaura su versión respaldada, conservando su ID y su historial, o se le escribe el cuerpo respaldado como una versión nueva cuando esa versión ya no existe.
• Una página que ya está se adopta. Antes de crear una página, la restauración busca una página vigente con su título y la toma como la página restaurada, añadiendo solo lo que le falta. Una ejecución interrumpida se puede repetir sin riesgo.
• Los enlaces siguen a la restauración. Cuando todas las páginas existen, los enlaces entre páginas restauradas pasan a apuntar a sus nuevos ID, incluidos los enlaces que cambian a una clave de espacio nueva. Los enlaces a Jira, a otros sitios y a páginas que no se recrearon se dejan como están.
• Las propiedades de contenido no se sobrescriben. Las aplicaciones guardan estado en propiedades, por ejemplo una aprobación de control documental; una propiedad con un valor distinto se conserva salvo que pases --overwrite-properties.
• Lo que no puede volver: una página recreada es una página nueva, así que su ID, sus autores, su fecha de creación y su historial de versiones son nuevos; las páginas movidas a otro padre desde la copia no se devuelven a su sitio; las restricciones de página y los permisos del espacio no forman parte de la copia.

Una sola página es una recuperación de un comando, desde la copia del espacio, con el comando page restore que acs2md comparte con acp2md:

acs2md page restore --backup-dir /backups/DEVOPS --page-id 3134096561

La página Restaurar un espacio tiene los modos, el formato del plan y la lista completa de lo que una restauración puede y no puede devolver.

Paso 7 — Añade la capa de gobernanza: permisos, propiedades y una copia legible

Una copia de seguridad responde a “¿podemos recuperarlo?“. La gobernanza también pregunta “¿quién podía llegar a ello?” y “¿podemos leerlo cuando Confluence está caído?”. acs2md cubre ambas desde el mismo binario:

# Quién puede llegar al espacio, para la revisión de accesos
acs2md space permissions by-key DEVOPS -f json > /audit/DEVOPS.permissions.json
acs2md space properties by-key DEVOPS -f json > /audit/DEVOPS.properties.json

# Una copia Markdown que la gente puede leer en Git o en un archivo, refrescada solo con las páginas que cambiaron
acs2md space convert by-key DEVOPS --output-dir /continuity --sync

La copia de continuidad es el tema de nuestra guía sobre copias de continuidad en Git; la copia nativa y la copia legible se complementan, y la página de flujos las muestra una junto a otra.

La evidencia que deja detrás

Pon los pasos en un planificador y el directorio se llena exactamente con lo que pide un revisor:

Relaciónalos con los controles que cite tu programa, conserva los archivos JSON durante tu periodo de retención, y la parte de Confluence de un plan de continuidad de negocio deja de ser un párrafo y se convierte en un directorio.

Siguientes pasos

• La referencia de restauración paso a paso, con los modos y lo que no puede volver: Restaurar un espacio
• Los estados de verificación y el registro JSON: Comprobar frente a una copia de seguridad
• El mismo ciclo para una sola página crítica: nuestra guía de backup, comprobación y restauración de páginas con acp2md
• Las reglas de Jira Automation forman parte del mismo plan: gobiérnalas, respáldalas y restáuralas con ajat
• Planes y prueba gratuita: la tienda de Climakers; el caso de negocio: Backup y restauración de Confluence y Continuidad de negocio para Confluence en climakers.com