Administración del servidor¶

Esta página describe configuraciones de red para restringir el acceso, conectarse a un servicio Demucs remoto, enrutar descargas mediante un proxy y supervisar la aplicación.

Contenido¶

Restringir el acceso de usuarios de Wi-Fi para invitados
Exponer un servicio Demucs remoto
Usar un servidor proxy para las descargas
Supervisión del servidor

Restringir el acceso de usuarios de Wi-Fi para invitados¶

La aplicación está pensada para ejecutarse en una red local. De forma predeterminada, cualquiera conectado a esa red puede acceder a ella. En vez de conectar a los invitados a la misma LAN que los ordenadores personales, la mayoría de los routers domésticos, incluidos los proporcionados por ISP, pueden crear una red Wi-Fi de invitados aislada.

La Wi-Fi de invitados también puede ayudar a restringir el acceso a la aplicación de karaoke. Los invitados acceden mediante la dirección expuesta a Internet, mientras que el proxy inverso permite únicamente solicitudes procedentes de la red doméstica.

Requiere una IP pública y NAT hairpin

Si el router no admite NAT hairpin, o el ISP usa CGNAT, utiliza una de las alternativas de acceso remoto.

Cómo funciona esta configuración¶

Dirige un registro DNS a la IP pública de la red doméstica.
Configura un proxy inverso para permitir solicitudes desde la subred doméstica y denegar otras direcciones IP.
Conecta los dispositivos de invitados a la red Wi-Fi de invitados aislada.

Con NAT hairpin, una solicitud desde la Wi-Fi de invitados a la dirección DNS pública se envía a través del router o puerta de enlace y vuelve a la red doméstica. Desde el punto de vista del proxy inverso, la solicitud procede del router, que está incluido en la lista de permitidos. Las solicitudes de usuarios aleatorios de Internet se deniegan.

Esto proporciona un sólido límite de acceso para una instalación doméstica de karaoke, porque los invitados deben estar físicamente presentes en la red aprobada para acceder a la aplicación.

Configura la página de acceso restringido¶

La aplicación incluye una página /access-restricted que puede mostrar un mensaje a los usuarios denegados. También puedes configurar el proxy inverso para mostrar una página personalizada.

Página de acceso denegado

La configuración general del proxy inverso debe:

Permitir la subred doméstica y denegar todas las demás direcciones IP.
Reenviar el tráfico permitido a la dirección IP y el puerto de la aplicación de karaoke.
Permitir explícitamente todas las solicitudes a /access-restricted y reenviar esa ruta a la aplicación.
Redirigir las respuestas 403 generadas por el proxy inverso a /access-restricted.

Por ejemplo, en Nginx Proxy Manager, crea una Access List, añade la subred doméstica, como 192.168.0.0/24, permítela, deniega las demás direcciones y aplica la lista al host proxy.

Configuración Nginx personalizada de Nginx Proxy Manager

location /access-restricted {
    allow all;
    proxy_pass http://<your-application-ip>:<your-application-port>;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

error_page 403 = @handle_403;

location @handle_403 {
    # Replace with your destination URL or path.
    return 302 https://<your-karaoke-domain>/access-restricted;
}

Dirección del cliente detrás de un proxy inverso¶

Uvicorn solo usa X-Forwarded-For y X-Forwarded-Proto cuando confía en el par conectado directamente. Define FORWARDED_ALLOW_IPS con la dirección IP del proxy tal como la ve la aplicación, o con un rango CIDR que contenga únicamente proxies de confianza. El valor predeterminado es 127.0.0.1, que normalmente no coincide con un proxy de Docker o remoto. Uvicorn no usa X-Real-IP. En Docker Compose, añade el ajuste al archivo .env de la aplicación; para iniciar localmente, expórtalo o pásalo a Uvicorn mediante --forwarded-allow-ips. Consulta la referencia de variables de entorno. Mantén privado el puerto de la aplicación o restríngelo al proxy, y nunca uses * si clientes no confiables pueden acceder directamente a la aplicación.

Configuración de Caddy

Sustituye el nombre de host, la dirección de la aplicación y la subred doméstica por tus propios valores. Este ejemplo permite /access-restricted a todo el mundo, permite el resto de la aplicación solo desde la subred doméstica y redirige a los demás clientes a la página de acceso restringido.

your-karaoke-domain.example {
    route {
        @access_restricted path /access-restricted*
        handle @access_restricted {
            reverse_proxy http://<your-application-ip>:<your-application-port>
        }

        @outside_home not remote_ip 192.168.0.0/24
        handle @outside_home {
            redir /access-restricted 302
        }

        handle {
            reverse_proxy http://<your-application-ip>:<your-application-port>
        }
    }
}

El comparador remote_ip verifica la dirección de origen que ve Caddy. Si hay otro proxy o túnel delante de Caddy, configura proxies de confianza y confirma que se conserva la dirección del cliente antes de depender de esta lista de permitidos.

Esta configuración bloquea todas las direcciones IP fuera de la subred doméstica. Las solicitudes denegadas reciben una respuesta 403 y se redirigen a /access-restricted, que sigue disponible para todos.

CGNAT y otras alternativas de red¶

La configuración anterior requiere tanto NAT hairpin como una dirección IP pública. Si el ISP usa CGNAT, utiliza un VPS gratuito, Tailscale Funnel o Cloudflare Tunnel para gestionar el proxy inverso y el control de acceso. También puedes tener que actualizar la lista de permitidos del proxy cuando cambie tu IP WAN.

Exponer un servicio Demucs remoto¶

Puedes usar el ordenador de un amigo con GPU para ejecutar el servicio Demucs, o compartir tu propia GPU con esa persona. La aplicación de karaoke debe poder conectarse al servicio Demucs remoto; Cloudflare Tunnel y Tailscale son dos formas posibles de proporcionar esa conexión.

El rendimiento depende en gran medida de ambas conexiones a Internet. El procesamiento puede ser más lento si una conexión Tailscale se retransmite. Usa la página de prueba de velocidad /transfer de Demucs para comprobar el rendimiento de carga y descarga y ajusta el límite de contenido directo para separación según corresponda.

Prueba de velocidad de Demucs

Cloudflare Tunnel¶

Protege los servicios Demucs expuestos públicamente

Se recomienda encarecidamente una clave de API cuando el servicio Demucs se expone a Internet. Configura la misma clave en el servicio Demucs y la aplicación Karaoke, y prueba la conexión con Check Demucs.

Cloudflare Tunnel se puede usar sin registrar un dominio cuando basta un nombre de host temporal aleatorio. Usar tu propio dominio requiere un dominio gestionado por Cloudflare y configuración adicional del túnel; consulta Cloudflare Tunnel with Docker from Homelab Haven.

Instalar `cloudflared`¶

Consulta la página oficial de descargas de Cloudflare para los paquetes y binarios más recientes. Los ejemplos siguientes instalan el conector; aún debes crear un túnel con nombre y configurar su nombre de host y origen en Cloudflare.

WindowsmacOSLinuxDocker

Descarga el MSI de 64 bits o el ejecutable desde la página de descargas de Cloudflare.
Si descargaste el ejecutable, cámbiale el nombre a cloudflared.exe y colócalo en un directorio de tu PATH, como C:\Cloudflared\bin.
Abre PowerShell y verifica la instalación:
```
cloudflared.exe --version
```

Las instalaciones de Windows no se actualizan automáticamente. Descarga manualmente una versión más reciente cuando sea necesario.

Instala con Homebrew:

brew install cloudflared
cloudflared --version

Para instalar el conector como servicio de macOS después de crear un túnel con nombre, usa cloudflared service install para un agente de inicio de sesión o sudo cloudflared service install para un daemon de lanzamiento.

En Debian o Ubuntu, instala desde el repositorio de paquetes de Cloudflare:

sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg \
  | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main" \
  | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt-get update
sudo apt-get install cloudflared
cloudflared --version

Para distribuciones basadas en RPM, Arch Linux o descargas directas de binarios, usa las instrucciones oficiales de descarga. Después de crear un túnel con nombre, instala el servicio systemd con sudo cloudflared service install.

Descarga la imagen oficial y verifícala:

docker pull cloudflare/cloudflared:latest
docker run --rm cloudflare/cloudflared:latest version

Para un túnel administrado remotamente, copia el comando de instalación del panel de Cloudflare. Un ejemplo de Compose basado en token es:

services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: unless-stopped
    command: tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}

Crear y ejecutar el túnel¶

En el panel de Cloudflare, abre Networking → Tunnels, crea un túnel y elige cloudflared.
Añade un nombre de host público y dirígelo al origen local, por ejemplo http://<your-application-ip>:8000 para la aplicación de karaoke o http://<your-demucs-ip>:8001 para Demucs.

Ejecuta el conector con este comando:

cloudflared tunnel --no-autoupdate run --token <TUNNEL_TOKEN>

Protege el punto de acceso de Demucs con una clave de API y configura la misma clave en ambos servicios.

Los túneles rápidos son solo para pruebas

Un túnel rápido crea un nombre de host aleatorio trycloudflare.com sin requerir una cuenta de Cloudflare. Sirve para una prueba breve de conectividad, pero no es adecuado para karaoke en producción: Cloudflare documenta un límite de simultaneidad de 200 solicitudes y no admite Server-Sent Events.

cloudflared tunnel --url http://localhost:<port>

Límite de subida de Cloudflare CDN

Cloudflare CDN tiene un límite estricto de 100 MB para subidas de archivos. Establece el límite de contenido directo para separación en 100 MB o menos. De lo contrario, el procesamiento de karaoke de vídeos más grandes fallará.

Tailscale¶

Tailscale crea una red de malla entre la aplicación de karaoke y el servicio Demucs remoto. Comparte tu equipo con otros usuarios cuando el host de Demucs pertenezca a otra persona.

Instala Tailscale en ambos equipos.
Inicia sesión con la misma cuenta o únete a la misma tailnet.
Busca la dirección IP de Tailscale del servicio Demucs en la consola de administración o con tailscale status.
Configura la URL del servicio de separación de la aplicación con la dirección IP y el puerto de Tailscale del servicio Demucs.
Prueba la conexión y ejecuta la prueba de velocidad /transfer de Demucs.

Tailscale funciona mejor con una conexión directa. Consulta la guía de tipos de conexión y la guía de firewall para mejorar la conectividad directa.

Usar un servidor proxy para las descargas¶

La aplicación admite un servidor proxy para descargar vídeos de YouTube. Un proxy puede ayudar cuando una red doméstica se bloquea temporalmente o YouTube limita su velocidad.

Para enrutamiento más avanzado, usa un panel como Mihomo con metacubexd para añadir, gestionar y alternar entre varios servidores proxy.

Panel de Mihomo

Proxy SOCKS5 sencillo¶

Cloudflare WARP es una opción para crear un proxy. La imagen Docker warproxy convierte Cloudflare WARP en un proxy de salida SOCKS5.

Prueba un proxy SOCKS5 local con:

curl -4 -x socks5://localhost:1080 https://ifconfig.me
# A Cloudflare WARP proxy should return a 104.x.x.x IPv4 address.

Para convertir un punto de acceso comercial, WireGuard u OpenVPN en un proxy SOCKS5, consulta gluetun y su configuración de proxy HTTP.

Mihomo y metacubexd¶

Actualmente la aplicación admite un servidor proxy configurado y no proporciona alternancia ni equilibrio de carga de proxy. Mihomo puede ofrecer esas funciones sin que cambie el ajuste de proxy de la aplicación de karaoke.

Configura Mihomo con una entrada de proxy HTTP y luego añade y administra varios servidores proxy ascendentes mediante su panel.

Configuración básica de Mihomo y metacubexd

Ejemplo de configuración Docker Compose:

services:
  metacubexd:
    image: ghcr.io/metacubex/metacubexd-server:latest
    restart: unless-stopped
    environment:
      CONTROL_TOKEN: change-me-control
      CLASH_SECRET: change-me-clash
      CONTROL_PORT: "8080"
      CLASH_API_PORT: "9090"
      MIXED_PORT: "7890"
      TZ: Asia/Shanghai
    ports:
      - "8080:8080" # Dashboard UI and control agent API.
      - "9090:9090" # Mihomo Clash API and WebSocket.
      - "7890:7890" # Mixed proxy port.
    volumes:
      - metacubexd-data:/data

volumes:
  metacubexd-data: {}

Revisa la configuración de Mihomo y añade tus servidores proxy. Un ejemplo básico es:

external-controller: 0.0.0.0:9090
secret: change-me-clash
mixed-port: 7890
allow-lan: true
mode: rule
log-level: info
ipv6: false
proxies:
  - name: Proxy1

Abre http://<your-server-ip>:8080 y usa change-me-clash para acceder al panel. Sustituye todos los secretos de ejemplo antes de usar esta configuración.

Después de configurar el proxy, cambia a otro servidor proxy desde el panel de metacubexd si falla una descarga de yt-dlp. No es necesario modificar el ajuste de proxy de la aplicación de karaoke.

Supervisión del servidor¶

Para la aplicación principal, puedes identificar problemas o configuraciones incorrectas revisando los registros.

Si ejecutas la aplicación con uvicorn en primer plano o en una sesión tmux, los registros aparecen en la terminal.

Para Linux con systemd, usa:

sudo journalctl -u your-karaoke-service-name -f

Para Docker, usa:

docker logs -f your-karaoke-container-name
# Or: docker compose logs -f

La aplicación también registra los comandos concretos de descarga de yt-dlp, que pueden ayudar a rastrear fallos de descarga.

Para el servicio Demucs, los registros relevantes de Demucs y WhisperX se muestran en la terminal. Por ejemplo:

2026-09-12 14:43:34 - whisperx.asr - INFO - No language specified, language will be detected for each audio file (increases inference time)
2026-09-12 14:43:34 - whisperx.vads.pyannote - INFO - Performing voice activity detection using Pyannote..
2026-09-12 14:43:39 - whisperx.asr - INFO - Detected language: en (0.88) in first 30s of audio
started inference
Inference time for segment 0: 0.78 seconds

El servicio Demucs también expone un punto de acceso /metrics que puedes supervisar con una herramienta externa.

{"service":"demucs","snapshot_at":"2026-09-12T21:58:47.346862+00:00","active_job_count":0,"running_job_count":0,"active_job_counts_by_status":{},"active_job_counts_by_kind":{},"free_vram_bytes":11013193728,"total_vram_bytes":12878086144,"last_gc_at":"2026-09-12T21:48:58.140879+00:00","last_gc_mode":"full","last_gc_detail":"Released WhisperX caches and CUDA memory","active_jobs":[]}

En Windows, la mejor forma de supervisar la aplicación o depurar trabajos bloqueados es usar el Administrador de tareas y revisar el gráfico de GPU para ver el uso de VRAM y GPU.

Administrador de tareas de Windows mostrando uso de GPU

El Administrador de tareas no está disponible en un teléfono. Para este caso, usa RustDesk para acceder remotamente al escritorio de Windows.