Documentacion PWR Refugio

Instalacion

Refugio depende de Cuantica para el cifrado. Se puede usar como libreria PHP o desde CLI.

PHP

require_once __DIR__ . '/core/refugio.php';
// cuantica.php se carga automaticamente

Requisitos minimos

PHP 7.4 o superior
Extensiones openssl y sodium
Extension mysqli para backups de base de datos
Extension ftp para subida FTP (opcional)
Permisos de escritura en el directorio de destino

Uso por CLI

Terminal

php core/refugio.php [comando]

Inicio rapido

Backup cifrado de archivos en 3 lineas.

PHP

require_once 'core/refugio.php';

// Backup cifrado de una carpeta
$resultado = pwr_refugio_archivos(
    ['/var/www/mi-app/datos'],
    'mi_password_cifrado',
    'datos/backups/'
);

Funciones

pwr_refugio_bd()

Genera un backup cifrado de la base de datos MySQL. Exporta todas las tablas (o las indicadas) y cifra el dump SQL.

Firma

pwr_refugio_bd(array $config): array

Parametro	Tipo	Descripcion
`$config`	`array`	Configuracion de BD: `host`, `usuario`, `password`, `nombre`, `tablas`, `password_cifrado`, `destino`

Retorna: array con ok, archivo, tamano, tablas_exportadas.

pwr_refugio_archivos()

Genera un backup cifrado de directorios y archivos. Comprime con gzip antes de cifrar.

Firma

pwr_refugio_archivos(array $rutas, string $password, string $destino): array

Parametro	Tipo	Descripcion
`$rutas`	`array`	Array de rutas absolutas a incluir en el backup
`$password`	`string`	Password para cifrar el backup
`$destino`	`string`	Directorio donde guardar el backup cifrado

Retorna: array con ok, archivo, tamano, archivos_incluidos.

pwr_refugio_subir_ftp()

Sube un archivo de backup a un servidor FTP/FTPS.

Firma

pwr_refugio_subir_ftp(string $archivo, array $config_ftp): array

Parametro	Tipo	Descripcion
`$archivo`	`string`	Ruta al archivo de backup
`$config_ftp`	`array`	Configuracion FTP: `host`, `puerto`, `usuario`, `password`, `ruta_remota`, `ssl`

Retorna: array con ok y mensaje.

pwr_refugio_subir_local()

Copia un archivo de backup a otro directorio local (segundo disco, NAS, etc.).

Firma

pwr_refugio_subir_local(string $archivo, string $destino): array

Retorna: array con ok, ruta_destino.

pwr_refugio_restaurar_bd()

Restaura una base de datos desde un backup cifrado. Descifra y ejecuta el SQL.

Firma

pwr_refugio_restaurar_bd(string $archivo_cifrado, string $password, array $config_bd): array

Parametro	Tipo	Descripcion
`$archivo_cifrado`	`string`	Ruta al archivo de backup cifrado
`$password`	`string`	Password de descifrado
`$config_bd`	`array`	Configuracion de la BD destino: `host`, `usuario`, `password`, `nombre`

Retorna: array con ok, tablas_restauradas, mensaje.

pwr_refugio_restaurar_archivos()

Restaura archivos desde un backup cifrado. Descifra y extrae los archivos al destino.

Firma

pwr_refugio_restaurar_archivos(string $archivo_cifrado, string $password, string $destino): array

Retorna: array con ok, archivos_restaurados, mensaje.

pwr_refugio_rotar()

Elimina backups antiguos manteniendo solo los N mas recientes.

Firma

pwr_refugio_rotar(string $directorio, int $mantener = 5): array

Parametro	Tipo	Descripcion
`$directorio`	`string`	Directorio de backups
`$mantener`	`int`	Numero de backups a conservar (defecto: 5)

Retorna: array con ok, eliminados (array de archivos borrados), conservados.

pwr_refugio_verificar()

Verifica la integridad de un backup cifrado sin restaurarlo. Descifra y comprueba que el contenido es valido.

Firma

pwr_refugio_verificar(string $archivo_cifrado, string $password): array

Retorna: array con ok, valido (bool), tipo (bd/archivos), tamano_original.

pwr_refugio_info()

Devuelve informacion del modulo: version, configuracion activa y estadisticas de backups.

Firma

pwr_refugio_info(): array

Retorna: array con version, cuantica_version, backups_existentes, espacio_usado.

Configuracion

La configuracion se almacena en datos/refugio_config.json.

datos/refugio_config.json

{
    "bd": {
        "host": "localhost",           // Host de MySQL
        "usuario": "root",              // Usuario de MySQL
        "password": "",                 // Password de MySQL
        "nombre": "",                   // Nombre de la base de datos
        "tablas": "*"                   // "*" para todas o array de tablas
    },
    "destino_local": "datos/backups/",  // Directorio de backups
    "password_cifrado": "",            // Password para cifrar backups
    "rotacion": 5,                      // Mantener ultimos N backups
    "ftp": {
        "activado": false,              // Activar subida FTP
        "host": "",                     // Host FTP
        "puerto": 21,                   // Puerto FTP
        "usuario": "",                  // Usuario FTP
        "password": "",                 // Password FTP
        "ruta_remota": "/backups/",     // Ruta en el servidor FTP
        "ssl": true                     // Usar FTPS (recomendado)
    },
    "log_activado": true,              // Registrar operaciones
    "log_ruta": "logs/refugio.log"      // Ruta del log
}

Ejemplos

Backup completo de BD + archivos con rotacion

PHP

require_once 'core/refugio.php';

// Backup de base de datos
$bd = pwr_refugio_bd([
    'host' => 'localhost',
    'usuario' => 'root',
    'password' => 'mi_pass_mysql',
    'nombre' => 'mi_base_datos',
    'password_cifrado' => 'clave_backup_2025',
    'destino' => 'datos/backups/'
]);

// Backup de archivos
$archivos = pwr_refugio_archivos(
    ['/var/www/app/uploads', '/var/www/app/config'],
    'clave_backup_2025',
    'datos/backups/'
);

// Rotar: mantener solo los 5 ultimos
pwr_refugio_rotar('datos/backups/', 5);

Backup con subida a FTP

PHP

require_once 'core/refugio.php';

$backup = pwr_refugio_archivos(
    ['/var/www/mi-app'],
    'clave_cifrado',
    'datos/backups/'
);

if ($backup['ok']) {
    pwr_refugio_subir_ftp($backup['archivo'], [
        'host' => 'ftp.miserver.com',
        'puerto' => 21,
        'usuario' => 'backup_user',
        'password' => 'ftp_password',
        'ruta_remota' => '/backups/',
        'ssl' => true
    ]);
}

Verificar y restaurar un backup

PHP

require_once 'core/refugio.php';

$archivo = 'datos/backups/bd_2025-01-15_120000.enc';
$password = 'clave_backup_2025';

// Verificar integridad antes de restaurar
$check = pwr_refugio_verificar($archivo, $password);
if ($check['valido']) {
    // Restaurar base de datos
    pwr_refugio_restaurar_bd($archivo, $password, [
        'host' => 'localhost',
        'usuario' => 'root',
        'password' => 'mi_pass_mysql',
        'nombre' => 'mi_base_datos'
    ]);
}

Uso desde CLI

Terminal

# Backup de BD usando configuracion JSON
php core/refugio.php backup-bd

# Backup de archivos
php core/refugio.php backup-archivos /var/www/app datos/backups/ mi_password

# Verificar un backup
php core/refugio.php verificar datos/backups/archivo.enc mi_password

# Restaurar BD
php core/refugio.php restaurar-bd datos/backups/bd_backup.enc mi_password

# Rotar backups
php core/refugio.php rotar datos/backups/ 5

Upload a S3

Refugio puede subir backups cifrados a cualquier almacenamiento compatible con S3: Amazon S3, MinIO, DigitalOcean Spaces, Cloudflare R2, etc. La implementacion usa firma AWS Signature V4 pura, sin SDK ni dependencias externas.

pwr_refugio_subir_s3()

PHP

require_once 'core/refugio.php';

$backup = pwr_refugio_archivos(['/var/www/app'], 'mi_clave', 'datos/backups/');

if ($backup['ok']) {
    $s3 = pwr_refugio_subir_s3($backup['archivo'], [
        'endpoint'    => 's3.eu-west-1.amazonaws.com',
        'bucket'      => 'mi-bucket-backups',
        'region'      => 'eu-west-1',
        'access_key'  => 'AKIAIOSFODNN7EXAMPLE',
        'secret_key'  => 'wJalrXUtnFEMI/K7MDENG...',
        'ruta_remota' => 'backups/produccion',
    ]);
    // $s3['url'] = 'https://s3.eu-west-1.amazonaws.com/mi-bucket/backups/produccion/archivo.enc'
}

Configuracion S3 en JSON

Anade la clave s3 a datos/refugio_config.json:

JSON — datos/refugio_config.json

{
    "password_cifrado": "mi_clave_segura",
    "s3": {
        "endpoint": "s3.eu-west-1.amazonaws.com",
        "bucket": "mi-bucket",
        "region": "eu-west-1",
        "access_key": "AKIA...",
        "secret_key": "wJal...",
        "ruta_remota": "backups/",
        "ssl": true
    }
}

Compatibilidad: Funciona con cualquier servicio compatible con la API S3: Amazon S3, MinIO, DigitalOcean Spaces, Cloudflare R2, Backblaze B2, Wasabi, etc. Solo cambia el endpoint.

Auto-deteccion de backends

pwr_refugio_subir_auto() intenta subir el archivo al mejor backend disponible, con degradacion automatica si uno falla:

S3 — Si hay configuracion s3 con access_key
FTP/SFTP — Si hay configuracion ftp con host
Local — Copia a destino_local como ultimo recurso

PHP

require_once 'core/refugio.php';

$backup = pwr_refugio_archivos(['/var/www/app'], 'clave', 'datos/backups/');

if ($backup['ok']) {
    // Sube a S3, si falla intenta FTP, si falla copia local
    $resultado = pwr_refugio_subir_auto($backup['archivo']);
    // $resultado['backend'] = 's3' | 'ftp' | 'local'
}

Patron PQC: Este es el mismo patron de degradacion graceful que usa Cuantica para PQC: FFI > Docker > API > off. Si el backend preferido no esta disponible, el siguiente toma el relevo automaticamente.