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, esto no te aplica

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.

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.