Cómo crear un bot de Telegram para monitorear proxies: guía paso a paso para principiantes

Introducción

En esta guía paso a paso, crearás desde cero un bot de Telegram completamente funcional que monitorea automáticamente una lista de proxies, mide el tiempo de respuesta, detecta cambios de IP después de la rotación, verifica la geolocalización a través del servicio ip-api.com y envía notificaciones visibles en Telegram ante problemas y degradaciones. Pasaremos paso a paso desde la idea hasta el despliegue en un VPS con autoinicio, historia en SQLite y un dashboard simple con estadísticas de uptime y exportación de logs.

Esta guía está diseñada para principiantes, pero también tiene elementos para avanzados. Si nunca has programado un bot, no te preocupes: desglosaremos cada paso, explicando por qué es necesario y cómo comprobar el resultado. Al final, tendrás una herramienta de monitoreo de proxies estable que trabaja según un horario de 5 a 15 minutos, capaz de agrupar proxies por regiones y tipos, y que enviará alertas informativas a tu Telegram.

Antes de comenzar, es útil saber cómo abrir la terminal, instalar programas y crear carpetas y archivos. Todo lo demás lo explicaremos. Se estima que completar todos los pasos tomará entre 4 y 8 horas, incluida la configuración del entorno, escritura de código, pruebas y despliegue. Si ya tienes un VPS y habilidades básicas en Python, podrás hacerlo más rápido.

Al final de la guía, obtendrás: un bot de Telegram en aiogram 3, un módulo asíncrono de comprobaciones en aiohttp, un programador APScheduler para tareas periódicas, una base de datos SQLite con logs y estadísticas, un dashboard web simple con métricas clave y exportación CSV, así como instrucciones para mantenimiento y ampliación de funcionalidades.

Consejo: Es mejor seguir la guía de manera secuencial, sin saltar pasos. Después de cada etapa, hemos añadido comprobaciones para que te asegures de que todo funciona.

Preparativos previos

Antes de escribir el código, prepararemos todas las herramientas y el entorno necesarios. Esto evitará errores casuales y ahorrará tiempo.

Herramientas, programas y accesos necesarios

• Cuenta de Telegram para crear el bot y recibir notificaciones.
• VPS o computadora local con Linux (Ubuntu 22.04 o 24.04 preferiblemente). También se puede usar en Windows y macOS, pero las instrucciones de despliegue estarán en Ubuntu.
• Python 3.11 o superior. Comprobaremos la versión con el comando python3 --version.
• Terminal y permisos básicos de sudo para instalar paquetes.
• Lista de proxies para monitoreo en el formato host:port, más usuario y contraseña, si es necesario. Soportamos HTTP, HTTPS y SOCKS5.

Requisitos del sistema

• 1 CPU, 512-1024 MB de RAM son suficientes para 50-200 proxies con un intervalo de 5-15 minutos. Para miles de proxies es mejor tener 2 CPUs y 2 GB de RAM.
• Espacio libre en disco de al menos 1 GB. SQLite es ligera, pero los logs aumentan.
• Acceso abierto a Internet. Es obligatorio el acceso a la API de Telegram y a tus proxies. Para ip-api.com se necesita acceso HTTP saliente.

Qué necesitas instalar

• Python 3.11+ y venv para el entorno virtual.
• pip para instalar dependencias.
• Librerías: aiogram versión 3, aiohttp, APScheduler, aiosqlite, python-dotenv (para una configuración cómoda), uvloop (opcional para Linux), yarl (frecuentemente viene como dependencia).

Creación de copias de seguridad

Al inicio, las copias de seguridad no son críticas. Después de lanzar el bot, configuraremos una copia de seguridad simple de la base de datos SQLite con logs y configuraciones. Esto permitirá revertir cambios en caso de actualizaciones erróneas o daños en el archivo.

⚠️ Atención: SQLite es un solo archivo. Si se daña por un corte inesperado de energía, podrías perder registros recientes. Por eso, en el VPS activa las copias automáticas diarias del archivo de la base de datos con cron o timers de systemd. Mostraremos un script simple para esto al final.

Conceptos básicos

Para que no haya confusiones, acordemos algunos términos clave y principios de funcionamiento.

• Proxy — servidor intermediario a través del cual pasan tus solicitudes. Pueden ser HTTP, HTTPS y SOCKS5. El proxy puede requerir autorización usuario:contraseña o funcionar con enlace de IP.
• Latencia — tiempo que tardamos en hacer una solicitud a través del proxy y recibir una respuesta. Medimos en milisegundos. Cuanto menos, mejor.
• Rotación de IP — algunos proxies cambian periódicamente su IP externa. Nuestro bot debe monitorear estos cambios y notificar si la IP ha cambiado de forma inesperada o no coincide con la región esperada.
• Geolocalización — país, ciudad y operador de la IP. Lo obtenemos a través del servicio ip-api.com por IP. Esto ayudará a asegurarte de que tu proxy esté en el país correcto.
• Degradación — el proxy responde, pero mucho más lento de lo normal o con errores frecuentes. Vamos a distinguir entre DOWN (completamente inaccesible) y DEGRADED (funciona, pero mal).
• aiogram 3 — biblioteca asíncrona moderna para bots de Telegram. Simple, rápida, soporta todas las características actuales de Telegram en 2026.
• aiohttp — solicitudes HTTP asíncronas con timeouts y soporte para proxies.
• APScheduler — programador que ejecutará verificaciones de acuerdo a un horario cada N minutos.
• SQLite — base de datos incorporada. Un solo archivo, rápido y sin necesidad de instalación de servidor. Ideal para un registro local y estadísticas.

El principio de funcionamiento del bot es el siguiente: según el horario, el bot toma una lista de proxies, realiza pruebas rápidas a través de cada proxy, mide el tiempo, obtiene la IP externa y datos geográficos, y guarda los resultados en SQLite. Si un proxy falla o se degrada, el bot genera un mensaje adecuado y lo envía a Telegram. Adicionalmente, el bot reacciona a comandos del chat: mostrar estado, uptime, últimos errores, exportar CSV, agregar o desactivar proxies, cambiar intervalo.

Consejo: Para no exceder los límites de ip-api.com (generalmente 45 solicitudes por minuto para el nivel gratuito), implementaremos caché para datos geográficos y limitaciones en las solicitudes paralelas de geolocalización. Esto no ralentizará el funcionamiento, pero protegerá contra bloqueos.

Paso 1: Creando un bot en Telegram y configurando acceso

Objetivo de la etapa

Obtener el token del bot de Telegram y crear un chat privado para notificaciones, para que luego el bot pueda enviar mensajes sobre incidentes.

Instrucciones paso a paso

1. Abre la aplicación Telegram en tu teléfono o computadora.
2. En la barra de búsqueda, escribe BotFather y abre la cuenta oficial con la marca de verificación azul.
3. Haz clic en Iniciar o escribe el comando /start, luego escribe /newbot.
4. Inventa un nombre para el bot. Por ejemplo: ProxyMonitorBot.
5. Inventa un nombre de usuario único para el bot, que termine en bot. Por ejemplo: proxy_monitor_helper_bot.
6. Copia el token proporcionado. Aparece como un conjunto de caracteres y números separados por dos puntos.
7. Crea un chat privado o grupo, donde el bot enviará las notificaciones. Añade ahí al bot.
8. Escribe cualquier mensaje en el chat para que aparezca en la lista de tu cuenta.
9. Abre un diálogo con el bot y presiona Iniciar para activarlo.

Puntos importantes: Guarda el token en secreto. No lo compartas con nadie. Si se filtra, un malintencionado podrá controlar tu bot. Si el token se ve comprometido, en BotFather selecciona /revoke y obtén uno nuevo.

Consejo: Crea un grupo separado para alertas, donde solo estarás tú y el bot. Así, las notificaciones no se perderán entre otros mensajes.

✅ Verificación: Has obtenido un token y añadido el bot al chat correcto. El bot responde al comando /start en el diálogo privado.

Posibles problemas y soluciones

• Problema: El bot no responde a /start. Razón: No has presionado Iniciar o el token está escrito incorrectamente en el código. Solución: Asegúrate de que el bot esté activado y que más adelante indicaremos el token correctamente en el archivo .env.
• Problema: No ves el chat ID. Razón: Aún no lo hemos obtenido. Solución: Más adelante, un comando en el bot mostrará el chat_id automáticamente.

Paso 2: Preparando el entorno Python y la estructura del proyecto

Objetivo de la etapa

Crear una carpeta de proyecto, un entorno virtual Python 3.11+, instalar dependencias, configurar la configuración y la estructura de directorios.

Instrucciones paso a paso

1. Abre la terminal en tu máquina o conéctate al VPS a través de SSH.
2. Comprueba la versión de Python con el comando: python3 --version. Si la versión es inferior a 3.11, instala la actual.
3. En Ubuntu ejecuta: sudo apt update; sudo apt install -y python3.11 python3.11-venv python3-pip.
4. Crea la carpeta del proyecto: mkdir proxy-monitor-bot; cd proxy-monitor-bot.
5. Crea el entorno virtual: python3.11 -m venv .venv.
6. Activa el entorno: source .venv/bin/activate.
7. Actualiza pip: pip install --upgrade pip.
8. Instala las dependencias: pip install aiogram aiohttp aiosqlite APScheduler python-dotenv uvloop.
9. Crea la estructura de carpetas: mkdir app app/modules app/db app/bot app/web.
10. Crea los archivos: touch app/__init__.py app/config.py app/main.py app/modules/proxy_checker.py app/db/models.py app/db/migrations.py app/bot/handlers.py app/bot/notifications.py app/scheduler.py app/web/server.py .env .env.example README.md.

Configuración básica

Abre el archivo .env y añade las claves (reemplaza los valores por los tuyos):

BOT_TOKEN=tu_token_de_BotFather TELEGRAM_CHAT_ID=número_o_deja_vacío DB_PATH=./data/monitor.db PROBE_TIMEOUT=8 PROBE_RETRIES=2 CHECK_INTERVAL_MINUTES=10 GEO_CACHE_TTL_HOURS=24 IP_API_URL=http://ip-api.com/json PROXY_CONCURRENCY=20 GEO_CONCURRENCY=10 DASHBOARD_HOST=0.0.0.0 DASHBOARD_PORT=8080

Copia .env en .env.example y elimina los secretos, para que sea fácil compartir el proyecto sin tokens.

Consejo: Mantén el archivo .env fuera del control de versiones. Añade .env a .gitignore, para no subir accidentalmente el token al repositorio.

Estructura mínima del código

El archivo app/config.py leerá las variables de entorno y proporcionará la configuración. El archivo app/main.py ejecutará el bot, el programador y el dashboard web. El módulo proxy_checker.py realizará todas las verificaciones. En la carpeta db colocaremos los modelos y migraciones de SQLite. En bot escribiremos los manejadores de comandos y el envío de notificaciones. En web, ejecutaremos un servidor web simple con estadísticas y exportación.

✅ Verificación: Tienes un entorno virtual, las dependencias están instaladas, el archivo .env creado, y la estructura del proyecto es la correcta. El comando python -c "import aiogram, aiohttp, aiosqlite; print('ok')" muestra ok.

Posibles problemas y soluciones

• Problema: pip informa sobre un error de SSL o inaccesibilidad. Razón: No hay acceso a Internet. Solución: Comprueba la red o usa un espejo local de pip.
• Problema: Python 3.11 no está disponible. Razón: Sistema operativo antiguo. Solución: Actualiza el sistema o instala Python a través de deadsnakes PPA o pyenv.

Paso 3: Escribiendo el módulo de verificación de proxies: conexión, latencia, IP, geolocalización

Objetivo de la etapa

Crear un módulo asíncrono que verifique rápida y confiablemente los proxies: puede hacer una solicitud HTTP de prueba a través del proxy, medir la latencia, conocer la IP externa, hacer una solicitud a ip-api.com, cachear datos geográficos y manejar errores correctamente.

Ideas clave

• Para la verificación de disponibilidad, hacemos una solicitud a un recurso ligero, por ejemplo a https://api.ipify.org o a cualquier punto de eco rápido. Elegiremos obtener la IP a través del servicio y luego geolocalización a través de ip-api.com. Se puede hacer al revés también.
• Establecemos un timeout de 8 segundos por defecto, con 2 intentos. Estos parámetros son configurables a través de .env.
• aiohttp trabaja cómodamente con proxies: pasamos el parámetro proxy en ClientSession.request.
• Para la geolocalización, cacheamos datos por 24 horas por IP, para no gastar el límite.
• Paralelizamos las verificaciones, pero limitamos la simultaneidad con un semáforo, para no sobrecargar las conexiones y no chocar con los límites de ip-api.

Instrucciones detalladas

1. Abre el archivo app/modules/proxy_checker.py.
2. Describe el modelo de proxy como un diccionario: id, label, type (http, https, socks5), endpoint (host:port), username, password, region, group, expected_country, last_ip.
3. Crea una función asíncrona build_proxy_url que, a partir de type, host, port y opcionalmente username:password, forme una cadena en el formato scheme://user:pass@host:port.
4. Crea una función asíncrona fetch_ip(session, proxy_url) para obtener la IP externa a través del proxy. Usa la URL https://api.ipify.org?format=json o un servicio similar que retorne tu IP en JSON. Anota el tiempo antes de la llamada y después de la respuesta, para obtener la latencia.
5. Crea un caché de datos geográficos: un diccionario en memoria y una tabla en SQLite, para no perder el caché entre reinicios. La clave es la IP, el valor es un JSON del país, ciudad, organización y tiempo de cacheo.
6. Crea la función fetch_geo(session, ip) que realiza una solicitud GET a ip-api.com/json/{ip}?fields=status,country,countryCode,regionName,city,org,query. Si el estado es fail, retorna un indicador de error. Si tiene éxito, retorna los datos geográficos.
7. Implementa la función check_proxy(proxy) con la lógica: construir proxy_url, intentar obtener la IP con un timeout, medir la latencia, luego obtener los datos geográficos (del caché o de la red), formar el resultado: disponibilidad (ok), latencia en milisegundos, IP externa, país y ciudad, y tipo de resultado: UP, DEGRADED o DOWN.
8. Define los criterios para DEGRADED: si la latencia está por encima de tu umbral, por ejemplo de 1500 a 2000 ms, o si la proporción de errores en las últimas comprobaciones es significativa. Para simplicidad: si hay respuesta, pero la latencia es mayor a 2 segundos — DEGRADED, de lo contrario — UP. Si no hay respuesta — DOWN.
9. Retorna un resultado detallado para registro: timestamp, proxy_id, status, latency_ms o None, ip o None, geo o None, error_reason, changed_ip (True o False si la IP difiere de la anterior), changed_geo (si el país ha cambiado), region, group, type.
10. Agrega manejo de excepciones: asyncio.TimeoutError, aiohttp.ClientConnectorError, aiohttp.ClientHttpProxyError, aiohttp.ClientProxyConnectionError, errores de socket. En el campo error_reason anota una breve descripción.

Ejemplo de código (simplificado, en una línea)

Ejemplo de lógica en forma compacta: import asyncio, time, json, aiohttp; async def check_proxy(proxy, cfg, geo_cache, sem): async with sem: start=time.perf_counter(); purl=f"{proxy['type']}://{proxy.get('username', '')+(':'+proxy.get('password','') if proxy.get('username') else '')+'@' if proxy.get('username') else ''}{proxy['endpoint']}"; timeout=aiohttp.ClientTimeout(total=cfg['PROBE_TIMEOUT']); try: async with aiohttp.ClientSession(timeout=timeout) as s: t0=time.perf_counter(); async with s.get('https://api.ipify.org?format=json', proxy=purl, ssl=False) as r: data=await r.json(); ip=data.get('ip'); latency=int((time.perf_counter()-t0)*1000); if not ip: raise Exception('sin-ip'); geo=geo_cache.get(ip); if not geo or geo['ts']

En el código real, añadiremos registro en SQLite y semáforos para solicitudes de GEO, así como timeouts y reintentos ordenados.

⚠️ Atención: No hagas demasiadas solicitudes paralelas a ip-api.com. Si tienes una lista de cientos de proxies, cachea los resultados y limita la simultaneidad en las solicitudes. Esto protegerá contra límites y errores.

✅ Verificación: Llama manualmente a la función check_proxy para un proxy de prueba y imprime el resultado. Deberías ver un estado UP o DEGRADED con la latencia medida y la IP externa.

Posibles problemas y soluciones

• Problema: Error ClientHttpProxyError. Razón: El proxy no soporta el tipo solicitado o la autorización es incorrecta. Solución: Verifica el tipo y las credenciales, actualiza el endpoint.
• Problema: Geo siempre es desconocido. Razón: Error en la solicitud a ip-api o bloqueo. Solución: Verifica IP_API_URL y la red, activa el registro de excepciones.

Paso 4: Configurando la base de datos SQLite y el registro de historia

Objetivo de la etapa

Crear tablas en SQLite para almacenar la lista de proxies, la historia de verificaciones, incidentes, caché geográfico y configuraciones. Esto te proporcionará estadísticas detalladas y la capacidad de generar gráficos.

Estructura de la base

• proxies: id, label, type, endpoint, username, password, region, group_name, expected_country, last_ip, enabled, created_at, updated_at.
• checks: id, proxy_id, ts, status, latency_ms, ip, country, city, org, error_reason.
• incidents: id, proxy_id, opened_at, closed_at, kind (DOWN o DEGRADED), last_status, last_message, active.
• geo_cache: ip, country, city, org, ts.
• settings: key, value (por ejemplo, intervalo de verificación por defecto).

Instrucciones detalladas

1. Abre app/db/models.py. Describe las constantes SQL para crear tablas. Añade índices por proxy_id y ts, para acelerar las consultas.
2. Crea la función init_db(db_path), que crea la carpeta data si es necesario, abre la conexión a aiosqlite.connect y ejecuta create table if not exists para todas las tablas.
3. Agrega funciones para registrar resultados: add_proxy, update_proxy_last_ip, add_check, open_incident, close_incident_if_needed, upsert_geo_cache, get_recent_checks, get_uptime_stats.
4. Implementa migraciones en app/db/migrations.py. Para el primer inicio, es suficiente ejecutar todas las create table. Durante actualizaciones de versión, el script añadirá las columnas que falten.

Ejemplo SQL (en una línea)

CREATE TABLE IF NOT EXISTS proxies (id INTEGER PRIMARY KEY AUTOINCREMENT, label TEXT, type TEXT, endpoint TEXT, username TEXT, password TEXT, region TEXT, group_name TEXT, expected_country TEXT, last_ip TEXT, enabled INTEGER DEFAULT 1, created_at INTEGER, updated_at INTEGER); CREATE TABLE IF NOT EXISTS checks (id INTEGER PRIMARY KEY AUTOINCREMENT, proxy_id INTEGER, ts INTEGER, status TEXT, latency_ms INTEGER, ip TEXT, country TEXT, city TEXT, org TEXT, error_reason TEXT, FOREIGN KEY(proxy_id) REFERENCES proxies(id)); CREATE INDEX IF NOT EXISTS idx_checks_proxy_ts ON checks(proxy_id, ts); CREATE TABLE IF NOT EXISTS incidents (id INTEGER PRIMARY KEY AUTOINCREMENT, proxy_id INTEGER, opened_at INTEGER, closed_at INTEGER, kind TEXT, last_status TEXT, last_message TEXT, active INTEGER, FOREIGN KEY(proxy_id) REFERENCES proxies(id)); CREATE TABLE IF NOT EXISTS geo_cache (ip TEXT PRIMARY KEY, country TEXT, city TEXT, org TEXT, ts INTEGER); CREATE TABLE IF NOT EXISTS settings (key TEXT PRIMARY KEY, value TEXT);

Consejo: Si ya mantienes una lista de proxies en CSV o JSON, añade una importación conveniente a la base: un script simple lee el archivo y agrega registros en proxies.

✅ Verificación: Ejecuta la función init_db y asegúrate de que el archivo de la base de datos aparezca en la ruta de DB_PATH. Verifica que las tablas se hayan creado, ejecutando una consulta simple select count(*) from proxies y obteniendo una respuesta de 0.

Posibles problemas y soluciones

• Problema: Error no such table. Razón: La inicialización no se ha realizado. Solución: Llama a init_db al iniciar la aplicación antes de todas las operaciones.
• Problema: Bloqueos de escritura. Razón: Transacciones simultáneas. Solución: Siempre que sea posible, agrupa los registros de resultados en batches o usa transacciones cortas.

Paso 5: Implementamos el bot de Telegram en aiogram 3

Objetivo de la etapa

Levantar un bot que reacciona a comandos, envía notificaciones a tu chat y lee configuraciones del .env. Configuraremos los comandos básicos: /start, /status, /chatid, /addproxy, /list, /enable, /disable, /interval, /export.

Instrucciones detalladas

1. Abre app/bot/handlers.py. Crea las rutas de los comandos. Para aiogram 3, usa Router, Dispatcher y manejadores asíncronos.
2. Implementa /start: responde con una breve descripción de las capacidades y el intervalo actual de verificaciones.
3. Implementa /chatid: envía el identificador del chat, para que puedas guardar TELEGRAM_CHAT_ID en el .env. Esto es útil si inicias el bot desde un chat personal o grupo.
4. Implementa /status: encuentra las últimas N verificaciones para cada proxy y muestra un resumen breve: estado, latencia, país, tiempo de actualización.
5. Implementa /list: lista los proxies con id, label, type, region, enabled.
6. Implementa /addproxy: pasa como parámetros type, endpoint, username, password, region, group, expected_country. En el primer paso, se puede hacer una versión simple que acepte una cadena en el formato type=http endpoint=host:port region=EU y analice los parámetros.
7. Implementa /enable y /disable con el parámetro id, para activar y desactivar rápidamente un proxy específico.
8. Implementa /interval N para cambiar el intervalo de verificación en minutos. Guarda el valor en la tabla settings.
9. Implementa /export para generar un CSV con las últimas verificaciones durante un período. Más adelante, añadiremos un botón similar en el web-dashboard.

Envío de notificaciones

En app/bot/notifications.py, crea la función notify_change, que formateará el mensaje sobre eventos. Un ejemplo de mensaje: Proxy: EU-1 (http) Región: EU Grupo: EUROPA Estado: DOWN Razón: timeout Última IP: 203.0.113.45 Esperado: país DE Recibido: país NL Hora: 2026-02-01 12:34:56 Latencia: n/a. Para UP usa la etiqueta UP, para degradaciones usa DEGRADED. Añade clasificación por importancia: primero DOWN, luego DEGRADED, después mensajes de cambio de IP. Añade indicadores de emoji para mayor claridad, como ✅ para UP y ⚠️ para DEGRADED y ❌ para DOWN. Si TELEGRAM_CHAT_ID no está configurado, envía al chat actual del que provino el comando. En producción, es mejor fixar el chat_id en el .env.

Consejo: Para grupos, el bot puede necesitar permisos para enviar mensajes. Verifica la configuración del grupo para que el bot sea un participante con derecho a escribir.

✅ Verificación: Ejecuta el bot localmente y envíale /chatid. Deberías recibir un identificador numérico. Configura TELEGRAM_CHAT_ID en el .env. Envía /start y /status. El bot debería responder. El comando /list puede estar vacío por ahora, lo cual es normal.

Posibles problemas y soluciones

• Problema: El bot no inicia. Razón: Token incorrecto. Solución: Verifica BOT_TOKEN en el .env, espacios adicionales y saltos de línea.
• Problema: Los comandos no se ejecutan. Razón: Router no está conectado. Solución: Asegúrate de que hayas añadido el router en Dispatcher y estés ejecutando polling.

Paso 6: Programador de verificaciones en APScheduler

Objetivo de la etapa

Configurar verificaciones periódicas de todos los proxies habilitados cada 5-15 minutos, teniendo en cuenta el intervalo actual de las configuraciones, paralelizar las verificaciones sin sobrecarga, registrar la historia y enviar alertas ante cambios.

Instrucciones detalladas

1. Abre app/scheduler.py. Inicializa AsyncIOScheduler.
2. Crea una tarea run_checks que selecciona de la base todos los proxies con enabled=1, enviándolos a verificar en un pool de tareas asíncronas con semáforo PROXY_CONCURRENCY, recogiendo resultados.
3. Para cada resultado, registra una fila en checks. Actualiza last_ip en proxies si hay cambio.
4. Lógica de incidentes: si el estado es DOWN y no hay ningún incidente, crea un registro en incidents (active=1). Si el estado vuelve a ser UP, cierra el incidente (active=0, closed_at=ts). Para DEGRADED análogamente, pero puedes combinar DEGRADED en un solo incidente activo o cerrarlo al recuperarse.
5. Envía notificaciones: al primer paso a DOWN, a DEGRADED, al recuperar UP, al cambiar IP o país. Agrupa mensajes si simultáneamente varios proxies cambian de estado: envía un encabezado y una lista de elementos.
6. Crea un job scheduler.add_job(run_checks, 'interval', minutes=CHECK_INTERVAL_MINUTES, id='checks', replace_existing=True). Añade reacción a /interval, para reiniciar el job con un nuevo intervalo sin reiniciar el bot.
7. Ejecuta scheduler.start() junto con el inicio del bot y el servidor web en main.

Consejo:

Consejo: Añade un jitter aleatorio de 0-60 segundos al horario, para reducir la carga máxima y evitar solicitudes sincronizadas exactas.

✅ Verificación: Establece CHECK_INTERVAL_MINUTES=1 temporalmente y ejecuta la aplicación. En los registros debes ver que las verificaciones se realizan cada minuto y se añaden nuevas filas a la tabla checks.

Posibles problemas y soluciones

• Problema: Las verificaciones no se inician. Razón: El scheduler no inicia. Solución: Asegúrate de que se llame a scheduler.start() y no haya excepciones al crear el job.
• Problema: Bloqueos en la base. Razón: Registros demasiado frecuentes. Solución: Reduce el intervalo o añade buffering de registros, escribiendo en batches.

Instrucciones paso a paso: Paso 7: Integra todas las partes en el punto de entrada main.py

Objetivo de la etapa

Reunir la aplicación completa: configuración, BD, bot, verificaciones, programador y dashboard web. Asegurar el arranque y parada correctos, y manejar las señales de terminado.

Instrucciones detalladas

1. Abre app/main.py. Importa asyncio, logging, uvloop (si es Linux), aiogram, funciones init_db, router, scheduler, servicio web.
2. Carga configuración del .env a través de python-dotenv. Verifica claves obligatorias: BOT_TOKEN y DB_PATH.
3. Inicializa la DB: await init_db(DB_PATH).
4. Crea Dispatcher y Router de aiogram 3, añade manejadores de comandos.
5. Crea el programador APScheduler y añade la tarea run_checks según el intervalo.
6. Ejecuta simultáneamente tres componentes: polling del bot, scheduler.start(), servidor web. Usa asyncio.gather para ejecución paralela.
7. Maneja señales SIGINT y SIGTERM: detén correctamente scheduler, cierra conexiones a la BD y finaliza polling.

La idea simplificada de arranque en una línea: import asyncio, logging; async def main(): await init_db(...); dp=Dispatcher(); dp.include_router(router); scheduler=AsyncIOScheduler(); scheduler.add_job(run_checks, 'interval', minutes=interval); scheduler.start(); await asyncio.gather(dp.start_polling(bot), start_web_server(), wait_for_signals(scheduler)); asyncio.run(main()).

Consejo: Añade registro detallado a nivel INFO y WARN. Esto ayudará a entender rápidamente qué sucede al inicio y durante las verificaciones.

✅ Verificación: Ejecuta python app/main.py. El bot debe responder a /start, el dashboard web debe abrirse en http://localhost:8080, y el scheduler debe iniciar verificaciones según el intervalo.

Posibles problemas y soluciones

• Problema: Dirección 0.0.0.0:8080 ocupada. Razón: El puerto está usando otro proceso. Solución: Cambia DASHBOARD_PORT en el .env o detén el proceso que lo ocupa.
• Problema: Error al iniciar polling. Razón: Token incorrecto o problemas de red. Solución: Verifica BOT_TOKEN y acceso a Internet.

Paso 8: Formato de notificaciones y agrupación de proxies

Objetivo de la etapa

Hacer que las notificaciones sean claras, compactas e informativas. Configurar agrupación de proxies por regiones y tipos, para que los mensajes sean estructurados.

Formato de notificaciones

• Título: Cambios en el estado de los proxies.
• Subtítulo: fecha y hora.
• Secciones por prioridad: DOWN, luego DEGRADED, luego Recuperación, luego Cambio de IP, luego Cambio de geo.
• Cada ítem: [Región] [Grupo] [Label] ([type]) estado, latencia, IP, país, razón.
• Íconos: DOWN marcamos ❌, DEGRADED — ⚠️, UP — ✅.

Agrupación de proxies

• Por el campo region: EU, US, ASIA y otros.
• Por el campo group_name: agrupación lógica, por ejemplo EUROPE, PAID, TESTING.
• Por tipo: http, https, socks5.

Implementación

1. En app/bot/notifications.py, crea funciones group_by_region y group_by_type para agrupar resultados antes del envío. Esto permitirá enviar menos mensajes y aumentar la legibilidad.
2. Para cada bloque, forma cadenas cortas con datos clave: "EU, EUROPE, EU-1 (http): ❌ DOWN, timeout" o "US, AMERICA, US-2 (socks5): ⚠️ DEGRADED, 2300ms, país US".
3. Si hay muchos cambios, envía un único encabezado de resumen y varios mensajes por regiones. Esto es mejor que 100 mensajes individuales.

✅ Verificación: Sustituye temporalmente un proxy por un endpoint infalible. Espera a la verificación. Recibirás una notificación con el bloque DOWN. Restaura el proxy a funcionamiento, y verás una notificación de recuperación.

Posibles problemas y soluciones

• Problema: Mensajes demasiado largos. Razón: Demasiados detalles. Solución: Reduce campos, para detalles usa el comando /status o /details id.
• Problema: Alertas duplicadas. Razón: Reenvío al persistir el estado. Solución: Envía notificación solo al cambiar estados y ante cambios evidentes de IP o país.

Paso 9: Despliegue en VPS (Ubuntu) y autoinicio

Objetivo de la etapa

Desplegar el bot en un servidor remoto, configurar el autoinicio a través de systemd, asegurar el registro y la actualización sencilla.

Preparación del VPS

1. Conéctate al VPS: ssh user@server_ip.
2. Actualiza el sistema: sudo apt update && sudo apt upgrade -y.
3. Instala Python, si no está instalado: sudo apt install -y python3.11 python3.11-venv python3-pip.
4. Crea un usuario para la aplicación, si es necesario: sudo adduser botuser; luego inicia sesión como él.
5. Copia el proyecto en el servidor usando scp o git clone de tu repositorio.
6. Crea un entorno virtual e instala dependencias como en el paso 2.
7. Verifica .env. Rellena valores reales para BOT_TOKEN y TELEGRAM_CHAT_ID.

Servicio systemd

1. Crea un archivo de servicio: sudo nano /etc/systemd/system/proxy-monitor.service.
2. Ejemplo de Unit (una línea): [Unit] Description=Proxy Monitor Bot After=network.target [Service] Type=simple User=botuser WorkingDirectory=/home/botuser/proxy-monitor-bot ExecStart=/home/botuser/proxy-monitor-bot/.venv/bin/python -m app.main Environment=PYTHONUNBUFFERED=1 Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target.
3. Reinicia el daemon: sudo systemctl daemon-reload.
4. Activa el autoinicio: sudo systemctl enable proxy-monitor.service.
5. Inicia: sudo systemctl start proxy-monitor.service.
6. Verifica el log: journalctl -u proxy-monitor.service -f.

Consejo: Si usas uvloop, asegúrate de que esté instalado en el entorno virtual. En Windows uvloop no se usa, en Linux mejora el rendimiento.

✅ Verificación: El bot responde a /start desde tu Telegram cuando el servicio está en ejecución. En el log se ve el inicio del programador y el web-dashboard escucha en el puerto 8080.

Posibles problemas y soluciones

• Problema: El servicio se detiene inmediatamente. Razón: Ruta incorrecta a Python o al directorio de trabajo. Solución: Verifica ExecStart y WorkingDirectory, derechos del usuario.
• Problema: Acceso al puerto 8080 bloqueado desde fuera. Razón: UFW o firewall en la nube. Solución: Abre el puerto: sudo ufw allow 8080 o configura reglas en el panel del proveedor.

Verificación del resultado

Checklist

• El bot acepta comandos /start, /status, /list, /chatid.
• El programador ejecuta verificaciones según el intervalo, las entradas aparecen en la tabla checks.
• Al caer un proxy, el bot envía una notificación a Telegram.
• El cambio de IP es registrado y se notifica en los mensajes.
• La geolocalización se determina y se compara con el país esperado.
• El dashboard se muestra en el puerto indicado, mostrando uptime y últimos eventos.
• La exportación CSV funciona y proporciona un archivo correcto.

Cómo probar

1. Desconecta uno de los proxies o especifica un puerto incorrecto. Espera la alerta DOWN.
2. Cambia temporalmente el endpoint por otro, para provocar un cambio de IP. Asegúrate de que el bot informe del cambio de IP y país, si este cambia.
3. Aumenta artificialmente la latencia mediante limitación de red (si es posible) o verifica con una solicitud pesada, para obtener DEGRADED.
4. Comprueba comandos: /interval 5, /list, /enable, /disable y asegúrate de que el estado se refleje correctamente.

Métricas de ejecución exitosa

• Verificaciones estables sin errores en los logs.
• Alertas informativas a tiempo ante problemas reales.
• Funcionamiento correcto de la lógica de incidentes: apertura en DOWN y cierre en UP.

✅ Verificación: Si todos los puntos de la checklist se cumplen y los escenarios de prueba funcionan, tu bot está desplegado exitosamente y realiza correctamente las tareas de monitoreo.

Errores comunes y soluciones

• Problema: No hay notificaciones en Telegram → Razón: TELEGRAM_CHAT_ID incorrecto o el bot no es miembro del grupo → Solución: Ejecuta /chatid en el chat correcto, guarda ID en .env, añade el bot al chat y dale permiso para escribir.
• Problema: Todos los proxies DOWN aunque estén funcionando → Razón: Formato incorrecto de la URL del proxy o tipo → Solución: Verifica type=http, https o socks5, verifica la autorización user:pass y el endpoint host:port, prueba un proxy individualmente.
• Problema: La geolocalización no se determina → Razón: Límite de ip-api o error de red → Solución: Activa el caché, reduce la frecuencia de solicitudes a ip-api, verifica IP_API_URL.
• Problema: La base crece demasiado rápido → Razón: Verificaciones muy frecuentes y muchos proxies → Solución: Aumenta el intervalo, habilita limpieza de registros antiguos, exporta archivos y elimina registros de más de 30-90 días.
• Problema: Alta latencia en todos los proxies → Razón: El servidor está sobrecargado o hay problemas de red → Solución: Aumenta los recursos del VPS, reduce PROXY_CONCURRENCY, usa una región más cercana.
• Problema: Alertas duplicadas del mismo incidente → Razón: No se guarda el estado del incidente → Solución: Utiliza la tabla incidents y envía la alerta solo al cambiar el estado.
• Problema: El bot se detiene frecuentemente por excepciones → Razón: Errores no capturados → Solución: Envuelve operaciones de red en try-except, añade registro y reintentos.

Funcionalidades adicionales

Configuraciones avanzadas

• Umbrales de degradación flexibles: guarda los umbrales de latencia por grupos en la tabla settings.
• Diversos intervalos por grupos: verifica proxies importantes cada 5 minutos, secundarios cada 15-30.
• Parseo de comandos avanzado: usa el formato key=value y valida estrictamente parámetros.

Optimización

• Habilita uvloop en Linux para acelerar el ciclo de eventos.
• Usa registros por lotes en SQLite o el modo WAL para acelerar las escrituras concurrentes.
• Parametriza semáforos para equilibrar entre velocidad y carga.

Dashboard simple

En app/web/server.py, levanta un servidor aiohttp.web. En la página principal, muestra un resumen: cantidad de proxies, cuántos UP, DOWN, DEGRADED, latencia media, uptime en 24 horas. Crea un endpoint /export?from=ts&to=ts para exportar en CSV. El HTML mínimo puede ser una lista simple y una tabla con el estado. La visualización gráfica se podrá añadir más adelante mediante simples SVG.

Consejo: Añade un botón para Cambiar intervalo directamente en el dashboard que llame al endpoint y cambie el valor en settings. Esto agilizará la gestión sin comandos de Telegram.

Copias de seguridad

Script para hacer copias de seguridad de la base: tar -czf backup-$(date +%F).tar.gz data/monitor.db. Programa copias de seguridad diarias a través de cron o timers de systemd. Mantén al menos los últimos 7 archivos.

⚠️ Atención: No edites el archivo de la base en vivo. Para ediciones manuales, detén el servicio, haz una copia, edita y vuelve a iniciar.

FAQ

• ¿Cómo agregar un proxy con autorización? En el comando /addproxy indica username y password, o añade user:pass en el endpoint. Ejemplo: type=http endpoint=user:pass@host:port.
• ¿Cómo limitar las verificaciones de noche? Implementa un horario tipo cron en APScheduler, añadiendo un trigger con un intervalo, o simplemente aumenta el intervalo durante la noche mediante una regla automática.
• ¿Qué hacer si ip-api.com no está disponible? Usa el caché y saltea temporalmente las solicitudes de geo. Más adelante se puede agregar una fuente alternativa de geo.
• ¿Cómo filtrar notificaciones? Añade niveles de importancia y configuración: envía solo DOWN, y los DEGRADED envíalos agrupados una vez por hora.
• ¿Se puede usar PostgreSQL? Sí. Reemplaza aiosqlite con asyncpg, adapta SQL y la conexión. Para grandes volúmenes, esto es más conveniente.
• ¿Cómo almacenar tokens de manera segura? En .env en el servidor con derechos 600. Actualiza periódicamente el token si es necesario.
• ¿Por qué el bot a veces obtiene timeout? Las redes son inestables. Aumenta PROBE_TIMEOUT, reduce paralelismo, verifica rutas.
• ¿Se pueden verificar proxies IPv6? Sí, si los servicios destinados soportan IPv6. Verifica que el endpoint devuelve IPv6 y que ip-api maneja correctamente la dirección.
• ¿Cómo rastrear un operador de comunicación específico? En el mensaje guarda org de ip-api y compáralo con el valor esperado según la regla.
• ¿Cómo desactivar un proxy temporalmente? Usa /disable id, para excluir temporalmente el proxy de las verificaciones sin eliminarlo de la base.

Conclusión

Has recorrido el camino completo desde la idea hasta una solución funcional: creaste un bot de Telegram en aiogram 3, escribiste un módulo de verificación de proxies en aiohttp, configuraste el programador APScheduler, almacenaste el historial en SQLite, implementaste notificaciones de caídas, degradaciones, cambios de IP y geolocalización, desplegaste la aplicación en un VPS con autoinicio a través de systemd, y añadiste un simple web-dashboard con exportación de logs. Ahora tienes una herramienta flexible que puedes escalar: dividir grupos, ajustar umbrales, conectar gráficos e informes, migrar a PostgreSQL al aumentar la carga. El siguiente paso es automatizar el mantenimiento: configuraciones de rotación de logs, copias diarias de la base, monitoreo del propio bot a través de métricas del sistema. Puedes avanzar más: añadir un modelo de rol de acceso a los comandos del bot, implementar informes SLA por grupos, conectar fuentes alternativas de datos geográficos, crear una interfaz web en la biblioteca que prefieras. ¡Buena suerte y un uptime estable para tus proxies!