S3-Storage für Laravel: So integrieren Sie Backblaze B2 mit Flysystem
Cloud-Speicher mit S3-Protokoll sind flexibel, skalierbar und weit verbreitet, jedoch oft teuer. Backblaze B2 bietet eine kostengünstige Alternative mit hoher Verfügbarkeit. Dank der S3-Kompatibilität lässt es sich nahtlos in Laravel mit Flysystem integrieren. Kürzlich führte eine API-Änderung jedoch zu Problemen, die sich mit einer kleinen Anpassung schnell beheben lassen.
Flysystem ist eine Abstraktionsbibliothek für Laravel, die den Zugriff auf verschiedene Speicherlösungen wie lokale Festplatten, S3 oder Backblaze B2 vereinheitlicht. Dadurch lassen sich Speicheranbieter flexibel wechseln, ohne den Code anzupassen. Vorteile sind eine einfache Konfiguration, einheitliche API-Methoden und breite Unterstützung für Cloud- und lokale Speicher.
Renick Büttner
Senior Software Engineer & IT-Sachverständiger
Probleme mit Backblaze und der S3-Kompatibilität in Laravel Flysystem
Backblaze B2 ist bisher stets zuverlässig und unkompliziert für uns gewesen. Dies macht den Dienst zu einer attraktiven Alternative zu AWS S3, insbesondere für Laravel-Entwickler, die das Flysystem-Storage-Interface nutzen. Doch kürzlich hat Backblaze eine Änderung an seiner API vorgenommen, die zu unerwarteten Integrationsproblemen mit S3-Treibern führte – darunter auch Laravel Flysystem.
Das Problem: Abgelehnte Anfragen durch neue API-Restriktionen
Die Änderungen an der Backblaze API führten dazu, dass bestimmte Anfragen mit einem 400 Bad Request-Fehler abgelehnt wurden. Dies geschieht insbesondere dann, wenn eine Anfrage bestimmte Checksum-Header enthält.
InvalidArgument (client): Unsupported header 'x-amz-checksum-crc32' received for this API call.
Unsupported header 'x-amz-checksum-crc32' received for this API call.
Die folgenden Header werden von Backblaze nun standardmäßig blockiert:
-
x-amz-checksum-crc32
-
x-amz-checksum-crc32c
-
x-amz-checksum-crc64nvme
-
x-amz-checksum-sha1
-
x-amz-checksum-sha256
-
x-amz-checksum-algorithm
Da Laravel Flysystem automatisch mit der S3-Kompatibilität arbeitet, kann es dazu kommen, dass diese Header von der Laravel-Storage-Schicht an Backblaze gesendet werden – was wiederum die Fehlermeldung 400 Bad Request verursacht.
Die schnelle Lösung:
Anpassung der Flysystem-Konfiguration
Glücklicherweise lässt sich dieses Problem innerhalb weniger Sekunden beheben. Laravel Flysystem bietet zwei Konfigurationsparameter, die genau diese Checksum-Berechnung steuern. Durch eine einfache Anpassung in der Storage-Konfiguration können wir sicherstellen, dass diese Header nur dann gesendet oder überprüft werden, wenn es erforderlich ist.
Fügen Sie dazu in Ihrer config/filesystems.php die folgenden Optionen innerhalb des S3-Adapters hinzu:
'request_checksum_calculation' => 'when_required',
'response_checksum_validation' => 'when_required',
Diese beiden Parameter sorgen dafür, dass Laravel nicht unnötig Checksum-Header sendet oder überprüft, was die Kompatibilität mit Backblaze B2 wiederherstellt. Nach dieser Anpassung sollten alle Datei-Uploads und -Downloads mit Backblaze als S3-Storage wieder reibungslos funktionieren.
Wie sieht die vollständige Integration von B2 in Flysystem aus?
Die vollständige Integration kann wie folgt aussehen. Einmal eine Beispielkonfiguration für config/filesystems.php:
<?php
return [
/*
|--------------------------------------------------------------------------
| Default Filesystem Disk
|--------------------------------------------------------------------------
|
| Here you may specify the default filesystem disk that should be used
| by the framework. A "local" driver, as well as a variety of cloud
| based drivers are available for your choosing. Just store away!
|
*/
'default' => env('FILESYSTEM_DRIVER', 'local'),
/*
|--------------------------------------------------------------------------
| Filesystem Disks
|--------------------------------------------------------------------------
|
| Here you may configure as many filesystem "disks" as you wish, and you
| may even configure multiple disks of the same driver. Defaults have
| been setup for each driver as an example of the required options.
|
| Supported Drivers: "local", "ftp", "sftp", "s3"
|
*/
'disks' => [
/* your other disks... */
'backblaze_bucket' => [
'driver' => 's3',
'key' => env('B2_ACCESS_KEY_ID'),
'secret' => env('B2_SECRET_ACCESS_KEY'),
'region' => env('B2_DEFAULT_REGION'),
'bucket' => env('B2_BUCKET'),
'url' => env('B2_URL'),
'endpoint' => env('B2_ENDPOINT'),
'use_path_style_endpoint' => env('B2_USE_PATH_STYLE_ENDPOINT', false),
'throw' => env('B2_THROW_ERROR', true),
'request_checksum_calculation' => 'when_required',
'response_checksum_validation' => 'when_required',
],
],
];
Die dazugehörigen Umgebungsvariablen könnten wie folgt aussehen:
B2_ACCESS_KEY_ID="xxxxxxxxxxxxxxxx"
B2_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxx"
B2_DEFAULT_REGION=us-west-000
B2_BUCKET=your-bucket-slug
B2_ENDPOINT=https://s3.us-west-004.backblazeb2.com
B2_URL=https://your-bucket-slug.s3.us-west-004.backblazeb2.com/
