Strapi S3 upload provider: vlastní endpoint a path-style

Aby Strapi posílalo nahrané soubory do S3-kompatibilního úložiště, které nepatří Amazonu, nainstaluj @strapi/provider-upload-aws-s3, nastav provider: 'aws-s3' v config/plugins.js a do providerOptions.s3Options dej čtyři věci: přihlašovací údaje, název regionu, endpoint úložiště a forcePathStyle: true. Přidej params.Bucket pro bucket a baseUrl pro adresu, ze které budou prohlížeče soubory načítat. To je celá konfigurace. Skoro každá porucha potom vzniká na jednom ze tří míst: styl adresování (SDK sestaví název hostitele, který neexistuje), veřejná URL (soubory se nahrají, ale nezobrazí se) nebo seznam řízení přístupu, který se posílá s každým nahráním (úložiště ho odmítne). Tento článek provider nastaví pořádně, vysvětlí každý klíč a pak projde chyby v pořadí, v jakém na ně pravděpodobně narazíš.

Předpokládáme, že Strapi už běží. K ostatním rozhodnutím pro produkci - tajné klíče, databáze, build administrace, aktualizace - se podívej do článku Strapi v produkci, který stejný provider popisuje v jedné sekci. Tento článek je dlouhá verze té sekce.

Co upload provider dělá#

Plugin Upload ve Strapi je kód, na kterém stojí Media Library a endpoint /api/upload. Plugin soubory sám neukládá. Každý soubor předá provideru, malému balíčku se třemi úkoly: nahrát buffer, nahrát stream a smazat. Výchozí provider zapisuje do public/uploads na disku serveru. Provider pro S3 místo toho zapisuje do bucketu.

Cesta, kterou soubor urazí, je důležitá pro hledání chyb, takže si ji pamatuj:

1. Editor přetáhne soubor do Media Library. Prohlížeč ho pošle do Strapi, ne do bucketu.
2. Strapi přijme multipart požadavek, přečte soubor a u obrázků vytvoří další velikosti (varianty thumbnail_, small_, medium_ a large_ podle tvých breakpointů).
3. Pro každý soubor a každou variantu provider pošle z procesu Strapi na endpoint jeden požadavek S3 PutObject.
4. Strapi uloží výslednou veřejnou URL do databáze, do pole url záznamu o souboru.
5. Když stránka nebo administrace zobrazí obrázek, prohlížeč tuto URL načte přímo z úložiště. Strapi v té cestě není.

Plynou z toho dva závěry. Zaprvé, pro nahrávání nepotřebuješ žádné nastavení CORS na bucketu, protože do něj prohlížeč nikdy nezapisuje; CORS má smysl, až když později přidáš přímé nahrávání z prohlížeče přes presigned URL (viz presigned URL v S3). Zadruhé, server se Strapi musí dosáhnout na endpoint úložiště a tví návštěvníci na adresu, na kterou ukazuje baseUrl. Mohou to být dvě různé adresy a držet je od sebe je většina konfigurace.

Co potřebuješ od úložiště#

Než se dotkneš Strapi, zjisti ze svého S3-kompatibilního úložiště pět hodnot:

Na regionu lidé váznou nejčastěji. Amazon podle něj vybírá datové centrum a sestavuje podpis požadavku. Úložiště, které není od Amazonu, žádný region k výběru nemá, ale SDK hodnotu přesto vyžaduje, protože podpis region obsahuje. Pravidlo zní: použij to, co úložiště uvádí, a pokud neuvádí nic, na většině funguje jakýkoli rozumně vypadající název, třeba us-east-1. Důležité je, aby se všude, odkud k úložišti přistupuješ, použil stejný řetězec. Proč tomu tak je, vysvětluje článek S3 path-style vs virtual-hosted URL a regiony.

Hodnoty si nejdřív vyzkoušej něčím jiným než Strapi. Když AWS CLI nedokáže bucket vypsat, Strapi ho také nezvládne a CLI hlásí chybu mnohem srozumitelněji. Řekni CLI, ať použije adresování path-style, a vypiš obsah:

$ aws configure set default.s3.addressing_style path$ export AWS_ACCESS_KEY_ID=...$ export AWS_SECRET_ACCESS_KEY=...$ aws --endpoint-url https://s3.example.com --region us-east-1 s3 ls s3://strapi-media/

Prázdný bucket nevypíše nic a skončí bez chyby, což je úspěch. Špatný klíč vrátí InvalidAccessKeyId nebo SignatureDoesNotMatch; špatný bucket NoSuchBucket. Úplný přehled příkazů, pokud chceš jít dál, najdeš v článku úložiště S3 a AWS CLI.

Instalace provideru#

Ze složky projektu Strapi:

$ npm install @strapi/provider-upload-aws-s3

I přes název je to provider pro jakoukoli službu kompatibilní s S3. Žádný samostatný „obecný S3“ balíček od Strapi neexistuje. Komunitní providery pro konkrétní dodavatele existují, ale pro endpoint, který ovládáš, je lepší ten oficiální, protože sleduje vydání Strapi. Hlavní verze provideru má odpovídat hlavní verzi Strapi; balíček se vydává se stejným číslováním jako Strapi samotné a provider ze starší hlavní verze je častou příčinou matoucích chyb po aktualizaci. Nainstalovanou verzi zjistíš příkazem npm ls @strapi/provider-upload-aws-s3 a porovnáš ji s verzí @strapi/strapi v package.json.

Konfigurace klíč po klíči#

Vytvoř nebo uprav config/plugins.js (nebo config/plugins.ts v projektu v TypeScriptu, kde je struktura stejná, jen s export default):

module.exports = ({ env }) => ({  upload: {    config: {      provider: 'aws-s3',      providerOptions: {        baseUrl: env('S3_PUBLIC_URL'),        rootPath: env('S3_ROOT_PATH', ''),        s3Options: {          credentials: {            accessKeyId: env('S3_ACCESS_KEY_ID'),            secretAccessKey: env('S3_SECRET_ACCESS_KEY'),          },          region: env('S3_REGION', 'us-east-1'),          endpoint: env('S3_ENDPOINT'),          forcePathStyle: true,          params: {            Bucket: env('S3_BUCKET'),          },        },      },      actionOptions: {        upload: {},        uploadStream: {},        delete: {},      },    },  },});

Názvy uvnitř env() si volíš sám; struktura kolem nich je pevná. Co který klíč dělá:

Vše pod s3Options se předává konstruktoru S3Client z AWS SDK for JavaScript v3, proto názvy odpovídají dokumentaci samotného SDK. To je užitečné vědět: do s3Options může přijít jakákoli volba, kterou klient SDK přijímá, včetně voleb kontrolních součtů, o kterých je řeč níže.

O rootPath je třeba říct pár slov. Bez něj objekty končí v kořeni bucketu s vygenerovaným klíčem jako thumbnail_cat_4f2a1b.jpg. S rootPath: 'cms' se klíč změní na cms/thumbnail_cat_4f2a1b.jpg. Vyplatí se ho nastavit, pokud bucket sdílíš s něčím dalším, a hned první den to nic nestojí. Pozdější změna existující objekty nepřesune a uložené URL dál ukazují na staré klíče.

Proměnné prostředí#

Přihlašovací údaje nech mimo konfigurační soubor, v .env ve složce projektu vedle tajných klíčů Strapi:

S3_ENDPOINT=https://s3.example.comS3_REGION=us-east-1S3_BUCKET=strapi-mediaS3_ACCESS_KEY_ID=...S3_SECRET_ACCESS_KEY=...S3_PUBLIC_URL=https://s3.example.com/strapi-mediaS3_ROOT_PATH=

Tento soubor nikdy necommituj. Strapi čte .env při startu, takže po úpravě server restartuj; build administrace není potřeba, protože tyto hodnoty používá serverový proces, ne balíček v prohlížeči. Návyky, které drží .env mimo repozitář, popisuje článek proměnné prostředí a tajné klíče. Pokud Strapi hostuješ na RE:NODE, správce souborů i SFTP se dostanou do složky projektu, takže soubor můžeš upravit v prohlížeči - viz SFTP a správce souborů.

Jeden detail, na kterém se zakopává: prázdná hodnota jako S3_ROOT_PATH= je prázdný řetězec a env('S3_ROOT_PATH', '') ho tak vrátí. Tady to nevadí. Ale prázdné S3_ENDPOINT= je také prázdný řetězec, který SDK bere jako žádný endpoint, a požadavky tiše posílá Amazonu. Pokud nahrávání selhává se zprávou InvalidAccessKeyId od úložiště, které tvůj klíč nikdy neslyšelo, zkontroluj, že je proměnná opravdu nastavená a pojmenovaná tak, jak ji čte konfigurace.

Proč path-style a co se stane bez něj#

Z endpointu a bucketu sestaví AWS SDK jednu ze dvou URL. Virtual-hosted, výchozí, dává bucket do názvu hostitele: https://strapi-media.s3.example.com/cat.jpg. Path-style ho dává do cesty: https://s3.example.com/strapi-media/cat.jpg. Virtual-hosted potřebuje DNS záznam pro každý název bucketu a certifikát, který je pokryje všechny. Úložiště za jediným názvem hostitele nemá ani jedno, takže výchozí chování SDK vyrobí název, který se nevyřeší.

Porucha je rozpoznatelná. Když forcePathStyle chybí nebo je false, log Strapi při prvním nahrání ukáže něco takového:

error: getaddrinfo ENOTFOUND strapi-media.s3.example.com

Podívej se na název hostitele ve zprávě. Pokud začíná názvem tvého bucketu, SDK používá virtual-hosted a opravou je forcePathStyle: true v s3Options. Pokud je název hostitele prostě s3.example.com a chyba je jiná, adresování je v pořádku a problém je jinde. Tato jediná kontrola odstraní polovinu hádání.

Existuje i jemnější verze. Úložiště s wildcard DNS a wildcard certifikátem může virtual-hosted požadavky přijímat a nahrávání bez tohoto nastavení bude fungovat. Pokud později přejdeš na úložiště, které to nedovoluje, stejná konfigurace přestane fungovat. Nastav forcePathStyle: true tak či tak; path-style funguje na každém S3-kompatibilním úložišti včetně Amazonu, který ho u existujících bucketů stále přijímá.

baseUrl: proč se soubory nahrají, ale nezobrazí#

Provider zapisuje objekty přes endpoint, ale URL, kterou ukládá do databáze, se sestavuje z baseUrl. Jsou oddělené záměrně, protože adresa, na kterou zapisuješ, často není adresa, ze které chceš soubory zpřístupnit světu. CDN, proxy s hezčím názvem hostitele nebo veřejná cesta na stejném hostiteli jsou běžné případy.

Pokud baseUrl není nastavena, provider sestaví URL podle toho, kde SDK bucket předpokládá. S vlastním endpointem a adresováním path-style je to obvykle endpoint plus bucket, což může být správně, ale může to být i adresa, na kterou dosáhne jen server Strapi, například interní nebo přes prosté HTTP. Explicitní baseUrl hádání odstraní.

Při adresování path-style obsahuje základní URL bucket: https://s3.example.com/strapi-media. Uložená URL je pak základ plus klíč, takže soubor uložený jako thumbnail_cat_4f2a1b.jpg se servíruje z https://s3.example.com/strapi-media/thumbnail_cat_4f2a1b.jpg. Otevři tuto adresu v anonymním okně prohlížeče, bez přihlašovacích údajů, a podívej se, jestli se obrázek načte. Tento jediný test rozliší tři běžné poruchy:

• Prohlížeč varuje před smíšeným obsahem nebo obrázek zablokuje. Administrace běží na HTTPS a uložená URL je prosté http://. Prohlížeče blokují HTTP obrázky na stránce s HTTPS. Použij v baseUrl název s HTTPS.
• URL vrací `403` nebo `AccessDenied`. Objekt existuje, ale anonymní čtení není povoleno. Viz další sekce.
• URL vrací `404` nebo `NoSuchKey`. URL neodpovídá klíči. Zkontroluj rootPath a zda je název bucketu v baseUrl.

Media Library má ještě čtvrtý, pro Strapi specifický způsob selhání: soubory se načtou na nové kartě, ale náhledy v administraci jsou rozbité. To je vlastní Content Security Policy Strapi, která odmítá obrázky z hostitele, o kterém neví, a oprava je v config/middlewares.js. Průvodce Strapi v produkci obsahuje přesný blok strapi::security s img-src a media-src; přidej do obou hostitele ze své baseUrl.

Veřejné a soukromé soubory a ACL#

Provider ve výchozím stavu nahrává každý objekt s ACL public-read, díky čemuž odkazy z baseUrl fungují pro anonymní návštěvníky. U obrázků marketingového webu je to správné chování. Pro cokoli, co veřejné být nemá, je špatné a úložiště ho navíc může odmítnout.

ACL je hlavička s oprávněním pro jednotlivý objekt, která se posílá spolu s PutObject. Amazon od nich ustupuje: nové buckety Amazonu ACL ve výchozím stavu blokují a spoléhají na bucket policy. Některá S3-kompatibilní úložiště je nikdy neimplementovala a na nahrání s ACL odpoví AccessControlListNotSupported nebo obecným NotImplemented. Pokud nahrávání selhává kvůli ACL a přihlašovací údaje jsou v pořádku, je to příčina. Provider čte ACL z params, takže ji tam řídíš:

params: {  ACL: 'private',  signedUrlExpires: 15 * 60,  Bucket: env('S3_BUCKET'),},

S ACL: 'private' nejsou objekty anonymně čitelné a provider přepne na podepsané URL: když Strapi vrací soubor v odpovědi API, podepíše URL s omezenou platností a vrátí ji místo prosté. signedUrlExpires je platnost v sekundách. Dvě praktické poznámky:

• Podepsané URL vyprší, takže stránka, která cachuje odpověď API déle než signedUrlExpires, bude ukazovat rozbité obrázky. Slaď dobu cache s platností podpisu, nebo nech bucket veřejný pro soubory, které patří na veřejné stránky.
• Podpis pokrývá název hostitele. Podepsaná URL se sestavuje z endpoint, takže ten endpoint musí být dostupný z prohlížeče návštěvníka. Interní adresa, která funguje pro server Strapi, podepíše URL, které nikdo jiný neotevře. Proč, vysvětlují presigned URL v S3.

Zda dokáže konkrétní úložiště zpřístupnit bucket nebo cestu ke čtení bez ACL, je vlastnost úložiště, ne Strapi: některá používají bucket policy, některá mají přepínač „public“ pro bucket, některá ani jedno. Zjisti, co podporuje to tvoje, a než editorům řekneš, že je hotovo, otestuj anonymní přístup příkazem curl -I na nahraném souboru. Totéž platí pro úložiště, které ACL odmítá: pokud nemůžeš poslat ACL public-read ani nastavit policy, fungující cestou jsou podepsané URL s ACL: 'private'. Přesné chování při null nebo vynechané ACL najdeš v README provideru pro svou nainstalovanou verzi, protože se mezi vydáními měnilo.

Kontrolní součty při nahrávání v novějších verzích SDK#

Provider je postavený na AWS SDK for JavaScript v3. Od začátku roku 2025 SDK ve výchozím stavu přidává k nahrávání kontrolní součet založený na CRC. Některé S3-kompatibilní servery tyto hlavičky navíc nepřijímají a porucha vypadá podivně: Media Library objekty bez problému vypíše, bez problému smaže, ale každé nahrání selže s SignatureDoesNotMatch, MissingContentLength nebo stížností na kontrolní součty či x-amz-content-sha256.

Klient SDK má dvě volby, které nové chování omezí na „jen když to operace vyžaduje“. Protože se s3Options předává přímo klientovi, patří sem:

s3Options: {  credentials: { /* ... */ },  region: env('S3_REGION', 'us-east-1'),  endpoint: env('S3_ENDPOINT'),  forcePathStyle: true,  requestChecksumCalculation: 'WHEN_REQUIRED',  responseChecksumValidation: 'WHEN_REQUIRED',  params: { Bucket: env('S3_BUCKET') },},

Přidej je, jen když vidíš tento příznak: existují ve vydáních SDK od začátku roku 2025 a starší SDK neznámé volby ignoruje. Pokud tvůj nainstalovaný provider tahá starší SDK, čistší je provider aktualizovat. Stejný problém se objevuje u klienta příkazové řádky i u jiných SDK a S3 z Node.js a Pythonu ukazuje odpovídající nastavení tam. Užitečné vodítko: pokud aws s3 cp s tímto endpointem funguje a Strapi ne, porovnej nejdřív verze CLI a SDK.

Test a kontrola, co se opravdu stalo#

Když je konfigurace na místě, restartuj Strapi a nahraj jeden obrázek přes Media Library. Kontroluj v tomto pořadí:

1. Log serveru. Spusť Strapi v terminálu nebo čti konzoli v panelu. Každá chyba provideru se zapíše v okamžiku nahrávání se skutečnou zprávou. Nevěř obecnému upozornění „Internal Server Error“ v administraci.
2. Bucket. Vypiš ho přes CLI. Měl bys vidět originál a u obrázků varianty thumbnail_, small_, medium_ a large_, každou jako samostatný objekt. Použij aws --endpoint-url https://s3.example.com s3 ls s3://strapi-media/ jako dříve.
3. URL. Klikni v Media Library na soubor, zkopíruj jeho odkaz a otevři ho v anonymním okně.
4. Smazání. Smaž testovací soubor v administraci a vypiš obsah znovu. Volání delete provideru odstraní originál i všechny varianty; pokud nějaké objekty zůstaly, přihlašovací údaje pravděpodobně nemají právo mazat, což snadno přehlédneš, když byl klíč vytvořen jen pro zápis.

Krok 4 je ten, který lidé vynechávají. Klíč, který smí zapisovat, ale ne mazat, nechává v bucketu sirotky, které nikdo nevidí, dokud je neukáže účet nebo kvóta.

Přesun souborů, které už máš#

Změna provideru nic nepřesouvá. Dříve nahrané soubory mají v databázi stále URL /uploads/... a stále leží v public/uploads. Jsou tři poctivé možnosti:

• Nechat je. Nech public/uploads na disku serveru a nové soubory posílej do bucketu. Staré odkazy fungují, dokud složka existuje. Je to nejméně riskantní volba a pro malou knihovnu stačí.
• Zkopírovat a přepsat. Synchronizuj public/uploads do bucketu nástrojem jako rclone nebo AWS CLI (viz rclone a úložiště S3) a pak aktualizuj url (a URL jednotlivých formátů ve sloupci JSON formats) v tabulce files na novou základnu. Je to změna databáze, takže nejdřív udělej backup Strapi a vyzkoušej to na kopii. Skutečné názvy sloupců zjisti ze svého schématu, ne z návodu.
• Export a import. Příkazy strapi export a strapi import přesouvají obsah a se správnými přepínači i média. Je to podporovaná cesta mezi prostředími, ale než na ni při migraci spolehneš, ověř, že import ve tvé verzi zapisuje přes nakonfigurovaný provider.

Ať zvolíš cokoli, dělej to v klidné hodině a nech si backup databáze i public/uploads, dokud se na výsledek nepodíváš v administraci. Migrace, kterou ověřilo jen nahrání nového obrázku, ty staré neotestovala.

Jak udržet bucket a databázi v souladu#

Jakmile nahrávané soubory žijí v bucketu, databáze a bucket jsou dvě věci, které se musí shodovat. Backup jednoho bez druhého dá buď záznamy bez souborů, nebo soubory bez záznamů.

• Backup Strapi (kopie databáze nebo strapi export) drží odkazy. Obrázky v něm nejsou.
• Kopie bucketu drží obrázky. Neví, které se používají.
• Obnovuj obojí ze stejného dne, nebo se smiř s tím, že některé záznamy budou ukazovat na chybějící soubory.

Bucket má i vlastní odolnost, nad kterou se vyplatí zamyslet. Pokud úložiště drží jednu kopii na jednom místě, není to backup ničeho; je to primární kopie a potřebuje vlastní backup. Jak to dimenzovat, čti v článku pravidlo 3-2-1 pro úložiště S3 a jak ho pořídit, v článku restic a backup do S3.

Strapi s tarifem S3 na RE:NODE#

Na RE:NODE je Strapi aplikace na jedno kliknutí na stránce hostingu aplikací, instaluje se a builduje při prvním startu serveru s daty v SQLite na serveru. Tarif objektového úložiště S3 je samostatný server, který poskytuje to, co tento článek potřebuje: S3-kompatibilní endpoint, přístupový a tajný klíč vygenerované pro ten server a už vytvořený první bucket. Používá adresování path-style a přijímá libovolný název regionu, takže správné hodnoty jsou forcePathStyle: true a region jako us-east-1. Endpoint odpovídá přes prosté HTTP na vlastním portu a HTTPS jde přes slot proxy tarifu: nasměruj název hostitele na zobrazenou adresu a certifikát se vystaví a obnovuje sám. Tento název s HTTPS použij v endpoint i baseUrl, jinak administrace obrázky zablokuje jako smíšený obsah.

Tarify S3 nemají sloty pro backup a úložiště je jedna kopie na NVMe na jednom místě, bez replikace. Pro média, která lze znovu vytvořit, to stačí, a u všeho nenahraditelného je důvod kopírovat to ještě jinam. Sloty pro backup serveru Strapi pokrývají složku projektu a soubor SQLite, ne bucket. Zda funguje anonymní čtení bucketu a jak ho zapnout, za tebe tento článek slíbit nemůže; otestuj nahraný soubor v anonymním okně, jak je popsáno výše.

Řešení potíží#

Několik poznámek, které se do tabulky nevejdou. SignatureDoesNotMatch u každého požadavku znamená, že přihlašovací údaje jsou špatné, nebo že se podpis cestou rozbíjí; obvyklým viníkem cestou je reverzní proxy před úložištěm, která nepředává původní hlavičku Host, protože ji podpis pokrývá. Pokud se to děje jen při nahrávání, mysli na kontrolní součty dřív než na přihlašovací údaje.

U 413 je limit nastavením proxy, která stojí před Strapi. Nahrávání z administrace jde přes ni. Zvyš tam limit velikosti těla a zvaž vlastní sizeLimit Strapi v config pluginu upload, aby editoři dostali srozumitelnou zprávu místo utrženého spojení.

Pokud Strapi po změně nenastartuje a hlásí, že provider nelze načíst, balíček není nainstalovaný ve složce, ze které Strapi běží: spusť npm install tam, ne na notebooku, a restartuj. A pamatuj: změna config/plugins.js vyžaduje restart, ale i změny Content Security Policy administrace v config/middlewares.js vyžadují restart; build není potřeba ani v jednom případě.

FAQ#

Potřebuju pro nahrávání do Strapi nastavit CORS na bucketu?

Ne. Nahrávání jde z prohlížeče do Strapi a ze Strapi do bucketu, takže prohlížeč do bucketu nezapisuje a CORS se neuplatní. CORS potřebuješ, jen když přidáš přímé nahrávání z prohlížeče přes presigned URL, nebo když z bucketu načítáš fonty či data pro canvas.

Jaký název regionu použít u úložiště, které není od Amazonu?

Ten, který uvádí dokumentace úložiště. Pokud žádný neuvádí, použij us-east-1. SDK potřebuje nějakou hodnotu k podepsání požadavků a úložiště, které není od Amazonu, přijme to, co od něj čeká. Drž stejný řetězec ve Strapi, v CLI i ve všech dalších klientech.

Dá se provider S3 použít s bucketem, který není veřejný?

Ano. Nastav ACL: 'private' v s3Options.params a provider bude vracet podepsané URL, které vyprší po signedUrlExpires sekundách. Odpovědi API cachuj kratší dobu a ujisti se, že endpoint, kterým se URL podepisují, je dostupný z prohlížeče návštěvníka.

Proč nahrávání funguje, ale náhledy v Media Library zůstávají prázdné?

Content Security Policy Strapi povoluje obrázky jen z vlastního původu a z krátkého seznamu hostitelů. Přidej hostitele ze své baseUrl do img-src a media-src v config/middlewares.js a restartuj.

Přesune přechod na S3 moje stávající média?

Ne. Stávající soubory si ponechají URL /uploads/... a zůstanou na disku serveru. Zkopíruj je do bucketu a aktualizuj uložené URL, nebo je nech, kde jsou, a do bucketu nech jít jen nová nahrání.

Maže Strapi soubory z bucketu, když je smažu v administraci?

Ano, přes volání delete provideru, které odstraní originál i jeho varianty jiných velikostí. Přístupový klíč musí mít právo mazat objekty a klíč jen pro zápis nechá soubory na místě.