Ako self-hostovať Directus v roku 2026: databáza, uploady a verejná URL

Vnímajte Directus ako malý systém, nie ako Docker image. Cieľ Directus z pohľadu používateľa je jasný: REST a GraphQL API spolu s admin rozhraním nad vašimi dátami; deployment je prijateľný až vtedy, keď dokážete inicializovať administrátora, vytvoriť kolekciu a rolu, zapisovať cez REST, queryovať cez GraphQL a nahrať súbor.

Toto rozlíšenie odhalí failure mode, s ktorým sa operátori stretávajú po lokálnom testovaní: database client je nesprávny alebo upload storage nie je zapisovateľné. Zároveň umožňuje pripraviť dostatočne konkrétny plán zálohovania a upgrade, ktorý sa dá otestovať.

Overte, že Directus prežije nahradenie

Container image možno znova stiahnuť; databázu, uploady, extensions, flows a snapshots schémy nie. Pred inicializáciou pripojte /directus/database, zapíšte neškodné testovacie dáta a nahraďte container, aby ste overili, že táto cesta je skutočne persistentná. Skontrolujte efektívny mount namiesto toho, aby ste sa spoliehali na názov Compose súboru, a overte, či runtime user môže zapisovať tam, kde to Directus očakáva.

Zvoľte retention a umiestnenie mimo hostiteľa, potom si nacvičte obnovu bez zásahu do produkcie. Test je úspešný iba vtedy, keď sa vrátia schéma, roly, flows, items, extensions a uploady a prejdú sondy REST aj GraphQL. Pri stave uloženom v databáze kombinujte snapshots úložiska s exportmi konzistentnými z pohľadu aplikácie, ako je opísané v článku point-in-time recovery versus snapshots.

Produkčná podoba Directus

Nakreslite okolo Directus tri hranice: ingress na port 8055, persistentný stav a podporné požiadavky. Container je nahraditeľný, no o ďalšie dve oblasti sa treba explicitne postarať. Network contract pre Directus tvorí Postgres a voliteľne Redis a object storage pre škálované deploymenty. Súkromné endpointy ponechajte na internom DNS, povoľte iba potrebné outbound calls a Directusu prideľte service credential s obmedzeným rozsahom.

Diagram je kompletný vtedy, keď čistý klient dokáže inicializovať administrátora, vytvoriť kolekciu a rolu, zapisovať cez REST, queryovať cez GraphQL a nahrať súbor. Zaznamenávajte timing a resource dáta pre database connection pool, súbežnosť API requestov, Flow workers, generovanie thumbnails a upload storage. Ak transakcia zlyhá, prvá hranica, ktorá sa nespráva podľa dokumentácie, určí, či treba skúmať routing, lokálnu kapacitu alebo podpornú službu.

Overte Directus end to end

Vytvorte malý, dočasný Directus fixture a uchovávajte ho pre každý release. Fixture musí testovať skutočný workflow: inicializáciu administrátora, vytvorenie kolekcie a roly, zápis cez REST, queryovanie cez GraphQL a upload súboru. Zaznamenajte digest image, externý hostname, adresu dependency a očakávaný výsledok, aby neskorší operátor mohol test zopakovať bez interpretácie tejto príručky.

Fixture spustite trikrát. Prvýkrát použite čerstvý deployment. Druhýkrát nahraďte container bez zásahu do persistentného stavu. Tretíkrát obnovte backup do prázdneho prostredia. Tretí beh je úspešný iba vtedy, keď sa vrátia schéma, roly, flows, items, extensions a uploady a prejdú sondy REST aj GraphQL. Počas každého behu zaznamenávajte latenciu a využitie zdrojov v oblasti database connection pool, súbežnosti API requestov, Flow workers, generovania thumbnails a upload storage; tieto údaje sa stanú baseline pre alerty namiesto ľubovoľne zvoleného percenta CPU.

Nakoniec zámerne otestujte negatívny scenár: dočasne odoberte testovacej identity prístup k Postgresu a voliteľným službám Redis a object storage pre škálované deploymenty. Overte, že Directus zlyhá viditeľným spôsobom bez poškodenia stavu, obnovte správne podmienky a zopakujte úspešnú transakciu. Release record obsahujúci tieto štyri výsledky je silnejším dôkazom než screenshots z dashboardu alebo jednorazová odpoveď z curl.

Spustite Directus s pozorovateľnými predvolenými nastaveniami

Spustite Directus tak, aby route zostala súkromná, kým nebude dokončená inicializácia.

docker run -d \
  --name directus \
  --restart unless-stopped \
  -p 127.0.0.1:8055:8055 \
  -v directus-data:/directus/database \
  -v directus-uploads:/directus/uploads \
  -v directus-extensions:/directus/extensions \
  -e SECRET=replace-with-a-long-random-value \
  -e KEY=replace-with-a-second-long-random-value \
  -e ADMIN_EMAIL=admin@example.com \
  -e ADMIN_PASSWORD=replace-with-a-strong-bootstrap-password \
  -e DB_CLIENT=sqlite3 \
  -e DB_FILENAME=/directus/database/data.db \
  -e PUBLIC_URL=https://app.example.com \
  directus/directus:latest

Ak process cyklí, porovnajte očakávaného usera image s ownerom každej pripojenej cesty. Ak zostane bežať, lokálne otestujte port 8055 a potom okamžite prejdite na workflow: inicializujte administrátora, vytvorte kolekciu a rolu, zapisujte cez REST, queryujte cez GraphQL a nahrajte súbor. Image pripnite na konkrétnu verziu až po úspešnom end-to-end teste a presnú konfiguráciu zaznamenajte pri službe.

Credentials, roly a vystavené povrchy

Bootstrap window zatvorte hneď po vytvorení prvého dôveryhodného administrátora. Konkrétnou pascou v Directuse je používanie bootstrap hesla po prvom prihlásení alebo bezhlavá rotácia SECRET; bezpečnejším postupom je nahradiť bootstrap credentials, používať least-privilege roly a ponechať SECRET stabilný, pretože chráni sessions a tokens aplikácie.

SECRET vygenerujte raz, neukladajte ho do Gitu a zachovajte ho v recovery manifeste, pretože jeho zmena môže zneplatniť šifrovaný alebo podpísaný stav aplikácie. Credentials pre dependencies by mala prenášať private network a roly v Directuse by mali povoľovať iba nevyhnutné akcie. Citlivé request bodies a odpovede providerov neukladajte do bežných logov.

Ujasnite verejný origin

Vyhnite sa dočasným aj trvalým verejným originom pre Directus. Namiesto toho nastavte PUBLIC_URL na kanonickú HTTPS adresu, nasmerujte zvolený DNS názov na platform route a proxyujte iba na port 8055.

Túto operáciu otestujte mimo hostiteľa: inicializujte administrátora, vytvorte kolekciu a rolu, zapisujte cez REST, queryujte cez GraphQL a nahrajte súbor. Ak ingress zlyhá, príručka riešenia problémov s chybou 502 pokrýva chyby portov a listenerov. Ak Directus požiadavku prijme, ale database client je nesprávny alebo upload storage nie je zapisovateľné, dôkazy teraz smerujú mimo proxy.

Failure drills pre Directus

Pri Directuse monitorujte transakciu, nie process: inicializáciu administrátora, vytvorenie kolekcie a roly, zápis cez REST, queryovanie cez GraphQL a upload súboru. Jej latenciu a error rate kombinujte s database connection pool, súbežnosťou API requestov, Flow workers, generovaním thumbnails a upload storage, aby alert identifikoval komponent s obmedzenou kapacitou.

Upgrade rehearsal musí pokrývať skutočnosť, že schema migrations v Directuse, extensions a podpora database vendorov sa musia kontrolovať ako jeden celok. Pred nahradením v produkcii obnovte stav, vykonajte migráciu a spustite transakciu. Ak je database client nesprávny alebo upload storage nie je zapisovateľné, nemažte dáta len preto, aby startup skončil v zelenom stave; v tomto poradí porovnajte verziu, variables, mounts a dostupnosť dependencies.

Čo by mal Dockup automatizovať pre Directus

Platform layer pre Directus tvoria port 8055, ingress, TLS, runtime configuration, storage a dostupnosť dependencies. Dockup môže tieto časti reprodukovať pre vlastnú infraštruktúru alebo server pripojený zákazníkom.

Operátor potom dokončí product layer: nastaví PUBLIC_URL na kanonickú HTTPS adresu; vynúti toto access rule — nahradí bootstrap credentials, použije least-privilege roly a ponechá SECRET stabilný, pretože chráni sessions a tokens aplikácie; a spustí „inicializujte administrátora, vytvorte kolekciu a rolu, zapisujte cez REST, queryujte cez GraphQL a nahrajte súbor“. Zaznamenanie tohto testu spolu s deploymentom zabráni zámene automatizovaného provisioningu za pripravenosť aplikácie.

Často kladené otázky

Čo Directus potrebuje pre produkčný deployment?

Nasmerujte Directus container na porte 8055 cez jeden HTTPS origin. Sieťovou požiadavkou pre podporné služby je Postgres a voliteľne Redis a object storage pre škálované deploymenty. Directus nepovažujte za pripravený, kým nedokážete inicializovať administrátora, vytvoriť kolekciu a rolu, zapisovať cez REST, queryovať cez GraphQL a nahrať súbor.

Ktoré dáta Directus patria do backupu?

Persistujte /directus/database a do rovnakého recovery manifestu zahrňte databázu, uploady, extensions, flows a snapshots schémy. Obnova čistého Directusu je úspešná iba vtedy, keď sa vrátia schéma, roly, flows, items, extensions a uploady a prejdú sondy REST aj GraphQL.

Vyžaduje Directus HTTPS za reverse proxy?

Pre verejný Directus origin používajte HTTPS a port 8055 ponechajte na internej route. Nastavenie Directusu aplikujte správne: nastavte PUBLIC_URL na kanonickú HTTPS adresu. HTTPS pri Directuse chráni credentials a user content počas prenosu a zachováva konzistentné správanie klienta závislé od originu.

Ako testovať upgrade Directusu?

Obnovte aktuálny stav Directusu do izolovaného deploymentu, aplikujte kandidátnu verziu a zopakujte acceptance transaction. Venujte osobitnú pozornosť tomu, že schema migrations v Directuse, extensions a podpora database vendorov sa musia kontrolovať ako jeden celok. Predchádzajúci Directus image si ponechajte, kým nebudú jasné hranice migrácie dát a rollbacku.