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.

Por Alfonso Andrade • • 10 min de lectura • Actualizado el 12 de noviembre de 2026
Arquitectura de transmisión remota desde una cámara PTZ Hikvision mediante FFmpeg, Cloudflare Tunnel y MediaMTX.

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:

  1. 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.
  2. 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:1 y, si el video deja de avanzar durante 20 segundos, mata a FFmpeg y lo vuelve a lanzar.
  3. 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:

  1. Cloudflare WAF: solo se permiten GET, POST y OPTIONS, con un límite de peticiones por IP en la ruta de la API.
  2. 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-ID no es autenticación: cualquiera lo puede inventar.
  3. La IP real, no la que dice el cliente. X-Forwarded-For lo controla el cliente. Detrás de Cloudflare la IP real viene en CF-Connecting-IP, y solo se acepta si la conexión llega desde localhost, que es donde corre cloudflared.
  4. Límites en tres niveles: por usuario, por IP y uno global que protege a la cámara sin importar cuántos usuarios haya.
  5. Solo POST para mover. Si un GET mueve la cámara, basta con una etiqueta de imagen en cualquier página para moverla.
  6. 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.
  7. 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) o 102 (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 seccion environment de Docker compose, que tiene prioridad sobre el .env.
  • sed -i y un archivo montado no se llevan. sed -i crea un archivo nuevo en lugar de editar el existente. Un contenedor que monta un solo archivo sigue viendo el original, incluso después de docker restart. Hay que recrear el contenedor.
  • Las variables mal escritas deben detener el arranque. Una duración escrita como 500*time.Millisecond en el .env se 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

  1. Transmitir video y controlar un dispositivo son problemas distintos, con fallas distintas. Van por caminos separados.
  2. No siempre hace falta transcodificar, pero entonces el formato de origen tiene que ser compatible con el destino.
  3. Un túnel evita publicar un servicio local, pero no reemplaza la autenticación.
  4. Los comandos a un dispositivo físico necesitan serializarse y un stop garantizado, aunque falle la red.
  5. Recibido, aceptado y ejecutado son estados distintos. La API debe responder el que realmente ocurrió.

De operación

  1. 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.
  2. Un reintento agresivo con credenciales equivocadas puede bloquearte del dispositivo. Valida antes y usa backoff.
  3. Las plataformas de despliegue agregan su propia configuración. Antes de depurar un archivo, revisa qué variables recibe realmente el contenedor.
  4. Un health check que siempre responde “ok” no sirve. El nuestro ahora responde 503 cuando 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
Compartir

Tienes un proyecto en mente?

Platicanos que necesitas y armamos una propuesta a la medida.

Cotizar Proyecto