Skip to content

README_ESPANOL.md

Latest commit

 

History

History
451 lines (335 loc) · 11.8 KB

README_ESPANOL.md

File metadata and controls

451 lines (335 loc) · 11.8 KB

🤖 WGDashboard Erinys (Telegram Bot)

Bot profesional de Telegram para administrar y consultar WireGuard mediante la API de WGDashboard. Permite a administradores gestionar peers, monitorear estado del servidor y ejecutar acciones administrativas directamente desde Telegram.

✨ Características principales

Administradores

  • 📡 Gestión de Configuraciones: Ver todas las configuraciones WireGuard
  • 👥 Gestión de Peers: Crear, eliminar, ver detalles y monitorear peers
  • 🔒 Restricciones: Restringir/permitir acceso de peers específicos
  • 🧹 Limpiar Tráfico: Resetear contadores de datos de peers
  • ⏰ Schedule Jobs: Crear trabajos programados (límites de datos y fechas de expiración)
  • 🖥️ Estado del Sistema: Monitorear CPU, memoria, discos e interfaces
  • 📊 Estadísticas: Ver información detallada del sistema
  • 👷 Supervisión de Operadores: Ver actividad de operadores autorizados
  • 🌐 Multiidioma: Soporte para español e inglés

Operadores

  • ➕ Crear Peers Temporales: Generar peers con límites automáticos
  • 📥 Descargar Config: Obtener archivo .conf para el nuevo peer
  • 🌐 Cambiar Idioma: Seleccionar entre español e inglés
  • ⏳ Límites Automáticos: 1 GB de datos y 24 horas de duración por peer

📁 Estructura del proyecto

TGBot-saveOK/
├── main.py                    # Punto de entrada del bot
├── config.py                  # Configuración y variables de entorno
├── handlers.py                # Handlers de comandos y callbacks (4100+ líneas)
├── keyboards.py               # Teclados inline de Telegram
├── i18n.py                    # Sistema de traducción multiidioma
├── operators.py               # Control de operadores autorizados
├── utils.py                   # Funciones utilitarias
├── wg_api.py                  # Cliente de la API WGDashboard
├── setup_logging.py           # Configuración de logs
├── .env                       # Variables de entorno (NO subir a git)
├── requirements.txt           # Dependencias del proyecto
├── README.md                  # Este archivo
├── locales/
│   ├── es.json                # Traducción al español
│   └── en.json                # Traducción al inglés
└── info/
    ├── resumen.md             # Documentación técnica
    ├── CAMBIOS_REALIZADOS.md  # Historial de cambios
    └── IMPLEMENTACION_*.md    # Documentación de features

🛠️ Requisitos previos

Sistema operativo

  • Linux (Ubuntu 20.04 LTS o superior recomendado)
  • Python 3.10 o superior
  • pip (Python Package Manager)

Dependencias externas

  • WireGuard: Instalado y configurado en el servidor
  • WGDashboard: Funcionando y accesible via API
  • Bot de Telegram: Creado con @BotFather

📦 Instalación paso a paso

1. Clonar o descargar el proyecto

git clone https://github.com/WGDashboard/WGErinys
cd WGErinys

2. Crear entorno virtual (recomendado)

python3 -m venv .venv
source .venv/bin/activate  # En Windows: .venv\Scripts\activate

3. Instalar dependencias

pip install -r requirements.txt

4. Configurar variables de entorno

Crear archivo .env en la raíz del proyecto:

# ===== TELEGRAM =====
TELEGRAM_BOT_TOKEN=tu_token_aqui  # Obtener de @BotFather en Telegram

# ===== WGDASHBOARD API =====
WG_API_BASE_URL=https://tu-dominio.com/api  # URL base de la API
WG_API_KEY=tu_api_key_aqui                   # API Key de WGDashboard
WG_API_PREFIX=wg                             # Prefijo de la API (si aplica)
API_TIMEOUT=10                               # Timeout en segundos

# ===== LOGGING =====
LOG_FILE=wg_bot.log                          # Archivo de logs
LOG_LEVEL=INFO                               # DEBUG, INFO, WARNING, ERROR

# ===== ACCESO =====
ALLOWED_USERS=123456789,987654321            # IDs de Telegram autorizados
ROLE_ADMIN=admin                             # Rol de administrador
ROLE_OPERATOR=operator                       # Rol de operador
ADMIN_IDS=123456789                          # IDs que son administradores
OPERATOR_IDS=987654321,111222333             # IDs que son operadores

# ===== LÍMITES DE OPERADOR =====
OPERATOR_DATA_LIMIT_GB=1                     # GB por peer creado
OPERATOR_TIME_LIMIT_HOURS=24                 # Horas de duración del peer

5. Configurar usuarios autorizados

Editar config.py y agregar los IDs de Telegram:

# IDs autorizados a usar el bot
ALLOWED_USERS = [
    123456789,  # Admin 1
    987654321,  # Admin 2
    111222333,  # Operador 1
]

# Configuración de roles
ADMIN_USERS = [123456789, 987654321]
OPERATOR_USERS = [111222333]

# Límites para operadores
OPERATOR_DATA_LIMIT_GB = 1          # 1 GB por peer
OPERATOR_TIME_LIMIT_HOURS = 24      # 24 horas de duración

Para obtener tu ID de Telegram:

  1. Abre @userinfobot en Telegram
  2. El bot te mostrará tu ID

🚀 Ejecutar el bot

Desarrollo local

# Con el entorno virtual activado
python main.py

Producción en VPS

Opción 1: Usando systemd (recomendado)

Crear archivo de servicio:

sudo nano /etc/systemd/system/wgbot.service

Contenido del archivo:

[Unit]
Description=WGDashboard Telegram Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=wgbot
Group=wgbot
WorkingDirectory=/home/wgbot/TGBot-saveOK
Environment="PATH=/home/wgbot/TGBot-saveOK/.venv/bin"
ExecStart=/home/wgbot/TGBot-saveOK/.venv/bin/python main.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Habilitar e iniciar el servicio:

# Recargar systemd
sudo systemctl daemon-reload

# Habilitar para que inicie automáticamente
sudo systemctl enable wgbot

# Iniciar el bot
sudo systemctl start wgbot

# Ver estado
sudo systemctl status wgbot

# Ver logs en tiempo real
sudo journalctl -u wgbot -f

# Detener
sudo systemctl stop wgbot

# Reiniciar
sudo systemctl restart wgbot

Opción 2: Usando Docker (si está disponible)

# Construir imagen
docker build . -f docker/Dockerfile -t wgerinys:latest

# Ejecutar contenedor
docker run -d --name wgerinys --env-file .env wgerinys:latest

Opción 3: Usando tmux (simple)

# Instalar tmux
sudo apt-get install tmux

# Crear sesión
tmux new-session -d -s wgbot -c /ruta/al/bot python main.py

# Ver sesión
tmux list-sessions

# Conectar a sesión
tmux attach-session -t wgbot

# Desconectar (Ctrl+b, luego d)

📋 Comandos disponibles

Para Administradores

Comando Descripción
/start Inicia el bot y muestra menú principal
/help Muestra ayuda y comandos disponibles
/stats Muestra estadísticas del sistema
/configs Lista todas las configuraciones WireGuard

Funciones via menú:

  • 📡 Configuraciones - Gestionar todas las configs
  • 👥 Peers - Ver, crear, eliminar, listar
  • 🖥️ Estado del Sistema - CPU, RAM, discos, network
  • ⚡ Protocolos - Ver protocolos habilitados
  • 👷 Operadores - Ver actividad de operadores
  • 🌐 Idioma - Cambiar entre español e inglés

Para Operadores

Comando Descripción
/start Muestra menú para crear peers
/help Información sobre límites y funciones

Funciones:

  • ➕ Crear Peer - Generar nuevo peer temporal
  • 📥 Descargar - Obtener archivo de configuración
  • 🌐 Idioma - Cambiar idioma

🔐 Seguridad y control de acceso

Niveles de permisos

Administrador (acceso completo)

  • Todas las funciones del bot
  • Gestión total de peers
  • Acceso a estadísticas
  • Supervisión de operadores

Operador (acceso limitado)

  • Solo crear peers temporales
  • Descargar configuración de peers creados
  • Sin acceso a gestión de peers existentes

No autorizado (sin acceso)

  • El bot rechaza cualquier comando
  • Mensaje de error: "Acceso restringido"

Mejores prácticas de seguridad

  1. API Key de WGDashboard

    • Usar en variables de entorno .env
    • Nunca subir .env a git
    • Agregar a .gitignore

  2. Token del Bot de Telegram

    • Mantener en .env
    • Cambiar si se expone
    • Usar restricciones de webhook si es posible

  3. Acceso al servidor

    • Firewall activo
    • SSH con claves públicas
    • Cambiar puerto SSH por defecto
    • Monitorear logs regularmente

  4. WGDashboard

    • Detrás de proxy reverso (nginx)
    • HTTPS obligatorio
    • Autenticación fuerte
    • Backups regulares

📊 Funcionalidades detalladas

Gestión de Peers

Crear Peer

  • Nombre único
  • IP automática
  • Claves WireGuard generadas
  • Archivo .conf enviado directamente
  • Límites automáticos aplicados

Detalles de Peer

  • Información de red (IP, endpoint, DNS)
  • Estado de conexión (conectado/desconectado)
  • Tráfico (enviado, recibido, acumulativo)
  • Claves (pública, pre-shared)
  • Trabajos programados
  • Enlaces compartidos

Restricciones

  • Restringir peer (bloquea conexión)
  • Permitir access (quita restricción)
  • Visualización por página
  • Filtros disponibles

Schedule Jobs

Los trabajos programados permiten:

  • Límite de datos: Restringir cuando alcanza X GB
  • Fecha de expiración: Restringir automáticamente en fecha X
  • Crear/eliminar jobs sobre la marcha
  • Gestión completa de tareas

Estadísticas del Sistema

Monitorea en tiempo real:

  • 💻 Uso de CPU (%)
  • 🧠 Uso de RAM (% y detalles)
  • 💾 Uso de discos (principales)
  • 📡 Interfaces de red (tráfico)
  • 🔗 Interfaces WireGuard

🌐 Multiidioma

El bot soporta automáticamente:

  • 🇪🇸 Español - Interfaz completa en español
  • 🇬🇧 Inglés - Interfaz completa en inglés

Los usuarios pueden cambiar el idioma desde el menú en cualquier momento. Las preferencias se guardan automáticamente.

📝 Logs y debugging

Ver logs en tiempo real

# Si usas systemd
sudo journalctl -u wgbot -f

# Si ejecutas directamente
tail -f wg_bot.log

Niveles de log

DEBUG   - Información detallada para debugging
INFO    - Eventos importantes
WARNING - Advertencias (problemas potenciales)
ERROR   - Errores que afectan funcionamiento

Configurar nivel de log

Editar .env:

LOG_LEVEL=DEBUG  # Para más detalle en desarrollo

🆘 Troubleshooting

El bot no responde

# Verificar que está corriendo
sudo systemctl status wgbot

# Ver logs
sudo journalctl -u wgbot -n 50

# Reiniciar
sudo systemctl restart wgbot

Error: "No se puede conectar a API"

  • Verificar WG_API_BASE_URL en .env
  • Verificar WG_API_KEY es correcta
  • Probar conectividad: curl https://tu-url/api/handshake
  • Verificar firewall/proxy permite la conexión

Error: "Token de Telegram inválido"

  • Verificar TELEGRAM_BOT_TOKEN en .env
  • Crear nuevo token con @BotFather
  • Verificar no hay espacios en blanco

El bot no ve mis cambios

# Reiniciar para cargar cambios
sudo systemctl restart wgbot

# O si usas tmux
tmux send-keys -t wgbot "C-c"
python main.py

📚 Documentación adicional

  • info/resumen.md - Análisis técnico de la API
  • info/CAMBIOS_REALIZADOS.md - Historial de cambios
  • info/IMPLEMENTACION_*.md - Detalles de features

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

  1. Fork del proyecto
  2. Crear rama para tu feature (git checkout -b feature/AmazingFeature)
  3. Commit cambios (git commit -m 'Add AmazingFeature')
  4. Push a rama (git push origin feature/AmazingFeature)
  5. Abrir Pull Request

👨‍💻 Autor

Jorge Elián Martinez Perdomo

Bot profesional de Telegram para administración de WireGuard usando WGDashboard