Jak hostować Directus samodzielnie w 2026 roku: baza danych, uploady i publiczny URL

Traktuj Directus jak niewielki system, a nie jak obraz Docker. Cel Directus z perspektywy użytkownika jest jasny: REST i GraphQL API oraz panel administracyjny nad Twoimi danymi. Wdrożenie można uznać za poprawne dopiero wtedy, gdy da się zainicjalizować konto administratora, utworzyć kolekcję i rolę, zapisać dane przez REST, wykonać zapytanie przez GraphQL oraz przesłać plik.

To rozróżnienie pomaga wykryć problem, z którym operatorzy spotykają się po testach lokalnych: nieprawidłowy klient bazy danych albo brak możliwości zapisu w storage uploadów. Dzięki temu plan backupu i aktualizacji staje się wystarczająco konkretny, by można go było przetestować.

Sprawdź, czy Directus przetrwa wymianę kontenera

Obraz kontenera można pobrać ponownie, ale bazy danych, uploadów, extensions, flows i snapshotów schematu nie. Zamontuj /directus/database przed bootstrapem, zapisz nieszkodliwe dane testowe i wymień kontener, aby potwierdzić, że ta ścieżka rzeczywiście jest trwała. Sprawdź faktycznie używany mount zamiast ufać nazwie pliku Compose i upewnij się, że użytkownik uruchomieniowy może zapisywać w miejscu oczekiwanym przez Directus.

Ustal retencję i lokalizację poza hostem, a następnie przećwicz odtwarzanie bez dotykania środowiska produkcyjnego. Próba kończy się powodzeniem tylko wtedy, gdy wracają schemat, role, flows, items, extensions i uploady, a testy REST i GraphQL przechodzą poprawnie. W przypadku stanu opartego na bazie danych połącz snapshoty storage’u z eksportami spójnymi z aplikacją, zgodnie z opisem w artykule odzyskiwanie point-in-time a snapshoty.

Produkcyjny kształt Directus

Wyznacz wokół Directus trzy granice: ingress do portu 8055, trwały stan oraz wymagania pomocnicze. Kontener można wymienić, ale pozostałe dwa obszary wymagają jasno określonych właścicieli. Kontrakt sieciowy Directus obejmuje Postgres oraz opcjonalnie Redis i object storage w skalowanych wdrożeniach. Prywatne endpointy utrzymuj w wewnętrznym DNS, zezwalaj tylko na wymagane połączenia wychodzące i nadaj Directus ograniczone uprawnienia service credential.

Diagram jest kompletny, gdy czysty klient może zainicjalizować konto administratora, utworzyć kolekcję i rolę, zapisać dane przez REST, wykonać zapytanie przez GraphQL oraz przesłać plik. Zbieraj dane o czasie i zasobach dla connection pool bazy danych, współbieżności żądań API, workerów Flow, generowania miniaturek i storage’u uploadów. Jeśli transakcja się nie powiedzie, pierwsza granica, która nie zachowuje się zgodnie z dokumentacją, wskazuje, czy należy zbadać routing, lokalną wydajność czy usługę pomocniczą.

Sprawdź wdrożenie Directus od początku do końca

Utwórz mały, tymczasowy fixture Directus i zachowaj go dla każdego release’u. Fixture powinien obsługiwać rzeczywisty workflow: zainicjalizować konto administratora, utworzyć kolekcję i rolę, zapisać dane przez REST, wykonać zapytanie przez GraphQL oraz przesłać plik. Zapisz digest obrazu, zewnętrzny hostname, adres zależności i oczekiwany rezultat, aby kolejny operator mógł powtórzyć test bez konieczności interpretowania tego poradnika.

Uruchom fixture trzy razy. Najpierw użyj świeżego wdrożenia. Następnie wymień kontener bez modyfikowania trwałego stanu. Na końcu odtwórz backup w pustym środowisku. Trzecia próba kończy się powodzeniem tylko wtedy, gdy wracają schemat, role, flows, items, extensions i uploady, a testy REST i GraphQL przechodzą poprawnie. Podczas każdej próby zbieraj informacje o latency i wykorzystaniu zasobów dla connection pool bazy danych, współbieżności żądań API, workerów Flow, generowania miniaturek i storage’u uploadów. Stanie się to bazą dla alertów zamiast arbitralnego procentowego progu CPU.

Na koniec celowo przetestuj ścieżkę negatywną: tymczasowo odbierz testowej tożsamości dostęp do Postgres oraz opcjonalnych Redis i object storage w skalowanych wdrożeniach. Potwierdź, że Directus kończy działanie w widoczny sposób, nie uszkadzając stanu, przywróć poprawne warunki i ponów udaną transakcję. Rekord release’u zawierający te cztery wyniki jest mocniejszym dowodem niż screenshoty dashboardu lub jednorazowa odpowiedź curl.

Uruchom Directus z domyślną obserwowalnością

Uruchom Directus tak, aby trasa pozostała prywatna do czasu zakończenia bootstrapu.

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

Jeśli proces wpada w pętlę restartów, porównaj oczekiwanego użytkownika obrazu z właścicielem każdej zamontowanej ścieżki. Jeśli kontener działa, przetestuj lokalnie port 8055, a następnie od razu przejdź do workflow: zainicjalizuj konto administratora, utwórz kolekcję i rolę, zapisz dane przez REST, wykonaj zapytanie przez GraphQL oraz prześlij plik. Przypnij wersję obrazu dopiero po pomyślnym przejściu testu end-to-end i zapisz dokładną konfigurację obok definicji usługi.

Dane dostępowe, role i wystawione powierzchnie

Zamknij okno bootstrapu, gdy tylko pojawi się pierwszy zaufany administrator. Konkretna pułapka w Directus polega na używaniu hasła administratora bootstrapu po pierwszym logowaniu albo na bezrefleksyjnej rotacji SECRET. Bezpieczniejsza granica to wymiana danych bootstrapu, używanie ról zgodnych z zasadą najmniejszych uprawnień oraz zachowanie stałej wartości SECRET, ponieważ chroni ona sesje aplikacji i tokeny.

Wygeneruj SECRET raz, nie przechowuj go w Git i zachowaj go wraz z manifestem odtwarzania, ponieważ jego zmiana może unieważnić zaszyfrowany lub podpisany stan aplikacji. Prywatna sieć powinna przenosić dane dostępowe do zależności, a role wewnątrz Directus powinny przyznawać najmniejszy użyteczny zakres działań. Nie zapisuj w standardowych logach wrażliwych body żądań ani odpowiedzi providerów.

Ujednoznacznij publiczny origin

Unikaj tymczasowych i stałych publicznych originów dla Directus. Zamiast tego ustaw PUBLIC_URL na kanoniczny adres HTTPS, skieruj wybraną nazwę DNS na route platformy i proxy’uj wyłącznie do portu 8055.

Wykonaj tę czynność spoza hosta: zainicjalizuj konto administratora, utwórz kolekcję i rolę, zapisz dane przez REST, wykonaj zapytanie przez GraphQL oraz prześlij plik. Jeśli ingress nie działa, poradnik rozwiązywania problemów z błędem 502 opisuje błędy portów i listenerów. Jeśli Directus otrzymuje żądanie, ale klient bazy danych jest nieprawidłowy albo storage uploadów nie pozwala na zapis, dowody wskazują już poza proxy.

Próby awarii dla Directus

W przypadku Directus monitoruj transakcję, a nie proces: zainicjalizuj konto administratora, utwórz kolekcję i rolę, zapisz dane przez REST, wykonaj zapytanie przez GraphQL oraz prześlij plik. Połącz latency i error rate z connection pool bazy danych, współbieżnością żądań API, workerami Flow, generowaniem miniaturek i storage’em uploadów, aby alert wskazywał ograniczony komponent.

Próba aktualizacji musi obejmować sprawdzenie migracji schematu Directus, extensions i wsparcia dla danego vendora bazy danych jako jednej całości. Przed wymianą środowiska produkcyjnego odtwórz stan, wykonaj migrację i uruchom transakcję. Jeśli klient bazy danych jest nieprawidłowy albo storage uploadów nie pozwala na zapis, nie usuwaj danych tylko po to, by uzyskać poprawny start. Porównaj kolejno wersję, zmienne, mounty i osiągalność zależności.

Co Dockup powinien automatyzować dla Directus

Warstwa platformy dla Directus obejmuje port 8055, ingress, TLS, konfigurację runtime’u, storage i osiągalność zależności. Dockup może odtworzyć te elementy dla własnej infrastruktury albo serwera podłączonego przez klienta.

Następnie operator kończy konfigurację warstwy produktu: ustawia PUBLIC_URL na kanoniczny adres HTTPS, egzekwuje tę zasadę dostępu — wymienia dane bootstrapu, używa ról zgodnych z zasadą najmniejszych uprawnień i zachowuje stałą wartość SECRET, ponieważ chroni ona sesje aplikacji i tokeny — oraz uruchamia „zainicjalizuj konto administratora, utwórz kolekcję i rolę, zapisz dane przez REST, wykonaj zapytanie przez GraphQL oraz prześlij plik”. Zapisanie tego testu obok wdrożenia pomaga uniknąć mylenia automatycznego provisioningu z gotowością aplikacji.

Najczęściej zadawane pytania

Czego Directus potrzebuje do wdrożenia produkcyjnego?

Skieruj kontener Directus na porcie 8055 przez jeden origin HTTPS. Wymaganie sieciowe po stronie usług pomocniczych obejmuje Postgres oraz opcjonalnie Redis i object storage w skalowanych wdrożeniach. Nie uznawaj Directus za gotowy, dopóki nie możesz zainicjalizować konta administratora, utworzyć kolekcji i roli, zapisać danych przez REST, wykonać zapytania przez GraphQL oraz przesłać pliku.

Które dane Directus powinny być objęte backupem?

Utrwal /directus/database i uwzględnij bazę danych, uploady, extensions, flows oraz snapshoty schematu w jednym manifeście odtwarzania. Czyste odtworzenie Directus kończy się powodzeniem tylko wtedy, gdy wracają schemat, role, flows, items, extensions i uploady, a testy REST i GraphQL przechodzą poprawnie.

Czy Directus wymaga HTTPS za reverse proxy?

Używaj HTTPS dla publicznego originu Directus, a port 8055 pozostaw na trasie wewnętrznej. Poprawnie zastosuj ustawienie Directus: ustaw PUBLIC_URL na kanoniczny adres HTTPS. W przypadku Directus HTTPS chroni dane dostępowe i treści użytkowników podczas transmisji oraz zapewnia spójne działanie klienta zależne od originu.

Jak testować aktualizację Directus?

Odtwórz bieżący stan Directus w odizolowanym wdrożeniu, zastosuj wersję kandydującą i powtórz transakcję akceptacyjną. Zwróć szczególną uwagę na to, że migracje schematu Directus, extensions i wsparcie dla danego vendora bazy danych muszą zostać sprawdzone jako jedna całość. Zachowaj poprzedni obraz Directus do czasu zrozumienia granic migracji danych i rollbacku.