350 lines
14 KiB
Markdown
350 lines
14 KiB
Markdown
# Documentación del Proyecto dtic-BKPs
|
|
|
|
## Resumen del Proyecto
|
|
|
|
**Nombre del Proyecto:** dtic-BKPs
|
|
**Versión:** v5.5.1
|
|
**Autor:** Lic. Ricardo MONLA (rmonla@)
|
|
**Organización:** Dirección de TIC, Facultad Regional La Rioja, Universidad Tecnológica Nacional
|
|
**Licencia:** MIT License
|
|
|
|
### Propósito y Descripción
|
|
|
|
dtic-BKPs es un procesador automatizado de respaldos escrito en Ruby, diseñado para manejar el procesamiento, compresión y sincronización de respaldos de máquinas virtuales desde diversas plataformas de virtualización. El sistema proporciona un menú interactivo basado en terminal para gestionar operaciones de respaldo en entornos XenServer/XCP-ng y Proxmox VE.
|
|
|
|
La aplicación automatiza el flujo de trabajo de descarga de respaldos desde servidores remotos, procesándolos (compresión, organización) y subiéndolos a almacenamiento en la nube u otros destinos utilizando rclone para sincronización universal de archivos.
|
|
|
|
### Características Principales
|
|
|
|
- **Interfaz de Terminal Interactiva:** Sistema basado en menús para ejecutar tareas de respaldo
|
|
- **Soporte Multiplataforma:** Procesamiento nativo para XenServer/XCP-ng (archivos .xva) y respaldos de Proxmox VE
|
|
- **Sincronización Universal:** Integración con rclone para sincronizar a cualquier destino local o remoto
|
|
- **Arquitectura Modular:** Estructura de código organizada con procesadores separados para diferentes tipos de respaldo
|
|
- **Tareas Configurables:** Definiciones de tareas editables a través de la interfaz de la aplicación
|
|
- **Logging Integral:** Logging detallado con retroalimentación visual e indicadores de progreso
|
|
- **Secuencias de Comandos:** Soporte para flujos de trabajo de respaldo de múltiples pasos
|
|
|
|
## Estructura del Proyecto
|
|
|
|
### Diseño de Directorios
|
|
|
|
```
|
|
dtic-BKPs/
|
|
├── _vStable/ # Directorio de versión estable
|
|
│ ├── dtic-BKPs_app.rb # Script principal de la aplicación
|
|
│ ├── dtic-BKPs_tasks.rb # Archivo de configuración de tareas
|
|
│ ├── runDticBKPs.sh # Script de ejecución
|
|
│ ├── README.md # Documentación del proyecto
|
|
│ ├── LICENSE # Licencia MIT
|
|
│ ├── logs/ # Directorio de archivos de log
|
|
│ │ └── dtic-BKPs.log # Log principal de la aplicación
|
|
│ ├── fxs/ # Módulos de funciones
|
|
│ │ ├── config_handler.rb # Gestión de configuración
|
|
│ │ ├── ui_handlers.rb # Manejadores de interfaz de usuario
|
|
│ │ ├── proc_syncPmox.rb # Procesador de respaldos Proxmox
|
|
│ │ ├── proc_syncXEN.rb # Procesador de respaldos Xen
|
|
│ │ └── sync_rclone.rb # Sincronización rclone
|
|
│ └── src/ # Código fuente y documentación
|
|
│ ├── install.sh # Script de instalación
|
|
│ ├── project__v5.5.0_*.md # Documentación del proyecto
|
|
│ └── core/ # Módulos principales
|
|
│ └── globals.rb # Constantes globales y utilidades
|
|
├── _vStable/ # Versiones estables anteriores
|
|
└── _basurero/ # Directorio de archivos
|
|
```
|
|
|
|
### Componentes Principales
|
|
|
|
#### Aplicación Principal (`dtic-BKPs_app.rb`)
|
|
- Punto de entrada del procesador de respaldos
|
|
- Sistema de menú interactivo
|
|
- Motor de ejecución de tareas
|
|
- Carga y gestión de configuración
|
|
|
|
#### Configuración de Tareas (`dtic-BKPs_tasks.rb`)
|
|
- Define tareas individuales de respaldo
|
|
- Contiene secuencias de comandos (flujos de trabajo de múltiples pasos)
|
|
- Parámetros configurables para cada tipo de tarea
|
|
|
|
#### Módulos de Funciones (`fxs/`)
|
|
- **config_handler.rb:** Carga y guarda configuraciones de tareas
|
|
- **ui_handlers.rb:** Gestiona interfaz de usuario e interacciones de menú
|
|
- **proc_syncPmox.rb:** Procesa conjuntos de respaldos de Proxmox VE
|
|
- **proc_syncXEN.rb:** Procesa archivos .xva de XenServer/XCP-ng
|
|
- **sync_rclone.rb:** Maneja operaciones de sincronización rclone
|
|
|
|
## Stack Tecnológico
|
|
|
|
### Tecnologías Principales
|
|
|
|
| Componente | Tecnología | Versión | Propósito |
|
|
|------------|------------|---------|-----------|
|
|
| **Lenguaje de Programación** | Ruby | 2.7+ | Lógica principal de la aplicación |
|
|
| **Sincronización** | rclone | Última | Transferencia universal de archivos |
|
|
| **Compresión** | tar/gzip | Sistema | Compresión de respaldos |
|
|
| **Monitoreo de Progreso** | pv | Opcional | Visualización de progreso |
|
|
| **Logging** | Ruby Logger | Integrado | Logging de la aplicación |
|
|
|
|
### Dependencias
|
|
|
|
#### Dependencias Requeridas
|
|
- **Ruby 2.7+:** Entorno de ejecución principal
|
|
- **rclone:** Herramienta universal de sincronización de archivos
|
|
- **tar y gzip:** Utilidades de compresión (generalmente preinstaladas en Linux)
|
|
|
|
#### Dependencias Opcionales
|
|
- **pv (Pipe Viewer):** Proporciona barras de progreso durante operaciones de compresión
|
|
|
|
#### Requisitos del Sistema
|
|
- **Sistema Operativo:** Linux (Debian/Ubuntu recomendado)
|
|
- **Permisos:** Acceso a directorios de origen y destino de respaldos
|
|
- **Red:** Conectividad a orígenes remotos de respaldos (si aplica)
|
|
- **Almacenamiento:** Espacio suficiente para procesamiento de respaldos y archivos temporales
|
|
|
|
## Funcionalidades
|
|
|
|
### Tipos de Procesamiento de Respaldos
|
|
|
|
#### 1. Procesamiento XenServer/XCP-ng (`:xva`)
|
|
- **Entrada:** Archivos de respaldo de máquinas virtuales .xva
|
|
- **Proceso:** Comprime archivos .xva individuales en archivos .tar.gz
|
|
- **Organización:** Agrupa respaldos por nombre de máquina virtual
|
|
- **Salida:** Archivos comprimidos en estructura de directorios de destino
|
|
|
|
#### 2. Procesamiento Proxmox VE (`:proxmox_log_notes`)
|
|
- **Entrada:** Conjuntos de respaldos de Proxmox (archivos .log, .notes y datos)
|
|
- **Proceso:** Lee archivo .notes para nombre de MV, comprime conjunto completo de respaldo
|
|
- **Organización:** Crea archivos con timestamp por máquina virtual
|
|
- **Salida:** Archivos .tar.gz consolidados con nomenclatura apropiada
|
|
|
|
#### 3. Sincronización Universal (`:rclone_sync`)
|
|
- **Entrada:** Cualquier directorio local o remoto
|
|
- **Proceso:** Utiliza rclone para sincronizar archivos entre ubicaciones
|
|
- **Destinos:** Rutas locales, almacenamiento en nube, servidores remotos
|
|
- **Características:** Sincronización incremental, reporte de progreso, manejo de errores
|
|
|
|
### Gestión de Tareas
|
|
|
|
#### Tareas Individuales
|
|
Cada tarea define:
|
|
- **ID Único:** Identificador simbólico para la tarea
|
|
- **Texto de Visualización:** Descripción amigable para el usuario
|
|
- **Tipo de Proceso:** `:xva`, `:proxmox_log_notes`, o `:rclone_sync`
|
|
- **Ruta de Origen:** Directorio origen (local o remoto rclone)
|
|
- **Ruta de Destino:** Directorio destino (local o remoto rclone)
|
|
- **Opciones:** Eliminar origen después del procesamiento, sobrescribir destino
|
|
|
|
#### Secuencias de Comandos
|
|
Flujos de trabajo de múltiples pasos que ejecutan múltiples tareas en orden:
|
|
- **Descargar y Procesar:** Sincronizar desde remoto, luego procesar respaldos
|
|
- **Ciclo Completo de Respaldo:** Descargar → Procesar → Subir a nube
|
|
- **Operaciones Masivas:** Procesar múltiples orígenes de respaldos
|
|
|
|
### Interfaz de Usuario
|
|
|
|
#### Menú Principal
|
|
- **Tareas Individuales:** Ejecutar operaciones de respaldo únicas
|
|
- **Secuencias de Comandos:** Ejecutar flujos de trabajo de respaldo de múltiples pasos
|
|
- **Editor de Tareas:** Modificar tareas existentes o crear nuevas
|
|
- **Salir:** Cierre limpio de la aplicación
|
|
|
|
#### Modo Editor de Tareas
|
|
- **Editar Tareas:** Modificar parámetros de tareas existentes
|
|
- **Crear Tareas:** Agregar nuevas operaciones de respaldo
|
|
- **Eliminar Tareas:** Remover tareas no utilizadas
|
|
- **Guardar Cambios:** Persistir modificaciones en archivo de configuración
|
|
|
|
### Sistema de Configuración
|
|
|
|
#### Archivo de Configuración de Tareas
|
|
- **Formato:** Array Ruby de hashes de tareas
|
|
- **Ubicación:** `dtic-BKPs_tasks.rb`
|
|
- **Editable:** A través de interfaz de aplicación o manualmente
|
|
- **Auto-generado:** Comentarios y formato preservados
|
|
|
|
#### Configuración de Runtime
|
|
- **Avance Automático:** Opción para proceder automáticamente a través de tareas
|
|
- **Nivel de Logging:** Verbose configurable
|
|
- **Salida en Color:** Retroalimentación visual con colores ANSI
|
|
|
|
## Instalación y Configuración
|
|
|
|
### Proceso de Instalación
|
|
|
|
1. **Descarga:** Obtener todos los archivos del proyecto
|
|
2. **Permisos:** Hacer ejecutable el script de instalación
|
|
```bash
|
|
chmod +x install.sh
|
|
```
|
|
3. **Ejecutar Instalador:** Ejecutar el script de instalación
|
|
```bash
|
|
./install.sh
|
|
```
|
|
4. **Verificación de Dependencias:** El script verifica instalación de Ruby y rclone
|
|
5. **Configuración:** Genera configuración inicial de tareas
|
|
|
|
### Configuración de Tareas
|
|
|
|
#### Ejemplos de Configuración de Tareas
|
|
|
|
**Procesamiento de Respaldo Xen:**
|
|
```ruby
|
|
{
|
|
id: :proc_syncXen1,
|
|
menu_texto: "Procesar respaldos de MV Xen01",
|
|
tipo_proceso: :xva,
|
|
origen: "/mnt/respaldos/xen01/",
|
|
destino: "/mnt/procesados/xen01/",
|
|
eliminar_origen: true,
|
|
sobrescribir_destino: false,
|
|
}
|
|
```
|
|
|
|
**Procesamiento de Respaldo Proxmox:**
|
|
```ruby
|
|
{
|
|
id: :proc_syncPmox,
|
|
menu_texto: "Procesar respaldos Proxmox",
|
|
tipo_proceso: :proxmox_log_notes,
|
|
origen: "servidor_pve:/var/lib/vz/dump/",
|
|
destino: "/mnt/procesados/proxmox/",
|
|
eliminar_origen: false,
|
|
sobrescribir_destino: false,
|
|
}
|
|
```
|
|
|
|
**Subida a Nube:**
|
|
```ruby
|
|
{
|
|
id: :subir_nube,
|
|
menu_texto: "Subir a almacenamiento en nube",
|
|
tipo_proceso: :rclone_sync,
|
|
origen: "/mnt/procesados/",
|
|
destino: "proveedor_nube:/respaldos/",
|
|
eliminar_origen: false,
|
|
sobrescribir_destino: false,
|
|
}
|
|
```
|
|
|
|
## Guía de Uso
|
|
|
|
### Operación Básica
|
|
|
|
1. **Iniciar Aplicación:**
|
|
```bash
|
|
./dtic-BKPs_app.rb
|
|
```
|
|
|
|
2. **Seleccionar Operación:**
|
|
- Ingresar número de tarea para ejecución individual
|
|
- Ingresar número de comando para ejecución de secuencia
|
|
- Presionar 'E' para modo de edición de tareas
|
|
|
|
3. **Monitorear Progreso:**
|
|
- Indicadores visuales de progreso
|
|
- Actualizaciones de estado en tiempo real
|
|
- Logging detallado a archivo
|
|
|
|
### Características Avanzadas
|
|
|
|
#### Secuencias de Comandos
|
|
Ejecutar flujos de trabajo complejos de respaldo:
|
|
- **C1:** Descargar y procesar respaldos Proxmox
|
|
- **C2:** Ciclo completo (descargar → procesar → subir)
|
|
- **C3:** Sincronización masiva a nube
|
|
|
|
#### Personalización de Tareas
|
|
Modificar tareas a través del editor:
|
|
- Cambiar rutas de origen/destino
|
|
- Ajustar opciones de procesamiento
|
|
- Agregar nuevos orígenes de respaldo
|
|
- Crear secuencias de comandos personalizadas
|
|
|
|
## Logging y Monitoreo
|
|
|
|
### Archivos de Log
|
|
- **Log Principal:** `logs/dtic-BKPs.log`
|
|
- **Formato:** Timestamp, severidad, mensaje
|
|
- **Rotación:** Rotación diaria con limpieza automática
|
|
|
|
### Niveles de Log
|
|
- **INFO:** Operaciones normales y completación
|
|
- **WARN:** Problemas no críticos (archivos faltantes, etc.)
|
|
- **ERROR:** Fallos críticos que requieren atención
|
|
|
|
### Características de Monitoreo
|
|
- **Estadísticas de Ejecución:** Seguimiento de tareas completadas y rendimiento
|
|
- **Indicadores de Progreso:** Retroalimentación visual durante operaciones largas
|
|
- **Reportes de Error:** Mensajes de error detallados con contexto
|
|
- **Rastro de Auditoría:** Registro completo de todas las operaciones
|
|
|
|
## Consideraciones de Seguridad
|
|
|
|
### Control de Acceso
|
|
- **Permisos de Archivos:** Acceso apropiado a directorios de respaldo
|
|
- **Acceso Remoto:** Configuraciones remotas rclone seguras
|
|
- **Gestión de Credenciales:** Almacenamiento seguro de credenciales de acceso
|
|
|
|
### Protección de Datos
|
|
- **Encriptación:** Usar almacenamiento remoto encriptado cuando sea posible
|
|
- **Integridad de Respaldos:** Verificación de completitud de respaldos
|
|
- **Logging de Acceso:** Rastro de auditoría de operaciones de respaldo
|
|
|
|
## Mantenimiento y Solución de Problemas
|
|
|
|
### Mantenimiento Regular
|
|
- **Rotación de Logs:** Monitorear tamaños de archivos de log
|
|
- **Respaldo de Configuración:** Preservar configuraciones de tareas
|
|
- **Actualizaciones de Dependencias:** Mantener rclone y Ruby actualizados
|
|
|
|
### Problemas Comunes
|
|
- **Dependencias Faltantes:** Ejecutar script de instalación para verificar
|
|
- **Errores de Permisos:** Verificar permisos de acceso a directorios
|
|
- **Problemas de Red:** Verificar conectividad a orígenes remotos
|
|
- **Errores de Configuración:** Validar definiciones de tareas
|
|
|
|
### Optimización de Rendimiento
|
|
- **Procesamiento Paralelo:** Considerar múltiples instancias para diferentes orígenes
|
|
- **Planificación de Almacenamiento:** Asegurar espacio adecuado para procesamiento
|
|
- **Ancho de Banda de Red:** Monitorear velocidades de transferencia para operaciones remotas
|
|
|
|
## Desarrollo y Extensión
|
|
|
|
### Arquitectura
|
|
- **Diseño Modular:** Procesadores separados para diferentes tipos de respaldo
|
|
- **Configuración Dirigida:** Definiciones de tareas en archivos externos
|
|
- **Extensible:** Fácil adición de nuevos tipos de procesador
|
|
|
|
### Agregar Nuevos Procesadores
|
|
1. Crear nuevo módulo procesador en `fxs/`
|
|
2. Agregar mapeo de procesador en aplicación principal
|
|
3. Definir parámetros de configuración de tareas
|
|
4. Actualizar documentación y ejemplos
|
|
|
|
### Estándares de Código
|
|
- **Estilo Ruby:** Seguir convenciones y mejores prácticas de Ruby
|
|
- **Documentación:** Comentarios y documentación comprehensivos
|
|
- **Manejo de Errores:** Manejo robusto de errores y logging
|
|
- **Testing:** Testing manual de nuevas características
|
|
|
|
## Soporte y Recursos
|
|
|
|
### Documentación
|
|
- **README.md:** Instalación y uso básico
|
|
- **Archivos del Proyecto:** Documentación técnica detallada
|
|
- **Ejemplos de Configuración:** Definiciones de tareas de ejemplo
|
|
|
|
### Comunidad y Soporte
|
|
- **Autor:** Lic. Ricardo MONLA (rmonla@)
|
|
- **Organización:** Dirección de TIC, Universidad Tecnológica Nacional
|
|
- **Licencia:** MIT License (código abierto)
|
|
|
|
### Historial de Versiones
|
|
- **v4.4:** Versión modular inicial con soporte Xen y Proxmox
|
|
- **v5.2:** Sistema de configuración mejorado y editor de tareas
|
|
- **v5.5.0:** Automatic execution via command-line parameters
|
|
- **v5.5.1 (2025-11-14):** Fixed naming inconsistencies across the application to ensure correct app name references.
|
|
|
|
---
|
|
|
|
*Esta documentación proporciona una visión comprehensiva del procesador automatizado de respaldos dtic-BKPs. Para detalles específicos de implementación, referirse al código fuente y archivos de configuración.* |