Własny magazyn + CDN

Dostępne w: planach API Velocity i Momentum. Niedostępne w Ignite (nie ma CDN), w piaskownicy deweloperskiej (pliki w piaskownicy są tymczasowe) ani w planach WordPress (korzystają z zarządzanego CDN smallPict).

W skrócie: W trybie BYO smallPict zapisuje Twoje oryginały i zoptymalizowane obrazy w Twoim buckecie, a Twój CDN je dostarcza. Magazyn i CDN są zawsze podłączane razem: nie można użyć jednego bez drugiego.

Czym jest BYO

Velocity i Momentum mają dwa tryby dostarczania. Wybierasz jeden w Panel → CDN i magazyn.

• Zarządzany (domyślny): smallPict przechowuje Twoje oryginały w swoim szyfrowanym magazynie (po 90 dniach przenoszone do archiwum długoterminowego) i dostarcza zoptymalizowane obrazy z cdn.smallpict.app. Bez konfiguracji.
• Własny magazyn + CDN (BYO): podłączasz bucket zgodny z S3 na swoim koncie i CDN na swoim koncie. Każde nowe zadanie zapisuje oryginał i zoptymalizowany plik w Twoim buckecie, a API zwraca adresy URL w Twojej domenie CDN.

Zasada łączenia istnieje, ponieważ smallPict musi móc wykonać obie połowy dostarczania: zapisywać pliki i usuwać nieaktualne kopie z pamięci podręcznej. Bucket bez CDN nie miałby dokąd wysyłać czyszczenia pamięci podręcznej; CDN bez bucketu nie miałby czego dostarczać.

Tryb zarządzany a BYO

Obsługiwani dostawcy

Magazyn (dostępne już teraz): Amazon S3, Cloudflare R2, Google Cloud Storage (interoperacyjność S3), Alibaba Cloud OSS, Tencent Cloud COS, DigitalOcean Spaces, SumoPod Storage, MinIO oraz każda inna usługa zgodna z S3 przez własny endpoint (na przykład Hetzner, Vultr lub Wasabi).

CDN (dostępne już teraz): Cloudflare i Amazon CloudFront.

Planowane: Azure Blob Storage i inne CDN. O wcześniejszy dostęp możesz poprosić na stronie Dostawcy chmury.

Zanim zaczniesz

1. Masz plan API Velocity lub Momentum i jesteś zalogowany jako administrator konta.
2. Masz bucket oraz CDN, który dostarcza pliki z tego bucketu przez HTTPS.
3. Endpoint magazynu jest dostępny z internetu przez HTTPS. Endpointy prywatne, wewnętrzne i zwykłe HTTP są odrzucane.
4. Utworzyłeś dla smallPict klucze o wąskim zakresie (zobacz Minimalne uprawnienia poniżej). Nie używaj kluczy root ani kluczy administratora swojego konta.

Następnie otwórz Panel → CDN i magazyn, wybierz Własny magazyn + CDN, wypełnij obie części i wybierz Zapisz magazyn + CDN. smallPict wykonuje sprawdzenie połączenia (opisane poniżej) i przełącza Cię na BYO tylko wtedy, gdy zakończy się ono powodzeniem.

Przewodniki konfiguracji

A. Amazon S3 + Amazon CloudFront

1. Utwórz bucket w wybranym regionie, na przykład my-images w ap-southeast-1. Pozostaw włączone Block Public Access.
2. Utwórz dystrybucję CloudFront z bucketem jako originem. Użyj Origin access control (OAC), aby CloudFront mógł czytać bucket, który pozostaje prywatny, i zastosuj zasady bucketu proponowane przez CloudFront.
3. Opcjonalnie: własna domena. Dodaj do dystrybucji alternatywną nazwę domeny (na przykład images.example.com) i certyfikat, a następnie skieruj rekord DNS na dystrybucję.
4. Utwórz użytkownika IAM (lub rolę) dla magazynu z tymi zasadami:

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Action": [        "s3:PutObject",        "s3:GetObject",        "s3:DeleteObject"      ],      "Resource": "arn:aws:s3:::my-images/*"    }  ]}

5. Utwórz użytkownika IAM dla CloudFront (może to być ten sam użytkownik) z tymi zasadami. cloudfront:GetDistribution jest opcjonalne; dzięki niemu smallPict może wykryć domenę dystrybucji, gdy pozostawisz domenę CDN pustą.

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Action": [        "cloudfront:CreateInvalidation",        "cloudfront:GetDistribution"      ],      "Resource": "arn:aws:cloudfront::123456789012:distribution/E2QWRUHAPOMQZL"    }  ]}

6. W panelu:
   • Dostawca magazynu Amazon S3, bucket my-images, region ap-southeast-1, endpoint pusty (używany jest standardowy endpoint regionu) oraz access key ID i secret dla magazynu.
   • CDN Amazon CloudFront, Distribution ID (na przykład E2QWRUHAPOMQZL), access key ID i secret dla CloudFront oraz opcjonalnie domena CDN (https://images.example.com). Pozostaw domenę pustą, aby użyć własnej domeny dystrybucji *.cloudfront.net.

B. Cloudflare R2 + Cloudflare

1. Utwórz bucket R2, na przykład my-images.
2. Podłącz własną domenę do bucketu (R2 → Twój bucket → Settings → Custom Domains), na przykład images.example.com, w strefie na tym samym koncie Cloudflare. Żądania do tej domeny przechodzą przez pamięć podręczną Cloudflare. Nie używaj deweloperskiego adresu r2.dev w środowisku produkcyjnym.
3. Utwórz token API R2 (R2 → Manage API tokens) z uprawnieniem Object Read & Write, ograniczony tylko do tego bucketu. Skopiuj wyświetlone Access Key ID i Secret Access Key.
4. Utwórz token API Cloudflare (My Profile → API Tokens) dla strefy z uprawnieniem Zone → Cache Purge → Purge. Zone → Zone → Read jest opcjonalne.
5. W panelu:
   • Dostawca magazynu Cloudflare R2, bucket my-images, endpoint https://<account_id>.r2.cloudflarestorage.com (widoczny w szczegółach S3 API bucketu), region auto oraz R2 Access Key ID i Secret Access Key.
   • CDN Cloudflare, Zone ID (strona Overview domeny, sekcja API), token API i domena CDN https://images.example.com.

C. Google Cloud Storage + Cloudflare

Google Cloud Storage jest podłączany przez zgodne z S3 XML API z kluczami HMAC.

1. Utwórz bucket, na przykład my-images.
2. Utwórz konto usługi i nadaj mu rolę Storage Object User (roles/storage.objectUser) tylko dla tego bucketu.
3. Utwórz klucz HMAC dla konta usługi: Cloud Storage → Settings → Interoperability → Create a key for a service account. Skopiuj access ID i secret.
4. Udostępnij zoptymalizowane pliki swojemu CDN. Cloudflare pobiera pliki z Cloud Storage przez HTTPS, więc obiekty w optimized/ muszą być publicznie odczytywalne. Przy jednolitym dostępie na poziomie bucketu nadanie allUsers roli Storage Object Viewer sprawia, że odczytywalny jest cały bucket, łącznie z originals/. Jeśli oryginały muszą pozostać prywatne, umieść przed bucketem warstwę uwierzytelniającą (na przykład Cloudflare Worker, który podpisuje żądania do bucketu).
5. Skieruj proxowany rekord DNS Cloudflare na Cloud Storage, na przykład images.example.com. Nazwij bucket tak jak nazwę hosta i użyj proxowanego rekordu CNAME do c.storage.googleapis.com albo użyj Cloudflare Origin Rule, która wysyła żądania do storage.googleapis.com z nazwą bucketu na początku ścieżki.
6. Utwórz token API Cloudflare dla strefy z uprawnieniem Zone → Cache Purge → Purge (Zone → Zone → Read opcjonalnie).
7. W panelu: dostawca magazynu Google Cloud Storage, bucket, endpoint https://storage.googleapis.com, region auto, access ID i secret HMAC; CDN Cloudflare, Zone ID, token API i domena CDN https://images.example.com.

D. MinIO lub dowolny magazyn zgodny z S3 + Cloudflare

Dotyczy MinIO i usług zgodnych z S3, takich jak Hetzner, Wasabi, Vultr, SumoPod, Alibaba Cloud OSS, Tencent Cloud COS i DigitalOcean Spaces.

1. Utwórz bucket i klucz ograniczony do tego bucketu z uprawnieniami put, get i delete do obiektów (zobacz Minimalne uprawnienia poniżej).
2. Udostępnij optimized/ swojemu CDN do odczytu, na przykład za pomocą zasad bucketu, które zezwalają na anonimowe s3:GetObject tylko dla optimized/*. W MinIO:

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Principal": {        "AWS": [          "*"        ]      },      "Action": [        "s3:GetObject"      ],      "Resource": [        "arn:aws:s3:::my-images/optimized/*"      ]    }  ]}

3. Umieść Cloudflare przed bucketem: proxowany rekord DNS dla images.example.com, który wskazuje na publiczny host bucketu. Jeśli dostawca wymaga w żądaniu własnej nazwy hosta, dodaj Cloudflare Origin Rule, która przepisuje nagłówek Host (a w przypadku hostów path-style dodaje nazwę bucketu do ścieżki).
4. Utwórz token API Cloudflare dla strefy z uprawnieniem Zone → Cache Purge → Purge (Zone → Zone → Read opcjonalnie).
5. W panelu: wybierz dostawcę z tabeli, wpisz bucket, endpoint, region (auto, jeśli dostawca go nie ma) i klucze; włącz żądania path-style tam, gdzie wskazuje tabela; następnie CDN Cloudflare, Zone ID, token API i domena CDN.

Minimalne uprawnienia

Daj smallPict klucze, które mogą robić tylko to, co jest potrzebne, w jednym buckecie.

Sprawdzenie połączenia

Przy każdym zapisie (oraz po wybraniu Sprawdź ponownie) smallPict sprawdza całe połączenie, zanim zacznie z niego korzystać:

1. Magazyn: zapisuje mały plik testowy w .smallpict-probe/ w Twoim buckecie, odczytuje go i usuwa.
2. Cloudflare: wysyła do Twojej strefy jedno testowe czyszczenie pojedynczego adresu URL.
3. CloudFront: tworzy jedną testową invalidację dla ścieżki /.smallpict-probe/.... Wlicza się ona do ścieżek invalidacji CloudFront w danym miesiącu.

Jeśli którykolwiek krok się nie powiedzie, nic nie zostaje przełączone. Panel pokazuje przyczynę obok pola, którego dotyczy, na przykład nazwy bucketu lub tokenu API. Sprawdzenie połączenia jest ograniczone do 5 prób na minutę.

Dostęp CDN do bucketu

• optimized/ musi być odczytywalny dla Twojego CDN: albo publiczny odczyt dla tego prefiksu, albo dostęp originu CDN do prywatnego bucketu (CloudFront origin access control lub własna domena R2).
• originals/ może pozostać prywatny. Twój CDN nigdy go nie potrzebuje.
• CORS jest potrzebny tylko wtedy, gdy przeglądarki pobierają obrazy z innego originu z poziomu JavaScriptu (na przykład fetch() lub canvas). Zwykłe tagi <img> go nie potrzebują. Jeśli go potrzebujesz, zezwól na GET i HEAD z originu swojej witryny.

Układ obiektów i adresy URL

Domena CDN może zawierać prefiks ścieżki, na przykład https://example.com/images; adres URL ma wtedy postać https://example.com/images/optimized/<job_id>.<ext>.

Nagłówki pamięci podręcznej

Zoptymalizowane pliki są zapisywane z nagłówkiem Cache-Control: public, max-age=31536000, immutable. Każde zadanie otrzymuje unikalny klucz, więc nowy wynik zawsze ma nowy adres URL, a czyszczenie jest rzadko potrzebne. Nie pozwól, aby reguły pamięci podręcznej Twojego CDN nadpisywały ten nagłówek krótszym czasem.

Czyszczenie pamięci podręcznej

• Żądania czyszczenia wysyłane przez API (POST /v1/purge) trafiają w paczkach do Twojego CDN.
• W Cloudflare pliki są czyszczone według adresu URL. „Wyczyść wszystko” czyści tylko Twój host dostarczania i prefiks ścieżki, a nie całą strefę.
• W CloudFront pliki są czyszczone za pomocą invalidacji. „Wyczyść wszystko” tworzy invalidację /*. Ścieżki invalidacji ponad miesięczny darmowy limit CloudFront są rozliczane przez AWS na Twoim koncie.

Zmiana trybu

Zmiana trybu nie przenosi istniejących plików. Pliki już dostarczone zachowują obecne adresy URL; tylko nowe zadania korzystają z nowego trybu.

• Zarządzany → BYO: nowe zadania trafiają do Twojego bucketu i są dostarczane przez Twój CDN. Pliki, które już są w cdn.smallpict.app, pozostają tam.
• BYO → zarządzany: nowe zadania znów korzystają z zarządzanego magazynu i CDN. Twoje ustawienia BYO i klucze pozostają zapisane, ale nieużywane, więc możesz wrócić bez ponownego ich wpisywania, dopóki nie wybierzesz Odłącz.
• Odłącz: usuwa zapisane klucze i ustawienia BYO i przywraca tryb zarządzany. Pliki w Twoim buckecie pozostają nietknięte.

Gdy coś się nie powiedzie

• Jeśli smallPict nie może zapisać do Twojego bucketu, ponawia próbę, a następnie oznacza zadanie jako nieudane z przyczyną, którą możesz odczytać w odpowiedzi API.
• Panel pokazuje ostatni błąd i czas jego wystąpienia wraz z przyciskiem Sprawdź ponownie.
• Otrzymujesz jeden e-mail na incydent, a nie jeden na każde nieudane zadanie.
• smallPict nigdy nie przełącza się awaryjnie na zarządzany magazyn. Twoje pliki nigdy nie są przechowywane w miejscu, którego nie wybrałeś.

Bezpieczeństwo

• Klucze są przechowywane w szyfrowanym magazynie sekretów. Nigdy nie są ponownie wyświetlane, nigdy nie są zwracane przez API i nigdy nie są zapisywane w logach.
• Aby wymienić klucz, wpisz nowy i zapisz; sprawdzenie połączenia zostanie wykonane z nowym kluczem. Pozostaw pole klucza puste, aby zachować zapisany klucz.
• Endpointy magazynu i CDN muszą używać HTTPS. Endpointy, które wskazują na adresy prywatne, loopback, link-local lub inne adresy wewnętrzne, są odrzucane.
• Używaj dla smallPict osobnych kluczy o wąskim zakresie i unieważnij je w konsoli dostawcy, jeśli przestaniesz korzystać z BYO.