Arquitectura de videovigilancia remota con Go, RTSP, FFmpeg y MediaMTX: transmisión y control PTZ
Explora una implementación práctica de videovigilancia remota con una cámara PTZ Hikvision, RTSP, FFmpeg, Cloudflare Tunnel y MediaMTX, incluyendo el flujo de video y el control remoto.
Teníamos una cámara PTZ Hikvision en la red local de la oficina y queríamos dos cosas desde la web: ver el video en vivo y mover la cámara. Sin abrir puertos en el router y sin poner la cámara directamente en internet.
La solución es un pequeño servicio en Go que corre en un servidor de la oficina, un servidor de medios MediaMTX en la nube y un túnel de Cloudflare. En este artículo explico cómo está armado, qué cambiamos en la segunda versión y, sobre todo, qué aprendimos cuando dejó de funcionar y tuvimos que recuperarlo.
La idea central: separar video y control
Transmitir video y controlar un dispositivo parecen parte del mismo problema, pero no lo son. El video es un flujo continuo y pesado que solo va en una dirección. El control son comandos pequeños, esporádicos, que necesitan respuesta y que mueven algo físico. Fallan de formas distintas y se protegen de formas distintas, así que van por caminos separados:
VIDEO
Cámara ──RTSP──> Servicio Go + FFmpeg ──RTSP (publicar)──> MediaMTX (nube) ──WebRTC/HLS──> Navegador
(red local) (sale de la oficina)
CONTROL
Navegador ──HTTPS──> Cloudflare ──túnel──> Servicio Go ──ISAPI──> Cámara
(solo localhost) (red local)
Las dos conexiones salen de la oficina: FFmpeg publica hacia el servidor de medios y cloudflared abre el túnel hacia Cloudflare. No hay ningún puerto abierto hacia adentro.
El camino del video
Copiar, no recodificar
La cámara ya entrega H.264 comprimido. Recodificarlo solo gastaría CPU y agregaría latencia, así que FFmpeg copia el stream tal cual y descarta el audio:
ffmpeg -rtsp_transport tcp -timeout 10000000 \
-i rtsp://usuario:contraseña@CAMARA:554/Streaming/Channels/101 \
-c:v copy -an \
-f rtsp -rtsp_transport tcp rtsp://publicador:contraseña@SERVIDOR:8554/camara
Un detalle que importa: como no se recodifica, el códec de la cámara es el que llega al navegador. Si la cámara está en H.265, la mayoría de los navegadores no lo van a reproducir. Hay que configurarla en H.264 y apagar los “smart codecs” como H.264+.
Mantener vivo a FFmpeg
El servicio en Go lanza FFmpeg como proceso hijo y lo vigila. La primera versión simplemente lo reiniciaba cada 5 segundos si terminaba. En la práctica hubo tres problemas que esa estrategia no resolvía:
- FFmpeg se puede colgar sin morir. Si la cámara deja de mandar datos, el proceso puede quedarse esperando para siempre. La opción
-timeout(en microsegundos) hace que termine si el socket no recibe nada. - El destino también se puede trabar. Si el servidor de medios deja de aceptar datos, la entrada sigue viva pero el video no avanza. Para eso el servicio lee la salida de
-progress pipe:1y, si el video deja de avanzar durante 20 segundos, mata a FFmpeg y lo vuelve a lanzar. - Reintentar cada 5 segundos puede empeorar las cosas. Ahora los reintentos empiezan en 2 segundos y se duplican hasta un minuto.
Un dato que costó encontrar: con -c:v copy, FFmpeg no siempre reporta frame= en -progress. Lo que sí avanza es out_time_us, el tiempo de video ya enviado. Si tu detección de congelamiento depende de frame=, va a reiniciar un stream sano cada 20 segundos.
Que no queden procesos huérfanos
En Windows, si el servicio en Go muere de golpe, su FFmpeg hijo sigue vivo y empujando video. Al reiniciar el servicio terminas con dos FFmpeg publicando en la misma ruta. La solución es meter el proceso en un Job Object de Windows con KILL_ON_JOB_CLOSE: cuando el servicio muere, Windows mata automáticamente a todos sus hijos.
MediaMTX: publicar con contraseña, leer libre
MediaMTX recibe el stream y lo sirve a los navegadores por WebRTC o HLS. Su configuración por defecto deja que cualquiera publique en cualquier ruta, lo que significa que cualquiera podría reemplazar tu video por el suyo. Hay que separar los permisos:
authMethod: internal
authInternalUsers:
- user: publicador
pass: una-contraseña-larga
permissions:
- action: publish
path: camara
- user: any
permissions:
- action: read
path: camara
paths:
camara:
Solo el servicio de la oficina puede publicar, cualquiera puede ver, y no existe ninguna otra ruta. Un detalle de MediaMTX 1.16: los usuarios any no deben llevar la línea pass, ni siquiera vacía.
El camino del control
El túnel no es autenticación
El servicio en Go expone una API HTTP pequeña que solo escucha en 127.0.0.1. La única forma de llegar a ella desde fuera es el túnel de Cloudflare. Eso evita publicar un servicio local, pero no decide quién puede mover la cámara. Esa es una capa aparte (más abajo).
Hablar con la cámara
Hikvision expone ISAPI por HTTP. Para mover la cámara se manda un PUT a /ISAPI/PTZCtrl/channels/1/continuous con velocidades de paneo, inclinación y zoom entre -100 y 100, y para detenerla se manda lo mismo con todo en cero. Las cámaras actuales exigen autenticación Digest, no Basic, así que el cliente HTTP implementa ese intercambio.
Un comando a la vez, y el stop siempre llega
Mover algo físico tiene un riesgo que una API normal no tiene: si el comando de stop se pierde, la cámara se queda girando. La primera versión lanzaba cada movimiento en su propia goroutine, y eso causaba dos problemas: los pulsos se pisaban entre sí (el stop de uno cortaba al siguiente) y, si el stop fallaba, nadie lo reintentaba.
En la segunda versión, todos los comandos pasan por un solo controlador protegido con un mutex:
- Cada movimiento arma un temporizador. Si nadie lo renueva, la cámara se detiene sola.
- Un movimiento nuevo reemplaza al anterior en lugar de competir con él.
- El stop se reintenta. Si falla tres veces, el controlador sigue considerando que la cámara se mueve y lo reintenta cada 2 segundos hasta lograrlo.
- Un movimiento continuo tiene un tope de duración, por si el cliente se queda mandando keepalives por un error.
Con esto la API soporta dos modos: pulso (un clic mueve la cámara medio segundo) y mantener presionado (el navegador manda un keepalive cada 0.7 s; si deja de llegar porque se cerró la pestaña o se cayó la red, la cámara se detiene en 2 segundos).
Un usuario a la vez
Si dos personas mueven la cámara al mismo tiempo, ninguna logra lo que quiere. El servicio da un turno de control: el primero que mueve la cámara lo toma, se renueva con cada comando y expira tras 60 segundos sin uso. Los demás reciben 423 Locked con los segundos que faltan.
Responder lo que realmente pasó
La primera versión respondía 202 Accepted y movía la cámara en segundo plano. 202 solo dice “recibí tu petición”, no “la cámara se movió”. Ahora el movimiento es síncrono y la respuesta dice qué pasó:
| Código | Significado |
|---|---|
| 200 | La cámara aceptó el comando |
| 401 | Falta el token o expiró |
| 423 | Otro usuario tiene el turno |
| 429 | Demasiadas peticiones |
| 502 | La cámara no respondió |
Seguridad en capas
Ninguna medida aislada es suficiente. Estas son las que usamos, de afuera hacia adentro:
- Cloudflare WAF: solo se permiten
GET,POSTyOPTIONS, con un límite de peticiones por IP en la ruta de la API. - Autenticación con token: el backend del sitio, que ya sabe quién es el usuario, emite un token corto firmado con HMAC-SHA256. El servicio de la oficina solo verifica la firma y la expiración. Un header como
X-User-IDno es autenticación: cualquiera lo puede inventar. - La IP real, no la que dice el cliente.
X-Forwarded-Forlo controla el cliente. Detrás de Cloudflare la IP real viene enCF-Connecting-IP, y solo se acepta si la conexión llega desde localhost, que es donde corre cloudflared. - Límites en tres niveles: por usuario, por IP y uno global que protege a la cámara sin importar cuántos usuarios haya.
- Solo
POSTpara mover. Si unGETmueve la cámara, basta con una etiqueta de imagen en cualquier página para moverla. - Usuario de bajo privilegio en la cámara: un Operador con permisos de vista en vivo y control PTZ, nada más. Si la contraseña se filtra, no sirve para cambiar la configuración.
- Secretos fuera de los logs. FFmpeg imprime la URL con usuario y contraseña cuando falla. Todo lo que va a los logs pasa por una función que reemplaza los secretos por
****.
Lo que aprendimos al recuperarlo
Un día el control dejó de funcionar. La primera sospecha fue “se cayó el túnel”. No era eso, y el camino hasta encontrar la causa real dejó varias lecciones de operación.
- “Se cayó el túnel” no era el túnel. cloudflared estaba instalado como servicio de Windows y seguía conectado. Lo que no estaba corriendo era la aplicación: el servidor se había reiniciado y PM2 en Windows no arranca solo con
pm2 save. Hay que instalarlo como servicio, por ejemplo con pm2-installer. - Dos PM2 se pelean. Al instalar PM2 como servicio, el PM2 de la sesión del usuario seguía vivo. En Windows todos usan el mismo named pipe, así que los comandos fallaban con
EPERM. Hubo que matar el PM2 viejo y sus procesos hijos. - Las cámaras bloquean la IP. Con la contraseña equivocada, el servicio reintentaba cada pocos segundos. Hikvision bloquea la IP de origen tras varios intentos fallidos, así que después ni la contraseña correcta funciona hasta que expira el bloqueo. Antes de arrancar con credenciales nuevas, conviene validarlas con una sola petición.
- Los usuarios nuevos de Hikvision no sirven hasta activarse. Un usuario creado por el administrador aparece como Not Activated hasta que inicia sesión por primera vez y cambia su contraseña. Mientras tanto, RTSP e ISAPI lo rechazan con
401. Además, la lista de usuarios de ONVIF es independiente y no sirve para RTSP. - La ruta RTSP depende del fabricante. La configuración tenía una ruta con formato de otra marca. En Hikvision es
Streaming/Channels/101(canal 1, stream principal) o102(substream). - La plataforma de despliegue inyectaba variables que pisaban la configuración. El servicio de MediaMTX se había creado desde una plantilla que definía variables de entorno
MTX_*, y esas variables se aplican encima del archivo de configuración. Eran también la razón de que la publicación estuviera abierta. Como la plataforma las regeneraba al borrarlas, la solución fue anularlas desde la seccionenvironmentde Docker compose, que tiene prioridad sobre el.env. sed -iy un archivo montado no se llevan.sed -icrea un archivo nuevo en lugar de editar el existente. Un contenedor que monta un solo archivo sigue viendo el original, incluso después dedocker restart. Hay que recrear el contenedor.- Las variables mal escritas deben detener el arranque. Una duración escrita como
500*time.Milliseconden el.envse ignoraba en silencio y se usaba el valor por defecto. Ahora cualquier valor inválido detiene el servicio con un mensaje claro.
Lecciones
De diseño
- Transmitir video y controlar un dispositivo son problemas distintos, con fallas distintas. Van por caminos separados.
- No siempre hace falta transcodificar, pero entonces el formato de origen tiene que ser compatible con el destino.
- Un túnel evita publicar un servicio local, pero no reemplaza la autenticación.
- Los comandos a un dispositivo físico necesitan serializarse y un stop garantizado, aunque falle la red.
- Recibido, aceptado y ejecutado son estados distintos. La API debe responder el que realmente ocurrió.
De operación
- Un servicio que no arranca solo después de un reinicio va a fallar el día que menos lo esperas. Hay que probar el reinicio.
- Un reintento agresivo con credenciales equivocadas puede bloquearte del dispositivo. Valida antes y usa backoff.
- Las plataformas de despliegue agregan su propia configuración. Antes de depurar un archivo, revisa qué variables recibe realmente el contenedor.
- Un health check que siempre responde “ok” no sirve. El nuestro ahora responde
503cuando no llega video, y eso es lo que vigila el monitoreo.
Si quieres hacer una prueba, te dejamos el link aquí abajo:
munozsolutions.com.mxProbar nuestra cámara PTZ de Hikvision
Tienes un proyecto en mente?
Platicanos que necesitas y armamos una propuesta a la medida.
Cotizar Proyecto