Copia de seguridad y restauración

Una vez que su instancia esté en uso, cree una copia de seguridad antes de realizar actualizaciones o mover servidores. La configuración del cliente por primera vez se trata en Primera solicitud.

SubLane puede exportar una instancia en ejecución, verificar una copia de seguridad y restaurarla en un nuevo directorio. Tanto la línea de comando como Configuración del sistema → Copia de seguridad y restauración utilice la misma implementación de validación y restauración de archivo. La recuperación nunca sobrescribe la instancia en ejecución; cambiar a datos restaurados es un reinicio explícito del operador.

Que esta incluido

Las nuevas copias son archivos age binarios cifrados con contraseña. Tras descifrarlos, el archivo gzip/tar contiene:

• sublane.db: una instantánea SQLite consistente, que incluye datos WAL confirmados.
• credentials.key: la clave de cifrado coincidente para las credenciales de suscripción y las claves de puerta de enlace recuperables.
• manifest.json: versión de formato, hora de creación, SubLane versión de compilación, versión de esquema, tamaños de archivo y sumas de comprobación SHA-256.

Se incluyen usuarios, hashes de contraseñas, claves API, cuentas de suscripción, grupos, permisos, catálogos, configuraciones, registros de solicitudes, resúmenes de uso, tiempos de reutilización y registros de afinidad. Las sesiones del navegador se capturan en la copia de seguridad pero se borran en un directorio restaurado. No se incluyen las opciones de tema/idioma local del navegador, el entorno de proceso, los archivos de implementación ni los intentos pendientes en memoria OAuth.

Las nuevas exportaciones requieren una contraseña de 12–128 caracteres. SubLane no la guarda. Consérvala por separado: si la pierdes, no podrás recuperar la copia cifrada. Los archivos .tar.gz antiguos sin cifrar siguen siendo verificables y restaurables sin contraseña, pero contienen claves legibles y deben guardarse en privado.

línea de comando

Ejecute los comandos desde un directorio con suficiente espacio libre para la instantánea de la base de datos y el archivo comprimido:

mkdir -p backups
./bin/sublane backup --password-stdin --output ./backups/team.sublane-backup.tar.gz.age < /secure/backup-password
./bin/sublane backup verify --password-stdin --input ./backups/team.sublane-backup.tar.gz.age < /secure/backup-password
./bin/sublane restore --password-stdin --input ./backups/team.sublane-backup.tar.gz.age --data-dir ./data-restored < /secure/backup-password

backup lee SUBLANE_DATA_DIR o ./data, con una opción --data-dir anular. restore siempre requiere un nuevo directorio explícito; incluso se rechaza un directorio vacío existente. El directorio principal debe existir. Los archivos de almacenamiento y los directorios de restauración existentes nunca se reemplazan. Los comandos exitosos imprimen un resultado JSON con la operación, la ruta y los metadatos de la copia de seguridad. sublane --help enumera los comandos.

Los comandos de mantenimiento no inician el servidor HTTP, los ejecutores SDK, OAuth ni las comprobaciones de liberación automática, y no dependen de la dirección del servidor/configuración de URL pública. Tienen un plazo de quince minutos y responden a SIGINT/SIGTERM. Las instantáneas de la base de datos están limitadas a 4 GiB y el archivo IO utiliza buffers limitados. Permita espacio en disco para extracción y migraciones al verificar o restaurar, además del archivo en sí.

Después de una restauración exitosa:

1. Detenga el servicio SubLane actual.
2. Mantenga intacto su directorio de datos original.
3. Inicie SubLane con el directorio restaurado:

SUBLANE_DATA_DIR=./data-restored ./bin/sublane

4. Inicie sesión nuevamente y verifique los usuarios, grupos, claves y estados de cuenta esperados antes de reanudar el tráfico del equipo.

El directorio original está disponible para revertir deteniendo SubLane y cambiando SUBLANE_DATA_DIR atrás. No ejecute dos instancias de puerta de enlace en el mismo directorio de datos. La restauración revierte todo el estado almacenado a la instantánea: no se incluyen revocaciones de claves posteriores, cambios de contraseña ni registros nuevos. Es posible que un proveedor de suscripción haya invalidado tokens de actualización más antiguos desde la copia de seguridad; reautorizar las cuentas afectadas cuando sea necesario. La verificación verifica el descifrado y la integridad local sin contactar a los proveedores.

interfaz web

Solo los administradores habilitados pueden usar la página o sus puntos finales. Las mutaciones requieren el origen exacto del navegador y la exportación vuelve a verificar la sesión del administrador después de preparar el archivo.

• Descargar copia de seguridad crea y descarga un archivo completo mientras la instancia permanece disponible.
• Verificar copia de seguridad comprueba el archivo seleccionado y muestra su hora de creación, SubLane versión y tamaño de la base de datos.
• Preparar restauración carga y valida el archivo nuevamente, luego crea <current data directory>/restore-ready. La página muestra la ruta completa y las instrucciones de reinicio. La instancia actual continúa ejecutándose con sus datos originales hasta que el operador cambia de directorio.

Un existente restore-ready El camino bloquea otra preparación. Inspeccione en el servidor o utilice la CLI con un nuevo destino diferente. No se puede sobrescribir ningún directorio a través de la web API. Si se prepararon datos de recuperación pero falló la escritura de auditoría en vivo, el directorio se conserva y la página informa el error de auditoría; inspeccione antes de volver a intentarlo.

Las cargas y descargas web están limitadas a 256 MiB de datos comprimidos; las copias de seguridad más grandes requieren la CLI. Se ejecuta una operación de exportación/verificación/restauración a la vez por servidor. La carga, tramitación y descarga tienen plazos acotados. Los archivos temporales se eliminan después de su finalización, falla o cancelación normal. Una interrupción forzada del proceso o una pérdida de energía pueden dejar a un privado .sublane-backup-* directorio; elimine los directorios provisionales sobrantes sólo cuando no se esté ejecutando ninguna operación de copia de seguridad.

Las exportaciones y las restauraciones preparadas se auditan sin registrar el contenido del archivo, los nombres de los archivos, las rutas del sistema de archivos ni las credenciales. Uso de descargas Cache-Control: no-store. La página transmite cargas desde el archivo seleccionado; el navegador recibe el archivo descargado como un blob temporal y publica su URL después de iniciar la descarga.

Ejemplos de controles de copia de seguridad y restauración del navegador:

Docker Compose

Para exportar y verificar dentro del contenedor en ejecución:

docker compose -f docker.compose.yaml exec sublane sh -c 'mkdir -p /data/backups'
docker compose -f docker.compose.yaml exec -T sublane sublane backup --password-stdin --output /data/backups/team.sublane-backup.tar.gz.age < /secure/backup-password
docker compose -f docker.compose.yaml exec -T sublane sublane backup verify --password-stdin --input /data/backups/team.sublane-backup.tar.gz.age < /secure/backup-password
docker compose -f docker.compose.yaml cp sublane:/data/backups/team.sublane-backup.tar.gz.age ./team.sublane-backup.tar.gz.age

Para la recuperación, copie una copia de seguridad en una ubicación privada de escritura visible dentro del contenedor y luego prepare un directorio separado:

docker compose -f docker.compose.yaml exec -T sublane sublane restore --password-stdin --input /data/backups/team.sublane-backup.tar.gz.age --data-dir /data/restore-ready < /secure/backup-password

La acción de restauración web produce el mismo objetivo. Para activarlo, cree una anulación local Compose, por ejemplo docker.compose.restore.yaml:

services:
  sublane:
    environment:
      SUBLANE_DATA_DIR: /data/restore-ready

Luego detenga el proceso original y comience con la anulación:

docker compose -f docker.compose.yaml stop sublane
docker compose -f docker.compose.yaml -f docker.compose.restore.yaml up -d

Para un contenedor ya detenido, use docker compose -f docker.compose.yaml run --rm --no-deps sublane ... en lugar de exec para ejecutar comandos de mantenimiento en su volumen de datos nombrado. Mantenga la anulación seleccionada en los comandos de implementación posteriores. No elimine el volumen nombrado durante este procedimiento.

Comportamiento de validación y falla.

La verificación verifica las entradas y tamaños exactos del archivo, los resúmenes SHA-256, la integridad de gzip, la versión del esquema consolidado compatible, SQLite la integridad y las claves externas, los registros de credenciales delimitados y el descifrado de las credenciales de la cuenta y las claves cifradas API. Las conexiones de validación también limitan los valores SQLite individuales y las declaraciones SQL a 1 MiB. Se rechazan los enlaces simbólicos, el recorrido de rutas, los archivos duplicados/inesperados, los archivos faltantes, los archivos truncados y los esquemas futuros desconocidos. Esta versión preliminar no acepta esquemas de desarrollo más antiguos.

Restaurar cierra y sincroniza su base de datos/clave preparada antes de publicar todo el nuevo directorio con una operación atómica sin reemplazo. Linux y macOS requieren soporte de sistema de archivos para esa operación; una operación no admitida falla sin recurrir a una sobrescritura. El soporte de copia de seguridad no introduce ninguna tabla de base de datos adicional ni migración de esquemas. SQLite La creación de instantáneas utiliza el SQLite Copia de seguridad en línea API a través del controlador Go anclado, en lugar de copiar un archivo de base de datos en vivo.

Usar application/gzip o application/octet-stream para cargas. Los archivos no válidos devuelven 400, un destino existente devuelve 409, las cargas de gran tamaño devuelven 413 y un espacio de operación ocupado devuelve 429 con Retry-After. El almacenamiento y otras fallas operativas devuelven errores 503 desinfectados.

credentials.key · Contraseña de la copia

Detén la instancia existente, copia su clave original a una ubicación privada fuera del directorio de datos y configura los permisos del usuario del servicio. Elimina la copia antigua solo después de verificar el inicio y una copia cifrada.

SUBLANE_CREDENTIALS_KEY_FILE: Archivo privado de clave opcional fuera del directorio de datos; si no se configura, conserva la ubicación actual.

Si usas una clave separada, mueve el archivo credentials.key restaurado a una nueva ubicación privada fuera del directorio de datos y actualiza SUBLANE_CREDENTIALS_KEY_FILE antes de reiniciar. No sobrescribas la clave de la instancia original.

Usa entre 12 y 128 caracteres. Guarda la contraseña por separado; no se puede restablecer si se pierde. Obligatoria para copias cifradas. Déjala vacía para archivos antiguos sin cifrar.

--key-file FILE · --password-stdin · scrypt: 18 (~256 MiB)

Lee la contraseña con --password-stdin desde un archivo privado de una sola línea con permisos 0600; no la incluyas en argumentos ni variables de entorno.

La interfaz envía multipart/form-data, con password antes de file. Las cargas sin procesar de archivos antiguos siguen admitiéndose sin contraseña.

Migración automática de la clave en Compose

El repositorio de la aplicación incluye scripts/separate-key.sh para despliegues Compose existentes con SubLane v0.12.0+. Guarda y revisa el script antes de ejecutarlo en el host de Docker. Primero exporta y verifica una copia de recuperación cifrada con contraseña.

sudo bash scripts/separate-key.sh --dir /srv/sublane --key-dir /srv/sublane-secrets

--dir indica el despliegue existente con docker.compose.yaml y su .env opcional. --key-dir debe ser una ruta absoluta nueva en almacenamiento persistente del host, fuera del montaje real de datos y del directorio de recuperación, con el directorio padre ya creado. Se admiten rutas ASCII habituales, incluidos espacios. Se requieren Linux local con Docker rootful sin reasignación userns ni SELinux, Compose, Bash, jq y GNU coreutils. El servicio debe llamarse sublane, estar saludable y montar su directorio de datos en la raíz de un bind mount o volumen con nombre que permita escritura. Compose debe usar dos espacios para indentar los servicios, un mapa de bloque para environment y una lista de bloque para volumes. Las estructuras no admitidas se rechazan antes de detener el servicio.

El script comprueba el proyecto, la imagen, el montaje, los permisos privados, los 32 bytes y el hash de la clave original. Conserva el texto y la interpolación de variables de Compose y compara su configuración normalizada. El nuevo directorio del host sigue perteneciendo a root con modo 0700; solo se monta en modo de solo lectura el archivo de clave 0600, propiedad del UID/GID del servicio. No se elevan los permisos del servicio.

Antes del cambio, después y tras borrar la clave antigua, crea y verifica una copia cifrada temporal con una contraseña aleatoria nueva. El espacio temporal está fuera del directorio de datos y se elimina al terminar. Reserva espacio suficiente y memoria para la KDF del backup. Estas comprobaciones no conservan una copia de recuperación. Solo se elimina la copia antigua cuando pasan la configuración, el estado de salud, el hash y la validación de credenciales; otra recreación y verificación confirma que ya no se depende del archivo antiguo.

Los errores o señales capturables tras iniciar el cambio provocan un intento de reversión. También puedes revertir una migración completada:

sudo bash scripts/separate-key.sh --dir /srv/sublane --rollback

Los registros privados de recuperación permanecen en /srv/sublane/.key-migration. La reversión restaura la configuración original y su clave correspondiente, recrea el servicio original y lo verifica. Rechaza sobrescribir cambios posteriores en la configuración o el entorno, o una clave diferente; nunca degrada la imagen ni la base de datos. La clave externa y los registros siguen siendo privados tras revertir. Una nueva migración no sobrescribe registros ni destinos existentes: archiva de forma segura los registros verificados y elige un nuevo directorio de clave antes de reintentar.

El script comparte .update-lock con el instalador; no ejecutes otras operaciones de despliegue a la vez. Tras una terminación forzada o corte eléctrico, confirma que no se esté migrando ni actualizando, elimina únicamente el .update-lock vacío abandonado y ejecuta --rollback. Si no se puede verificar la reversión, conserva el material de clave de recuperación y un operation.log privado. Mantén ambos directorios hasta completar la recuperación. Las copias que conserves y sus contraseñas deben seguir guardándose por separado.

Copias cifradas automáticas

Activa la configuración de despliegue indicada. Directorio privado (0700) y contraseña independiente de 12–128 caracteres en un archivo normal privado (0600, sin enlace simbólico), separado de datos y copias. Se relee en cada ejecución.

export SUBLANE_BACKUP_DIR=/srv/sublane-backups
export SUBLANE_BACKUP_PASSWORD_FILE=/secure/sublane/backup-password
export SUBLANE_BACKUP_INTERVAL=24h
export SUBLANE_BACKUP_KEEP=7

Se ejecuta al iniciar y espera el intervalo después de cada intento. Verifica completamente la nueva copia antes de rotar nombres reservados scheduled-; conserva copias manuales y la nueva verificada. Resultados en registros del servicio. Sin subida remota ni formulario de programación; desactivado en demostración.

SUBLANE_BACKUP_INTERVAL: 1h–720h (default 24h). SUBLANE_BACKUP_KEEP: 1–365 (default 7).

Usa un destino de copias exclusivo para cada instancia.

El ajuste opcional SUBLANE_BACKUP_WEBHOOK_URL envía a un destino HTTPS público un evento JSON backup_failure acotado por intento fallido. Es un destino del operador de instancia, separado de alertas del espacio; los fallos de envío se registran.

En Docker usa rutas del contenedor y monta el archivo privado y el directorio dedicado escribible mediante una configuración Compose local, dando acceso al usuario del servicio. El tmpfs /tmp predeterminado tiene 64 MiB. Para verificaciones mayores añade un montaje privado escribible y TMPDIR en la configuración.