📘 Manual de Operaciones y Migración: tg-ytdlp-bot + Cloudflare WARP

Autor: Jonatan

Rol / Enfoque: Ingeniería de Sistemas (Senior IT) Entorno: Synology / Xpenology (Container Manager & Docker CLI) Propósito: Documentación estandarizada para la configuración, migración y puesta en marcha del bot de descargas con proxy SOCKS5 indetectable.

---

🛠️ 1. Archivos de Configuración del Bot

Antes de levantar el proyecto en un entorno nuevo, es necesario configurar las credenciales de Telegram y los parámetros del bot. Los datos de conexión se establecen en el directorio raíz del proyecto (/volume2/docker/tg-ytdlp-bot/).

• El archivo .env: Aquí se definen las variables de entorno principales (BOT\\\_TOKEN, API\\\_ID, API\\\_HASH).
• Archivos Python (config.py): Configuración de directorios de descarga y permisos de administrador.

🛡️ \*\*Plan de Backup (Rollback):\*\* Antes de editar cualquier configuración en producción, realiza siempre una copia de seguridad en frío:

cp .env .env.bak
cp config.py config.py.bak

🐳 1.1. Arquitectura Base (docker-compose.yml)

Este es el manifiesto de infraestructura como código (IaC) definitivo. Define el enrutamiento interno aislando el tráfico del bot hacia el proxy SOCKS5 (puerto 1080), puenteando el túnel de WARP hacia el puerto 40000.

version: '3.8'

services:
  bot:
    container\\\_name: tg-ytdlp-bot
    image: tg-ytdlp-bot:latest
    env\\\_file:
      - .env
    # Forzamos al bot a salir por el proxy de Warp
    environment:
      - ALL\\\_PROXY=socks5://tg-ytdlp-warp:1080
      - HTTP\\\_PROXY=socks5://tg-ytdlp-warp:1080
      - HTTPS\\\_PROXY=socks5://tg-ytdlp-warp:1080
    restart: unless-stopped
    depends\\\_on:
      bgutil-provider:
        condition: service\\\_started
      warp:
        condition: service\\\_started
    volumes:
      - /volume2/docker/tg-ytdlp-bot:/app
    working\\\_dir: /app

  dashboard:
    container\\\_name: tg-ytdlp-dashboard
    image: tg-ytdlp-bot:latest  # Usa la misma imagen del bot
    env\\\_file:
      - .env
    restart: unless-stopped
    depends\\\_on:
      - bot
    volumes:
      - /volume2/docker/tg-ytdlp-bot:/app
      - /var/run/docker.sock:/var/run/docker.sock
    working\\\_dir: /app
    command: \\\["python", "-m", "uvicorn", "web.dashboard\\\_app:app", "--host", "0.0.0.0", "--port", "5555"]
    ports:
      - "5555:5555"

  bgutil-provider:
    image: brainicism/bgutil-ytdlp-pot-provider:latest
    container\\\_name: tg-ytdlp-bgutil-provider
    restart: unless-stopped
    # El proveedor también debe pasar por el proxy
    environment:
      - ALL\\\_PROXY=socks5://tg-ytdlp-warp:1080
      - HTTP\\\_PROXY=socks5://tg-ytdlp-warp:1080
      - HTTPS\\\_PROXY=socks5://tg-ytdlp-warp:1080
    depends\\\_on:
      warp:
        condition: service\\\_started

  warp:
    image: caomingjun/warp
    container\\\_name: tg-ytdlp-warp
    restart: unless-stopped
    # Permisos específicos requeridos por el cliente oficial
    device\\\_cgroup\\\_rules:
      - 'c 10:200 rwm'
    cap\\\_add:
      - NET\\\_ADMIN
    environment:
      - WARP\\\_SLEEP=2
      - GOST\\\_ARGS=-L :1080 -F=127.0.0.1:40000
    sysctls:
      net.ipv6.conf.all.disable\\\_ipv6: 0
      net.ipv4.conf.all.src\\\_valid\\\_mark: 1
    volumes:
      - /volume2/docker/tg-ytdlp-bot/warp-cli-data:/var/lib/cloudflare-warp

---

🔄 2. Procedimiento de Migración (De Desarrollo a Producción)

Para evitar errores de dependencias (como pull access denied en Container Manager), migraremos la imagen compilada localmente de forma manual.

🛡️ \*\*Plan de Rollback:\*\* Si el despliegue en Producción falla catastróficamente, simplemente ejecuta sudo docker-compose down, elimina la carpeta /volume2/docker/tg-ytdlp-bot en el NAS destino y el entorno de Desarrollo seguirá intacto y funcional.

📦 2.1. Empaquetar la imagen local (En NAS Origen)

Exportamos la imagen compilada a un archivo comprimido (.tar):

sudo docker save -o /volume2/docker/tg-ytdlp-bot/bot\\\_imagen.tar tg-ytdlp-bot:latest

📂 2.2. Transferencia de Archivos

Copia el directorio completo /volume2/docker/tg-ytdlp-bot (que ahora incluye el archivo .tar) desde el NAS de Origen al de Destino.

📥 2.3. Importar la imagen (En NAS Destino)

Inyecta la imagen directamente en el motor de Docker local del servidor de Producción:

sudo docker load -i /volume2/docker/tg-ytdlp-bot/bot\\\_imagen.tar

---

🧹 3. Preparación de la Red (Limpieza de WARP)

⚠️ \*\*¡CRÍTICO! Análisis de Riesgo:\*\* Levantar el contenedor de WARP copiando los datos del entorno anterior generará una colisión de llaves criptográficas (mismo ID de dispositivo, distinta IP física), lo que resultará en un bloqueo por parte de Cloudflare.

🗑️ 3.1. Vaciar la identidad criptográfica

Fuerza al cliente a generar una nueva identidad borrando la caché clonada. Este paso no afecta a los datos del bot, solo a la red:

sudo rm -rf /volume2/docker/tg-ytdlp-bot/warp-cli-data/\\\*

(También realizable vía File Station eliminando el contenido de dicha carpeta de forma manual).

---

🌐 4. Despliegue y Aprovisionamiento del Túnel

🚀 4.1. Levantar la infraestructura

Ejecuta el stack completo. Al estar vacía la carpeta de WARP, el demonio se iniciará en modo "fábrica":

cd /volume2/docker/tg-ytdlp-bot
sudo docker-compose up -d

🛡️ 4.2. Configurar Cloudflare WARP en Modo Proxy

Dado que el NAS utiliza iptables y WARP requiere nftables, evitamos el conflicto en el Kernel inyectando la configuración en modo Aplicación (Proxy SOCKS5).

Ejecuta estos 3 comandos estrictamente en este orden:

# 1. Modo Proxy (Deshabilita el túnel global invasivo del kernel)
sudo docker exec tg-ytdlp-warp warp-cli mode proxy

# 2. Asignar el puerto de enlace interno (GOST bridge)
sudo docker exec tg-ytdlp-warp warp-cli proxy port 40000

# 3. Negociar llaves criptográficas y establecer conexión
sudo docker exec tg-ytdlp-warp warp-cli connect

---

✅ 5. Auditoría y Comprobaciones Finales

📡 5.1. Comprobación 1: Estado del Cliente WARP

Verifica que el demonio está corriendo sin restricciones:

sudo docker exec tg-ytdlp-warp warp-cli status

• Resultado esperado: Status update: Connected y Network: healthy.

🕵️‍♂️ 5.2. Comprobación 2: Test de Fuga de Tráfico (Leak Test)

Simula una traza HTTP desde dentro del contenedor del bot forzando la salida por el proxy configurado para asegurar el enmascaramiento de IP.

sudo docker exec tg-ytdlp-bot curl -s -x socks5://tg-ytdlp-warp:1080 \\\[https://www.cloudflare.com/cdn-cgi/trace](https://www.cloudflare.com/cdn-cgi/trace) | grep warp

• Resultado esperado: warp=on o warp=plus.
• (Si aparece warp=off, la IP pública está expuesta. Aplica sudo docker-compose stop inmediatamente y revisa la configuración).

---

🚑 6. Troubleshooting (Resolución de Problemas)

🔴 Síntoma 1: Error pull access denied al hacer docker-compose up

• Diagnóstico: Docker no encuentra la imagen del bot en Docker Hub (porque no es pública) y tampoco la encuentra en el almacenamiento local del NAS.
• Solución: Has omitido la importación manual. Vuelve y ejecuta el Paso 2.3: sudo docker load -i bot\\\_imagen.tar.

🔴 Síntoma 2: warp-cli status devuelve "Disconnected (Manual)"

• Diagnóstico: El demonio WARP se ha protegido cerrando el túnel de emergencia. Esto ocurre por corrupción de los archivos de identidad local o por colisión de dispositivo en la red de Cloudflare.

• Solución (Reset de identidad / Rollback):

  1. Detén el túnel: sudo docker-compose stop warp
  2. Purga la base de datos: sudo rm -rf warp-cli-data/\\\*
  3. Arranca en limpio: sudo docker-compose start warp
  4. Vuelve a ejecutar los 3 comandos del Paso 4.2 para reconfigurar el proxy.

🔴 Síntoma 3: El Bot de Telegram no responde a los comandos

• Diagnóstico: El contenedor del bot ha arrancado más rápido que el proxy de WARP (condición de carrera), o la conexión de la API de Telegram se ha quedado en un limbo de tiempo de espera (Timeout).

• Solución:

  1. Revisa los logs para confirmar: sudo docker logs tg-ytdlp-bot --tail 30.
  2. Si observas errores del tipo Network is unreachable o Timeout, simplemente reinicia el bot para que vuelva a engancharse al proxy ya establecido: sudo docker restart tg-ytdlp-bot.

🔴 Síntoma 4: El test curl devuelve "Connection refused"

• Diagnóstico: El puerto 1080 no está abierto. El binario GOST (el motor del proxy SOCKS5) dentro del contenedor warp no ha podido inicializarse correctamente.
• Solución: Verifica que tu docker-compose.yml tiene la variable de entorno GOST\\\_ARGS escrita exactamente como en la Sección 1.1 (respetando los espacios), y fuerza a Docker a recrear el contenedor de forma controlada: sudo docker-compose up -d --force-recreate warp.

🔴 Síntoma 5: Error "Unable to download API page" + "[Errno -2] Name or service not known"

* Diagnóstico: Fuga de DNS y desconexión del túnel SOCKS5. El bot está intentando usar un proxy que no responde y no puede resolver nombres de dominio.

* Solución:

1. Ejecuta el Reset de identidad completo de la **Sección 6.2** (detener, purgar warp-cli-data/\* y arrancar).

2. Re-aprovisiona los 3 comandos mágicos de red (**Sección 4.2**).

3. Reinicia el bot para vaciar su caché DNS interna: sudo docker restart tg-ytdlp-bot.

4. Sella la fuga de IP lanzando el test final de la **Sección 5.2**.