Docker Compose stop a down: różnice i usuwanie danych
Dowiedz się, czym różni się docker compose stop od down. Pierwsze polecenie zatrzymuje kontenery, drugie usuwa je wraz z siecią. Sprawdź, kiedy użyć flagi --volumes.
Krótka odpowiedź
docker compose stop zatrzymuje kontenery i pozostawia je na dysku. docker compose down zatrzymuje je, a następnie usuwa kontenery oraz sieć utworzoną przez Compose dla danego projektu. Żadne z tych poleceń nie narusza wolumenów nazwanych. Dodanie flagi -v, jak w poleceniu docker compose down -v, usuwa niezewnętrzne wolumeny nazwane zadeklarowane w sekcji volumes pliku Compose, które należą do tego projektu. To, co polecenie down trwale usuwa, to wszelkie dane zapisane przez kontener w jego własnej warstwie zapisu, poza jakimkolwiek wolumenem.
To cała różnica ujęta w jednym akapicie. Reszta tego przewodnika dowodzi tego na przykładzie wolumenu Postgres, który przetrwa polecenie down, a zniknie po użyciu down -v, oraz wyjaśnia dwa przypadki, w których wymagane jest użycie --force-recreate.
docker compose stop: kontenery pozostają
stop wysyła do głównego procesu w każdym kontenerze skonfigurowany sygnał zatrzymania (domyślnie SIGTERM), czeka, a następnie wysyła SIGKILL, jeśli proces nadal działa. Domyślny czas oczekiwania wynosi 10 sekund, a -t pozwala go zmienić. Nic nie jest usuwane. Kontener zachowuje swój identyfikator, warstwę zapisu oraz logi.
docker compose stop
docker compose ps -adocker compose ps samodzielnie wyświetla tylko uruchomione kontenery, więc po wykonaniu stop polecenie to zwraca pustą tabelę, co bywa mylnie interpretowane jako usunięcie kontenerów. ps -a uwzględnia również zatrzymane jednostki; w tym widoku przy każdej usłudze pojawi się status Exited wraz z kodem wyjścia zwróconym przez proces. Poprawne zamknięcie często skutkuje kodem Exited (0), choć nie jest to regułą. Niektóre serwery kończą bezpieczne wyłączanie, a następnie ponownie wyzwalają sygnał zatrzymania, przez co proces kończy się tym sygnałem – tak właśnie działa Uvicorn, więc nawet prawidłowe zatrzymanie może skutkować kodem innym niż zero. Kod różny od zera może również oznaczać, że proces uległ awarii lub został zabity po przekroczeniu limitu czasu. Kontenery można przywrócić za pomocą docker compose start, co powoduje ponowne użycie dokładnie tych samych instancji.
Ponieważ kontenery nadal istnieją, wszelkie dane zapisane wewnątrz nich poza wolumenami są zachowane. Dotyczy to pakietów zainstalowanych ręcznie za pomocą docker compose exec oraz plików konfiguracyjnych edytowanych wewnątrz kontenera. Jest to praktyczny powód, dla którego podczas debugowania warto preferować stop: pozwala to na restart do dokładnie tego samego stanu.
docker compose down: kontenery i sieci są usuwane
down zatrzymuje kontenery, a następnie usuwa je wraz z domyślną siecią utworzoną przez Compose dla danego projektu. Dokumentacja Docker opisuje to jako zatrzymywanie i usuwanie kontenerów, sieci, wolumenów oraz obrazów utworzonych przez up, jednak operacje na wolumenach i obrazach są wykonywane tylko po użyciu flag -v oraz --rmi.
docker compose down
docker compose ps -a
docker network lsPo wykonaniu down, polecenie ps -a nie wyświetla żadnych informacji dla projektu, a sieć <project>_default przestaje istnieć. Nazwa projektu pochodzi od nazwy katalogu, chyba że w pliku Compose zdefiniowano name:, ustawiono zmienną COMPOSE_PROJECT_NAME lub przekazano flagę -p. Każda zmiana wprowadzona w zapisywalnej warstwie kontenera jest teraz nieodwracalna, dlatego należy traktować down jako polecenie usuwające kontener przy jednoczesnym zachowaniu danych zapisanych w wolumenach.
Jeśli Compose nie znajdzie pliku konfiguracyjnego w bieżącym katalogu ani w katalogach nadrzędnych, a użytkownik nie wskazał go za pomocą -f lub COMPOSE_FILE, wystąpi błąd no configuration file provided: not found. Compose nie jest w stanie określić, o który projekt chodzi, więc przerywa działanie. W przypadku pracy poza folderem projektu należy użyć docker compose -f /srv/myapp/compose.yaml down.
Czy docker compose down usuwa wolumeny?
Nie. Nazwany wolumen zadeklarowany w kluczu najwyższego poziomu volumes przetrwa działanie down, a także kontener, do którego był podpięty. Jest to najczęstsza obawa związana z tym poleceniem. Wersja Compose 5.7.0 zmieniła działanie down -v: obecnie pomija on nazwane wolumeny należące do innego projektu lub utworzone poza Compose, wyświetlając stosowne ostrzeżenie.
Skonfiguruj stos, na którym można przeprowadzić testy. Umieść poniższą zawartość w compose.yaml w pustym katalogu o nazwie voltest.
services:
db:
image: postgres:16.4
restart: unless-stopped
environment:
POSTGRES_PASSWORD: example
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:Uruchom stos i zapisz wiersz, który będzie można później rozpoznać.
docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "create table marker (note text);"
docker compose exec -T db psql -U postgres -c "insert into marker values ('survived');"Teraz usuń kontener i sprawdź wolumen.
docker compose down
docker volume lsDane wyjściowe nadal zawierają voltest_pgdata. Kontener został usunięty, ale dane pozostały. Przywróć stos i odczytaj wiersz.
docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "select * from marker;"Otrzymasz jeden wiersz zawierający survived. Nowy kontener jest inną instancją o innym identyfikatorze, podpiętą do tego samego wolumenu. Jeśli potrzebujesz szerszego kontekstu, podstawowy przewodnik po Compose omawia nazwane wolumeny w zestawieniu z bind mounts oraz wyjaśnia, gdzie fizycznie znajdują się one na hoście.
Co dokładnie niszczy down -v
-v (w pełnej formie --volumes) usuwa nazwane wolumeny, które nie są zewnętrzne, zadeklarowane w sekcji volumes pliku Compose i należące do tego projektu, a także wolumeny anonimowe podpięte do kontenerów. W Compose v5.7.0 nazwany wolumen z etykietą własności innego projektu lub bez etykiety projektu jest pomijany z ostrzeżeniem; jeśli nie można sprawdzić jego własności, polecenie kończy się niepowodzeniem i zachowuje wolumen. Należy je uruchomić w odniesieniu do tego samego stosu.
docker compose down -v
docker volume lsvoltest_pgdata nie jest już wymieniony. Uruchom stos ponownie, a punkt wejścia Postgres znajdzie pusty katalog danych i zainicjuje nowy klaster. Dziennik kontenera informuje o tym wprost.
The files belonging to this database system will be owned by user "postgres".
PostgreSQL init process complete; ready for start up.Zobaczenie tego bloku w stosie, który działał od miesięcy, oznacza, że Postgres inicjuje pusty katalog danych. Twoja tabela marker przepadła, a jedynym sposobem na jej odzyskanie jest kopia zapasowa.
Niektóre zasoby pamięci masowej nigdy nie są usuwane przez -v. Bind mount to ścieżka na hoście, więc Docker jedynie odmontowuje ją, a pliki pozostają w swoim miejscu. Wolumen oznaczony jako external: true jest zadeklarowany jako należący do czegoś spoza tego projektu, więc Compose nigdy go nie usuwa. Nazwany wolumen, który został usunięty z pliku Compose przed uruchomieniem down -v, nie jest już zadeklarowany, więc Compose nie wie, że należy go usunąć; pozostaje on jako osierocony zasób dla docker volume prune -a, gdy żaden kontener się do niego nie odwołuje.
Ten ostatni przypadek często zdarza się podczas refaktoryzacji. Usunięcie usługi i jej wolumenu z pliku oraz uruchomienie down -v sprawia, że wolumen przetrwa, ponieważ plik już o nim nie wspomina. down -v należy uruchomić przed edycją pliku, a nie po niej.
Kiedy faktycznie potrzebne jest --force-recreate
docker compose up -d nie przebudowuje całego środowiska przy każdym uruchomieniu. Compose przechowuje skrót (hash) rozpoznanej konfiguracji każdej usługi jako etykietę kontenera. W wersji Compose v5.7.0 działający kontener pozostaje bez zmian, jeśli skrót konfiguracji, ID obrazu oraz suma kontrolna wolumenu obrazu są zgodne, wymagane połączenia sieciowe i montowania wolumenów nazwanych istnieją, a żaden nadrzędny element współdzielący przestrzeń nazw lub wolumen nie jest odtwarzany. Otrzymujesz wtedy Container voltest-db-1 Running zamiast Recreated. Jest to zachowanie pożądane w niemal każdym przypadku, ponieważ sprawia, że up -d można bezpiecznie uruchamiać wielokrotnie.
Jest to również powód, dla którego niektóre zmiany wydają się nie przynosić efektu. Compose tworzy skrót z rozpoznanej definicji usługi, a nie z zawartości plików, na które ta definicja wskazuje. Plik konfiguracyjny zamontowany w kontenerze i odczytany raz podczas startu nie wywoła odtworzenia kontenera po edycji, ponieważ ścieżka montowania nie uległa zmianie. Usługa kontynuuje działanie z wartościami odczytanymi podczas rozruchu.
docker compose up -d --force-recreateTo polecenie zatrzymuje i usuwa każdy kontener, a następnie tworzy nowy na podstawie tej samej definicji. Użyj go po edycji zamontowanego pliku konfiguracyjnego oraz w sytuacji, gdy kontener przeszedł w stan, którego nie można wyjaśnić. Wolumeny pozostają nienaruszone, więc baza danych przetrwa wymuszone odtworzenie. Aby pobrać nowszy obraz dla tego samego tagu, należy również wykonać operację pobierania.
docker compose pull
docker compose up -dpull pobiera nowe ID obrazu, a up -d wykrywa różnicę między tym ID a obrazem działającego kontenera i automatycznie go odtwarza. Dodanie --force-recreate bez pull skutkuje utworzeniem nowego kontenera z tego samego, starego obrazu. Dlatego stwierdzenie „wymusiłem odtworzenie, a nadal mam starą wersję” jest tak częstym problemem.
docker compose restart nie wykonuje żadnej z tych czynności. Restartuje istniejące kontenery bez stosowania zmian w ich konfiguracji, więc zmiana zmiennej środowiskowej lub mapowania portów nie zostanie uwzględniona. Jeśli edytowałeś plik, użyj up -d.
Model mentalny, o którym należy pamiętać
Kontenery są wymienne. Kontener to proces oraz cienka warstwa zapisu, a Compose może utworzyć zamiennik na podstawie pliku i obrazu. Wolumeny nie są wymienne, ponieważ przechowują jedyną kopię stanu, której żaden plik w repozytorium nie jest w stanie odtworzyć.
Każde polecenie Compose jest zgodne z tym podziałem. stop oraz start zachowują kontener. down oraz up zastępują kontener i zachowują wolumen. down -v to jedyne rutynowe polecenie, które usuwa stan, dlatego wymaga jawnej flagi. Przed wykonaniem go na jakimkolwiek rzeczywistym środowisku należy upewnić się, że istnieje kopia zapasowa, która została przynajmniej raz przywrócona.
Ta sama logika dotyczy sekretów. Hasło ustawione przez POSTGRES_PASSWORD jest używane tylko do ustawienia hasła bazy danych podczas jej pierwszej inicjalizacji, więc zmiana go w pliku środowiskowym i uruchomienie up -d pozostawia zapisane hasło bez zmian. Kontener jest nowy, a wolumen stary; stary wolumen nadal przechowuje stare hasło. Jak Compose rozwiązuje pliki env i sekrety wyjaśnia, która warstwa ma pierwszeństwo, gdy ta sama zmienna jest ustawiona dwukrotnie.
Tryby awarii i komunikaty, które zobaczysz
no configuration file provided: not found oznacza, że Compose nie mogło odnaleźć pliku konfiguracyjnego w bieżącym katalogu ani w katalogach nadrzędnych, -f lub COMPOSE_FILE. Użyj flagi -f z pełną ścieżką.
Network voltest_default Resource is still in use w down w Compose v5.7.0 oznacza, że kontenery są nadal podłączone do sieci projektu; zazwyczaj są to kontenery spoza tego projektu, uruchomione ręcznie za pomocą docker run --network. Usuń te kontenery, a następnie ponownie uruchom down.
Found orphan containers (voltest-old-1) for this project pojawia się po zmianie nazwy lub usunięciu usługi. Bieżąca wersja Compose wyświetla nazwy bezpośrednio, oddzielone przecinkami. Starsze wydania Compose v2 wyświetlają to samo ostrzeżenie z nazwami w nawiasach kwadratowych, jak w ([voltest-old-1]). Stary kontener nadal posiada etykietę projektu. docker compose down --remove-orphans usuwa te etykiety.
Error response from daemon: remove voltest_pgdata: volume is in use przy ręcznym docker volume rm oznacza, że jakiś kontener nadal odwołuje się do wolumenu, wliczając w to kontenery zatrzymane. Najpierw uruchom docker compose down, a następnie usuń wolumen, lub po prostu użyj down -v. W przypadku większego projektu, stos Compose z wieloma usługami pokazuje, jak wiele wolumenów może zgromadzić jeden projekt.
FAQ
Czy docker compose down usuwa moją bazę danych?
Nie, jeśli baza danych znajduje się w nazwanym wolumenie lub w podpiętym katalogu (bind mount). down usuwa kontenery oraz sieć projektu, natomiast wolumen pozostaje na dysku wraz z nienaruszonymi danymi. Kolejne polecenie docker compose up -d podłącza nowy kontener do tego samego wolumenu, w którym dane są dostępne. docker compose down -v usuwa nazwane wolumeny (niebędące zewnętrznymi), zadeklarowane w sekcji volumes pliku Compose, które należą do tego projektu.
Jaka jest różnica między stop a down w przypadku kontenera, który chcę zachować?
stop zatrzymuje kontener, więc docker compose start przywraca ten sam kontener z tą samą warstwą zapisu. Wszystkie zmiany wprowadzone ręcznie wewnątrz kontenera pozostają zachowane. down usuwa kontener, więc kolejne up -d tworzy nowy kontener z obrazu, a ręczne zmiany zostają utracone. Podczas debugowania należy używać stop.
Jak usunąć wszystko, co zostało utworzone przez projekt Compose?
docker compose down -v --rmi all --remove-orphans usuwa kontenery, sieć projektu, nazwane wolumeny (niebędące zewnętrznymi) zadeklarowane w pliku, które należą do projektu, obrazy używane przez usługi oraz osierocone kontenery projektu. Polecenie to nie usuwa podpiętych katalogów (bind mounts) ani wolumenów oznaczonych jako external: true. Przed uruchomieniem warto sprawdzić, co zostanie usunięte, za pomocą docker volume ls.
Dlaczego kontener ignoruje zmiany wprowadzone w podpiętym pliku konfiguracyjnym?
Compose decyduje o ponownym utworzeniu kontenera na podstawie porównania skrótu (hash) zdefiniowanej usługi, a skrót ten nie uwzględnia zawartości podpiętego pliku. Ścieżka nie uległa zmianie, więc Compose pozostawia kontener uruchomiony z wartościami odczytanymi podczas startu. Należy wykonać docker compose up -d --force-recreate, aby utworzyć nowy kontener, który ponownie odczyta plik.
Dlaczego nowe hasło POSTGRES_PASSWORD nie działa po jego zmianie?
Obraz Postgres używa POSTGRES_PASSWORD do ustawienia hasła bazy danych tylko podczas inicjalizacji pustego katalogu danych. Wolumen zawiera już zainicjalizowany klaster, więc zmienna jest ignorowana, a stare hasło pozostaje w mocy. Próba połączenia z nowym hasłem kończy się błędem password authentication failed for user "postgres". Należy zmienić hasło za pomocą ALTER USER wewnątrz uruchomionej bazy danych lub zaakceptować utratę danych i rozpocząć proces od nowa za pomocą docker compose down -v.