Gestionar archivos en DigitalOcean Spaces con rclone por CLI

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos ·

Usa el backend S3 de rclone para subir un directorio a un Space privado de DigitalOcean, listar sus objetos y volver a descargar los archivos. Este tutorial verifica los bytes descargados y muestra qué elimina sync dentro de un prefijo exclusivo para la demostración, sin hacer público el bucket.

Prepara un Space privado

Necesitas un Space de Standard Storage existente y su endpoint de origen regional, como fra1.digitaloceanspaces.com. Usa una clave de acceso de Spaces con permisos de lectura, escritura y eliminación en ese bucket. Un token de la API de DigitalOcean es una credencial distinta. La guía de claves de acceso de DigitalOcean explica las claves limitadas a un bucket; no copies una política de AWS IAM en Spaces suponiendo que otorga el mismo acceso.

Los comandos siguientes están dirigidos a Linux en procesadores Intel/AMD de 64 bits, con Bash, cURL, unzip y GNU coreutils instalados. La versión de rclone probada es la 1.75.2. Los nombres de archivo de este ejemplo usan UTF-8, incluido el de un archivo binario en un subdirectorio; el archivo vacío es intencional. Mantén este pequeño ejercicio secuencial separado de una copia de seguridad en uso o de un directorio que otro proceso esté modificando.

Instala rclone en un nuevo directorio de trabajo

Pega este bloque desde un directorio con permisos de escritura. Descarga la versión específica de rclone, verifica su suma de comprobación SHA-256 publicada e instala el ejecutable localmente. No continúa si ya existe un directorio rclone-spaces. Los paréntesis mantienen la navegación y las opciones del shell dentro de una subshell.

(
  set -eu
  for tool in curl sha256sum unzip install mv mkdir; do
    command -v "$tool" >/dev/null || { echo "Missing prerequisite: $tool" >&2; exit 1; }
  done
  mkdir rclone-spaces &&
  cd rclone-spaces &&
  curl -fsSLo rclone.zip https://downloads.rclone.org/v1.75.2/rclone-v1.75.2-linux-amd64.zip &&
  curl -fsSLo SHA256SUMS https://downloads.rclone.org/v1.75.2/SHA256SUMS &&
  mv rclone.zip rclone-v1.75.2-linux-amd64.zip &&
  sha256sum --check --ignore-missing SHA256SUMS &&
  unzip -q rclone-v1.75.2-linux-amd64.zip &&
  install -m 755 rclone-v1.75.2-linux-amd64/rclone rclone &&
  ./rclone version
)

La salida de la versión debe comenzar con rclone v1.75.2. Si falla la descarga o la verificación del archivo contenedor, detente ahí. Inspecciona el directorio parcial rclone-spaces antes de eliminarlo por tu cuenta y repetir la instalación; el instalador no sobrescribe un proyecto existente. Ejecuta los comandos restantes desde este nuevo directorio.

Configura el remoto de Spaces

Desde rclone-spaces, crea un archivo de configuración privado y vacío. Este bloque no continúa si el archivo ya existe y deja intacta tu configuración habitual de rclone:

(umask 077; set -C; : > spaces.conf)

Edita spaces.conf para que contenga la siguiente configuración y reemplaza los marcadores de credenciales y el endpoint. Mantén este archivo fuera del control de versiones.

[spaces]
type = s3
provider = DigitalOcean
env_auth = false
access_key_id = YOUR_SPACES_ACCESS_KEY
secret_access_key = YOUR_SPACES_SECRET_KEY
endpoint = fra1.digitaloceanspaces.com
region =
location_constraint =
acl = private
no_check_bucket = true
list_version = 1

Las instrucciones del backend de DigitalOcean dejan region y location_constraint vacíos: el endpoint identifica la región. Usa el endpoint de origen, sin un nombre de bucket ni un nombre de host de CDN. Establecer no_check_bucket omite las comprobaciones de existencia y creación del bucket; supone que el bucket ya existe y no otorga permisos sobre los objetos. Este ejemplo usa explícitamente ListObjects versión 1 para listar objetos.

Sube, lista y descarga un árbol de archivos

Guarda lo siguiente como spaces-demo.sh en el mismo directorio de trabajo. Pasa el nombre de tu bucket y un UUID nuevo al ejecutarlo. El script usa ese UUID para aislar su destino remoto y no continúa si el prefijo no está vacío o si ya existen los directorios locales upload/download.

#!/usr/bin/env bash
set -euo pipefail
space=${1:?Supply a bucket name}
run_id=${2:?Supply a fresh UUID}
[[ "$space" =~ ^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$ ]] || { echo 'Invalid bucket name' >&2; exit 1; }
[[ "$run_id" =~ ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ ]] || { echo 'Invalid UUID' >&2; exit 1; }
remote="spaces:$space/rclone-demo-$run_id"
[[ ! -e upload && ! -e download ]] || { echo 'Use a fresh local working directory' >&2; exit 1; }
existing=$(./rclone --config ./spaces.conf lsf "$remote" --recursive)
[[ -z "$existing" ]] || { echo 'Choose a new, empty demo prefix' >&2; exit 1; }
mkdir upload
mkdir download
mkdir upload/nested
printf 'Hello from rclone\n' > upload/hello.txt
printf '\000\001\177\200\377' > 'upload/nested/café 💾.bin'
: > upload/empty.txt
printf 'Remove this demo object during sync\n' > upload/obsolete.txt
./rclone --config ./spaces.conf copy ./upload "$remote"
./rclone --config ./spaces.conf lsjson "$remote" --recursive --files-only --s3-list-chunk 2
./rclone --config ./spaces.conf copy "$remote" ./download
./rclone --config ./spaces.conf check ./upload ./download --download
printf 'Verified the downloaded file tree. Remote prefix: %s\n' "$remote"

Ejecútalo con el nombre del bucket de tu Space. Linux proporciona un UUID nuevo mediante el archivo que se usa a continuación:

bash spaces-demo.sh your-space "$(cat /proc/sys/kernel/random/uuid)"

El listado JSON debe contener hello.txt, empty.txt, obsolete.txt y nested/café 💾.bin. El tamaño de página de dos objetos del listado pone a prueba deliberadamente la paginación en este pequeño árbol; no es una recomendación de rendimiento. copy transfiere el contenido de un directorio, por lo que las claves remotas no incluyen un directorio upload/ adicional. Conserva los archivos que solo existen en el destino, pero puede reemplazar archivos modificados con nombres coincidentes. No es una operación que impida sobrescribir.

La comprobación final con check --download lee ambos árboles locales y compara su contenido. Un estado de transferencia correcta o un tamaño de archivo coincidente, por sí solos, no equivalen a esta verificación de bytes. Si falla algún comando, el script se detiene; las subidas completadas pueden permanecer en el prefijo de demostración y la descarga local puede quedar incompleta. Inspecciona esos resultados antes de volver a intentarlo. Para una nueva ejecución, usa un directorio de trabajo y un UUID nuevos en lugar de eliminar un destino que no conoces para que el script continúe.

Previsualiza una sincronización de alcance limitado antes de eliminar nada

sync hace que el destino coincida con el origen, lo que incluye eliminar archivos que solo existen en el destino. Es unidireccional, no una combinación de modificaciones independientes. Invertir los argumentos convertiría el directorio local en el destino y podría eliminar archivos que solo existen localmente.

Después de que la transferencia se complete correctamente, copia el prefijo remoto que se muestra en la salida en el comando siguiente. Guarda el bloque como spaces-sync.sh. Elimina únicamente obsolete.txt de la demostración local y luego previsualiza una sincronización con destino al mismo prefijo UUID. Revisa la previsualización antes de confirmar la sincronización real. No lo sustituyas por la raíz del bucket ni por un prefijo compartido con otro proceso que escriba en él.

#!/usr/bin/env bash
set -euo pipefail
remote=${1:?Supply the printed demo prefix}
[[ "$remote" =~ ^spaces:[a-z0-9][a-z0-9-]{1,61}[a-z0-9]/rclone-demo-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ ]] || { echo 'Expected a demo prefix' >&2; exit 1; }
rm -f ./upload/obsolete.txt
./rclone --config ./spaces.conf sync ./upload "$remote" --dry-run
read -r -p 'Type sync to apply these destination changes: ' answer
[[ "$answer" == sync ]] || { echo 'Sync canceled'; exit 1; }
./rclone --config ./spaces.conf sync ./upload "$remote"
./rclone --config ./spaces.conf check ./upload "$remote" --download

bash spaces-sync.sh spaces:your-space/rclone-demo-REPLACE_WITH_THE_PRINTED_UUID

La previsualización debe indicar que se eliminará obsolete.txt. Tras la confirmación, el prefijo remoto debe contener los otros tres archivos y la última comprobación compara sus bytes con los de upload. Tu directorio original download sigue conteniendo los cuatro archivos. Una ejecución de prueba describe el estado que observó; no bloquea el destino para impedir cambios posteriores. Evita que otros procesos escriban en este prefijo. Los objetos restantes de la demostración permanecen en tu Space hasta que los elimines.

Diagnostica un comando fallido

Revisa el estado de salida del comando y su diagnóstico antes de continuar. Un rechazo de acceso puede deberse a una clave no válida o a permisos insuficientes en el bucket; no justifica hacer públicos los archivos. Revisa spaces.conf seleccionado, el nombre del bucket y el endpoint de origen. Para este tutorial, listar un prefijo conocido del bucket es una prueba más adecuada que listar todos los buckets de la cuenta.

Una copia fallida puede dejar algunos archivos transferidos correctamente. Usa el listado para identificarlos y repite la verificación de bytes después de completar la transferencia. No ejecutes sync como medida de reparación de una subida incompleta. Una discrepancia detectada por check indica que debes inspeccionar el archivo señalado antes de usar su copia descargada.

Para programar tareas, filtrar archivos o aplicar cifrado del lado del cliente más allá de este ejercicio, consulta la documentación de rclone. Estas funciones requieren su propia configuración. Los ajustes de s3 anteriores no aplican el cifrado del lado del cliente ni la compresión de rclone.