Configurar media.path en Traccar: guardar y servir las fotos de tus cámaras

Si ya tienes un dispositivo con cámara compatible, activar el almacenamiento de fotos en Traccar es sorprendentemente simple: una sola clave de configuración. Lo que no es tan simple es todo lo que viene después — disco, permisos y proxy. Vamos por partes.

¿Todavía no tienes el hardware? Antes de comprarlo, revisa qué cámaras son compatibles con Traccar y cómo verificarlo.

Las claves reales de traccar.xml

Solo existen dos claves relacionadas con multimedia. Estas:

<entry key='media.path'>/opt/traccar/media</entry>
<entry key='media.bufferSize'>33554432</entry>

media.path

Es la carpeta donde el servidor guarda audio, video y fotos. Su valor por defecto es ./media, relativo al directorio de trabajo del servidor. Traccar crea automáticamente una subcarpeta por dispositivo usando su identificador único.

Esta clave es también el interruptor. Si media.path tiene valor, el servlet que sirve los archivos se registra; si no, no. No busques una clave media.enable porque no existe — es un error frecuente en el foro. Como el valor por defecto ya es ./media, en la práctica el sistema está operativo desde la instalación; lo que suele faltar es apuntarlo a una ruta absoluta con espacio real.

media.bufferSize

Tamaño máximo, en bytes, de un archivo multimedia que un decodificador puede acumular desde un dispositivo. Por defecto son 32 MB (33554432). Las transferencias que superen ese límite se descartan.

Dos cosas a tener en cuenta:

1. Solo se mantiene un buffer por conexión. No esperes transferencias paralelas por el mismo socket.
2. Subir este valor a lo bestia no es gratis: es memoria que el servidor reserva por conexión activa en transferencia. Si vas a recibir clips de video de varios vehículos a la vez, dimensiona la RAM en consecuencia.

Para fotos de cámara ADAS/DSM típicas (100–500 KB) el valor por defecto sobra de largo.

Dónde acaban los archivos

La estructura en disco es:

/opt/traccar/media/
├── 356938035643809/
│   ├── 1754400000000.jpg
│   └── 1754400600000.jpg
└── 862205059000000/
    └── 1754401200000.h265

Una carpeta por uniqueId (el IMEI o identificador que registraste), y dentro archivos nombrados por marca de tiempo. En la posición correspondiente, Traccar añade un atributo image, video o audio cuyo valor es solo el nombre del archivo, no la ruta.

Cómo se acceden desde fuera

Traccar expone la carpeta en:

GET /api/media/{uniqueId}/{nombreDeArchivo}

Por ejemplo:

curl -u usuario:contrasena \
  https://tu-servidor.com/api/media/356938035643809/1754400000000.jpg \
  -o foto.jpg

Esto no es una carpeta pública. Delante hay un filtro que exige sesión válida y que comprueba que el usuario autenticado tenga permiso sobre ese dispositivo concreto. Un usuario de tu plataforma no puede sacar las fotos de otro cliente adivinando IMEIs.

Espacio en disco: la parte que muerde

Nadie planifica esto y luego el servidor se queda sin disco a las tres semanas. Haz la cuenta antes:

• Una foto de evento de 300 KB
• Por 10 eventos al día
• Por 50 vehículos
• Por 30 días

≈ 4,5 GB al mes. Con video la cifra se dispara con facilidad a decenas de GB.

Dos consecuencias prácticas:

1. Monta media.path en un volumen aparte del sistema operativo. Si se llena, que no tumbe la base de datos ni los logs.

2. La limpieza automática de posiciones antiguas de Traccar no borra los archivos de media. Si purgas el histórico, los JPG se quedan huérfanos en disco. Necesitas tu propia tarea de limpieza, por ejemplo:

   # Borrar archivos de media con más de 90 días
   find /opt/traccar/media -type f -mtime +90 -delete
   

   Pruébalo primero sin -delete y revisa la salida antes de programarlo en cron.

Permisos

El servicio de Traccar necesita escribir en esa carpeta. Si la creas a mano como root, el servicio va a fallar en silencio en las escrituras:

sudo mkdir -p /opt/traccar/media
sudo chown -R traccar:traccar /opt/traccar/media

Ajusta el usuario al que use tu instalación (en Docker suele ser distinto; ahí lo relevante es montar un volumen persistente en la ruta que declares en media.path, o perderás las fotos en cada recreación del contenedor).

Nota sobre el proxy inverso

Si tienes Nginx o Apache delante para HTTPS (y deberías — ver conexión segura para Traccar), ten presente que /api/media/ sirve archivos binarios que pueden ser bastante más pesados que una respuesta JSON normal de la API.

Si ves descargas cortadas o errores al abrir clips de video grandes, revisa los límites de tamaño de respuesta y los tiempos de espera de tu proxy. En Nginx, los parámetros habituales a mirar son proxy_read_timeout y el buffering de respuesta.

Y si además usas video en vivo JT1078, hay una segunda ruta que el proxy tiene que dejar pasar: /api/stream/, de donde salen la playlist live.m3u8 y los segmentos .ts. Es un fallo clásico: el video "no arranca" y en realidad la playlist carga bien pero los segmentos devuelven 404 o quedan atrapados en el buffering del proxy. Lo cuento con detalle en video en vivo JT1078 en Traccar.

Si tienes un MDVR JT808, no busques los videos en media.path

Aviso para ahorrarte horas de depuración: si tu equipo es un MDVR que habla JT808/JT1078, puedes configurar media.path perfectamente y aun así no vas a ver ni un solo archivo de video ahí. Ese protocolo no usa el sistema de media: Traccar hace de relay en vivo y el histórico se queda en la SD del vehículo.

Lo normal en esos servidores es encontrar la carpeta con únicamente algún device.jpg (la foto de perfil del dispositivo, que es otro mecanismo distinto). No está roto: es el diseño. Lo explico en video en vivo JT1078 en Traccar.

Configurar video para Traccar en traccar.xml

Esta es la parte que casi nadie documenta: el comando 0x9101 no lleva valores fijos, los lee de tu configuración. Si el XML está incompleto, Traccar manda la orden igual, no registra ningún error, y la cámara simplemente nunca aparece.

<entry key='web.url'>http://gps.tudominio.com</entry>
<entry key='media.path'>/opt/traccar/media</entry>
<entry key='jt808.port'>5015</entry>
<entry key='jt1078.port'>5263</entry>
<entry key='jimiphoto.port'>5267</entry>

web.url — de aquí sale la dirección que recibe la cámara

Al construir el videoStart, el codificador JT808 hace URI.create(web.url).getHost() y escribe ese host dentro de la trama. Traducción: lo que la cámara va a intentar resolver es el host de web.url.

Consecuencias prácticas:

• Si web.url no está definida, el comando de video no llega a formarse.
• Si apunta a localhost o a una IP privada, la cámara —que está en red celular— nunca llega. Tiene que ser un host público, resoluble desde el módem del vehículo.
• El http:// y el :8082 que pongas ahí son irrelevantes para la cámara: solo se usa el nombre de host.

jt1078.port — el puerto que viaja dentro de la orden

El puerto que Traccar escribe en el 0x9101 no es el de la web ni el de JT808: es el de jt1078, leído de la configuración con el prefijo del protocolo. Por defecto, 5263.

Y aquí hay un detalle que rompe instalaciones enteras: un protocolo solo arranca si su puerto es mayor que cero. Si además declaraste protocols.enable, esa clave se comporta como lista blanca — si jt1078 no aparece en ella, el puerto nunca escucha y la cámara termina conectándose contra un puerto cerrado.

jimiphoto.port — la subida de media de alarma

Cuando llega una alarma con adjunto, el decodificador JT808 le manda a la cámara una orden de subida con esta forma:

VIDEOUPLOAD,<host de web.url>,<jimiphoto.port>,<etiqueta de alarma>,1-2-3,2

Si web.url está vacía o el puerto de jimiphoto es cero, esa función se salta en silencio: no hay traza en el log, simplemente nunca se pide el adjunto. Es la causa número uno del clásico "me llega la alarma, pero nunca la foto".

<protocolo>.address — cuidado con el bind

Existe un sufijo .address por protocolo (jimiphoto.address, jt1078.address…) que define en qué interfaz de red escucha ese servicio. Si no lo declaras, escucha en todas.

Ponerlo en 127.0.0.1 limita el servicio a loopback, y entonces una cámara en internet no puede subir nada. Solo tiene sentido si delante hay un proxy en la misma máquina. Si tienes dudas, no declares la clave.

Y una clave que no existe: media.server

Circula por foros —y por respuestas de IA— la idea de configurar algo así:

<!-- esto no hace absolutamente nada -->
<entry key='media.server'>SERVER,2,gps.tudominio.com,5263,0#</entry>

media.server no existe en el código de Traccar. Ese SERVER,2,...# es un comando del dispositivo Jimi/Concox para apuntarlo a un servidor, no una clave de configuración: es inofensivo en el XML, pero se ignora por completo. La dirección que recibe la cámara sale de web.url, como se explica arriba.

Firewall y Docker

Los tres puertos tienen que estar abiertos de entrada:

Si el servidor corre en Docker, además hay que publicarlos explícitamente y montar media.path en un volumen; si no, pierdes los archivos en cada recreación del contenedor.

Verificar que funciona

1. Confirma que tu dispositivo usa un protocolo con soporte real de media — la lista es corta y la repaso en cómo funciona el sistema de media.

2. Dispara una foto (por comando o provocando el evento que la genera).

3. Mira la carpeta:

   ls -la /opt/traccar/media/TU_IMEI/
   

4. Si el archivo está en disco pero no lo ves en la interfaz, el problema es de permisos de usuario sobre el dispositivo o del proxy — no del decodificador.

5. Si no hay archivo, revisa el log del servidor: casi siempre es que el protocolo no implementa media, o que la transferencia superó media.bufferSize.