R2 storage from env + filename normalization
This commit is contained in:
+131
@@ -0,0 +1,131 @@
|
||||
# storage — media na Cloudflare R2
|
||||
|
||||
Offload mediów (obrazy, pliki) do Cloudflare R2 zamiast lokalnego dysku. R2 jest
|
||||
S3-kompatybilny; plugin dostarcza `buildR2Storage`, który czyta dane z `.env`
|
||||
i konfiguruje adapter.
|
||||
|
||||
> **Storage to infrastruktura, nie treść.** Dane R2 (klucze, bucket) idą do
|
||||
> `.env` — jak DATABASE_URI, PAYLOAD_SECRET, GRAPH_*. NIE do panelu (to sekrety
|
||||
> agencyjne, wiążą się przy starcie, nie zmienia ich redaktor).
|
||||
|
||||
## Zależność
|
||||
|
||||
```bash
|
||||
pnpm add @payloadcms/storage-s3
|
||||
```
|
||||
|
||||
## Zmienne .env
|
||||
|
||||
Patrz [R2-ENV-przyklad](../R2-ENV-przyklad.md) po pełną instrukcję skąd wziąć wartości.
|
||||
|
||||
```bash
|
||||
R2_BUCKET=nazwa-bucketa
|
||||
R2_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
|
||||
R2_ACCESS_KEY_ID=<access-key-id>
|
||||
R2_SECRET_ACCESS_KEY=<secret-access-key>
|
||||
```
|
||||
|
||||
## Wpięcie (payload.config.ts)
|
||||
|
||||
```ts
|
||||
import { buildR2Storage } from '@intecion/ipal-kit'
|
||||
|
||||
export default buildConfig({
|
||||
// ...
|
||||
plugins: [
|
||||
ipalKit({ /* ... */ }),
|
||||
buildR2Storage(['media']), // slugi kolekcji upload do offloadu
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
`buildR2Storage` przyjmuje listę kolekcji upload (domyślnie `['media']`). Jeśli
|
||||
masz więcej kolekcji plików: `buildR2Storage(['media', 'documents'])`.
|
||||
|
||||
## Zachowanie (fallback)
|
||||
|
||||
- **Wszystkie 4 zmienne** → media w R2.
|
||||
- **Brak zmiennych** → fallback na lokalny dysk (dev działa bez R2, zero konfiguracji).
|
||||
- **Część zmiennych** → ostrzeżenie w logu + fallback (częściowa konfiguracja =
|
||||
pewnie pomyłka).
|
||||
|
||||
To wzorzec „degrade gracefully" — jak mailAdapter, który wraca do SMTP, gdy brak
|
||||
Graph. Projekt działa niezależnie od tego, czy R2 jest skonfigurowany.
|
||||
|
||||
## Publiczny dostęp (WAŻNE)
|
||||
|
||||
R2 domyślnie prywatny. Upload zadziała, ale obrazy się NIE wyświetlą (403), dopóki
|
||||
nie skonfigurujesz publicznego odczytu:
|
||||
|
||||
1. Cloudflare → R2 → bucket → Settings → **Public access** → podłącz custom domain
|
||||
2. Albo serwuj przez Cloudflare CDN / własną domenę
|
||||
|
||||
Bez tego media wgrają się do R2, ale front nie pokaże obrazów. Konfiguracja domeny
|
||||
jest po stronie Cloudflare, nie kodu.
|
||||
|
||||
## Migracja istniejących mediów
|
||||
|
||||
Jeśli projekt miał media lokalnie i przełączasz na R2 — nowe uploady idą do R2,
|
||||
ale STARE zostają na dysku (i znikną przy redeployu bez wolumenu). Przed
|
||||
przełączeniem na produkcji przenieś istniejące pliki do bucketa (np. `rclone`
|
||||
albo ręcznie przez R2 dashboard), inaczej stare obrazy znikną.
|
||||
|
||||
## Weryfikacja
|
||||
|
||||
```bash
|
||||
# po wpięciu i ustawieniu .env:
|
||||
pnpm dev
|
||||
# wgraj obraz w panelu (Media) → sprawdź w Cloudflare R2, czy plik się pojawił
|
||||
```
|
||||
|
||||
## Dev na lokalnym I na R2 (seedowanie podczas developmentu)
|
||||
|
||||
Fallback (brak zmiennych → lokalny dysk) oznacza, że **dev działa w obu trybach**:
|
||||
|
||||
- **Dev bez R2 w .env** → media na lokalnym dysku. Szybki start, zero konfiguracji.
|
||||
- **Dev z R2 w .env** → media w R2 już podczas developmentu. Przydatne, gdy
|
||||
seedujesz treść w devie i chcesz, żeby od razu lądowała w buckecie (np. wspólny
|
||||
bucket dev, albo test realnego flow przed produkcją).
|
||||
|
||||
Przełączasz trybem po prostu obecnością zmiennych R2 w `.env`. Ten sam kod,
|
||||
`buildR2Storage` sam wykrywa. Nie musisz nic zmieniać w configu między trybami.
|
||||
|
||||
> Jeśli seedujesz w devie do R2 — pamiętaj, że to realny bucket. Używaj osobnego
|
||||
> bucketa dev (nie produkcyjnego), żeby nie mieszać danych testowych z realnymi.
|
||||
|
||||
## Normalizacja nazw plików (automatyczna)
|
||||
|
||||
Plik `normalizeFilenameHook` czyści nazwy wgrywanych plików — slugifikuje nazwę,
|
||||
zachowuje rozszerzenie:
|
||||
|
||||
```
|
||||
"Zdjęcie jeden nad morzem.jpg" → "zdjecie-jeden-nad-morzem.jpg"
|
||||
"Faktura #12 (2024).PDF" → "faktura-12-2024.pdf"
|
||||
```
|
||||
|
||||
Wpięcie w kolekcję Media (projekt):
|
||||
|
||||
```ts
|
||||
import { normalizeFilenameHook } from '@intecion/ipal-kit'
|
||||
|
||||
export const Media: CollectionConfig = {
|
||||
slug: 'media',
|
||||
upload: { staticDir: 'media' /* ... */ },
|
||||
hooks: {
|
||||
beforeOperation: [normalizeFilenameHook], // czyści nazwę przed zapisem
|
||||
},
|
||||
fields: [ /* alt itd. */ ],
|
||||
}
|
||||
```
|
||||
|
||||
Działa z lokalnym dyskiem i z R2/S3 (hook biegnie PRZED warstwą storage, więc
|
||||
czysta nazwa trafia i do bazy, i do bucketa). Dlaczego to ważne:
|
||||
|
||||
- **URL-e mediów są czyste** — `/media/zdjecie-nad-morzem.jpg`, nie
|
||||
`/media/Zdjęcie%20jeden%20nad%20morzem.jpg` (spacje/diakrytyki w URL = problemy).
|
||||
- **Przenośność** — nazwa bez polskich znaków/spacji działa wszędzie (CDN, S3, systemy plików).
|
||||
- **Bez kolizji kodowania** — spacje i `#`, `()` w nazwach plików potrafią psuć
|
||||
ścieżki i cache.
|
||||
|
||||
Sama funkcja `normalizeFilename(name)` też jest wyeksportowana, gdybyś potrzebował
|
||||
jej poza hookiem.
|
||||
Reference in New Issue
Block a user