179 lines
8.8 KiB
Markdown
179 lines
8.8 KiB
Markdown
# OnEver Drive
|
|
|
|
Plataforma empresarial centralizada de backup y sincronización para entornos Windows sobre infraestructura **Proxmox VE (Contenedores LXC Debian 12/13)**.
|
|
|
|
---
|
|
|
|
## 🚀 Arquitectura General
|
|
|
|
```text
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ CLIENTES WINDOWS (10/11/Server) │
|
|
│ │
|
|
│ [ Agente PyQt6 / System Tray (.EXE) ] │
|
|
│ ├── Selector visual de carpetas (QFileDialog) │
|
|
│ ├── Detección de bloqueos SQL Server (Locks/Growth) │
|
|
│ ├── Motor de Chunks (Bloques de 4MB con reanudación) │
|
|
│ └── Verificación de integridad SHA-256 local │
|
|
└──────────────────────────┬─────────────────────────────┘
|
|
│ HTTPS / TLS (Chunks + JSON)
|
|
▼
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ SERVIDOR PROXMOX VE (LXC Debian) │
|
|
│ │
|
|
│ [ Nginx Proxy Inverso + SSL / Let's Encrypt ] │
|
|
│ ├── Frontend Web Dashboard (React 19 + TypeScript) │
|
|
│ ├── Backend REST API (FastAPI Asíncrono) │
|
|
│ ├── WebSockets (Telemetría de subidas en tiempo real) │
|
|
│ ├── Ensamblado Streaming SHA-256 (Bajo consumo RAM) │
|
|
│ ├── Políticas de Retención (Diaria/Semanal/Mensual) │
|
|
│ └── Base de Datos (PostgreSQL 16 / SQLite dev) │
|
|
└────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Flujo de Trabajo (Workflow) y Resolución del Problema
|
|
|
|
OnEver Drive está diseñado específicamente para resolver la necesidad de **programar y monitorear backups en clientes fuera de la red local (a través de Internet)** mediante una consola de gestión web centralizada ejecutada en una VM Linux.
|
|
|
|
### 🌐 Conectividad a través de Internet (Sin VPN)
|
|
El agente de Windows no requiere de red local ni VPN para comunicarse con el servidor central. Toda la comunicación (Handshake, Sincronización de Tareas, Subida de Chunks e Historial de Ejecuciones) se realiza a través de **HTTPS/TLS** (puerto 443) con seguridad criptográfica robusta:
|
|
- Cada agente posee un par único de `device_id` y `device_token` permanente que se valida en el backend mediante un middleware de seguridad.
|
|
|
|
### 📦 Distribución del Agente "MeshCentral-Style" (Compilación y Enrolamiento)
|
|
Para facilitar el despliegue masivo y sencillo en clientes remotos:
|
|
1. **Compilación Centralizada**: El administrador puede empaquetar y generar el binario del agente directamente con el script de compilación `windows-agent/build_exe.py` (generando un archivo ejecutable portable de un solo archivo `OnEverDriveAgent-Standalone.exe`).
|
|
2. **Enrolamiento por Código**: Al igual que en MeshCentral, el administrador genera un **Código de Registro Único** (ej: `OED-5752-EFED`) con duración temporal (24 horas) en la interfaz web del servidor.
|
|
3. **Handshake Seguro**: El instalador del Agente de Windows se ejecuta en la máquina cliente, solicita este código y realiza una solicitud inicial segura. El servidor asocia la máquina al registro y devuelve un token exclusivo, vinculando el cliente de por vida.
|
|
|
|
### 📊 Diagrama de Secuencia del Flujo de Trabajo
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
actor Admin as Administrador Web
|
|
participant Server as VM Linux (FastAPI + React)
|
|
participant Agent as Agente Windows (en Internet)
|
|
|
|
Note over Admin,Server: 1. Descarga y Vinculación (Estilo MeshCentral)
|
|
Admin->>Server: Generar código de vinculación temporal (web)
|
|
Server-->>Admin: Código temporal (Ej: OED-5752-EFED)
|
|
Agent->>Server: Registro inicial con Código Temporal (HTTPS POST)
|
|
Server-->>Agent: device_id y device_token seguro (Guardado en config.json)
|
|
|
|
Note over Admin,Agent: 2. Sincronización de Configuración
|
|
Admin->>Server: Crear/Editar Trabajo (Filtros, Cron, Copia Local)
|
|
Agent->>Server: Consultar trabajos asignados (HTTPS GET)
|
|
Server-->>Agent: Retorna configuración del Trabajo
|
|
Agent->>Agent: Guarda/Actualiza config.json local
|
|
|
|
Note over Agent,Server: 3. Ejecución de Tarea y Sincronización
|
|
Agent->>Agent: Evalúa is_job_due (Planificador Cron / Proxmox)
|
|
Agent->>Server: Iniciar sesión de corrida (POST /runs/start)
|
|
Server-->>Agent: Retorna run_id
|
|
Agent->>Agent: Copia Local Duplicada Robusta (.tmp -> original)
|
|
Agent->>Server: Sube archivos por Chunks de 4MB (HTTPS)
|
|
Agent->>Server: Reporta métricas finales y estado (POST /runs/{id}/complete)
|
|
|
|
Note over Admin,Server: 4. Auditoría
|
|
Admin->>Server: Abre modal "Historial de Ejecuciones" (React)
|
|
Server-->>Admin: Muestra estadísticas de la corrida (eficiencia, errores, MBs)
|
|
```
|
|
|
|
---
|
|
|
|
## 📦 Estructura del Repositorio
|
|
|
|
- **`backend/`**: API REST FastAPI con autenticación JWT, registro de dispositivos por código temporal, motor de chunks con reanudación, políticas de retención y WebSockets.
|
|
- **`frontend/`**: Dashboard web moderno (Vite + React 19 + TypeScript) con telemetría en vivo, gestión de clientes, creación de trabajos y explorador de restauración.
|
|
- **`windows-agent/`**: Agente nativo en PyQt6 para Windows con System Tray, selector de carpetas, notificaciones discretas y empaquetado en binario `.exe` (PyInstaller).
|
|
- **`deployment/`**: Scripts de aprovisionamiento automatizado en contenedores nativos **Debian 12/13 LXC en Proxmox VE**, configuración de Nginx, SSL y mantenimiento de backups.
|
|
- **`docs/`**: Documentación técnica, manual del agente Windows, arquitectura del motor de chunks y guía de despliegue en Proxmox.
|
|
- **`tests/`**: Suite automatizada con Pytest para verificar reanudación ante microcortes, aislamiento de clientes y detección de bloqueos.
|
|
|
|
---
|
|
|
|
## 🧪 Ejecución Local para Desarrollo y Pruebas
|
|
|
|
Para depurar y probar la aplicación en tu máquina local:
|
|
|
|
### Backend (FastAPI)
|
|
|
|
```bash
|
|
cd backend
|
|
# 1. Crear y activar entorno virtual
|
|
python -m venv venv
|
|
# Windows: venv\Scripts\activate
|
|
# Linux/Mac: source venv/bin/activate
|
|
|
|
# 2. Instalar dependencias
|
|
pip install -r requirements.txt
|
|
|
|
# 3. Ejecutar servidor en modo desarrollo
|
|
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
|
|
```
|
|
|
|
### Frontend (React + Vite)
|
|
|
|
```bash
|
|
cd frontend
|
|
# 1. Instalar dependencias
|
|
npm install
|
|
|
|
# 2. Iniciar servidor de desarrollo
|
|
npm run dev
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ Requisitos de Despliegue en Proxmox VE
|
|
|
|
El backend y frontend se despliegan en un **Contenedor LXC Debian 12/13** sin dependencias de Docker:
|
|
|
|
```bash
|
|
# 1. Crear el contenedor en el host Proxmox
|
|
bash deployment/proxmox/01-create-lxc-pve-host.sh
|
|
|
|
# 2. Instalar el entorno, PostgreSQL, Nginx y Backend dentro del LXC
|
|
pct enter 100
|
|
bash /root/deployment/proxmox/02-install-backend-debian.sh
|
|
|
|
# 3. Configurar certificados SSL
|
|
bash /root/deployment/proxmox/03-configure-ssl.sh
|
|
```
|
|
|
|
---
|
|
|
|
## 💻 Agente de Windows (.EXE)
|
|
|
|
El agente se ejecuta en el área de notificaciones (System Tray) y cuenta con una interfaz gráfica en PyQt6 para apuntar al servidor y seleccionar las carpetas locales:
|
|
|
|
```powershell
|
|
# Ejecutar agente desde binario compilado
|
|
windows-agent\dist\OnEverDriveAgent-Standalone.exe
|
|
|
|
# O compilar nuevamente desde el código fuente
|
|
python windows-agent/build_exe.py
|
|
```
|
|
|
|
```powershell
|
|
# Código de Registro Único
|
|
OED-5752-EFED
|
|
```
|
|
|
|
---
|
|
|
|
## 🔒 Seguridad y Multi-Inquilino
|
|
|
|
- **Aislamiento por Dispositivo**: Cada máquina Windows tiene un `device_id` y `device_token` único generado criptográficamente.
|
|
- **Validación SHA-256**: Cada bloque de 4MB y el archivo final ensamblado se verifican mediante streaming de hash SHA-256.
|
|
- **Protección SQL Server**: Detección de archivos en uso para evitar transferencias incompletas de volcados `.bak`.
|
|
|
|
---
|
|
|
|
## 📝 Documentos y Cambios Recientes
|
|
|
|
- **Changelog**: Consulta el [Changelog de la Sesión](CHANGELOG_SESSION.md) para ver la lista completa de mejoras implementadas en la última sesión de desarrollo (sincronización bidireccional, planificación tipo Proxmox Backup Server y re-vinculación de agentes).
|
|
- **Visión Técnica / Roadmap**: Consulta la [Hoja de Ruta hacia Karen's Replicator](docs/roadmap_karens_replicator.md) para revisar el mapa de características y las fases de desarrollo propuestas.
|