Dateien aus Cloudflare R2 in Java mit Rclone importieren

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Cloudflare R2 bietet Entwicklern eine kostengünstige, performante und zuverlässige Lösung für Object Storage. Die Integration in Ihre Java-Anwendungen kann Ihre Workflows zur Dateiverwaltung deutlich vereinfachen. In diesem DevTip zeigen wir, wie Sie Dateien mithilfe des leistungsstarken Open-Source-Tools Rclone effizient aus Cloudflare R2 importieren.

Einführung in Cloudflare R2

Cloudflare R2 ist ein S3-kompatibler Object-Storage-Dienst, der Egress-Gebühren überflüssig macht und sich damit ideal für Anwendungen eignet, die häufig Daten abrufen. Die Kompatibilität mit der S3-API vereinfacht die Integration in bestehende Tools und Workflows für file importing.

Überblick über Rclone

Rclone ist ein Open-Source-Kommandozeilen-Tool, das Dateien und Verzeichnisse mit verschiedenen Cloud-Storage-Anbietern in beide Richtungen synchronisiert. Es unterstützt zahlreiche Storage-Backends, darunter Cloudflare R2, und bietet leistungsfähige Funktionen wie das Synchronisieren, Kopieren und Einbinden entfernter Speicherorte. Es gehört zu den beliebtesten open-source tools für die Verwaltung von Cloud Storage.

Rclone für Cloudflare R2 einrichten

Installieren Sie zunächst Rclone, falls noch nicht geschehen. In der Regel genügt dafür ein einziger Befehl. Prüfen Sie nach der Installation, ob es funktioniert:

# Install Rclone (linux/macos/bsd)
curl -fsSL --retry 3 https://rclone.org/install.sh | sudo bash

# Verify installation
rclone version

Für andere Betriebssysteme oder Methoden lesen Sie die offizielle Rclone-Installationsanleitung.

Konfigurieren Sie anschließend mit dem interaktiven Konfigurationstool die Verbindung von Rclone zu Ihrem Cloudflare-R2-Bucket:

# Configure Rclone (interactive)
rclone config

Folgen Sie den interaktiven Eingabeaufforderungen:

Wählen Sie n für ein neues Remote.
Geben Sie einen Namen für Ihr Remote ein (z. B. cloudflare_r2).
Wählen Sie s3 (oder die entsprechende Nummer) als Storage-Typ.
Wählen Sie als Anbieter Cloudflare (oder die entsprechende Nummer).
Wählen Sie Enter credentials value here (in der Regel Option 1) oder lassen Sie Rclone die Zugangsdaten finden, wenn sie an anderer Stelle konfiguriert sind (z. B. in Umgebungsvariablen).
Geben Sie Access Key ID für Cloudflare R2 an.
Geben Sie Secret Access Key für Cloudflare R2 an.
Legen Sie Endpoint URL für Ihren R2-Bucket fest: https://<accountid>.r2.cloudflarestorage.com (ersetzen Sie <accountid> durch Ihre tatsächliche Cloudflare-Konto-ID).
Setzen Sie region auf auto. R2-Buckets sind über das Netzwerk von Cloudflare verteilt, daher bietet die Cloudflare-Anleitung von Rclone auto als ersten Wert an. Lassen Sie Location constraint, eine davon getrennte S3-Option, leer.
Legen Sie ACL (Access Control List) fest. private ist eine gängige und sichere Wahl.
Prüfen Sie die erweiterten Konfigurationsoptionen (die Standardwerte sind oft ausreichend) und speichern Sie die Konfiguration.

Die daraus entstehende Konfiguration in der Rclone-Konfigurationsdatei (standardmäßig ~/.config/rclone/rclone.conf) sollte in etwa so aussehen:

[cloudflare_r2]
type = s3
provider = Cloudflare
access_key_id = YOUR_ACCESS_KEY_ID
secret_access_key = YOUR_SECRET_ACCESS_KEY
endpoint = https://<accountid>.r2.cloudflarestorage.com
region = auto
acl = private

Denken Sie daran, die Platzhalterwerte durch Ihre tatsächlichen Zugangsdaten und Ihre Konto-ID zu ersetzen, und stellen Sie sicher, dass diese Konfigurationsdatei angemessen geschützt ist.

Rclone in Java-Anwendungen integrieren

Java-Anwendungen können Rclone-Befehle mit der Klasse ProcessBuilder aufrufen. So nutzen Sie die Funktionen von Rclone direkt in Ihrem Code, der in Java geschrieben ist. Das folgende praxisnahe Beispiel zeigt, wie Sie Dateien aus Cloudflare R2 importieren. Die Beispiele setzen Java 17 oder neuer voraus:

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;

public class RcloneImporter {

    /** Rclone writes a lot on a large transfer, so only this many lines are kept for diagnostics. */
    private static final int MAX_REPORTED_LINES = 200;

    /** What Rclone exited with, and the (capped) output it produced. */
    public record RcloneResult(int exitCode, List<String> lines) {
        public boolean succeeded() {
            return exitCode == 0;
        }
    }

    /**
     * Runs an Rclone command, enforcing a wall-clock timeout, and returns its result.
     *
     * <p>Output is redirected to a file rather than read from a pipe. Draining a pipe on the calling
     * thread has to finish before {@code waitFor} is even reached, so a hung Rclone would block in
     * {@code readLine()} forever and the timeout would never fire.
     *
     * @param builder The command and optional environment, configured by the caller.
     * @param timeout How long to let the command run before killing it.
     * @throws IOException          If the process cannot be started or has to be killed.
     * @throws InterruptedException If this thread is interrupted while waiting.
     */
    private static RcloneResult runRclone(ProcessBuilder builder, Duration timeout)
            throws IOException, InterruptedException {
        Path output = Files.createTempFile("rclone-", ".log");
        try {
            builder.redirectErrorStream(true);
            builder.redirectOutput(output.toFile());
            Process process = builder.start();
            try {
                if (!process.waitFor(timeout.toMillis(), TimeUnit.MILLISECONDS)) {
                    throw new IOException("Rclone timed out after " + timeout);
                }
                return new RcloneResult(process.exitValue(), readCapped(output));
            } finally {
                // Finish cleanup even if the caller interrupts while waiting for termination.
                process.destroyForcibly();
                boolean interrupted = false;
                while (process.isAlive()) {
                    try {
                        process.waitFor();
                    } catch (InterruptedException e) {
                        interrupted = true;
                    }
                }
                if (interrupted) Thread.currentThread().interrupt();
            }
        } finally {
            Files.deleteIfExists(output);
        }
    }

    private static List<String> readCapped(Path output) throws IOException {
        // Diagnostics may contain non-UTF-8 filename bytes; they must not change transfer status.
        var decoder = StandardCharsets.UTF_8.newDecoder()
            .onMalformedInput(CodingErrorAction.REPLACE)
            .onUnmappableCharacter(CodingErrorAction.REPLACE);
        try (var reader = new BufferedReader(new InputStreamReader(Files.newInputStream(output), decoder))) {
            return reader.lines().limit(MAX_REPORTED_LINES).toList();
        }
    }

    /**
     * Imports files from a specified Cloudflare R2 path to a local path using Rclone.
     *
     * @param remoteName The name of the configured Rclone remote (e.g., "cloudflare_r2").
     * @param remotePath The path within the R2 bucket (e.g., "my-bucket/path/to/files").
     * @param localPath  The local directory path where files will be downloaded.
     * @param timeout    How long the copy may run before Rclone is killed.
     */
    public static void importFiles(String remoteName, String remotePath, String localPath,
            Duration timeout) throws IOException, InterruptedException {
        List<String> command = new ArrayList<>(List.of(
            "rclone",
            "copy", // Keeps destination-only files; "sync" would delete them
            remoteName + ":" + remotePath, // Format: remote:path/to/dir
            localPath // Destination local directory
        ));

        // Example: add flags for parallel transfers
        // command.addAll(List.of("--transfers", "8"));

        RcloneResult result = runRclone(new ProcessBuilder(command), timeout);
        for (String line : result.lines()) {
            // Replace with proper logging in a real application. Rclone echoes remote paths and
            // the endpoint, so treat these lines as diagnostics rather than user-facing output.
            System.out.println("Rclone Output: " + line);
        }
        if (!result.succeeded()) {
            throw new IOException("Rclone exited with code " + result.exitCode());
        }
    }

    public static void main(String[] args) {
        String rcloneRemoteName = "cloudflare_r2"; // Matches the name used in `rclone config`
        String bucketPath = "my-data-bucket/source-files"; // Path inside your R2 bucket
        String localDirectory = "./downloaded-files"; // Local destination directory

        try {
            Files.createDirectories(Path.of(localDirectory));
            System.out.println("Starting file import from Cloudflare R2...");
            importFiles(rcloneRemoteName, bucketPath, localDirectory, Duration.ofMinutes(10));
            System.out.println("File import completed successfully.");
        } catch (IOException e) {
            // Handle the error appropriately in your application
            System.err.println("Rclone import failed: " + e.getMessage());
        } catch (InterruptedException e) {
            // Only an actual interruption should restore the interrupt flag
            Thread.currentThread().interrupt();
            System.err.println("Rclone import was interrupted");
        }
    }

}

Diese verbesserte Implementierung in Java führt den Rclone-Befehl aus, der Dateien aus Ihrem Bucket bei Cloudflare R2 in ein lokales Verzeichnis kopiert. Sie umfasst eine bessere Verarbeitung der Prozessausgabe, ein besseres Timeout-Management und eine robustere Fehlerprüfung. Verwenden Sie ein dediziertes Ziel und sehen Sie sich einen Durchlauf mit --dry-run an, bevor Sie wertvolle Daten importieren: copy kann geänderte Dateien am Ziel ersetzen, während sync zusätzlich Dateien löscht, die nur am Ziel vorhanden sind.

Häufige Probleme und Tipps zur Fehlerbehebung

Bei der Integration von Rclone mit Java für Vorgänge mit Cloudflare R2 können diese Probleme auftreten:

1. Authentifizierungsfehler

Falsche Zugangsdaten: Überprüfen Sie access_key_id und secret_access_key in Ihrer Rclone-Konfiguration oder in den Umgebungsvariablen.
Falscher Endpunkt: Stellen Sie sicher, dass die URL in endpoint korrekt ist und Ihre spezifische Cloudflare-Konto-ID (https://<accountid>.r2.cloudflarestorage.com) enthält.
Berechtigungen: Prüfen Sie, ob das R2-API-Token, das zu Ihren Zugangsdaten gehört, über die erforderlichen Berechtigungen (z. B. Object Read only) für den Ziel-Bucket und die Zielobjekte verfügt.
ACL-Einstellungen: Stellen Sie sicher, dass die Einstellung acl in Ihrer Rclone-Konfiguration (private, public-read usw.) zu Ihrer Bucket-Policy und Ihren Zugriffsanforderungen passt.

2. Netzwerkprobleme

Firewall-Beschränkungen: Stellen Sie sicher, dass die Firewall Ihres Servers ausgehende HTTPS-Verbindungen (Port 443) zum Cloudflare-R2-Endpunkt (*.r2.cloudflarestorage.com) zulässt.
Konnektivität: Prüfen Sie die allgemeine Netzwerkverbindung von der Maschine, auf der die Java-Anwendung läuft, zu den Diensten von Cloudflare (z. B. mit ping oder curl).

3. Performance-Optimierung

Parallele Übertragungen: Verwenden Sie das Flag --transfers N (z. B. --transfers 8) in Ihrem Rclone-Befehl, um mehrere Dateiübertragungen gleichzeitig durchzuführen. Das beschleunigt Vorgänge mit vielen kleinen Dateien erheblich. Fügen Sie dies der Liste command im Java-Code hinzu.
Downloads großer Dateien: --s3-chunk-size optimiert Multipart-Uploads und bewirkt daher für die Importrichtung nichts. Verwenden Sie für große Downloads --multi-thread-streams N zusammen mit --multi-thread-cutoff SIZE, wodurch eine einzelne große Datei auf mehrere Verbindungen verteilt wird.
Bandbreitenbegrenzung: Verwenden Sie bei Bedarf --bwlimit RATE (z. B. --bwlimit 10M für 10 MiB/s, gemessen in Byte statt in Bit), um die Bandbreitennutzung zu steuern.

4. Java-spezifische Probleme

Rclone nicht gefunden: Stellen Sie sicher, dass die ausführbare Datei rclone in der Umgebungsvariablen PATH des Systems liegt, auf die der Java-Prozess zugreifen kann, oder geben Sie den vollständigen Pfad zur ausführbaren Datei in der Befehlsliste von ProcessBuilder an.
Prozessverarbeitung: Lesen Sie die Ausgabe eines Subprozesses niemals in demselben Thread, der auch das Timeout durchsetzen muss. Leiten Sie die Ausgabe in eine Datei um (wie oben gezeigt) oder lesen Sie sie in einem separaten Thread aus; andernfalls blockiert ein hängendes Rclone den lesenden Thread und das Timeout ist nicht mehr erreichbar. redirectErrorStream(true) hält stderr im selben Stream.
Timeouts: Rufen Sie process.waitFor(timeout, unit) auf, bevor Sie auf die Ausgabe zugreifen, und lassen Sie auf ein destroyForcibly() nach Zeitüberschreitung ein einfaches waitFor() folgen, damit der Prozess wirklich beendet ist, bevor Sie fortfahren. Passen Sie die Timeout-Dauer an die erwartete Dauer des Vorgangs an.
Ressourcenbereinigung: Stellen Sie sicher, dass Ressourcen vom Typ Process korrekt behandelt werden, besonders in lang laufenden Anwendungen. Das Beispiel leitet die Ausgabe in eine temporäre Datei um und löscht sie in einem Block mit finally; außerdem ist es entscheidend, dass der Prozess beendet wird (mit waitFor oder destroyForcibly).

Fortgeschrittene Anwendungsbeispiele

Für eine lesbare Objektauflistung verwenden Sie den Befehl lsf von Rclone. Für maschinenlesbare Inventare verwenden Sie lsjson, werten Sie dessen JSON-Ausgabe aus und halten Sie stdout von den diagnostischen Ausgaben auf stderr getrennt. Die oben begrenzten Diagnoseausgaben sind kein Inventar. Eine erfolgreiche oder nicht leere Verzeichnisauflistung belegt nicht, dass eine bestimmte Datei existiert, und S3-kompatible Speicher können ein fehlendes Präfix nicht von einem leeren Verzeichnis unterscheiden. Verwenden Sie die Anfrage für Objekt-Metadaten des S3-kompatiblen SDK, wenn Sie exakt prüfen müssen, ob ein Objekt existiert; Authentifizierungs- und Netzwerkfehler müssen Fehler bleiben und dürfen nicht als Nichtvorhandensein gemeldet werden.

Bewährte Verfahren für die Sicherheit

Wenn Sie externe Tools wie Rclone integrieren und Cloud-Zugangsdaten in Anwendungen verarbeiten, die in Java geschrieben sind, räumen Sie der Sicherheit Priorität ein:

Zugangsdaten nicht fest im Code hinterlegen: Betten Sie Access Key ID oder Secret Access Key für Cloudflare R2 niemals direkt in Ihren Quellcode ein.
Zugangsdaten sicher speichern:
- Rclone-Konfigurationsdatei: Lassen Sie Rclone seine Standardkonfigurationsdatei (rclone.conf) verwenden, achten Sie aber darauf, dass die Datei selbst eingeschränkte Leserechte hat (z. B. chmod 600 ~/.config/rclone/rclone.conf). Das ist oft der einfachste Ansatz.
- Umgebungsvariablen: Konfigurieren Sie Rclone so, dass es Zugangsdaten aus Umgebungsvariablen liest. Ein so definiertes Remote benötigt neben den Schlüsseln auch seinen Typ und seinen Endpunkt, sonst meldet Rclone didn't find section in config file: Setzen Sie RCLONE_CONFIG_CLOUDFLARE_R2_TYPE=s3, RCLONE_CONFIG_CLOUDFLARE_R2_PROVIDER=Cloudflare, RCLONE_CONFIG_CLOUDFLARE_R2_ENDPOINT=https://<accountid>.r2.cloudflarestorage.com, RCLONE_CONFIG_CLOUDFLARE_R2_ACCESS_KEY_ID und RCLONE_CONFIG_CLOUDFLARE_R2_SECRET_ACCESS_KEY sicher in Ihrer Deployment-Umgebung.
- System zur Verwaltung von Secrets: Binden Sie ein dediziertes Tool für die Verwaltung von Secrets ein (etwa HashiCorp Vault, AWS Secrets Manager usw.), um Zugangsdaten zur Laufzeit abzurufen.
Prinzip der geringsten Rechte: Stellen Sie sicher, dass das von Rclone verwendete R2-API-Token nur die für seine Aufgaben minimal erforderlichen Berechtigungen hat (z. B. ausschließlich Lesezugriff, wenn nur Dateien importiert werden). Erstellen Sie eigene Token für einzelne Anwendungen.
Eingabevalidierung: Bereinigen Sie gegebenenfalls alle von Nutzern bereitgestellten Pfade oder Parameter, die beim Zusammenstellen von Rclone-Befehlen verwendet werden. Der Einsatz von ProcessBuilder mit einer Argumentliste (wie gezeigt) verringert das Risiko von Command Injection allerdings deutlich gegenüber dem Zusammenbauen eines einzelnen Befehlsstrings. Diese Beispiele verwenden vertrauenswürdige Anwendungskonfiguration. Rclone interpretiert dennoch Flags und Remote-Syntax. Prüfen Sie daher vom Aufrufer übergebene Pfade gegen das vorgesehene lokale Wurzelverzeichnis sowie das zulässige Remote und den zulässigen Bucket, bevor Sie Rclone aufrufen.
Fehlerbehandlung und Logging: Implementieren Sie eine robuste Fehlerbehandlung, die Fehler sicher protokolliert. Verwenden Sie in der Produktion ein richtiges Logging-Framework (etwa Log4j2, SLF4j/Logback) statt System.out.println oder e.printStackTrace(). Protokollieren Sie im Fehlerfall keine sensiblen Informationen wie vollständige Zugangsdaten oder detaillierte interne Pfade.

Hier ist der Ansatz mit Umgebungsvariablen in Java. Rclone liest RCLONE_CONFIG_<REMOTE>_* aus der Prozessumgebung, sodass das Remote ohne Konfigurationsdatei definiert wird und Secrets nie in argv auftauchen, wo jeder Nutzer auf dem Rechner sie aus ps auslesen könnte. Der folgende Codeblock ist eine weitere Methode für die oben gezeigte Klasse RcloneImporter und keine eigene Datei. Fügen Sie ihn in die Klasse ein; er nutzt deren Importe und Prozess-Runner. Diese Variante verwendet ein separates Remote namens r2 statt des zuvor verwendeten Remotes cloudflare_r2:

/**
 * Defines an R2 remote purely through Rclone's environment-variable configuration.
 *
 * <p>Rclone needs the type and endpoint as well as the keys. With only the credentials set it
 * reports {@code didn't find section in config file}.
 */
public static void importWithEnvConfig(String remotePath, String localPath)
        throws IOException, InterruptedException {
    String accessKey = System.getenv("R2_ACCESS_KEY_ID");
    String secretKey = System.getenv("R2_SECRET_ACCESS_KEY");
    String endpoint = System.getenv("R2_ENDPOINT");

    if (accessKey == null || secretKey == null || endpoint == null) {
        throw new IllegalStateException("Required R2 environment variables are not set.");
    }

    ProcessBuilder builder = new ProcessBuilder(
        "rclone", "copy", "r2:" + remotePath, localPath);

    Map<String, String> env = builder.environment();
    env.put("RCLONE_CONFIG_R2_TYPE", "s3");
    env.put("RCLONE_CONFIG_R2_PROVIDER", "Cloudflare");
    env.put("RCLONE_CONFIG_R2_REGION", "auto");
    env.put("RCLONE_CONFIG_R2_ENDPOINT", endpoint);
    env.put("RCLONE_CONFIG_R2_ACCESS_KEY_ID", accessKey);
    env.put("RCLONE_CONFIG_R2_SECRET_ACCESS_KEY", secretKey);

    RcloneResult result = runRclone(builder, Duration.ofMinutes(10));
    if (!result.succeeded()) {
        // The log can echo the endpoint, so keep it out of anything user-facing.
        throw new IOException("Rclone exited with code " + result.exitCode());
    }
}

Vermeiden Sie rclone config create mit Zugangsdaten als Argumenten: Diese landen in der Prozessliste und oft auch in der Shell-Historie und in CI-Logs.

Fazit und weitere Ressourcen

Die Integration von Cloudflare R2 in Java mithilfe von Rclone bietet eine robuste und effiziente Lösung für Aufgaben rund um file importing. Die Kombination vereint Flexibilität, Performance und die Kosteneffizienz der wegfallenden Egress-Gebühren von R2 für den Storage-Bedarf Ihrer Anwendung. Wenn Sie ProcessBuilder sorgfältig einsetzen und die Kommandozeilenoptionen von Rclone verstehen, können Sie leistungsfähige Interaktionen mit Cloud Storage in Ihre Java-Dienste einbauen.

Weitere Informationen finden Sie in diesen Ressourcen:

Wenn Sie eine vollständig verwaltete Lösung suchen, die die Komplexität von Cloud-Importen übernimmt: Transloadit bietet einen dedizierten 🤖 Cloudflare Import Robot als Teil unseres Dateiimport-Dienstes. Dieser Robot vereinfacht den Ablauf und unterstützt fortgeschrittene Funktionen wie rekursive Verzeichnisimporte, Steuerung der Paginierung, das Erzeugen von Datei-Stubs für die On-Demand-Verarbeitung und sichere Authentifizierung mit Template-Zugangsdaten. Transloadit stellt außerdem ein praktisches Java SDK bereit, das die Integration mit unserer Plattform vereinfacht.