Gerenciar arquivos no DigitalOcean Spaces via CLI com rclone
Use o backend S3 do rclone para fazer upload de um diretório para um Space privado da DigitalOcean,
listar seus objetos e baixar os arquivos novamente. Este tutorial verifica os bytes baixados e
mostra o que sync exclui em um prefixo exclusivo de demonstração, sem tornar
o bucket público.
Preparar um Space privado
Você precisa de um Space Standard Storage existente e de seu endpoint de origem regional, como
fra1.digitaloceanspaces.com. Use uma chave de acesso do Spaces com permissões de leitura, gravação
e exclusão nesse bucket. Um token da API da DigitalOcean é uma credencial diferente. O
guia de chaves de acesso da DigitalOcean explica as chaves com
escopo restrito a um bucket; não copie uma política do AWS IAM para o Spaces supondo que ela
conceda o mesmo acesso.
Os comandos abaixo se destinam ao Linux em processadores Intel/AMD de 64 bits, com Bash, cURL, unzip e GNU coreutils instalados. A versão testada do rclone é a 1.75.2. Os nomes dos arquivos neste exemplo usam UTF-8, inclusive o de um arquivo binário em um subdiretório; o arquivo vazio é intencional. Mantenha este pequeno exercício sequencial separado de um backup em uso ou de um diretório que outro processo esteja alterando.
Instalar o rclone em um novo diretório de trabalho
Cole este bloco a partir de um diretório com permissão de gravação. Ele baixa a
versão específica do rclone, verifica sua soma de verificação
SHA-256 publicada e instala o executável localmente. Ele recusa um diretório
rclone-spaces existente. Os parênteses mantêm a navegação e as opções do shell
dentro de um 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
)
A saída da versão deve começar com rclone v1.75.2. Se o download ou a verificação
do pacote de distribuição falhar, pare por aí. Inspecione o diretório parcial
rclone-spaces antes de removê-lo por conta própria e repetir a configuração;
o instalador não sobrescreve um projeto existente. Execute os comandos restantes dentro desse
novo diretório.
Configurar a conexão remota do Spaces
Dentro de rclone-spaces, crie um arquivo de configuração privado e vazio. Esta
operação recusa um arquivo existente e mantém intacta sua configuração habitual do rclone:
(umask 077; set -C; : > spaces.conf)
Edite spaces.conf para incluir as configurações a seguir, substituindo os
marcadores de credenciais e o endpoint. Mantenha esse arquivo fora do controle de versão.
[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
As instruções do backend da DigitalOcean deixam
region e location_constraint em branco: o endpoint identifica a
região. Use o endpoint de origem, sem nome de bucket nem nome de host de CDN. Definir
no_check_bucket ignora as verificações de existência
e criação do bucket; essa configuração pressupõe que o bucket já existe e não concede permissões
sobre objetos. Este exemplo usa explicitamente a
versão 1 de ListObjects para a listagem.
Fazer upload, listar e baixar uma árvore de arquivos
Salve o conteúdo a seguir como spaces-demo.sh no mesmo diretório de trabalho.
Informe o nome do seu bucket e um novo UUID ao executá-lo. O script usa esse UUID para isolar seu
destino remoto e recusa um prefixo não vazio ou diretórios locais
upload/download existentes.
#!/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"
Execute-o com o nome do bucket do seu Space. O Linux fornece um novo UUID pelo arquivo usado abaixo:
bash spaces-demo.sh your-space "$(cat /proc/sys/kernel/random/uuid)"
A listagem JSON deve conter hello.txt, empty.txt,
obsolete.txt e nested/café 💾.bin. O tamanho de página de dois objetos
na listagem testa deliberadamente a paginação nesta pequena árvore; não é uma recomendação de
taxa de transferência. copy transfere o conteúdo de um diretório, então
as chaves remotas não incluem um diretório upload/ extra. Ele
preserva arquivos que existem apenas no destino, mas pode
substituir arquivos alterados com nomes correspondentes. Não é uma operação que impede
sobrescritas.
O check --download final lê as duas árvores locais
e compara seus conteúdos. Um status de transferência bem-sucedida ou apenas um tamanho de arquivo
correspondente não equivale a essa verificação dos bytes. Se algum comando falhar, o script para;
uploads concluídos podem permanecer no prefixo de demonstração, e o download local pode estar
incompleto. Inspecione esses resultados antes de tentar novamente. Para uma nova execução, use um
novo diretório de trabalho e um novo UUID, em vez de excluir um destino desconhecido para permitir
que o script prossiga.
Visualizar uma sincronização com escopo restrito antes de excluir
sync faz o destino corresponder à
origem, inclusive excluindo arquivos que existem apenas no destino. A sincronização é
unidirecional, não uma mesclagem de edições independentes. Inverter os argumentos tornaria o
diretório local o destino e poderia excluir arquivos que existem apenas localmente.
Após a transferência ser concluída com sucesso, copie o prefixo remoto exibido para o comando
abaixo. Salve o bloco como spaces-sync.sh. Ele remove apenas o
obsolete.txt da demonstração local e, em seguida, mostra uma prévia da
sincronização para o mesmo prefixo UUID. Revise a prévia antes de confirmar a sincronização real.
Não substitua esse prefixo pela raiz do bucket nem por um prefixo compartilhado com outro processo
de gravação.
#!/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
A prévia deve indicar obsolete.txt para exclusão. Após a confirmação, o prefixo
remoto deve conter os outros três arquivos, e a última verificação compara seus bytes com os de
upload. Seu download original ainda contém os quatro
arquivos. Uma simulação descreve o estado observado; ela não bloqueia o destino contra alterações
posteriores. Mantenha outros processos de gravação fora desse prefixo. Os objetos restantes da
demonstração permanecem no seu Space até que você os remova.
Diagnosticar um comando que falhou
Verifique o status de término do comando e seu diagnóstico antes de prosseguir. Uma recusa de
acesso pode decorrer de uma chave inválida ou de permissões insuficientes no bucket; isso não
justifica tornar os arquivos públicos. Confira o spaces.conf selecionado, o
nome do bucket e o endpoint de origem. Listar um prefixo conhecido do bucket é um teste melhor
para este tutorial do que listar todos os buckets da conta.
Uma cópia que falha pode deixar alguns arquivos transferidos com sucesso no destino. Use a
listagem para identificá-los e repita a verificação dos bytes após concluir a transferência. Não
execute sync como medida de correção para um upload incompleto. Uma divergência indicada por
check significa que você deve inspecionar o arquivo indicado antes de
usar sua cópia baixada.
Para agendamento, filtragem ou criptografia do lado do cliente além deste exercício, consulte a
documentação do rclone. Esses recursos exigem configurações
próprias. As configurações de s3 acima não aplicam a criptografia do
lado do cliente nem a compactação do rclone.