alumnos_ti/TIP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

First commit

Browse Source
This commit is contained in:
unknown
2026-06-09 21:18:13 -03:00
commit 5bff6b938b
66 changed files with 10922 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+766
View File
@@ -0,0 +1,766 @@
# TIP — Threat Intelligence Platform
> Plataforma centralizada de monitoreo e inteligencia de amenazas sobre Telegram.
---
## Tabla de Contenidos
1. [Descripción General](#descripción-general)
2. [Arquitectura del Sistema](#arquitectura-del-sistema)
3. [Microservicios](#microservicios)
4. [Flujo del Alimentador](#flujo-del-alimentador)
5. [Requisitos Previos](#requisitos-previos)
6. [Instalación y Configuración](#instalación-y-configuración)
7. [Gestión de Backups](#gestión-de-backups)
8. [Troubleshooting](#troubleshooting)
---
## Descripción General
**TIP (Threat Intelligence Platform)** es una plataforma de monitoreo en tiempo real diseñada para capturar, analizar y gestionar mensajes de grupos y canales de Telegram. Mediante reglas configurables basadas en expresiones regulares, el sistema detecta patrones sospechosos, genera alertas automáticas y mantiene un registro auditable de todas las operaciones.
### Características Principales
- **Monitoreo en tiempo real**: Captura automática de mensajes desde grupos y canales de Telegram
- **Detección basada en reglas**: Expresiones regulares configurables para identificar patrones de interés
- **Gestión de alertas**: Ciclo de vida completo — Pendiente → En Curso → Resuelta — con historial de notas
- **Auditoría integral**: Registro de IP, usuario y timestamp en cada operación del sistema
- **Exportación de reportes**: Generación de PDFs con trazabilidad completa al cerrar una alerta
- **Estadísticas en tiempo real**: Dashboards con métricas, heatmaps y análisis de actividad
- **Control de acceso por roles**: Administradores y Operadores con permisos diferenciados
- **Sistema de backups**: Exportación e importación de bases de datos, configuración y sesiones de Telegram
---
## Arquitectura del Sistema
TIP está compuesto por **4 microservicios** y **2 bases de datos** independientes, orquestados con Docker Compose y expuestos a través de un proxy NGINX con SSL.
```
╔══════════════════════════════════════════════════════════════════════════════════╗
║ INTERNET ║
╚══════════════════════════════════════════════╦═══════════════════════════════════╝
║ HTTPS :443 / HTTP :80
╔════════════════╩════════════════╗
║ NGINX Proxy ║
║ Terminación SSL · Routing ║
╚══════╦══════════╦═══════╦═══════╝
║ ║ ║
╔══════════════╝ ╔═════╝ ╔══=╩═════════════╗
▼ ▼ ▼ ▼
╔════════════════╗ ╔══════════════╗ ╔══════════════╗ ╔═══════════════╗
║ Frontend ║ ║ API Feeder ║ ║ API Users ║ ║Backup Service ║
║ Streamlit ║ ║ FastAPI ║ ║ FastAPI ║ ║ FastAPI ║
║ Python 3.11 ║ ║ Python 3.11 ║ ║ Python 3.11 ║ ║ Python 3.11 ║
║ :8501 ║ ║ :8000 ║ ║ :8090 ║ ║ :8099 ║
╚═══════╦════════╝ ╚══════╦═══════╝ ╚══════╦═══════╝ ╚═══════╦═══════╝
║ ║ ║ ║
HTTP ║ ╔════════╩══════╗ ║ ║
REST ╠ ║ Telegram ║ ║ ║
║ ║ API (MTProto)║ ║ ║
║ ╚═══════════════╝ ║ ║
║ ║ ║ ╔═══════╩══════╗
║ ╔════════╩═══════╗ ╔═══════╩══════╗ ║ /config/... ║
╚═════════║ MariaDB :3306 ║ ║MariaDB :3307 ║ ║ (volumes) ║
║ DB: feeder ║ ║ DB: users ║ ╚══════════════╝
╚════════════════╝ ╚══════════════╝
```
### Comunicación entre Servicios
| Origen | Destino | Protocolo | Propósito |
|--------|---------|-----------|-----------|
| Frontend | API Feeder | HTTP/REST | Alertas, mensajes, reglas, grupos, estadísticas |
| Frontend | API Users | HTTP/REST | Login, gestión de usuarios |
| Frontend | Backup Service | HTTP/REST | Estado y descarga de backups |
| API Feeder | Telegram | MTProto (Telethon) | Captura de mensajes y adjuntos |
| API Feeder | API Feeder (interno) | HTTP/REST | Persistencia de mensajes vía `api_implementations.py` |
| Backup Service | MariaDB Feeder | TCP/MySQL | mysqldump para backup |
| Backup Service | MariaDB Users | TCP/MySQL | mysqldump para backup |
| NGINX | Todos los servicios | HTTP (reverse proxy) | Enrutamiento y terminación SSL |
### Seguridad
- **JWT compartido**: Todos los microservicios validan tokens con la misma `SECRET_KEY`
- **Roles**: `admin` y `operator` con controles en cada endpoint
- **Rate limiting**: Registro público limitado a 5 peticiones/minuto (SlowAPI)
- **HTTPS**: Terminación SSL en NGINX con soporte TLSv1.2 y TLSv1.3
---
## Microservicios
### 1. Frontend — Streamlit
**Propósito**: Interfaz de usuario para el monitoreo y gestión de la plataforma.
**Lenguaje**: Python **3.11**
**Ubicación**: `/frontend`
| Librería | Versión | Propósito |
|----------|---------|-----------|
| Streamlit | ≥ 1.28.0 | Framework web reactivo |
| Requests | ≥ 2.31.0 | Cliente HTTP hacia las APIs |
| Pandas | ≥ 2.0.0 | Manipulación de datos en dashboards |
| ReportLab | ≥ 3.6.0 | Generación de reportes PDF |
| Matplotlib | ≥ 3.7.0 | Gráficos estáticos auxiliares |
**Funcionalidades**:
- Panel de inicio con métricas y estado del alimentador
- Gestión de alertas con notas, cambio de estado y exportación PDF
- Búsqueda avanzada de mensajes con filtros por texto, grupo, remitente y fecha
- Descarga de adjuntos directamente desde Telegram
- Exploración de remitentes con historial de mensajes
- Estadísticas con gráficos de línea, barras, heatmaps y ranking de senders
- Panel de administración para gestión de usuarios, auditoría y backups
---
### 2. API Feeder — FastAPI
**Propósito**: Backend principal. Captura mensajes de Telegram, evalúa reglas y sirve los datos al Frontend.
**Lenguaje**: Python **3.11**
**Ubicación**: `/app`
| Librería | Versión | Propósito |
|----------|---------|-----------|
| FastAPI | 0.104.1 | Framework REST asíncrono |
| Uvicorn | 0.24.0 | Servidor ASGI |
| Telethon | 1.28.5 | Cliente MTProto para Telegram |
| SQLAlchemy | 2.0.23 | ORM |
| PyMySQL | 1.1.0 | Driver MySQL/MariaDB |
| Pydantic | 2.11.9 | Validación y serialización |
| Alembic | 1.11.1 | Migraciones de base de datos |
| python-jose | 3.3.0 | Generación y validación de JWT |
| python-dotenv | 1.0.0 | Gestión de variables de entorno |
| httpx | latest | Cliente HTTP asíncrono |
| aiofiles | 23.2.1 | I/O asíncrono de archivos |
| Requests | 2.32.5 | Cliente HTTP síncrono (integraciones internas) |
**Endpoints principales**:
| Grupo | Método | Ruta | Descripción |
|-------|--------|------|-------------|
| Messages | POST | `/messages/` | Crear mensaje + evaluar reglas |
| Messages | GET | `/messages/search/` | Búsqueda con filtros |
| Alerts | GET | `/alerts/` | Listar con filtros |
| Alerts | POST | `/alerts/{id}/resolve` | Cerrar alerta |
| Alerts | POST | `/alerts/{id}/in-progress` | Marcar en curso |
| Rules | POST | `/rules/` | Crear regla (con apply_to_history) |
| Groups | PATCH | `/groups/{id}/update-position` | Actualizar cursor de mensajes |
| Attachments | GET | `/attachments/{id}/download` | Descargar adjunto desde Telegram |
| Audit | GET | `/audit/` | Consultar logs de auditoría |
| Stats | GET | `/stats/` | Métricas y estadísticas agregadas |
| Manage | POST | `/manage/` | Agregar grupo/canal de Telegram |
| Manage | GET | `/manage/init-session` | Iniciar autenticación Telegram |
| Manage | POST | `/manage/verify-code` | Verificar código de autenticación |
---
### 3. API Users — FastAPI
**Propósito**: Gestión de usuarios, autenticación y auditoría de cambios de permisos.
**Lenguaje**: Python **3.11**
**Ubicación**: `/usuarios`
| Librería | Versión | Propósito |
|----------|---------|-----------|
| FastAPI | 0.104.1 | Framework REST |
| Uvicorn | 0.24.0 | Servidor ASGI |
| SQLAlchemy | 2.0.23 | ORM |
| PyMySQL | 1.1.2 | Driver MySQL/MariaDB |
| Pydantic | 2.5.0 | Validación de datos |
| passlib[bcrypt] | 1.7.4 | Hash seguro de contraseñas |
| bcrypt | 4.0.1 | Backend de hashing |
| python-jose | 3.3.0 | JWT |
| SlowAPI | latest | Rate limiting en endpoints públicos |
| python-multipart | 0.0.6 | Formularios multipart |
**Endpoints principales**:
| Método | Ruta | Descripción |
|--------|------|-------------|
| POST | `/api/v1/login` | Autenticación — devuelve JWT |
| GET | `/api/v1/users/` | Listar usuarios (admin) |
| GET | `/api/v1/users/pending` | Usuarios pendientes de aprobación |
| POST | `/api/v1/users/common` | Registro público (rate-limited) |
| PUT | `/api/v1/users/{id}` | Actualizar datos |
| PATCH | `/api/v1/users/{id}/role` | Cambiar rol |
| POST | `/api/v1/users/{id}/activate` | Activar usuario |
| GET | `/api/v1/logs/users` | Historial de modificaciones |
---
### 4. Backup Service — FastAPI
**Propósito**: Centraliza la generación y verificación de backups del sistema completo.
**Lenguaje**: Python **3.11**
**Ubicación**: `/backup_service`
| Librería | Versión | Propósito |
|----------|---------|-----------|
| FastAPI | 0.104.1 | Framework REST |
| Uvicorn | 0.24.0 | Servidor ASGI |
| python-jose | 3.3.0 | Validación JWT (mismo SECRET_KEY) |
| mysqldump / mysqladmin | sistema | Dump de bases de datos (instalados en Dockerfile) |
**Endpoints**:
| Método | Ruta | Descripción |
|--------|------|-------------|
| GET | `/backup` | Genera y descarga ZIP con los componentes seleccionados |
| GET | `/backup/status` | Estado de cada componente sin generar backup |
| GET | `/health` | Verificación de salud del servicio |
**Componentes exportables**:
- `databases/` — mysqldump de las bases de datos Feeder y Users
- `config/` — nginx.conf y docker-compose.yml
- `ssl/` — Certificados SSL
- `telegram_sessions/` — Archivos `.session` de autenticación de Telegram
---
## Flujo del Alimentador
El **Feeder** (alimentador) es el núcleo de captura del sistema. Se ejecuta en un hilo de fondo independiente al inicio de la API y opera en ciclos continuos.
```
┌─────────────────────────────────────────────────────────────────────────┐
│ INICIO DE LA API (startup_event) │
│ └─► Lanza run_sync_scraper() en thread separado via asyncio.to_thread │
└──────────────────────────────┬──────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ CICLO PRINCIPAL (run_sync_scraper) │
│ │
│ ┌─ INICIO DEL CICLO ──────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 1. TelegramChatSingleton.get_scraper() │ │
│ │ └─► ¿Existe instancia singleton? │ │
│ │ ├─ NO → TelegramClientManager.connect() │ │
│ │ │ └─► Busca session_*.session en /telegram_sessions│ │
│ │ │ Autentica con Telethon (MTProto) │ │
│ │ └─ SÍ → Reutiliza cliente existente │ │
│ │ │ │
│ │ 2. scraper.add_chats() │ │
│ │ └─► GET /groups/ → obtiene todos los grupos activos │ │
│ │ Para cada grupo: │ │
│ │ └─► Consulta Telegram con get_entity(id) │ │
│ │ Actualiza nombre, tipo y descripción en la DB │ │
│ │ │ │
│ │ 3. scraper.feeder_loop() │ │
│ │ └─► Para cada grupo en la DB: │ │
│ │ │ │
│ │ a) set_chat_id(group_id) │ │
│ │ └─► Configura el canal objetivo en Telethon │ │
│ │ │ │
│ │ b) self.first_id = group.message_position │ │
│ │ └─► Lee el cursor del último mensaje procesado │ │
│ │ │ │
│ │ c) refresh_chat() │ │
│ │ └─► GetHistoryRequest(min_id=first_id) │ │
│ │ Descarga en lotes de 100 solo mensajes nuevos │ │
│ │ │ │
│ │ d) get_and_post_message_info() │ │
│ │ │ │ │
│ │ ├─► _preload_senders() │ │
│ │ │ └─► Para cada sender_id único: │ │
│ │ │ GET /senders/{id} → ¿existe? │ │
│ │ │ NO → get_entity(id) en Telegram │ │
│ │ │ POST /senders/ → crea el remitente │ │
│ │ │ │ │
│ │ └─► Para cada mensaje descargado: │ │
│ │ │ │ │
│ │ ├─► Extrae: id, content, date, sender_id, │ │
│ │ │ group_id, media (adjunto si existe) │ │
│ │ │ │ │
│ │ ├─► POST /messages/ (API interna) │ │
│ │ │ │ │ │
│ │ │ └─► Endpoint crea el mensaje y: │ │
│ │ │ Para cada regla activa: │ │
│ │ │ └─► re.search(regex, content) │ │
│ │ │ ¿Coincide? → crea Alert(status=open)│ │
│ │ │ │ │
│ │ └─► Si tiene adjunto → POST /attachments/ │ │
│ │ │ │
│ │ e) act_message_position(group_id, last_message_id) │ │
│ │ └─► PATCH /groups/{id}/update-position │ │
│ │ Actualiza el cursor para el próximo ciclo │ │
│ │ │ │
│ │ 4. Fin del ciclo → sleep(200 segundos) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ⚠️ Si ocurre una excepción en cualquier punto: │
│ └─► scraper_status["last_error"] = str(e) │
│ sleep(60 segundos) │
│ El singleton mantiene el cliente → intento de reconexión │
└──────────────────────────────────────────────────────────────────────────┘
```
### Descarga de Adjuntos (bajo demanda)
Cuando un usuario descarga un adjunto desde la UI, se sigue un flujo independiente para no interferir con el ciclo del Feeder:
```
Frontend
└─► GET /attachments/{id}/download
│
├─► Obtiene metadata del adjunto (group_id, message_id)
│
├─► TelegramChatSingleton.get_tmp_scraper()
│ └─► Crea un TelegramClientManager temporal
│ Copia el .session file a un archivo temporal
│ Lanza un thread dedicado con su propio event loop
│
└─► download_attachment_to_buffer(group_id, message_id)
└─► client.get_messages(group_id, ids=message_id)
client.download_media(message, file=BytesIO())
Devuelve los bytes → StreamingResponse al Frontend
Elimina la sesión temporal al finalizar
```
### Configuración del Ciclo
Los parámetros del ciclo se pueden ajustar directamente en `app/main.py`:
```python
scraper_config = {
"cicle_time": 200, # segundos entre ciclos (recomendado ≥ 200 para evitar flood)
"error_delay": 60, # segundos de espera tras un error antes de reintentar
}
```
---
## Requisitos Previos
### Hardware Mínimo
| Recurso | Mínimo | Recomendado |
|---------|--------|-------------|
| CPU | 2 núcleos | 4 núcleos |
| RAM | 4 GB | 8 GB |
| Almacenamiento | 20 GB | 50 GB+ |
### Software Requerido
| Componente | Versión Mínima | Instalación |
|-----------|----------------|-------------|
| Docker | 20.10+ | https://docs.docker.com/engine/install/ |
| Docker Compose | 1.29+ | Incluido en Docker Desktop |
| Git | 2.20+ | https://git-scm.com/downloads |
| jq (solo Linux/macOS) | 1.6+ | `sudo apt install jq` o `brew install jq` |
> **Nota sobre Python**: El proyecto utiliza **Python 3.11** en todos los microservicios. La versión está declarada en cada `Dockerfile` (`FROM python:3.11-slim`). No es necesario tener Python instalado localmente; Docker lo gestiona de forma aislada.
### Credenciales Necesarias
- **Telegram API ID y API Hash**: Obtener en https://my.telegram.org/apps con la cuenta que se usará para el monitoreo
- **Número de teléfono** de esa cuenta (formato internacional, ej: `+5491112345678`)
- Acceso a los grupos/canales de Telegram que se desean monitorear
---
## Instalación y Configuración
### Paso 1 — Clonar el Repositorio
```bash
git clone https://github.com/tu-usuario/tip.git
cd tip
```
### Paso 2 — Crear el Archivo `.env`
```bash
cp .env.example .env
```
Edita `.env` con tus valores reales:
```env
# ── TELEGRAM ────────────────────────────────────────────────────────────
# Obtener en https://my.telegram.org/apps
TELEGRAM_API_ID=123456789
TELEGRAM_API_HASH=abcdef0123456789abcdef0123456789
TELEGRAM_TELEPHONE=+5491112345678
# ── SEGURIDAD ────────────────────────────────────────────────────────────
# Clave compartida entre todos los microservicios (mínimo 20 caracteres)
# Generar con: openssl rand -hex 32
SECRET_KEY=reemplazar_con_clave_secreta_minimo_32_chars
# ── BASES DE DATOS ───────────────────────────────────────────────────────
DB_ROOT_PASS_FEEDER=password_feeder
DB_ROOT_PASS_USERS=password_users
# ── ADMIN (creado automáticamente en el primer inicio) ──────────────────
ADMIN_EMAIL=admin@tudominio.com
ADMIN_PASSWORD=contraseña_admin_segura
```
### Paso 3 — Configurar `docker-compose.yml`
```bash
cp docker-compose_example.yml docker-compose.yml
```
Reemplaza los valores marcados con `YOUR-*`:
```yaml
# Contraseñas de bases de datos
database:
environment:
MYSQL_ROOT_PASSWORD: password_feeder # ← cambiar
database_users:
environment:
MYSQL_ROOT_PASSWORD: password_users # ← cambiar
# URLs de conexión a las bases de datos
api:
environment:
DATABASE_URL: mariadb+pymysql://root:password_feeder@database:3306/feeder
TELEGRAM_API_ID: TU_API_ID
TELEGRAM_API_HASH: TU_API_HASH
TELEGRAM_TELEPHONE: TU_TELEFONO
SECRET_KEY: TU_SECRET_KEY
api_users:
environment:
DATABASE_URL: mariadb+pymysql://root:password_users@database_users:3307/users
SECRET_KEY: TU_SECRET_KEY # ← debe ser la misma que api
ADMIN_EMAIL: admin@tudominio.com
ADMIN_PASSWORD: contraseña_admin
# URLs para el backup service
backup:
environment:
FEEDER_DATABASE_URL: mariadb+pymysql://root:password_feeder@database:3306/feeder
USERS_DATABASE_URL: mariadb+pymysql://root:password_users@database_users:3307/users
SECRET_KEY: TU_SECRET_KEY
```
### Paso 4 — Configurar NGINX
```bash
mkdir -p nginx/ssl
cp nginx/nginx.conf_example nginx/nginx.conf
```
Edita `nginx/nginx.conf` y reemplaza `localhost` con tu dominio:
```nginx
server_name tu_dominio.com;
```
Para **desarrollo local sin SSL**, comenta el bloque HTTPS y usa solo el bloque HTTP.
**Para producción con Let's Encrypt**:
```bash
# Instalar certbot (fuera de Docker)
sudo apt install certbot
# Generar certificados
sudo certbot certonly --standalone -d tu_dominio.com
# Copiar al directorio del proyecto
sudo cp /etc/letsencrypt/live/tu_dominio.com/fullchain.pem ./nginx/ssl/
sudo cp /etc/letsencrypt/live/tu_dominio.com/privkey.pem ./nginx/ssl/
sudo chown $(whoami):$(whoami) ./nginx/ssl/*
```
### Paso 5 — Iniciar los Contenedores
```bash
# Construir imágenes e iniciar todos los servicios
docker compose up -d --build
# Verificar que todos estén corriendo
docker compose ps
```
Resultado esperado:
```
NAME SERVICE STATUS
feeder_api api running
users_api api_users running
frontend frontend running
backup_service backup running
feeder_db database running (healthy)
users_db database_users running (healthy)
nginx_proxy nginx running
```
```bash
# Ver logs en tiempo real
docker compose logs -f api api_users
```
### Paso 6 — Autenticar la Sesión de Telegram
La primera vez (o tras reinstalación) es necesario autenticar el cliente de Telegram:
1. Accede a la UI como **admin**: https://tu_dominio.com
2. Ve a **Panel de Administración** → **Sistema** → **Alimentador**
3. Haz clic en **Iniciar Nueva Sesión**
4. Revisa el código de verificación que llegó a tu cuenta de Telegram
5. Ingrésalo en el campo correspondiente (más la contraseña 2FA si aplica)
6. El alimentador se activará automáticamente
### Paso 7 — Agregar Grupos a Monitorear
1. Ve a **Grupos y Canales** → **Agregar grupo**
2. Abre el grupo en Telegram Web (`web.telegram.org`)
3. Copia la URL completa (contiene el ID: `.../#-100XXXXXXXXX`)
4. Pégala en el campo y haz clic en **Agregar Grupo**
5. El sistema valida el acceso contra Telegram y lo registra
---
## Gestión de Backups
### Generar un Backup
#### Desde la UI
1. Accede como **admin**
2. Ve a **Panel de Administración** → **Sistema** → **Backup del Sistema**
3. Selecciona los componentes a incluir
4. Haz clic en **⬇️ Generar y Descargar Backup**
5. Guarda el archivo `tip_backup_YYYYMMDD_HHMMSS.zip` en lugar seguro
#### Desde la línea de comandos
```bash
# Primero, obtener un token JWT (reemplazar por tus credenciales)
TOKEN=$(curl -s -X POST http://localhost:8090/api/v1/login \
-H "Content-Type: application/json" \
-d '{"email":"admin@tudominio.com","password":"tu_password"}' \
| jq -r '.access_token')
# Solicitar el backup
curl -X GET \
"http://localhost:8099/backup?include_db=true&include_config=true&include_ssl=true&include_sessions=true" \
-H "Authorization: Bearer $TOKEN" \
-o "tip_backup_$(date +%Y%m%d_%H%M%S).zip"
```
---
### Restaurar un Backup
> ⚠️ **ADVERTENCIA**: La restauración sobrescribe datos existentes. Asegúrate de que es lo que necesitas antes de continuar.
#### Windows (PowerShell)
```powershell
# 1. Coloca el archivo tip_backup_*.zip en la raíz del proyecto
# 2. Abre PowerShell como Administrador y navega al directorio
cd C:\ruta\al\proyecto
# 3. Habilitar ejecución de scripts (si no está habilitado)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 4. Ejecutar el script
.\restore_backup.ps1
```
#### Linux / macOS (Bash)
```bash
# 1. Coloca el archivo tip_backup_*.zip en la raíz del proyecto
# 2. Dar permisos de ejecución al script
chmod +x restore_backup.sh
# 3. Ejecutar el script
./restore_backup.sh
```
#### ¿Qué hace el script de restauración?
```
INICIO
│
├─ 1. Solicita confirmación al usuario
│
├─ 2. Localiza el tip_backup_*.zip más reciente en el directorio actual
│
├─ 3. Extrae el contenido en ./temp_restore/
│
├─ 4. Lee manifest.json → identifica componentes incluidos y advertencias
│
├─ 5. Obtiene credenciales de las bases de datos desde docker-compose.yml
│
├─ 6. Por cada componente en el manifiesto:
│ ├─ database:feeder → levanta feeder_db y restaura el .sql
│ ├─ database:users → levanta users_db y restaura el .sql
│ ├─ config:* → copia nginx.conf y/o docker-compose.yml
│ ├─ ssl → copia certificados a ./nginx/ssl/
│ └─ telegram_sessions → copia .session a ./app/telegram_sessions/
│
├─ 7. Muestra las advertencias registradas en el manifiesto
│
├─ 8. Elimina ./temp_restore/
│
└─ 9. Pregunta si desea reiniciar los contenedores (docker compose down && up)
```
#### Dependencias del Script
| Dependencia | Windows | Linux/macOS |
|-------------|---------|-------------|
| Docker + Docker Compose | ✅ Requerido | ✅ Requerido |
| jq | No requerido (usa PowerShell nativo) | ✅ `sudo apt install jq` |
---
### Buenas Prácticas de Backup
- **Frecuencia**: Realiza backups diarios en producción, especialmente antes de actualizaciones
- **Validación**: Prueba la restauración en un entorno de prueba periódicamente
- **Almacenamiento externo**: Guarda copias en un servidor remoto o servicio de almacenamiento (S3, OneDrive, etc.)
- **Encriptación**: Si el backup contiene sesiones o datos sensibles, encríptalo antes de transferirlo:
```bash
# Linux/macOS
openssl enc -aes-256-cbc -salt -in tip_backup_*.zip -out tip_backup_encrypted.zip
# Descifrar
openssl enc -d -aes-256-cbc -in tip_backup_encrypted.zip -out tip_backup_restored.zip
```
---
## Troubleshooting
### Los contenedores no inician
```bash
# Ver logs completos de todos los servicios
docker compose logs
# Ver logs de un servicio en particular
docker compose logs api
docker compose logs database
# Reconstruir imágenes sin caché
docker compose down
docker compose up -d --build --force-recreate
```
### Error de conexión a la base de datos
```bash
# Verificar que MariaDB está aceptando conexiones
docker compose exec database mysql -u root -p -e "SELECT 1;"
# Verificar conectividad entre contenedores
docker compose exec api ping database
```
### El alimentador aparece como inactivo
```bash
# Verificar si hay archivos de sesión de Telegram
docker compose exec api ls -la /app/telegram_sessions/
# Si no hay sesión o está corrupta, eliminarla y autenticar de nuevo desde la UI
docker compose exec api rm -f /app/telegram_sessions/session_*
# Luego: Panel de Administración → Sistema → Iniciar Nueva Sesión
```
### NGINX devuelve 502 Bad Gateway
```bash
# Verificar que los servicios upstream estén corriendo
docker compose ps
# Validar la configuración de NGINX
docker compose exec nginx nginx -t
# Ver logs de NGINX
docker compose logs nginx
```
### Las alertas no se generan automáticamente
```bash
# Verificar que existen reglas activas
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/rules/
# Verificar que el feeder está capturando mensajes
docker compose logs api | grep -E "Feeding|Cycle|feeder_loop"
# Verificar que no hay errores de regex en las reglas
docker compose logs api | grep -i "regex\|WARN"
```
---
## Estructura del Proyecto
```
tip/
├── app/ # API Feeder
│ ├── alembic/ # Migraciones de base de datos
│ ├── integrations/ # Cliente Telegram (chats.py, api_implementations.py)
│ ├── routers/ # Endpoints REST
│ ├── main.py # Entry point + scraper loop
│ ├── models.py # Modelos SQLAlchemy
│ ├── schemas.py # Schemas Pydantic
│ ├── auth.py # JWT helpers
│ └── audit.py # Logger de auditoría
├── usuarios/ # API Users
│ ├── main.py
│ ├── models.py
│ ├── schemas.py
│ ├── crud.py
│ ├── services.py
│ └── dependencies.py
├── frontend/ # UI Streamlit
│ ├── app.py
│ ├── src/
│ │ ├── api.py # Cliente HTTP hacia las APIs
│ │ ├── auth.py # Login / sesión
│ │ └── pages/
│ │ ├── dashboard.py
│ │ └── views/ # alerts, messages, rules, groups, stats, ...
│ └── .streamlit/
│ ├── config.toml # Tema visual
│ └── secrets.toml
├── backup_service/ # Backup Service
│ ├── main.py
│ ├── requirements.txt
│ └── Dockerfile
├── nginx/
│ ├── nginx.conf # Configuración del proxy (generada desde el ejemplo)
│ └── ssl/ # Certificados SSL (excluidos del repo)
├── Dockerfile # Imagen API Feeder
├── Dockerfile_users # Imagen API Users
├── Dockerfile_frontend # Imagen Frontend
├── docker-compose.yml # Orquestación (generado desde el ejemplo)
├── docker-compose_example.yml # Plantilla de configuración
├── entrypoint.sh # Ejecuta migraciones Alembic antes de iniciar la API
├── restore_backup.sh # Script de restauración (Linux/macOS)
├── restore_backup.ps1 # Script de restauración (Windows)
├── requirements.txt # Dependencias API Feeder
├── requirements_users.txt # Dependencias API Users
├── requirements_frontend.txt # Dependencias Frontend
└── .gitignore
```
---
*Plataforma desarrollada para uso interno — Municipio de Paraná.*