KiraDesktop

Sistema de escritorios virtuales remotos (X11 + XFCE) pensado para captura de streams con protección DRM (Widevine L3) reproducidos en Firefox. Cada instancia levanta un escritorio Linux headless, expone acceso VNC para control/depuración y ofrece una API REST que produce un stream de vídeo+audio en formato MPEG-TS (vía ffmpeg) listo para consumir con cualquier reproductor/pipeline aguas abajo.

La idea general: como el contenido DRM no se puede volcar "en crudo" (el decodificador protege los frames), se renderiza en una sesión X11 real dentro de Firefox y se captura la salida de pantalla (X11 grab) + audio (PulseAudio null-sink), re-codificando con ffmpeg a H.264/AAC en MPEG-TS. El resultado es funcionalmente equivalente a "grabar la pantalla" del escritorio remoto.

Arquitectura: variante CPU vs variante GPU

Variante CPU (`cpu/`)

Contenedores LXC (Proxmox pct), clonados: kiradesktop-cpu-1 ... kiradesktop-cpu-12. Son 12 instancias idénticas en el cluster, cada una con 1 escritorio por contenedor.
Servidor VNC: Xtigervnc (framebuffer virtual, no requiere GPU).
Captura: ffmpeg con -f x11grab + encoder software libx264 (preset superfast, escalado a 1280x720 para aliviar la carga de CPU aunque el VNC se sirve en 1080p).
Cada contenedor corre un único proceso (kiradesktop-cpu.py) que gestiona ese único escritorio (/desktop/0/...).
Incluye kiradesktop.py, una versión anterior/backup del mismo script. Ver sección "Diferencias" más abajo.

Variante GPU (`gpu/`)

Una VM KVM (kirastream-gpu1, Proxmox VM id 211) con GPU NVIDIA pasada por passthrough/vGPU.
Servidor VNC: x11vnc sobre sesiones Xorg reales con el driver NVIDIA (permite aceleración GLX/VDPAU y decodificación por hardware NVDEC/VA-API dentro de Firefox: LIBVA_DRIVER_NAME=nvidia, MOZ_X11_EGL=1).
Captura: ffmpeg con -f x11grab + encoder por hardware h264_nvenc.
Un único proceso (kiradesktop-gpu.py) gestiona hasta 6 escritorios en paralelo (/desktop/{0..5}/...), cada uno con su propio display (:1-:6), puerto VNC (5901-5906) y PulseAudio aislado.

API REST (puerto 8900 en ambas variantes)

Método	Ruta	Descripción
GET	`/health`	Estado de escritorio(s)
POST	`/desktop/{id}/start`	Arranca el escritorio `id`
POST	`/desktop/{id}/stop`	Detiene el escritorio `id`
GET	`/desktop/{id}/stream`	Stream MPEG-TS (multi-cliente)
GET	`/sync/firefox/export[/{slot}]`	Exporta el perfil de Firefox (.tar.gz)
POST	`/sync/firefox/import`	Importa un perfil de Firefox

En la variante CPU {id} es siempre 0 (un solo escritorio por contenedor). En la variante GPU {id} va de 0 a 5 (hasta 6 escritorios por VM).

Puertos

8900/tcp — API REST (FastAPI + uvicorn, 0.0.0.0:8900).
5901/tcp (y consecutivos 5902-5906 en GPU) — VNC directo al framebuffer X11 de cada escritorio.

Despliegue (systemd)

Cada instancia corre como servicio systemd (kiradesktop.service en CPU, kiradesktop-gpu.service en GPU) con Restart=always y toda la configuración por variables de entorno — así el mismo .py sirve para las 12 instancias CPU clonadas y para la VM GPU, cambiando solo el entorno:

MY_IP — IP pública/interna que se anuncia en las respuestas de la API (vnc_addr, stream_url). Debe fijarse por instancia al clonar el contenedor/VM (es lo único que realmente cambia entre clones CPU).
RESOLUTION, FRAMERATE, VIDEO_BITRATE, AUDIO_BITRATE — parámetros de codificación.
VNC_PORT / BASE_VNC_PORT — puerto(s) VNC.
WM_CMD — gestor de ventanas a lanzar (startxfce4 por defecto).
Variante GPU además: NUM_DESKTOPS (6), BASE_DISPLAY, NVENC_PRESET, XORG_CONFIG (ruta al xorg.conf con el driver NVIDIA).

Instalación típica en cada nodo:

cp kiradesktop-cpu.py /opt/kiradesktop-cpu.py   # o kiradesktop-gpu.py
cp kiradesktop.service /etc/systemd/system/     # o kiradesktop-gpu.service
systemctl daemon-reload
systemctl enable --now kiradesktop.service      # o kiradesktop-gpu.service

Diferencias entre `kiradesktop.py` y `kiradesktop-cpu.py`

cpu/kiradesktop.py es una versión previa/backup del script CPU actual (cpu/kiradesktop-cpu.py), tal como se encontró en /opt del contenedor. Se incluye igual por trazabilidad histórica, pero el que está desplegado y en uso (referenciado por el .service) es kiradesktop-cpu.py.

La diferencia real entre ambos archivos es mínima:

Se eliminó un comentario explicativo sobre el escalado a 720p.
Se cambió el preset del encoder libx264 de ultrafast a superfast (mejor relación calidad/CPU a cambio de un poco más de carga).

El resto del código (gestión de PulseAudio, Xtigervnc, ffmpeg, API FastAPI, export/import de perfil de Firefox) es idéntico.

Nota de seguridad (importante para un despliegue real)

Los servidores VNC de ambas variantes se levantan sin contraseña (Xtigervnc -SecurityTypes None en CPU, x11vnc -nopw en GPU) y la API REST no implementa autenticación. Esto asume que el servicio corre en una red interna/confiable (o detrás de un firewall/VPN/reverse-proxy que añada auth). No exponer el puerto 8900 ni los puertos VNC directamente a Internet sin añadir una capa de autenticación (por ejemplo, un proxy con Basic Auth o un túnel VPN) delante de ambos servicios.

No se encontraron contraseñas, tokens ni claves de API hardcodeadas en el código (se auditó con grep -iE "password|secret|token|key" antes de subir el repo).

Requisitos

Python 3 con fastapi, uvicorn.
ffmpeg (con soporte libx264 en CPU, o h264_nvenc/driver NVIDIA en GPU).
pulseaudio, dbus-launch, XFCE (startxfce4) o el WM que se configure.
CPU: Xtigervnc. GPU: Xorg + driver propietario NVIDIA + x11vnc.

6.1 KiB Raw Permalink Blame History