SSD Nodes Learn Hosting plans →
Przewodniki Matt ConnorAutor: Matt Connor

Gdzie Nextcloud w Docker przechowuje pliki użytkownika

Lokalizacja danych Nextcloud w kontenerze oraz na hoście. Sprawdź jak zmapować wolumeny, odnaleźć plik config.php i bazę danych, aby poprawnie wykonać pełną kopię zapasową.

Gdzie Nextcloud w Docker przechowuje pliki

Nextcloud w Docker przechowuje pliki w katalogu danych wewnątrz kontenera, a rzeczywista lokalizacja na serwerze to ta, do której podłączono wybrany wolumin lub bind mount. W obrazie linuxserver.io pliki użytkowników znajdują się w lscr.io/linuxserver/nextcloud, /data, a config.php, aplikacje i motywy znajdują się w /config. Obie te ścieżki są ścieżkami kontenera. Jedno polecenie wyświetla odpowiadającą im ścieżkę na hoście, a dalsza część tego poradnika omawia trudniejszą część pytania: wszystko, czego katalog danych nie zawiera.

Przypnij tag obrazu. Ścieżki należą do obrazu, a nie do Nextcloud, a zmienny tag może zmienić wskazywany obraz. Na dzień 20 listopada 2026 bieżącym stabilnym wydaniem obrazu jest 35.0.3-ls3, zawierające Nextcloud 35.0.3, czwarte wydanie głównej wersji Nextcloud 35. Obraz aktualizuje tylko jedną główną wersję naraz, więc stos nadal działający na 34.x przechodzi do 35 w jednym kroku. Przed wykonaniem tego kroku należy utworzyć kopię zapasową.

services:
  nextcloud:
    image: lscr.io/linuxserver/nextcloud:35.0.3-ls3
    container_name: nextcloud
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - nextcloud_config:/config
      - nextcloud_data:/data
    ports:
      - 443:443
    restart: unless-stopped

  nextcloud-db:
    image: mariadb:11.8
    container_name: nextcloud-db
    environment:
      - MARIADB_ROOT_PASSWORD=${MARIADB_ROOT_PASSWORD}
      - MARIADB_DATABASE=nextcloud
      - MARIADB_USER=nextcloud
      - MARIADB_PASSWORD=${NEXTCLOUD_DB_PASSWORD}
    volumes:
      - nextcloud_db:/var/lib/mysql
    restart: unless-stopped

volumes:
  nextcloud_config:
  nextcloud_data:
  nextcloud_db:

Oba hasła pochodzą z pliku .env umieszczonego obok pliku Compose, więc nie znajdują się w samym pliku Compose. Odpowiedź obejmuje zatem trzy woluminy, z których tylko jeden przechowuje pliki użytkowników.

Te ścieżki kontenera pochodzą z dokumentacji tego konkretnego obrazu. Inny obraz Nextcloud może mieć inny układ systemu plików i przechowywać instalację we własnym katalogu głównym serwera WWW, dlatego ścieżka skopiowana z wpisu na forum jest tylko przypuszczeniem. Należy sprawdzić rzeczywisty układ w uruchomionym kontenerze.

docker inspect nextcloud

Sekcja Mounts tego wyniku zawiera listę wszystkich zamontowanych zasobów, z Source po stronie hosta i Destination po stronie kontenera. Ta lista udziela odpowiedzi dla danej konfiguracji, niezależnie od wybranego obrazu.

Jak znaleźć rzeczywistą ścieżkę na hoście za wolumenem?

Wolumen nazwany jest zarządzany przez Docker, więc jego ścieżka nie jest wybierana ręcznie. Należy ją odczytać.

docker volume ls
docker volume inspect nextcloud_nextcloud_data

Nazwa ma znaczenie. Docker Compose dodaje do nazw wolumenów prefiks z nazwą projektu. Domyślnie jest to nazwa katalogu zawierającego plik Compose. Dlatego wolumen zapisany w pliku jako nextcloud_data zwykle występuje na dysku jako nextcloud_nextcloud_data. Polecenie docker volume ls wyświetla rzeczywiste nazwy. Skrócony wynik inspekcji wygląda następująco:

[
    {
        "CreatedAt": "2026-08-18T09:12:44Z",
        "Driver": "local",
        "Mountpoint": "/var/lib/docker/volumes/nextcloud_nextcloud_data/_data",
        "Name": "nextcloud_nextcloud_data",
        "Scope": "local"
    }
]

Mountpoint jest właściwą odpowiedzią. Należy odczytywać tę wartość z wyniku polecenia, zamiast ją zakładać, ponieważ ścieżka może się zmienić. W przypadku rootless Docker cały katalog danych Docker znajduje się domyślnie w katalogu domowym użytkownika uruchamiającego daemon, więc ścieżka zaczyna się w innym miejscu.

Bind mount usuwa ten problem. W pliku Compose należy wpisać - /srv/nextcloud/data:/data. Ścieżką na hoście będzie wtedy podana wartość, którą docker inspect raportuje jako Source. Ten wybór zmienia więcej niż samą ścieżkę, ponieważ wolumeny nazwane i bind mounty różnią się między innymi sposobem obsługi właścicieli plików i kopii zapasowych.

Dlaczego katalog danych nie jest kopią zapasową

Podręcznik Nextcloud wymienia pięć elementów, które musi obejmować kopia zapasowa: katalog konfiguracji, katalog niestandardowych aplikacji, katalog danych, katalog motywu oraz bazę danych. W tym obrazie katalogi konfiguracji, aplikacji i motywu znajdują się pod /config, natomiast baza danych działa w osobnym kontenerze i korzysta z własnego wolumenu. Skopiowanie samego /data oznacza zapisanie najmniej istotnej części problemu.

Baza danych ma znaczenie, ponieważ interfejs WWW nie wyświetla zawartości katalogu. Wyświetla wiersze z pamięci podręcznej plików. Dlatego podręcznik zaleca uruchomienie skanowania po ręcznym skopiowaniu plików do katalogu danych. Przywrócenie /data obok pustej bazy danych daje bajty bez indeksu: bez użytkowników, udziałów i czegokolwiek na liście plików. Przywrócenie bazy danych obok pustego /data sprawia, że każdy wiersz wskazuje plik, którego już nie ma.

config.php zawiera poświadczenia bazy danych i zaufane domeny. Zawiera również identyfikator instancji, który po dodaniu prefiksu appdata_ tworzy nazwę katalogu danych aplikacji. Należy odczytać te wartości z działającej instancji, zamiast polegać na zapamiętanych wartościach.

docker exec -it nextcloud occ config:system:get datadirectory
docker exec -it nextcloud occ config:system:get instanceid

Pierwsze polecenie wyświetla katalog danych faktycznie używany przez tę instancję, czyli tutaj /data. Ten obraz zawiera opakowanie occ dostępne w ścieżce systemowej, dlatego należy uruchomić je bezpośrednio przez docker exec. Nie należy kopiować dłuższej postaci sudo i php occ z podręcznika Nextcloud, ponieważ dotyczy ona instalacji działającej poza kontenerem.

Co niepostrzeżenie zapełnia wolumin danych?

Podglądy i historia poszczególnych użytkowników znajdują się w tym samym woluminie co pliki. Żadna z tych danych nie jest uwzględniana w informacji o zajętym miejscu wyświetlanej użytkownikowi w interfejsie WWW.

  • Podglądy to wygenerowane miniatury. Są przechowywane w folderze danych aplikacji wewnątrz katalogu danych, pod nazwą appdata_, po której następuje identyfikator instancji.
  • Usunięte pliki pozostają w koszu. trashbin_retention_obligation ma domyślnie wartość auto. Pozwala to przechowywać usunięte pliki dłużej niż 30 dni, gdy jest dostępne miejsce, ale także usuwać je przed upływem 30 dni, gdy potrzebne jest miejsce. Usunięte pliki nie są wliczane do zwykłego limitu użytkownika, ale kosz ma własny limit: domyślnie jest to maksymalnie 50% miejsca pozostałego użytkownikowi w ramach limitu albo wolne miejsce na dysku w przypadku użytkownika bez limitu. Po przekroczeniu tego limitu Nextcloud usuwa najpierw najstarsze kwalifikujące się elementy, w tym elementy młodsze niż 30 dni przy wartości auto.
  • Stare wersje również pozostają na dysku. versions_retention_obligation ma domyślnie wartość auto. Z czasem ogranicza to liczbę wersji i zachowuje najnowszą wersję w każdym przedziale czasowym. Po skonfigurowaniu maksymalnego okresu przechowywania zadanie działające w tle usuwa wersje starsze niż ten okres lub wersje, których plik już nie istnieje. W przypadku kont z limitem aplikacja Versions dąży do wykorzystania 50% miejsca aktualnie pozostałego użytkownikowi w ramach limitu. W przypadku kont bez limitu korzysta bezpośrednio z wolnego miejsca systemu plików. Gdy trzeba zwolnić miejsce, usuwa najstarsze wersje, zachowując co najmniej dwie najnowsze. Oznacza to, że wartość docelowa nie jest twardym limitem. Wersja nazwana ręcznie przez użytkownika nie jest obejmowana automatycznym wygaszaniem, ale użytkownik nadal może usunąć ją ręcznie. occ versions:cleanup usuwa nazwane wersje razem z pozostałymi.

Przed usunięciem czegokolwiek należy wykonać pomiar.

docker exec -it nextcloud sh -c 'du -sh /data/*'
docker exec -it nextcloud sh -c 'du -sh /data/appdata_*'

Pierwszy wiersz zawiera jedną wartość dla każdego folderu użytkownika oraz folderu danych aplikacji. Jeśli wartość dotycząca danych aplikacji jest duża, należy sprawdzić jej podkatalog preview. Dane aplikacji zawierają również awatary i buforowane zasoby. Poniższe polecenia służą do udokumentowanego czyszczenia. Każde z nich celowo usuwa dane.

docker exec -it nextcloud occ trashbin:cleanup --all-users
docker exec -it nextcloud occ versions:cleanup alice
docker exec -it nextcloud occ preview:cleanup

preview:cleanup usuwa wszystkie wygenerowane podglądy. Nextcloud wygeneruje je ponownie podczas otwierania tych plików przez użytkowników. Miejsce będzie więc stopniowo ponownie zajmowane, a procesor zostanie obciążony ich generowaniem. Jeśli wolumin jest tylko jednym z elementów szerszego problemu z miejscem na dysku, stare obrazy i nieaktualna pamięć podręczna kompilacji są zwykle drugim elementem.

Dlaczego pliki skopiowane na hosta nie pojawiają się w Nextcloud?

Nextcloud odczytuje pamięć podręczną plików z bazy danych, a nie bezpośrednio z katalogu. Skopiowanie pliku utworzyło go na dysku, ale nie dodało odpowiadającego mu wpisu w bazie danych, więc interfejs webowy nie ma czego wyświetlić. W podręczniku opisano dokładnie ten przypadek: po bezpośrednim skopiowaniu plików do katalogu danych należy wykonać skanowanie.

docker exec -it nextcloud occ files:scan --path="/alice/files/Photos"
docker exec -it nextcloud occ files:scan --all --unscanned -v
docker exec -it nextcloud occ files:scan --all

Argument --path pokazuje również układ katalogu danych: każdy użytkownik ma katalog nazwany zgodnie z nazwą użytkownika, a znajdujący się w nim katalog files zawiera pliki widoczne w interfejsie webowym. Należy przeskanować jedną ścieżkę, jeśli wiadomo, gdzie trafiły pliki. --all przechodzi przez wszystkich użytkowników i w dużej instancji wykonuje się długo. --unscanned przetwarza tylko pliki oznaczone jako jeszcze nie w pełni przeskanowane. -v wyświetla każdy przetwarzany plik, dzięki czemu można odróżnić polecenie, które tylko wygląda na zawieszone, od polecenia, którego postęp można monitorować.

Odpowiednie uprawnienia właściciela decydują o tym, czy samo skanowanie wystarczy. Jeśli użytkownik kontenera nie może zapisywać do pliku, plik zostanie zindeksowany, ale nie będzie można go przenieść. Lista będzie więc wyglądać poprawnie, natomiast zmiana nazwy lub usunięcie pliku z interfejsu webowego zakończy się niepowodzeniem.

Dlaczego operacje zapisu kończą się niepowodzeniem po ustawieniu PUID i PGID?

Jądro systemu porównuje liczby, a nie nazwy. PUID i PGID określają numeryczny identyfikator użytkownika (uid) oraz identyfikator grupy (gid), z którymi uruchamiany jest proces kontenera. Każdy plik na hoście również posiada numerycznego właściciela. Gdy te dwie liczby są różne, zapis jest odrzucany, niezależnie od tego, jak nazwy wyglądają po obu stronach.

docker exec -it nextcloud id abc
sudo ls -ln /var/lib/docker/volumes/nextcloud_nextcloud_data/_data

id abc wyświetla uid i gid, których kontener faktycznie używa; są to wartości PUID i PGID, które zostały ustawione. ls -ln wyświetla numerycznych właścicieli, przy czym kluczowe znaczenie ma -n: zwykłe ls -l tłumaczy te liczby za pomocą listy użytkowników hosta i pokazuje nazwę, która wewnątrz kontenera nie ma znaczenia. Należy porównać obie liczby.

Następnie należy przetestować zapis, zamiast zgadywać.

docker exec -u abc -it nextcloud touch /data/writetest

Permission denied z argumentem /data stanowi potwierdzenie. Należy naprawić uprawnienia właściciela z wnętrza kontenera, a następnie ponownie wykonać ten sam test.

docker exec -u 0 -it nextcloud chown -R abc:abc /data
docker exec -u abc -it nextcloud touch /data/writetest
docker exec -u abc -it nextcloud rm /data/writetest

Wykonanie tego z wnętrza kontenera jest celowe. W trybie rootless Docker identyfikatory użytkowników kontenera są mapowane poprzez zakres podrzędny w /etc/subuid, więc uid 1000 wewnątrz kontenera odpowiada znacznie wyższemu uid na hoście. Polecenie chown 1000:1000 wykonane na hoście ustawia właściciela, którego kontener nie może użyć, przez co zapis nadal kończy się niepowodzeniem. Uruchomienie chown wewnątrz kontenera przechodzi przez to samo mapowanie, którego używa proces Nextcloud, dzięki czemu liczby są zgodne z założenia. Jest to również powód, dla którego PUID i PGID muszą być zgodne z właścicielem na dysku przed rozpoczęciem jakiegokolwiek innego debugowania.

Jak wykonać kopię zapasową, aby przywracanie faktycznie zadziałało?

Bazę danych i katalogi należy pobrać z tego samego momentu. Tryb konserwacji blokuje logowanie, dzięki czemu między wykonaniem zrzutu a skopiowaniem danych nie zostanie przesłany żaden plik.

docker exec -it nextcloud occ maintenance:mode --on
docker exec nextcloud-db mariadb-dump --single-transaction -u nextcloud -p"$NEXTCLOUD_DB_PASSWORD" nextcloud > nextcloud-sqlbkp.sql
docker run --rm -v nextcloud_nextcloud_data:/data:ro -v "$PWD":/backup alpine:3.22 tar czf /backup/nextcloud-data.tgz -C /data .
docker run --rm -v nextcloud_nextcloud_config:/config:ro -v "$PWD":/backup alpine:3.22 tar czf /backup/nextcloud-config.tgz -C /config .
docker exec -it nextcloud occ maintenance:mode --off

Należy zwrócić uwagę, czego nie zawiera polecenie tworzące zrzut: flagi -t. TTY modyfikuje zakończenia wierszy, a zrzut SQL, który przez niego przejdzie, zostaje uszkodzony w sposób wykrywany dopiero podczas przywracania. Należy również pamiętać, że hasło podane w wierszu polecenia jest widoczne w danych wyjściowych ps podczas działania polecenia. Odczytanie go z pliku .env do powłoki pozwala uniknąć wpisywania go do historii powłoki, ale nie ukrywa rozwiniętego argumentu wiersza polecenia. Starsze obrazy baz danych zawierają mysqldump zamiast mariadb-dump. Dokumentacja opisuje oba warianty.

Aby przywrócić dane, należy wczytać zrzut do pustej bazy danych, rozpakować oba archiwa do nowych wolumenów, uruchomić kontenery, a następnie wyłączyć tryb konserwacji. Jeśli katalogi i zrzut pochodzą z różnych momentów, pamięć podręczna plików i dane na dysku są niespójne, a occ files:scan --all naprawia tylko jeden kierunek. Wyszukuje pliki, które istnieją bez odpowiadającego im wiersza. Nie może odtworzyć pliku, do którego odwołuje się wiersz.

Kopię należy przechowywać poza serwerem. Kopia znajdująca się na tym samym VPS zostanie utracona razem z VPS, dlatego restic do repozytorium poza serwerem jest częścią tego procesu. Z tego samego powodu migawka dostawcy jest innym narzędziem niż kopia zapasowa. Jeśli stos jest dopiero tworzony, pełna instalacja Nextcloud na VPS obejmuje reverse proxy i certyfikat TLS (transport layer security), których ten poradnik nie opisuje.

FAQ

Gdzie znajduje się katalog danych Nextcloud w kontenerze?

W przypadku obrazu linuxserver.io jest to /data wewnątrz kontenera, a config.php, aplikacje i motywy znajdują się w /config. Są to ścieżki w kontenerze. Aby ustalić ścieżkę na hoście, uruchom docker inspect nextcloud i odczytaj wartość Source w sekcji Mounts albo uruchom docker volume inspect dla woluminu i odczytaj Mountpoint. Inne obrazy Nextcloud używają innych ścieżek w kontenerze. Należy sprawdzić dokumentację przypisanego tagu i potwierdzić ścieżkę za pomocą docker exec -it nextcloud occ config:system:get datadirectory.

Dlaczego pliki skopiowane do woluminu nie pojawiają się w Nextcloud?

Nextcloud wyświetla wpisy z pamięci podręcznej plików w bazie danych, a nie odczytuje bezpośrednio katalogu. Plik, który trafił do katalogu bez użycia Nextcloud, nie ma odpowiedniego wpisu i pozostaje niewidoczny. Uruchom docker exec -it nextcloud occ files:scan --path="/alice/files/Photos" dla jednego katalogu albo occ files:scan --all dla wszystkich użytkowników. Jeśli pliki są widoczne, ale nie można ich przenosić ani usuwać, przyczyną są własności plików. Użytkownik kontenera musi mieć uprawnienia do ich zapisu.

Czy kopia woluminu danych wystarczy do odtworzenia Nextcloud?

Nie. Wolumin danych zawiera treść plików. Baza danych zawiera indeks plików, użytkowników i udostępnionych zasobów, a config.php zawiera dane uwierzytelniające bazy danych oraz identyfikator instancji. Do poprawnego odtworzenia potrzebne są katalog danych, katalog konfiguracji, baza danych oraz niestandardowe katalogi aplikacji i motywów, jeśli są używane. Wszystkie te elementy należy skopiować z tego samego momentu, ponieważ baza danych nowsza niż pliki może wskazywać pliki, które nie istnieją.

Dlaczego mój wolumin danych jest znacznie większy niż pliki widoczne dla użytkowników?

Podglądy, usunięte pliki i stare wersje znajdują się w tym samym woluminie, ale nie są uwzględniane w wartości widocznej dla użytkownika. Zmierz ich rozmiar za pomocą docker exec -it nextcloud sh -c 'du -sh /data/*'. Domyślnie kosz usuwa pliki przed upływem 30 dni, gdy potrzebne jest miejsce, a gdy miejsca jest wystarczająco dużo, przechowuje je dłużej. Czyszczenie wersji obejmuje połowę pozostałego miejsca przydzielonego kontom z limitem. W pozostałych przypadkach bezpośrednio wykorzystuje wolne miejsce systemu plików. Zachowanie najnowszych wersji może uniemożliwić osiągnięcie tego celu. Usuń te dane za pomocą occ trashbin:cleanup --all-users, occ versions:cleanup alice i occ preview:cleanup. Należy oczekiwać, że podglądy będą ponownie zajmować miejsce, gdy użytkownicy otworzą swoje pliki.

Czy można przenieść katalog danych Nextcloud na inny dysk?

Zamontuj nową lokalizację pod tą samą ścieżką w kontenerze zamiast zmieniać ścieżkę znaną Nextcloud. Zatrzymaj kontener i skopiuj starą zawartość na nowy dysk, zachowując własności (cp -a lub rsync -aAX). Następnie wskaż nową lokalizację jako wolumin lub bind mount w pliku Compose i uruchom kontener ponownie. Nextcloud nadal będzie widzieć /data, więc nie trzeba zmieniać żadnego wpisu w bazie danych. Zweryfikuj konfigurację za pomocą docker exec -it nextcloud occ config:system:get datadirectory i wykonaj jedno testowe przesłanie pliku.

Czy ten artykuł był przydatny?