Desplegar Syncthing con Docker: Compose, puertos y mapeo de directorios

Serie Syncthing

• Cómo usar Syncthing: notas prácticas desde el emparejamiento de dispositivos hasta la sincronización de archivos
• Desplegar Syncthing con Docker: Compose, puertos y mapeo de directorios
• Cómo configurar Syncthing con varios dispositivos: red entre pares, topología en estrella e introducers
• Cómo usar Syncthing en Android: configuración de Syncthing-Fork y copia de fotos
• Cómo gestionar varios dispositivos y carpetas en Syncthing: topología, nombres y versionado
• Cómo sincronizar fotos de iPhone con un ordenador o NAS usando Syncthing

Desplegar Syncthing en Docker encaja muy bien en un NAS, un servidor doméstico o un VPS. Puede actuar como un nodo de sincronización siempre encendido para fotos, documentos, notas Markdown o carpetas de descargas.

Lo importante al desplegar Syncthing con Docker no es solo que el contenedor arranque. Hay tres puntos que conviene resolver desde el principio:

• persistir el directorio de configuración;
• mapear en el contenedor las carpetas de datos que se quieren sincronizar;
• preparar puertos y permisos antes de empezar.

Si estos detalles quedan mal, una actualización del contenedor puede hacerte perder la configuración, la ruta que escribas en el Web UI puede no apuntar a la carpeta real del host, o la sincronización puede fallar con Permission denied.

Planificación de directorios

Primero crea un directorio dedicado en el servidor o NAS, por ejemplo:

1
2

mkdir -p ~/syncthing
cd ~/syncthing

Coloca docker-compose.yml en ese directorio y guarda la configuración de Syncthing en un subdirectorio:

1
2
3

syncthing/
├── docker-compose.yml
└── config/

Los datos reales que se van a sincronizar pueden estar en rutas existentes del host, por ejemplo:

1
2

/volume1/downloads
/volume1/photos

Separa el directorio de configuración de los directorios de datos. config guarda la configuración propia de Syncthing, sus claves y la base de datos de índices. Carpetas como downloads y photos son los datos reales que quieres sincronizar.

Opción 1: Docker Compose

Para uso permanente es mejor Docker Compose, porque las actualizaciones, reinicios y migraciones quedan mucho más claros.

Escribe esto en ~/syncthing/docker-compose.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

version: "3"

services:
  syncthing:
    image: syncthing/syncthing:latest
    container_name: syncthing
    hostname: my-nas-syncthing
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/var/syncthing/config
      - /volume1/downloads:/var/syncthing/downloads
      - /volume1/photos:/var/syncthing/photos
    ports:
      - 8384:8384
      - 22000:22000/tcp
      - 22000:22000/udp
      - 21027:21027/udp
    restart: unless-stopped

Arranca el servicio:

1

docker compose up -d

Comprueba el estado:

1
2

docker compose ps
docker logs -f syncthing

Abre el Web UI:

1

http://ip-del-servidor:8384

La primera vez que entres, configura antes que nada un usuario y una contraseña para la GUI.

Opción 2: docker run

Para una prueba rápida, también puedes usar directamente docker run:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

docker run -d \
  --name syncthing \
  --hostname my-nas-syncthing \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -p 8384:8384 \
  -p 22000:22000/tcp \
  -p 22000:22000/udp \
  -p 21027:21027/udp \
  -v /path/to/config:/var/syncthing/config \
  -v /path/to/data1:/var/syncthing/data1 \
  --restart unless-stopped \
  syncthing/syncthing:latest

Sustituye /path/to/config y /path/to/data1 por rutas reales del host.

Por ejemplo:

1
2

-v /volume1/docker/syncthing/config:/var/syncthing/config
-v /volume1/photos:/var/syncthing/photos

Para uso a largo plazo, conviene convertirlo en un archivo Compose y evitar reconstruir el comando completo cada vez que recrees el contenedor.

Rutas del contenedor y rutas del host

El punto que más confunde al empezar con Docker son las rutas.

Por ejemplo, en Compose puedes tener:

1
2

volumes:
  - /volume1/photos:/var/syncthing/photos

La parte izquierda, /volume1/photos, es la ruta del host. La parte derecha, /var/syncthing/photos, es la ruta dentro del contenedor.

Cuando añadas una carpeta de sincronización en el Web UI de Syncthing, la ruta de carpeta debe ser la ruta dentro del contenedor:

1

/var/syncthing/photos

Así Syncthing operará realmente sobre esta ruta del host:

1

/volume1/photos

Si escribes /volume1/photos en el Web UI, esa ruta normalmente no existe dentro del contenedor. Syncthing puede mostrar un error o crear una carpeta nueva dentro del sistema de archivos del contenedor, que no es lo que querías.

La configuración debe ser persistente

Esta línea es crítica:

1

- ./config:/var/syncthing/config

Syncthing guarda sus archivos de configuración, claves de dispositivo y base de datos de índices en el directorio de configuración. Si no lo montas en el host, al borrar o recrear el contenedor puede cambiar el device ID y dejar sin efecto los emparejamientos existentes.

Usa una ruta estable, por ejemplo:

1

/volume1/docker/syncthing/config

No pongas la configuración en un directorio temporal, ni la mezcles con los directorios de datos sincronizados.

Puertos y firewall

Los puertos habituales son:

1
2
3
4

8384/TCP   Administración Web UI
22000/TCP Tráfico de sincronización entre dispositivos
22000/UDP Tráfico de sincronización QUIC
21027/UDP Descubrimiento en red local

Si Syncthing está desplegado en un NAS doméstico, normalmente debes revisar:

• si el firewall del NAS permite estos puertos;
• si el mapeo de puertos del puente Docker es correcto;
• si el router separa la red Wi-Fi de la red cableada;
• si el teléfono y el ordenador están en la misma subred.

Si está desplegado en un servidor cloud, revisa también el grupo de seguridad del proveedor. En especial, si 22000/TCP y 22000/UDP no están abiertos, otros dispositivos quizá solo puedan conectar mediante relay, con una velocidad mucho menor.

8384 es el puerto de administración. No lo expongas directamente a Internet. Si necesitas administración remota, usa al menos una contraseña fuerte y, mejor aún, combínalo con proxy inverso, HTTPS, control de acceso o VPN.

Problemas de permisos: PUID y PGID

Si Syncthing arranca y puedes abrir el Web UI, pero una carpeta de sincronización muestra:

1

Permission denied

normalmente el proceso del contenedor no tiene permisos de lectura y escritura sobre la carpeta del host.

Primero comprueba el UID y GID del usuario actual en el host:

1

id

La salida puede ser similar a:

1

uid=1000(user) gid=1000(user) groups=1000(user)

Luego ajusta las variables de entorno en Compose:

1
2
3

environment:
  - PUID=1000
  - PGID=1000

Confirma también que la propia carpeta del host permite leer y escribir a ese usuario:

1

ls -ld /volume1/photos

Si hace falta, ajusta propietario o permisos:

1

sudo chown -R 1000:1000 /volume1/photos

En un NAS, no cambies de forma recursiva los permisos de toda una carpeta compartida sin pensarlo, sobre todo si la usan varias personas. Es más seguro preparar una carpeta de sincronización dedicada para Syncthing, o conceder permisos al usuario correspondiente desde la interfaz de permisos del NAS.

Seguridad inicial del Web UI

Después de arrancar el contenedor, visita:

1

http://ip-del-servidor:8384

En la primera entrada, Syncthing normalmente te pedirá configurar usuario y contraseña para la GUI. No omitas este paso.

Recomendaciones:

• configura de inmediato un usuario GUI y una contraseña fuerte;
• no expongas 8384 a Internet;
• para acceso remoto, prioriza VPN, túnel SSH o un proxy inverso controlado;
• si usas proxy inverso, asegúrate de exponer solo el Web UI y no otros puertos innecesarios.

Si alguien controla el panel de administración, podría añadir dispositivos, modificar carpetas compartidas y cambiar relaciones de sincronización. Syncthing cifra la transferencia de datos, pero el punto de administración también necesita protección.

Añadir carpetas de sincronización en el Web UI

Tomemos una carpeta de fotos como ejemplo. En Compose ya está montada así:

1

- /volume1/photos:/var/syncthing/photos

Al añadir la carpeta en el Web UI:

• Folder Label: puedes usar Photos;
• Folder ID: usa un ID estable en inglés, por ejemplo photos;
• Folder Path: escribe /var/syncthing/photos;
• Sharing: elige los dispositivos con los que compartirla;
• Folder Type: elige Send & Receive, Send Only o Receive Only según el flujo de datos.

Si este nodo Docker es el nodo central del NAS, algunas configuraciones comunes son:

• documentos normales: Send & Receive;
• recopilación de fotos del teléfono: Receive Only en el NAS;
• carpeta de distribución hacia otros dispositivos: Send Only en el NAS.

La elección depende de la dirección real de los datos. No conviertas todas las carpetas en sincronización bidireccional por inercia.

Actualizar el contenedor

Con Compose, una actualización suele ser:

1
2

docker compose pull
docker compose up -d

Mientras el directorio de configuración y los directorios de datos estén bien montados, actualizar el contenedor no hará que se pierdan el device ID, los emparejamientos ni la configuración de carpetas.

Antes de actualizar, puedes hacer una copia del directorio de configuración:

1

tar -czf syncthing-config-backup.tar.gz ./config

El directorio de configuración contiene claves privadas del dispositivo. No subas esa copia a ubicaciones públicas sin cuidado.

Problemas frecuentes

El Web UI no abre

Primero comprueba que el contenedor esté ejecutándose:

1
2

docker ps
docker logs syncthing

Después revisa el mapeo de puertos:

1

docker port syncthing

Si el contenedor está bien pero la página no abre, revisa el firewall del host, el firewall del NAS o el grupo de seguridad del servidor cloud.

La carpeta añadida dice que no existe

Comprueba si la ruta que escribiste en el Web UI es la ruta dentro del contenedor.

Por ejemplo, si la ruta del host es:

1

/volume1/downloads

y la ruta dentro del contenedor es:

1

/var/syncthing/downloads

en el Web UI debes escribir la segunda.

Solo conecta por Relay y va muy lento

Revisa primero:

• si 22000/TCP está permitido;
• si 22000/UDP está permitido;
• si el reenvío de puertos del router es correcto;
• si el grupo de seguridad cloud permite TCP y UDP;
• si el firewall local bloquea los puertos mapeados por Docker.

Relay mejora la conectividad, pero no es adecuado para soportar grandes volúmenes de sincronización de forma permanente.

Los permisos de archivos quedan mal después de sincronizar

Primero confirma que el usuario de ejecución del contenedor sea correcto, y luego revisa los permisos de la carpeta del host. Linux, NAS y carpetas compartidas de Windows usan modelos de permisos distintos. No uses Syncthing como herramienta para reparar permisos.

Para sincronización entre sistemas, intenta sincronizar archivos y directorios normales. Evita carpetas del sistema que dependan de ACL complejas, propietarios o atributos extendidos.

Una forma más estable de usarlo

Si tu objetivo es usar un NAS o servidor como nodo central, puedes diseñarlo así:

1. Ejecuta Syncthing con Docker en el NAS.
2. Monta el directorio de configuración en /volume1/docker/syncthing/config.
3. Monta cada tipo de dato por separado, por ejemplo /volume1/photos y /volume1/notes.
4. Añade el device ID del NAS desde teléfonos y ordenadores.
5. Activa el versionado de archivos en carpetas importantes del lado del NAS.
6. Accede al Web UI solo desde la LAN o mediante VPN.
7. Haz también una copia de seguridad independiente del NAS. No trates la sincronización como la única copia.

Con este diseño, Syncthing se encarga de la sincronización entre dispositivos, el NAS aporta disponibilidad permanente y una capa de versionado, y la copia de seguridad real queda en snapshots, discos externos o backups fuera del sitio.

Resumen

La clave para desplegar Syncthing con Docker es separar el ciclo de vida del contenedor del ciclo de vida de los datos sincronizados.

El contenedor puede actualizarse, recrearse o migrarse en cualquier momento. Pero el directorio de configuración y los directorios de datos deben permanecer estables en el host. En el Web UI se introducen rutas internas del contenedor; los permisos del host se gestionan con PUID, PGID y permisos de directorio; y los puertos deben abrirse según el entorno de red real.

Cuando estas piezas están claras, Syncthing funciona muy bien como una capa ligera de sincronización entre un NAS, un servidor y dispositivos personales.