Zmienne środowiskowe i sekrety w Dockup
Zmienne środowiskowe i sekrety w Dockup: bezpieczne ustawianie, importowanie, maskowanie, rotowanie i ponowne wdrażanie konfiguracji usług oraz autonomicznych agentów.
Zmienne środowiskowe i sekrety łączą kod aplikacji z konfiguracją produkcyjną, ale wymagają odmiennego podejścia do ujawniania i cyklu życia. Publiczny bazowy URL API może być bezpieczny do wyświetlenia w logach, ale hasło do bazy danych lub klucz podpisujący już nie. Dockup jawnie rozróżnia te wartości i maskuje zapisane sekrety w wynikach odczytu.
Zmiany konfiguracji wymagają również ponownego wdrożenia. Ustawienie nowej wartości aktualizuje docelową konfigurację usługi, ale już działający proces zachowuje środowisko otrzymane podczas uruchamiania.
Jaka jest różnica między zmienną a sekretem?
Obie wartości trafiają do procesu aplikacji jako dane środowiskowe, ale są inaczej obsługiwane operacyjnie.
| Typ | Przykład | Czy może pojawić się w wynikach odczytu? | Zalecana obsługa |
|---|---|---|---|
| Zwykła zmienna | NODE_ENV=production | Tak | Konfiguracja możliwa do przeglądania |
| Zwykła zmienna | PUBLIC_API_URL=https://... | Tak | Może znajdować się w dockup.yaml |
| Sekret | DATABASE_URL=postgres://... | Zapisana wartość — nie | Polecenie sekretu lub magazyn CI |
| Sekret | JWT_SIGNING_KEY=... | Zapisana wartość — nie | Rotacja i ograniczenie dostępu |
| Sekret | DOCKUP_TOKEN=... | Nigdy nie przechowuj jako konfiguracji aplikacji, chyba że jest to wymagane | Uwierzytelnianie na poziomie procesu |
Oznacz wartość jako sekret, gdy jej ujawnienie umożliwiłoby uzyskanie dostępu, podszycie się, odszyfrowanie, podpisywanie lub ruch lateralny. Stwierdzenie „frontend już ją zawiera” oznacza, że wartość jest publiczną konfiguracją, a nie sekretem.
Nie umieszczaj sekretów w kontroli wersji, dockup.yaml, przykładowych wynikach, zrzutach ekranu, promptach agentów ani opisach issue. Zredagowany placeholder jest bezpieczniejszy niż realistycznie wyglądający token, ponieważ skopiowane przykłady często stają się praktyką produkcyjną.
Jak ustawiać i sprawdzać konfigurację środowiska?
Wyświetl bieżące klucze dla konkretnego celu:
dockup env list -s production/api --json
Odpowiedź zawiera każdy klucz, informację, czy jest sekretem, oraz wartość — tylko gdy nie jest chroniona.
Ustaw zwykłą zmienną:
dockup env set NODE_ENV=production \
-s production/api \
--json
Ustaw sekret z bieżącego środowiska powłoki:
dockup env set DATABASE_URL="$DATABASE_URL" \
--secret \
-s production/api \
--json
Usuń nieaktualną wartość:
dockup env remove OLD_FEATURE_FLAG \
-s production/api \
--json
Zaimportuj zbiorczo plik w stylu .env:
dockup env import .env.production \
-s production/api \
--json
Używaj --secret podczas importu tylko wtedy, gdy każda importowana wartość ma być traktowana jako sekret. Pliki mieszane są trudniejsze do przeglądania i często prowadzą do nadmiernego klasyfikowania nieszkodliwej konfiguracji jako sekretu albo do pomijania danych uwierzytelniających. Jeśli to możliwe, rozdziel je.
Dokładny zestaw dostępnych poleceń jest opisany w dokumentacji Dockup CLI.
Dlaczego po zmianie konfiguracji wymagane jest ponowne wdrożenie?
Zmienne środowiskowe są odczytywane podczas uruchamiania procesu. Aktualizacja konfiguracji platformy nie zmienia pamięci działającego procesu Node.js, Python, Go ani innego procesu. Usługa musi uruchomić nowy kontener z nowym środowiskiem.
Prawidłowa sekwencja wygląda następująco:
dockup env set FEATURE_FLAG=on \
-s production/api \
--json
dockup deploy production/api --wait --json
--wait sprawia, że drugi krok można zweryfikować. Domyślny limit czasu wynosi 900 sekund, kod wyjścia 0 oznacza powodzenie, a błędy zwracają wartość różną od zera wraz ze структурowanymi kodami.
Proces blue-green Dockup bez przestojów uruchamia nową wersję, stosuje bramkę zdrowia, a dopiero potem przełącza ruch. Dzięki temu bieżący kontener nie jest restartowany bezpośrednio z niezweryfikowaną konfiguracją.
Jeśli rotacja sekretu zmienia zarówno producenta, jak i konsumenta, zaplanuj okres kompatybilności. Rotacja hasła do bazy danych przed przekazaniem aplikacji nowej wartości może spowodować awarię. W miarę możliwości zastosuj okres nakładania, obsługę dwóch kluczy albo zmianę w odpowiedniej kolejności.
Mechanika wdrożeń została wyjaśniona w artykule wdrożenia bez przestojów.
Jak maskowanie sekretów zmniejsza ryzyko związane z agentami?
Agenci kodujący często podsumowują wyniki poleceń. Narzędzie zwracające zapisane sekrety może zmienić nieszkodliwą prośbę „pokaż bieżącą konfigurację” w ujawnienie danych uwierzytelniających.
Dockup maskuje wartości sekretów. Agent może zobaczyć, że DATABASE_URL istnieje i jest oznaczony jako sekret, ale nie może odczytać zapisanego connection stringa. Może zastąpić wartość, gdy użytkownik poda nową za pośrednictwem bezpiecznego środowiska.
Umożliwia to zastosowanie bezpieczniejszej instrukcji:
Potwierdź, że wymagane klucze sekretów istnieją, ale nigdy nie wyświetlaj ich wartości. Jeśli wartość musi się zmienić, odczytaj ją wyłącznie ze środowiska procesu i zwróć nazwę klucza, a nie sekret.
Maskowanie sekretów powinno obejmować również diagnostykę. Unikaj:
printenv
w transkrypcie agenta, mimo że polecenie PRO exec może uruchamiać jednorazowe polecenia kontenera. Preferuj ukierunkowane sprawdzenie aplikacji, które raportuje obecność, klasę długości lub powodzenie połączenia bez ujawniania wartości.
Przewodnik zasady bezpieczeństwa dla agentów AI na produkcji opisuje wspólnie granice promptów i narzędzi.
Jak rotować sekrety i przeprowadzać audyt?
Rotacja to kontrolowana zmiana produkcyjna, a nie edycja tekstu. Zastosuj następującą sekwencję:
- Utwórz lub uzyskaj nowe dane uwierzytelniające w systemie, który jest ich właścicielem.
- Zapisz je w zatwierdzonym środowisku CI lub operatora.
- Ustaw nowy sekret w Dockup bez jego wyświetlania.
- Wdróż zmianę z opcją
--wait. - Zweryfikuj stan usługi i działanie aplikacji.
- Unieważnij stare dane uwierzytelniające po aktywowaniu nowej wersji.
- Przejrzyj log audytu Dockup.
- Zapisz datę i właściciela rotacji, ale nie zapisuj wartości.
dockup audit --writes --json
Dowody audytowe powinny pokazywać, że konfiguracja została zmieniona, a następnie wykonano wdrożenie. Nie powinny zawierać wartości sekretu.
W przypadku danych uwierzytelniających do bazy danych uwzględnij pule połączeń. Istniejące połączenia mogą pozostać uwierzytelnione po rotacji, podczas gdy nowe połączenia będą używać nowego hasła. Weryfikacja powinna obejmować nowe połączenie, a nie tylko żądania obsłużone przez starą pulę.
W przypadku kluczy API z ograniczeniami uprawnień bezpiecznie przechwyć wygenerowaną wartość podczas tworzenia. Natychmiast zapisz ją w zatwierdzonym systemie sekretów, ogranicz zakres wymaganych uprawnień i przeprowadź rotację bez powielania wartości w wynikach wdrożenia.
Jaka polityka konfiguracji zapobiega driftowi?
Zdefiniuj, które wartości należą do poszczególnych źródeł:
| Źródło | Odpowiednia zawartość |
|---|---|
| Kod repozytorium | Wartości domyślne, które nie zależą od środowiska |
dockup.yaml | Konfiguracja wdrożenia możliwa do przeglądania |
| Zmienne sekretów Dockup | Dane uwierzytelniające używane w runtime |
| Magazyn sekretów CI | Token wdrożeniowy i wstrzykiwane wartości rotacji |
| Wynik zarządzanej bazy danych | Dane połączenia przekazywane usłudze korzystającej z bazy |
Lokalny .env | Wartości tylko dla dewelopera, wykluczone z Git |
Polecenie apply dla dockup.yaml domyślnie dodaje wartości. Zwykłe wartości środowiskowe, których nie ma w pliku, pozostają do momentu jawnego użycia --prune, a sekrety nigdy nie są usuwane za pomocą tej ścieżki. Przed wdrożeniem porządkowania manifestu zapoznaj się z artykułem dockup.yaml jako konfiguracja w kodzie.
Używaj spójnych nazw kluczy we wszystkich środowiskach, ale nie zakładaj, że wartości są wymienne. Klucz stagingowy nie powinien zapewniać dostępu do produkcji. Wdrożenia preview w projekcie z prywatną siecią otrzymują automatycznie utworzonego użytkownika bazy danych z uprawnieniami tylko do odczytu danych produkcyjnych; domyślnie nie powinny dziedziczyć danych uwierzytelniających z uprawnieniami do zapisu.
Reagowanie na incydent związany z wyciekiem sekretu
Jeśli sekret pojawi się w transkrypcie, logu, commicie lub zrzucie ekranu, późniejsze zamaskowanie go nie wystarczy. Potraktuj go jako przejęty:
- Unieważnij go lub przeprowadź jego rotację w systemie źródłowym.
- Zaktualizuj sekret Dockup.
- Wdróż zmianę i przeprowadź weryfikację.
- Usuń ujawnione materiały, jeśli to możliwe.
- Przeszukaj logi audytu i dostępu pod kątem nadużyć.
- Udokumentuj przyczynę i zmianę zapobiegawczą.
Przepisanie historii Git może ograniczyć przyszłe odnajdywanie danych, ale nie pozwala dowieść, że skopiowane dane uwierzytelniające zniknęły. Unieważnienie jest decydującym działaniem.
Lista kontrolna przeglądu środowiska
Przed każdym wydaniem produkcyjnym sprawdź, czy wymagane klucze istnieją, klucze sekretów są oznaczone jako sekrety, żaden sekret nie został zapisany w repozytorium, zwykłe wartości odpowiadają zamierzonemu środowisku, a ponowne wdrożenie jest częścią zmiany. Następnie sprawdź status i czas działania:
dockup status production/api --json
dockup uptime production/api --hours 24 --json
Monitoring działa co minutę i obejmuje czas odpowiedzi p95. Udane wdrożenie konfiguracji nadal należy obserwować pod kątem regresji w runtime.
Informacje o tworzeniu usług i początkowej konfiguracji znajdziesz w artykule Od repozytorium Git do produkcji.
Weryfikuj konfigurację bez jej ujawniania
Aplikacje powinny jasno zgłaszać brak wymaganego klucza, ale diagnostyka nie może wyświetlać jego wartości. Sprawdzenie podczas uruchamiania może raportować listę taką jak missing: ["DATABASE_URL"] lub invalid format: ["PUBLIC_URL"], a następnie kończyć działanie kodem różnym od zera.
W przypadku wartości opcjonalnej zdefiniuj fallback w kodzie i udokumentuj, czy jest on bezpieczny na produkcji. Ciche wartości domyślne z developmentu — lokalne hosty baz danych, tryby debugowania, zbyt liberalny CORS lub testowe dane uwierzytelniające — nie powinny aktywować się tylko dlatego, że brakuje klucza produkcyjnego.
Taka walidacja sprawia, że zmienne środowiskowe i sekrety są obserwowalne bez przekształcania logów w spis danych uwierzytelniających.
Świadomie obsługuj wiele usług i współdzielone dane uwierzytelniające
Kopiowanie jednego sekretu do kilku usług tworzy zależność rotacji. Jeśli system zewnętrzny na to pozwala, preferuj dane uwierzytelniające przypisane do konkretnych usług. Przejęty token workera nie powinien zapewniać takiego samego dostępu jak publiczne API.
Gdy współdzielenie wartości jest nieuniknione, prowadź listę właścicieli i konsumentów. Rotuj wszystkie wartości w uzgodnionym oknie i po każdym ponownym wdrożeniu weryfikuj nowe połączenia. Nie proś agenta o „znalezienie każdej usługi, która prawdopodobnie używa tego klucza” na podstawie podobieństwa nazw — korzystaj z jawnego spisu i dowodów audytowych.
Prywatna sieć może ograniczyć ekspozycję ruchu do bazy danych, ale nie eliminuje potrzeby używania danych uwierzytelniających. Wewnętrzne nazwy hostów kontrolują ścieżkę, a uwierzytelnianie kontroluje, kto może korzystać z bazy danych.
Zacznij od wdrożenia, które można zweryfikować
Przed ustawieniem sklasyfikuj każdy klucz, upewnij się, że odczyty sekretów są maskowane, i uwzględnij wymagane ponowne wdrożenie w ramach tej samej przejrzanej zmiany.
Zacznij bezpłatnie w app.dockup.ai. Plan Free kosztuje 0 USD miesięcznie, obejmuje początkowy kredyt w wysokości 10 USD oraz obsługuje jeden workspace, trzy bazy danych i trzy wdrożenia.
FAQ
Czy Dockup zwraca zapisane wartości sekretów?
Nie. Wartości sekretów są maskowane w wynikach odczytu. Klucze i oznaczenia sekretów pozostają widoczne, dzięki czemu operatorzy mogą sprawdzić, czy wymagana konfiguracja istnieje.
Dlaczego po zmianie zmiennej środowiskowej muszę ponownie wdrożyć usługę?
Działający proces otrzymał swoje środowisko podczas uruchamiania. Nowe wdrożenie tworzy nowy kontener ze zaktualizowanymi wartościami i weryfikuje go za pomocą bramki zdrowia.
Czy mogę umieszczać sekrety w dockup.yaml?
Nie. Używaj dockup.yaml do zwykłej konfiguracji możliwej do przeglądania, a poleceń dotyczących sekretów środowiskowych lub wstrzykiwania sekretów CI do obsługi danych uwierzytelniających.
Jak importować wiele zmiennych środowiskowych?
Użyj polecenia dockup env import z plikiem w stylu .env i dokładnym celem usługi. Opcji import --secret używaj wyłącznie wtedy, gdy wszystkie importowane wartości są sekretami.
Co zrobić, jeśli sekret zostanie ujawniony w logu?
Natychmiast go unieważnij lub przeprowadź jego rotację, zaktualizuj sekret Dockup, wykonaj ponowne wdrożenie, przeanalizuj logi dostępu i napraw proces, który umożliwił ujawnienie.