Docker Compose polecenia: praktyczny cheat sheet
Zestawienie niezbędnych komend Docker Compose V2 do zarządzania kontenerami na serwerze. Sprawdź jak poprawnie obsługiwać cykl życia, logi, sieci oraz bezpieczne czyszczenie zasobów.
Polecenia Compose używane w codziennej pracy
Docker Compose udostępnia dziesiątki podpoleceń. W codziennej pracy na serwerze wykorzystuje się około tuzina. Niniejsza strona grupuje je według wykonywanych zadań, podaje jedno proste uzasadnienie dla każdego z nich oraz wskazuje szczegółowe opracowania w sytuacjach, gdy polecenie kryje pułapki.
Wszystkie poniższe przykłady dotyczą Compose V2 lub V5: docker compose ze spacją, a nie starego skryptu docker-compose. Oba są wtyczkami Go; w systemie Linux wtyczka Compose jest instalowana oddzielnie od Docker Engine. Ubuntu 24.04 LTS nadal oferuje starsze narzędzie Python V1 jako docker-compose w wersji 1.29.2-6ubuntu1 w swoim repozytorium universe. Należy to sprawdzić za pomocą docker compose version. Jeśli polecenie jest niedostępne, należy skonfigurować repozytorium Docker i zainstalować pakiet docker-compose-plugin.
Każde z poniższych poleceń uruchamia się z katalogu zawierającego plik compose.yaml; Compose używa nazwy tego katalogu jako domyślnej nazwy projektu, chyba że zostanie ona nadpisana. Bez użycia -f lub COMPOSE_FILE, Compose przeszukuje bieżący katalog roboczy oraz katalogi nadrzędne w poszukiwaniu pliku konfiguracyjnego, więc uruchomienie polecenia poziom wyżej znajdzie stos tylko wtedy, gdy plik znajduje się w ścieżce wyszukiwania. Jeśli format pliku jest nowością, należy zacząć od pierwszego pliku Compose na VPS, a następnie wrócić tutaj po zestaw poleceń.
Cykl życia: cztery polecenia, które wpisujesz, oraz to jedno, które usuwa kontenery
docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose downup -d tworzy sieć, tworzy kontenery, uruchamia je i kończy działanie. Polecenie kończy się po uruchomieniu kontenerów, nie czekając na gotowość aplikacji, dlatego skrypt wdrożeniowy, który wykonuje po nim sondę curl, często kończy się niepowodzeniem przy pierwszej próbie. up -d --wait czeka, aż usługi z weryfikacją stanu (healthcheck) uzyskają status "healthy", a usługi bez niej zostaną uruchomione; niezdrowa usługa lub przekroczony czas --wait-timeout powodują zakończenie z kodem błędu. Flaga jest skuteczna tylko w takim stopniu, w jakim poprawna jest weryfikacja, dlatego przed oparciem na niej automatyzacji należy przygotować weryfikację stanu, której Compose może zaufać.
stop zatrzymuje kontenery, ale ich nie usuwa, dzięki czemu start przywraca te same kontenery z tą samą warstwą zapisu. down zatrzymuje kontenery, a następnie usuwa je wraz z siecią projektu. Wszystko, co zostało zapisane wewnątrz kontenera poza wolumenem, zostaje utracone. Jest to najkosztowniejsze nieporozumienie w Compose, a artykuł pełna różnica między down a stop omawia sytuacje, w których prowadzi to do problemów.
restart nie jest przeładowaniem konfiguracji. Zatrzymuje i uruchamia ten sam kontener z istniejącą konfiguracją, więc zmiana zmiennej środowiskowej, nowy tag obrazu czy edycja mapowania portów nie wywołują żadnego efektu. Aby zastosować zmianę w pliku, należy ponownie uruchomić up -d. Compose porównuje każdą usługę z jej uruchomionym kontenerem i odtwarza te, których konfiguracja lub obraz uległy zmianie.
Wdrażanie zmian: odtworzenie, pobranie lub przebudowanie
docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build webup -d używa ponownie uruchomionych kontenerów, jeśli ich konfiguracja i obraz nie uległy zmianie; pobieranie obrazów i budowanie odbywa się zgodnie z polityką pull danej usługi. --force-recreate pomija to porównanie i zastępuje każdy kontener, nawet jeśli konfiguracja jest identyczna, dlatego jest to najszybszy sposób na wyczyszczenie nietypowego stanu wewnątrz kontenera.
Procedura jawnej aktualizacji obrazu wykorzystuje dwa polecenia, ponieważ wykonują one różne zadania. pull pobiera aktualny obraz dla każdego tagu wymienionego w pliku. up -d następnie wykrywa, że identyfikator obrazu usługi nie pasuje już do uruchomionego kontenera i odtwarza go. Przy domyślnej polityce pull missing, zbuforowane tagi są używane ponownie, z wyjątkiem latest, który jest zawsze pobierany. Przeciwne ryzyko pojawia się w stosie wielousługowym, gdzie pobranie latest dla każdej usługi jednocześnie może uszkodzić aplikację, która działała dziesięć sekund wcześniej, dlatego samodzielnie hostowany obszar roboczy AFFiNE zaleca przypięcie obrazu aplikacji i migracji do tego samego skrótu (digest). Przypięcie zmienia również aktualizację w celową edycję tagu, po której następuje to samo pobranie i odtworzenie, a w przypadku stosu, który migruje bazę danych podczas uruchamiania, należy posiadać zrzut przed wykonaniem któregokolwiek z tych poleceń, co jest procedurą, którą samodzielnie hostowane biuro obsługi Chatwoot stosuje przy każdej zmianie wersji.
build dotyczy usług, które deklarują sekcję build:, w tym usług, które deklarują również image:. up -d --build buduje i uruchamia w jednym kroku, co jest standardową pętlą podczas zmiany kodu. Użyj --no-cache tylko wtedy, gdy zbuforowana warstwa jest wyraźnie nieaktualna, ponieważ przebudowuje ona każdą warstwę od podstaw. Niektóre projekty udostępniają obie ścieżki z jednego sklonowanego repozytorium, a wtedy te dwie pętle stanowią alternatywne ścieżki aktualizacji: samodzielnie hostowany tracker treningów openGym używa docker compose up -d --build do budowania przypiętego checkoutu, ponieważ pobieranie jego obrazów latest może uruchomić nowszą wersję niż ten checkout.
Podgląd uruchomionych procesów
docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose lsps wyświetla wyłącznie uruchomione kontenery. Usługa, która uległa awarii podczas uruchamiania, nie jest tam widoczna, dopóki nie zostanie dodana flaga -a. Zatem sytuacja, w której kontenera brakuje w ps, podczas gdy ps -a wskazuje jego stan jako Exited (1), jest typowym objawem błędu startowego. Należy odczytać kod wyjścia, a następnie sprawdzić logi.
logs -f śledzi wszystkie usługi jednocześnie i poprzedza każdą linię nazwą usługi. Jest to widok przydatny, gdy usługi komunikują się ze sobą i kolejność zdarzeń ma znaczenie. Należy podać nazwę usługi, aby zawęzić zakres. --tail=100 jest istotne w przypadku kontenera działającego od miesiąca, ponieważ domyślne ustawienie wypisuje całą historię i zaśmieca terminal. --since 15m odpowiada na najczęstsze pytanie: co wydarzyło się podczas ostatniego restartu.
top wyświetla listę procesów wewnątrz każdego kontenera, co pozwala odróżnić stan "kontener działa" od "proces wewnątrz kontenera działa". ls wychodzi poza bieżący katalog i wyświetla listę uruchomionych projektów Compose na hoście wraz z ich statusem; należy dodać -a, aby uwzględnić projekty zatrzymane.
Uzyskiwanie dostępu do powłoki wewnątrz usługi
docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web shexec uruchamia polecenie wewnątrz kontenera, który już działa. run uruchamia nowy kontener na podstawie tej samej definicji usługi; jest to konieczne, gdy usługa nie działa wystarczająco długo, aby wykonać polecenie exec. Zawsze używaj run w połączeniu z --rm, ponieważ bez tego każde wywołanie pozostawia zatrzymany kontener, a ich liczba rośnie, aż wynik docker compose ps -a staje się nieczytelny.
Przed użyciem bash wypróbuj sh. Niektóre obrazy oparte na Alpine zawierają bash, w tym oficjalny obraz PostgreSQL Alpine; gdy go brakuje, błąd brzmi exec: "bash": executable file not found in $PATH. Dodanie --no-deps do run pomija zależności usługi, co zapobiega uruchomieniu całej bazy danych podczas szybkiego sprawdzania konfiguracji.
run --rm web env to najszybszy sposób na sprawdzenie środowiska, które faktycznie otrzymała usługa po scaleniu wszystkich plików .env, bloków environment: oraz zmiennych powłoki. Jeśli wartość jest nieprawidłowa, przyczyną jest zazwyczaj kolejność scalania, a sposób, w jaki Compose rozwiązuje pliki env i sekrety wyjaśnia, które źródło ma pierwszeństwo.
Sieci, porty i rozpoznawanie nazw
docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networksDomyślnie Compose umieszcza każdą usługę w jednej sieci projektu, a każda nazwa usługi staje się w niej nazwą DNS. Uruchomienie getent hosts db wewnątrz web, gdy obraz zawiera getent, sprawdza rozpoznawanie nazw; nie testuje to jednak, czy db akceptuje połączenia. Jeśli nazwa jest rozpoznawana, ale połączenie zostaje odrzucone, należy sprawdzić, czy serwer działa i nasłuchuje na żądanym adresie oraz porcie; powiązanie (binding) wyłącznie z 127.0.0.1 jest jedną z możliwych przyczyn. Ta sama granica wyjaśnia, dlaczego kontener uruchomiony poza projektem, czy to przez docker run, czy jako własny stos, wymaga współdzielonej sieci, aby rozpoznać nazwę usługi taką jak jellyfin. Jest to pierwsza rzecz do sprawdzenia, gdy frontend Halcyon dla biblioteki Jellyfin nie może połączyć się z serwerem, na który wskazuje. Reszta tego modelu znajduje się w sposobie działania sieci Compose i DNS usług.
port web 80 wyświetla adres hosta i port, na którym opublikowany jest port kontenera, co pozwala uniknąć zgadywania, gdy mapowanie pochodzi ze zmiennej. Opublikowanie portu powoduje również zapisanie reguły zapory sieciowej, którą Docker zarządza samodzielnie. Reguła ta znajduje się przed regułami użytkownika, więc usługa, która miała być prywatna, może być dostępna z Internetu. Ten przypadek został omówiony w dlaczego opublikowane porty Docker omijają ufw. Pozostawienie tych portów nieopublikowanych i umieszczenie jednego uwierzytelniającego proxy w sieci projektu przed usługami jest bezpieczniejszym rozwiązaniem, co zapewnia uruchomienie Authentik jako warstwy jednokrotnego logowania.
Wolumeny i dane
docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -vconfig --volumes wyświetla nazwane wolumeny zadeklarowane w projekcie, po jednym w każdej linii. Ta lista stanowi jedynie część inwentarza kopii zapasowych: należy również sprawdzić montowania typu bind oraz pliki konfiguracyjne. Gdy wolumeny przechowują dane, których nie da się odtworzyć, dokładna komenda tworzenia kopii zapasowej jest równie ważna co sama lista; dlatego porównanie PhotoPrism i Immich szczegółowo opisuje komendy zrzutu i kopiowania wymagane przez każdy z serwerów zdjęć. cp kopiuje plik do lub z kontenera bez otwierania powłoki, używając formatu service:path po stronie, która jest kontenerem.
down -v usuwa zadeklarowane nazwane wolumeny, z wyjątkiem tych zewnętrznych, a także wolumeny anonimowe przypisane do kontenerów oraz same kontenery. Jest to właściwa komenda do usuwania stosu testowego, ale niewłaściwa w przypadku jakichkolwiek danych, na których zależy użytkownikowi, ponieważ nie wymaga potwierdzenia i nie posiada funkcji cofania zmian. Montowania typu bind przetrwają tę operację, ponieważ znajdują się w systemie plików hosta. Ta różnica w zasięgu działania jest jednym z powodów, dla których należy świadomie wybierać między montowaniami typu bind a wolumenami nazwanymi.
Oczyszczanie zwalniające miejsce na dysku bez utraty danych
docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune--remove-orphans usuwa kontenery należące do projektu, które nie znajdują się już w pliku, co jest typowym zachowaniem po zmianie nazwy usługi. Bez tego parametru kontenery te nadal działają, a docker compose ps domyślnie uwzględnia uruchomione osierocone kontenery.
docker system df pokazuje wykorzystanie dysku przed usunięciem jakichkolwiek danych, dzieląc je na obrazy, kontenery, wolumeny lokalne oraz pamięć podręczną budowania wraz z wartością możliwą do odzyskania dla każdej z tych kategorii. image prune -a usuwa każdy obraz, który nie jest używany przez żaden kontener, niezależnie od tego, czy posiada tag. Na serwerze, na którym pobrano wiele wersji dużego obrazu, jest to zazwyczaj najbardziej efektywna metoda odzyskiwania miejsca. builder prune domyślnie usuwa niepowiązane elementy pamięci podręcznej budowania; należy dodać -a, aby usunąć całą nieużywaną pamięć podręczną budowania.
Żadne z powyższych poleceń nie usuwa nazwanych wolumenów. docker volume prune --all, docker compose down -v oraz docker volume rm służą do usuwania nazwanych wolumenów. Zwykłe docker volume prune usuwa wyłącznie wolumeny anonimowe.
Weryfikacja pliku przed wystąpieniem awarii
docker compose config --quiet
docker compose config --services
docker compose --dry-run up -dconfig --quiet sprawdza poprawność i nie wyświetla żadnych komunikatów w przypadku powodzenia, dlatego należy go używać w kroku przed wdrożeniem lub w git hook. Zwykłe polecenie config wyświetla w pełni scalony i zinterpolowany plik, co pozwala potwierdzić, czy zmienna została poprawnie rozwiązana, a plik nadpisań nałożony zgodnie z oczekiwaniami. Niezdefiniowana zmienna pojawi się tam jako pusta wartość, obok ostrzeżenia The "X" variable is not set. Defaulting to a blank string..
--dry-run jest flagą globalną, a nie flagą podpolecenia, dlatego umieszcza się ją przed up. Wyświetla ona wszystkie akcje, które wykonałby Compose, nie wprowadzając przy tym żadnych zmian. Jest to trzydzieści sekund, które warto poświęcić przed wykonaniem down na istotnym stosie usług.
Praca z wieloma plikami, profilami i projektami
docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -dWiele flag -f jest łączonych w kolejności wystąpienia, przy czym późniejsze pliki nadpisują wcześniejsze klucz po kluczu. Jest to standardowy sposób utrzymywania jednego pliku bazowego z niewielkim nadpisaniem dla środowiska produkcyjnego. Zasady różnią się jednak dla list i map, dlatego przed debugowaniem nieoczekiwanych zachowań należy zapoznać się z sposobem łączenia wielu plików przez Compose.
Flaga --profile uruchamia usługi oznaczone danym profilem wraz z usługami nieoznaczonymi, co pozwala na wykluczenie narzędzi diagnostycznych z typowego polecenia up. Flaga -p ustawia nazwę projektu, dzięki czemu dwie kopie tego samego stosu mogą działać równolegle, korzystając z oddzielnych sieci i nazw wolumenów. Aby przywrócić stos po restarcie systemu, należy użyć polityki restartu lub jednostki systemd, która uruchamia Compose automatycznie, zgodnie z opisem w uruchamianiu stosów Compose podczas startu systemu.
FAQ
Co zastąpiło docker-compose z myślnikiem?
Compose V2 i V5, wywoływane jako docker compose z użyciem spacji. W systemie Linux Compose jest instalowany jako oddzielna wtyczka; Ubuntu 24.04 LTS wciąż oferuje narzędzie V1 oparte na Pythonie w swoim repozytorium universe. Jeśli wywołanie ze spacją jest niedostępne, należy skonfigurować repozytorium Docker i zainstalować pakiet docker-compose-plugin. Stare skrypty należy zaktualizować do formatu ze spacją zamiast dodawania aliasu, ponieważ V2 posiada flagi, których V1 nie obsługiwało.
Dlaczego docker compose restart nie uwzględnia zmian w konfiguracji?
restart zatrzymuje i uruchamia istniejący kontener z konfiguracją, z którą został utworzony, i nigdy nie odczytuje ponownie compose.yaml. Każda zmiana zmiennych środowiskowych, portów, wolumenów lub tagu obrazu wymaga użycia docker compose up -d, które porównuje każdą usługę z uruchomionym kontenerem i odtwarza te, które się różnią. Należy dodać --force-recreate, jeśli wymiana ma nastąpić mimo braku zmian w pliku.
Jak zaktualizować usługę do nowszego obrazu?
Należy wykonać docker compose pull, a następnie docker compose up -d. Polecenie pull pobiera aktualny obraz dla każdego tagu w pliku, a up -d odtwarza każdą usługę, której ID obrazu nie zgadza się z kontenerem. Uruchomienie samego up -d podlega polityce pobierania: domyślna polityka missing używa obrazów z pamięci podręcznej, z wyjątkiem tagu latest, który jest zawsze pobierany.
Które polecenia czyszczące są bezpieczne na działającym serwerze?
docker system df raportuje użycie dysku bez usuwania danych; docker image prune -a oraz docker builder prune usuwają nieużywane obrazy i pamięć podręczną budowania, więc działające usługi pracują bez zakłóceń, a nazwane wolumeny pozostają nienaruszone. Niebezpieczną parą jest docker compose down -v, które usuwa zadeklarowane w projekcie wolumeny nazwane (niebędące zewnętrznymi) oraz podłączone wolumeny anonimowe bez pytania o potwierdzenie, oraz docker volume prune --all, które usuwa nieużywane wolumeny lokalne, w tym nazwane, po pojedynczym potwierdzeniu y/N lub bez żadnego przy użyciu -f. Należy najpierw uruchomić docker compose config --volumes, aby sprawdzić, co jest zagrożone usunięciem.
Czy można uruchomić jedno polecenie bez startowania całego stosu?
Tak. docker compose run --rm --no-deps web sh uruchamia pojedynczy kontener na podstawie definicji usługi web, pomija zależności i usuwa kontener po zakończeniu pracy. Należy użyć exec, gdy kontener już działa, ponieważ exec wykonuje polecenie wewnątrz działającego kontenera i pokazuje stan, w jakim faktycznie znajduje się usługa.