Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

Docker Compose .env: jak bezpiecznie przechowywać konfigurację aplikacji

Panel z jasnymi pokrętłami i osobną stacyjką z kluczem

Plik .env porządkuje konfigurację Docker Compose, ale nie szyfruje haseł i nie przekazuje automatycznie wszystkich zmiennych do kontenera. To rozróżnienie wyjaśnia wiele sytuacji, w których aplikacja widzi pustą wartość albo nadal korzysta ze starego ustawienia.

W tym poradniku rozdzielimy trzy rzeczy: podstawianie wartości do pliku Compose, środowisko procesu w kontenerze i przechowywanie sekretów. Przykład używa wyłącznie jawnych danych demonstracyjnych. Możesz sprawdzić jego działanie bez uruchamiania bazy i bez wystawiania portów.

Do czego służy Docker Compose .env

Compose odczytuje plik YAML i przygotowuje na jego podstawie konfigurację usług. Zapis ${APP_MODE} oznacza, że przed utworzeniem kontenera trzeba podstawić wartość zmiennej. Źródłem może być środowisko powłoki albo plik wskazany opcją --env-file.

Samo umieszczenie APP_MODE=demo w .env nie sprawia jeszcze, że aplikacja odczyta tę wartość. Musisz przekazać ją przez environment, przez env_file usługi albo wykorzystać w innym polu konfiguracji. Jeśli dopiero poznajesz strukturę YAML, zacznij od poradnika Docker Compose.

Mechanizm Co robi Czego nie zapewnia
.env lub --env-file Dostarcza wartości do podstawiania w Compose Nie jest automatycznym eksportem całego pliku do kontenera
environment Ustawia wskazane zmienne procesu usługi Nie chroni wartości przed osobą mającą dostęp administracyjny
env_file przy usłudze Wczytuje zmienne do środowiska kontenera Nie jest tym samym co opcja CLI --env-file
secrets Udostępnia wybranym usługom pliki z sekretami W lokalnym Compose nie szyfruje źródłowego pliku na dysku

W przykładach używam jawnego --env-file .env. Dzięki temu nie trzeba zgadywać, który plik został znaleziony przy uruchomieniu polecenia z innego katalogu.

Przygotuj mały projekt demonstracyjny

Utwórz osobny katalog roboczy. Nie kopiuj tych plików do działającej aplikacji bez dostosowania nazw i ustawień.

1. Zapisz wartości do podstawienia

Plik .env:

APP_MODE=demo
IMAGE_TAG=3.22
ONLY_FOR_COMPOSE=not-exported

Plik runtime.env:

MESSAGE=hello-from-runtime
APP_MODE=from-runtime

Oba pliki są zwykłym tekstem. Nazwa z kropką może ukrywać plik w domyślnym widoku menedżera plików, ale nie stanowi zabezpieczenia.

2. Zapisz compose.yaml

services:
  demo:
    image: alpine:${IMAGE_TAG:?Set IMAGE_TAG in .env}
    network_mode: none
    read_only: true
    mem_limit: 64m
    cpus: 0.25
    env_file:
      - runtime.env
    environment:
      APP_MODE: ${APP_MODE:?Set APP_MODE in .env}
    command:
      - sh
      - -c
      - 'printf "mode=%s message=%s hidden=%s\n" "$$APP_MODE" "$$MESSAGE" "$${ONLY_FOR_COMPOSE-unset}"'

Podwójny dolar powstrzymuje podstawienie przez Compose. Wartość odczyta dopiero powłoka wewnątrz kontenera. Bez tego część polecenia mogłaby zostać przetworzona wcześniej, na komputerze uruchamiającym Compose.

Zapis ${APP_MODE:?komunikat} zatrzymuje przygotowanie projektu, gdy zmienna jest pusta lub nieustawiona. To lepsze zachowanie dla wymaganej konfiguracji niż cichy start z błędnymi parametrami. Dla opcjonalnego ustawienia można zastosować ${APP_MODE:-demo}, które daje wartość domyślną również przy pustej zmiennej.

3. Sprawdź wynik

W katalogu projektu uruchom:

docker compose --env-file .env -p tt-env-demo config --quiet
docker compose --env-file .env -p tt-env-demo run --rm demo

Oczekiwany wynik procesu:

mode=demo message=hello-from-runtime hidden=unset

APP_MODE pochodzi z environment, dlatego nadpisuje wartość z runtime.env. MESSAGE dociera przez env_file. ONLY_FOR_COMPOSE pozostaje poza środowiskiem kontenera, bo nie przekazaliśmy jej do usługi.

Obraz Alpine może wymagać pobrania przez silnik Dockera. Sam uruchomiony kontener nie ma sieci. Zestawienie codziennych poleceń znajdziesz w ściądze Dockera.

Dlaczego terminal może nadpisać plik .env

Są dwa osobne etapy ustalania wartości. Najpierw Compose wykonuje interpolację YAML, a później składa środowisko kontenera. Mieszanie tych etapów prowadzi do mylącego przekonania, że istnieje jeden prosty ranking wszystkich plików i opcji.

W powłoce Bash sprawdź:

APP_MODE=from-shell docker compose --env-file .env -p tt-env-demo run --rm demo

Teraz mode powinno wynosić from-shell, ponieważ przy podstawianiu ${APP_MODE} środowisko powłoki ma pierwszeństwo przed plikiem. To ustawienie dotyczy jednego wywołania polecenia. Składnia przypisania na początku wiersza jest składnią Bash, a nie PowerShell.

Możesz też nadpisać wartość bezpośrednio dla jednorazowego kontenera:

docker compose --env-file .env -p tt-env-demo run --rm -e APP_MODE=from-cli demo

Przy diagnozowaniu problemu sprawdzaj więc kolejno: skąd pochodzi podstawiana wartość, gdzie jest przekazywana do kontenera i czy polecenie uruchomieniowe jej nie nadpisuje. Nie dopisuj tej samej zmiennej do kolejnych plików na próbę.

Jak trzymać konfigurację w repozytorium

Do repozytorium dodaj .env.example z nazwami ustawień i bezpiecznymi przykładami. Właściwe wartości produkcyjne przechowuj poza historią kodu. Przykładowy .gitignore może zawierać:

.env
.env.*
!.env.example
runtime.env
secrets/

To reguła ignorowania nowych plików, nie sposób usunięcia sekretu z istniejącej historii. Jeśli hasło trafiło do commita, samo dopisanie .gitignore nie rozwiązuje problemu. Unieważnij ujawniony sekret i zastąp go nowym. Historię repozytorium uporządkuj osobno, uwzględniając kopie i współpracowników.

Na Linuksie ogranicz dostęp do plików zawierających wrażliwe wartości:

chmod 600 .env runtime.env

Pliki nadal musi móc odczytać użytkownik uruchamiający Compose. Tryb 600 nie chroni przed rootem ani przed wyciekiem przez kopię zapasową. Znaczenie uprawnień możesz sprawdzić w kalkulatorze chmod, a polecenia kontroli plików w ściądze Linuksa.

Kiedy zamiast zmiennej użyć secrets

Hasło do bazy i klucz API nie są tym samym rodzajem ustawień co poziom logowania. Jeśli aplikacja potrafi czytać sekret z pliku, udostępnij go tylko usłudze, która go potrzebuje:

services:
  app:
    image: twoj-obraz:konkretna-wersja
    secrets:
      - api_token

secrets:
  api_token:
    file: ./secrets/api_token.txt

To fragment do dostosowania, nie gotowy obraz do pobrania. Sekret będzie dostępny dla tej usługi jako plik /run/secrets/api_token. Program musi go sam odczytać. Sufiks _FILE, spotykany w niektórych obrazach, jest konwencją konkretnej aplikacji, a nie uniwersalną funkcją każdej zmiennej Dockera.

Lokalny Compose korzystający z pliku nie zmienia go w zaszyfrowany sejf. Pilnuj praw źródła, kopii i dostępu do hosta. Oddziel również sekrety uruchomieniowe od danych aplikacji: wolumen przechowujący dane rozwiązuje problem trwałości, a nie zarządzania hasłami.

Zmieniony plik, a aplikacja nadal widzi starą wartość

docker compose restart restartuje istniejący kontener. Nie tworzy go ponownie z nowym środowiskiem. Dla działającej usługi po walidacji konfiguracji zastosuj docker compose up -d app, używając tego samego pliku i nazwy projektu co podczas wdrożenia.

Gdy aplikacja nadal zachowuje stare ustawienie, sprawdź, czy nie zapisała go we własnej bazie. Przykładem programu z ustawieniami utrwalanymi przez panel jest Open WebUI z Ollamą. Zmiana środowiska nie zawsze oznacza zmianę wartości zapisanej przez aplikację.

Uważaj też na diagnostykę. docker compose config bez --quiet może wypisać rozwiązane wartości. docker inspect pokazuje środowisko kontenera. Nie wklejaj całego wyniku do zgłoszenia ani czatu. W przykładzie demonstracyjnym dane są jawne; dla projektu produkcyjnego sprawdzaj konkretne niewrażliwe pola.

Najczęstsze pytania

Czy plik .env jest bezpiecznym miejscem na hasła?

Jest plikiem tekstowym. Może być elementem kontrolowanego wdrożenia, ale sam nie zapewnia szyfrowania ani ochrony przed administratorem hosta. Jeśli aplikacja obsługuje pliki sekretów, rozważ taki sposób przekazania haseł.

Czym różni się -env-file od env_file?

Opcja --env-file dostarcza Compose wartości do interpolacji i konfiguracji jego działania. Pole env_file przy konkretnej usłudze ustawia środowisko kontenera. Ten sam format zapisu nie oznacza identycznej funkcji.

Dlaczego zmienna z .env nie istnieje w kontenerze?

Sprawdź, czy przekazano ją przez environment lub env_file. Sama obecność zmiennej w pliku odczytywanym przez Compose nie eksportuje jej automatycznie do procesu aplikacji.

Jak zapisać znak dolara w command?

W pliku Compose użyj $$, gdy znak ma dotrzeć do dalszego etapu bez interpolacji przez Compose. Jeśli potem polecenie wykonuje powłoka, ona może rozwinąć zmienną. Znaczenie zależy więc również od samego programu uruchamiającego polecenie.

Czy restart wystarczy po zmianie .env?

Nie, jeśli zmieniasz środowisko kontenera. Zastosuj konfigurację przez up -d dla właściwej usługi i sprawdź efekt. W aplikacji przechowującej ustawienia w bazie może być potrzebna dodatkowa zmiana w jej panelu.

Źródła

Data publikacji: 24.10.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *