A Directus saját üzemeltetése 2026-ban: adatbázis, feltöltések és nyilvános URL

A Directust ne egyszerű Docker image-ként kezeld, hanem kis rendszerként. A Directus felhasználói célja egyértelmű: REST- és GraphQL API, valamint adminisztrációs felület az adataidhoz; a deployment csak akkor tekinthető megfelelőnek, ha létre tudod hozni az adminisztrátort, egy collectiont és egy role-t, REST-en keresztül tudsz írni, GraphQL-en keresztül tudsz lekérdezni, és fájlt is fel tudsz tölteni.

Ez a megkülönböztetés segít felismerni azt a hibamódot, amellyel az üzemeltetők a helyi tesztelés után találkoznak: nem megfelelő az adatbázis-kliens, vagy a feltöltési tárhely nem írható. Emellett a backup- és frissítési tervet is elég konkréttá teszi ahhoz, hogy tesztelhető legyen.

Bizonyítsd, hogy a Directus túléli a cserét

Egy container image újra letölthető, az adatbázis, a feltöltések, az extensionök, a flow-k és a schema snapshotok viszont nem. A bootstrap előtt csatold a /directus/database könyvtárat, írj bele ártalmatlan mintaadatokat, majd cseréld le a containert annak bizonyítására, hogy az útvonal valóban tartós. Ne egy Compose-fájlnév alapján bízz a konfigurációban: ellenőrizd a tényleges mountot, és győződj meg arról, hogy a futtatási user írhat oda, ahol a Directus ezt elvárja.

Válassz megőrzési időt és off-host célhelyet, majd gyakorold a helyreállítást az éles környezet érintése nélkül. A gyakorlat csak akkor sikeres, ha a schema, a role-ok, a flow-k, az itemek, az extensionök és a feltöltések is visszaállnak, továbbá a REST- és GraphQL-probe-ok is sikeresek. Adatbázis-alapú állapot esetén a storage snapshotokat az alkalmazással konzisztens exportokkal együtt használd, a point-in-time recovery versus snapshots leírásában ismertetettek szerint.

A Directus production architektúrája

Húzz három határt a Directus köré: az ingress és a 8055-ös port közötti útvonalat, a tartós állapotot, valamint a támogató követelményeket. A container cserélhető, a másik két területhez viszont egyértelmű felelősökre van szükség. A Directus hálózati szerződése Postgres, valamint skálázott deploymentek esetén opcionálisan Redis és object storage. A privát endpointokat tartsd belső DNS-en, csak a szükséges kimenő kapcsolatokat engedélyezd, és adj a Directusnak korlátozott hatókörű service credentialt.

A diagram akkor teljes, ha egy tiszta klienssel létre tudod hozni az adminisztrátort, egy collectiont és egy role-t, REST-en keresztül tudsz írni, GraphQL-en keresztül tudsz lekérdezni, valamint fájlt is fel tudsz tölteni. Rögzítsd az adatbázis connection pool, az API-kérések konkurenciája, a Flow workerek, a thumbnail-generálás és a feltöltési tárhely időzítési és erőforrásadatait. Ha a tranzakció meghiúsul, az első dokumentált módon nem működő határ jelzi, hogy routing, helyi kapacitás vagy valamelyik támogató service vizsgálata szükséges.

Bizonyítsd a Directus deployment teljes működését

Hozz létre egy kisméretű, eldobható Directus fixture-t, és tartsd meg minden release-hez. A fixture a valódi munkafolyamatot gyakorolja: az adminisztrátor létrehozását, egy collection és egy role létrehozását, a REST-en keresztüli írást, a GraphQL-en keresztüli lekérdezést és egy fájl feltöltését. Rögzítsd az image digestjét, a külső hostnevet, a dependency címét és az elvárt eredményt, hogy egy későbbi üzemeltető az útmutató értelmezése nélkül is megismételhesse a tesztet.

Futtasd le a fixture-t háromszor. Elsőként friss deploymenttel. Másodszor úgy, hogy lecseréled a containert, de nem módosítod a tartós állapotot. Harmadszor állítsd vissza a backupot egy üres környezetbe. A harmadik futás csak akkor sikeres, ha a schema, a role-ok, a flow-k, az itemek, az extensionök és a feltöltések is visszaállnak, továbbá a REST- és GraphQL-probe-ok is sikeresek. Minden futás során rögzítsd az adatbázis connection pool, az API-kérések konkurenciája, a Flow workerek, a thumbnail-generálás és a feltöltési tárhely körüli latency- és erőforrás-használatot; ez lesz a riasztások alapja egy önkényes CPU-százalék helyett.

Végül szándékosan teszteld a negatív útvonalat is: ideiglenesen vond meg a tesztidentitás hozzáférését a Postgrestől, valamint skálázott deploymentek esetén az opcionális Redistől és object storage-tól. Ellenőrizd, hogy a Directus látható hibával áll le, miközben nem sérül az állapot, majd állítsd vissza a helyes feltételt, és ismételd meg a sikeres tranzakciót. Az ezt a négy eredményt tartalmazó release-rekord erősebb bizonyíték, mint egy dashboardról készült képernyőkép vagy egy egyszeri curl válasz.

Indítsd el a Directust megfigyelhető alapértelmezésekkel

Úgy indítsd el a Directust, hogy az útvonal privát maradjon a bootstrap befejezéséig.

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

Ha a process újra és újra elindul, hasonlítsd össze az image által elvárt usert az egyes mountolt útvonalak tulajdonosával. Ha stabilan fut, teszteld helyben a 8055-ös portot, majd azonnal haladj tovább a munkafolyamaton: hozd létre az adminisztrátort, egy collectiont és egy role-t, írj REST-en keresztül, kérdezz le GraphQL-en keresztül, és tölts fel egy fájlt. Az image verzióját csak akkor rögzítsd, ha ez az end-to-end ellenőrzés sikeres, és a pontos konfigurációt rögzítsd a service mellett.

Credentialök, role-ok és kitett felületek

Amint létrejött az első megbízható adminisztrátor, zárd le a bootstrap időszakát. A Directus egyik konkrét csapdája, ha az első bejelentkezés után is a bootstrap admin jelszavát használod, vagy vakon rotálod a SECRET értékét; a biztonságosabb határ a bootstrap credentialök cseréje, a legkisebb jogosultságú role-ok használata, valamint a SECRET változatlanul hagyása, mivel ez védi az alkalmazás sessionjeit és tokenjeit.

A SECRET értékét egyszer generáld le, tartsd távol a Git-től, és őrizd meg a recovery manifestben, mert a módosítása érvénytelenítheti a titkosított vagy aláírt alkalmazásállapotot. A dependency credentialök továbbítására használj privát hálózatot, a Directuson belüli role-ok pedig csak a legkisebb szükséges műveleti jogosultságot adják. Az érzékeny request body-kat és provider-válaszokat ne írd a szokásos logokba.

Tedd egyértelművé a nyilvános origint

Kerüld a Directus ideiglenes és végleges nyilvános originjeinek párhuzamos használatát. Ehelyett állítsd a PUBLIC_URL értékét a kanonikus HTTPS-címre, irányítsd a kiválasztott DNS-nevet a platform route-jára, és csak a 8055-ös portra proxyzz.

A műveletet a hoston kívülről hajtsd végre: hozd létre az adminisztrátort, egy collectiont és egy role-t, írj REST-en keresztül, kérdezz le GraphQL-en keresztül, és tölts fel egy fájlt. Ha az ingress hibázik, a 502-es hibakeresési útmutató a port- és listenerhibákat tárgyalja. Ha a Directus megkapja a kérést, de nem megfelelő az adatbázis-kliens, vagy a feltöltési tárhely nem írható, akkor a bizonyíték már a proxyn túli problémára mutat.

Hibagyakorlatok a Directushoz

A Directus esetén ne processzt, hanem tranzakciót monitorozz: hozd létre az adminisztrátort, egy collectiont és egy role-t, írj REST-en keresztül, kérdezz le GraphQL-en keresztül, és tölts fel egy fájlt. A latencyt és a hibaarányt egészítsd ki az adatbázis connection pool, az API-kérések konkurenciája, a Flow workerek, a thumbnail-generálás és a feltöltési tárhely adataival, hogy a riasztás azonosítsa a korlátozó komponenst.

A frissítés próbájának ki kell terjednie arra, hogy a Directus schema migrationjeit, extensionjeit és az adatbázis-vendor támogatását egy egységként kell ellenőrizni. A productionben történő csere előtt állítsd vissza az adatokat, futtasd le a migrationöket, majd hajtsd végre a tranzakciót. Ha nem megfelelő az adatbázis-kliens, vagy a feltöltési tárhely nem írható, ne töröld az adatokat azért, hogy a startup zöld legyen; ebben a sorrendben hasonlítsd össze a verziót, a változókat, a mountokat és a dependencyk elérhetőségét.

Mit érdemes a Dockupnak automatizálnia a Directushoz?

A Directus platformrétege a 8055-ös portból, az ingressből, a TLS-ből, a runtime-konfigurációból, a storage-ból és a dependencyk elérhetőségéből áll. A Dockup ezeket a részeket a saját infrastruktúrájához, illetve az ügyfél által csatlakoztatott serverhez is reprodukálhatja.

Ezután az üzemeltető fejezi be a product layer konfigurációját: állítsa a PUBLIC_URL értékét a kanonikus HTTPS-címre; érvényesítse ezt a hozzáférési szabályt — cserélje le a bootstrap credentialöket, használjon legkisebb jogosultságú role-okat, és tartsa stabilan a SECRET értékét, mert ez védi az alkalmazás sessionjeit és tokenjeit —; majd futtassa le ezt: „hozza létre az adminisztrátort, egy collectiont és egy role-t, írjon REST-en keresztül, kérdezzen le GraphQL-en keresztül, és töltsön fel egy fájlt”. Ha ezt a tesztet a deploymenttel együtt rögzítitek, nem keveritek össze az automatizált provisioninget az alkalmazás készültségével.

Gyakran ismételt kérdések

Mire van szüksége a Directusnak egy production deploymenthez?

Irányítsd a Directus containert a 8055-ös porton egyetlen HTTPS-originen keresztül. A támogató hálózati követelmény Postgres, valamint skálázott deploymentek esetén opcionálisan Redis és object storage. Ne tekintsd késznek a Directust addig, amíg létre nem tudod hozni az adminisztrátort, egy collectiont és egy role-t, REST-en keresztül nem tudsz írni, GraphQL-en keresztül nem tudsz lekérdezni, és fájlt sem tudsz feltölteni.

Mely Directus-adatoknak kell szerepelniük a backupban?

Tartsd meg a /directus/database könyvtárat, és ugyanabba a recovery manifestbe vedd fel az adatbázist, a feltöltéseket, az extensionöket, a flow-kat és a schema snapshotokat. A tiszta Directus-restore csak akkor sikeres, ha a schema, a role-ok, a flow-k, az itemek, az extensionök és a feltöltések is visszaállnak, továbbá a REST- és GraphQL-probe-ok is sikeresek.

Szüksége van a Directusnak HTTPS-re reverse proxy mögött?

Használj HTTPS-t a nyilvános Directus-originhez, a 8055-ös portot pedig tartsd a belső útvonalon. Helyesen alkalmazd a Directus beállítását: állítsd a PUBLIC_URL értékét a kanonikus HTTPS-címre. A Directus esetén a HTTPS védi a credentialöket és a felhasználói tartalmakat az átvitel során, valamint konzisztenssé teszi az originérzékeny kliensviselkedést.

Hogyan kell tesztelni egy Directus-frissítést?

Állítsd vissza az aktuális Directus-állapotot egy izolált deploymentbe, alkalmazd a jelölt verziót, majd ismételd meg az elfogadási tranzakciót. Különösen figyelj arra, hogy a Directus schema migrationjeit, extensionjeit és az adatbázis-vendor támogatását egy egységként kell ellenőrizni. Tartsd meg az előző Directus-image-et addig, amíg nem érted pontosan az adatmigration és a rollback határát.