Gdzie Nextcloud w Docker przechowuje pliki użytkownika

Gdzie Nextcloud w Dockerze przechowuje pliki

Nextcloud w Dockerze przechowuje pliki w katalogu danych wewnątrz kontenera, a rzeczywista lokalizacja na serwerze zależy od wolumenu lub montowania typu bind mount, które zostało do niego przypisane. W obrazie linuxserver.io, lscr.io/linuxserver/nextcloud, pliki użytkowników znajdują się w /data, a instalacja Nextcloud wraz z config.php znajduje się w /config. Obie te ścieżki są ścieżkami wewnątrz kontenera. Jedno polecenie wyświetla odpowiadającą im ścieżkę na hoście, a reszta tego przewodnika omawia trudniejszą część pytania: wszystko to, czego katalog danych nie zawiera.

Przypnij tag obrazu. Ścieżki są przypisane do obrazu, a nie do samego Nextcloud, a zmienny tag może ulec zmianie bez ostrzeżenia. Według stanu na sierpień 2026 aktualnym stabilnym tagiem dla tego obrazu jest 34.0.3.

services:
  nextcloud:
    image: lscr.io/linuxserver/nextcloud:34.0.3
    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:

Dwa hasła pochodzą z pliku .env znajdującego się obok pliku compose, dzięki czemu nie znajdują się one bezpośrednio w pliku compose. To łącznie trzy wolumeny w odpowiedzi, z czego tylko jeden przechowuje pliki użytkowników.

Wspomniane ścieżki kontenera pochodzą z dokumentacji tego konkretnego obrazu. Inny obraz Nextcloud może mieć inną strukturę systemu plików i przechowywać instalację w swoim własnym katalogu głównym serwera WWW, więc ścieżka skopiowana z wpisu na forum jest jedynie przypuszczeniem. Sprawdź faktyczną konfigurację uruchomionego kontenera.

docker inspect nextcloud

Sekcja Mounts tego wyjścia zawiera listę wszystkich montowań, z Source po stronie hosta oraz Destination po stronie kontenera. To zestawienie odpowiada na pytanie dotyczące Twojej konfiguracji, niezależnie od wybranego obrazu.

Jak znaleźć rzeczywistą ścieżkę hosta dla wolumenu?

Wolumen nazwany jest zarządzany przez Docker, więc użytkownik nie wybiera jego ścieżki. Należy o nią zapytać.

docker volume ls
docker volume inspect nextcloud_nextcloud_data

Nazwa ma znaczenie. Docker Compose dodaje prefiks do nazw wolumenów na podstawie nazwy projektu, która domyślnie odpowiada nazwie katalogu zawierającego plik compose. Wolumen zdefiniowany jako nextcloud_data w pliku zazwyczaj istnieje jako nextcloud_nextcloud_data na dysku. Polecenie docker volume ls wyświetla rzeczywiste nazwy. Wynik polecenia inspect wygląda następująco (wersja skrócona):

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

Mountpoint to właściwa odpowiedź. Należy odczytać ją z polecenia zamiast zakładać jej lokalizację, ponieważ ścieżka ta może ulec zmianie. W trybie rootless Docker cały katalog główny danych Docker znajduje się wewnątrz katalogu domowego użytkownika uruchamiającego demona, więc ścieżka ta zaczyna się w innym miejscu.

Bind mount eliminuje ten problem. Wystarczy wpisać - /srv/nextcloud/data:/data w pliku compose, a ścieżką hosta będzie ta, która została wpisana, co polecenie docker inspect raportuje jako Source. Wybór ten zmienia więcej niż tylko ścieżkę, ponieważ wolumeny nazwane a bind mounts różnią się sposobem obsługi uprawnień oraz tworzenia kopii zapasowych.

Dlaczego katalog danych nie jest kopią zapasową

Podręcznik Nextcloud wymienia pięć elementów, które musi zawierać kopia zapasowa: folder konfiguracyjny, folder niestandardowych aplikacji, folder danych, folder motywów oraz bazę danych. W tym obrazie foldery config, apps i theme znajdują się w /config, podczas gdy baza danych działa w osobnym kontenerze z własnym wolumenem. Skopiowanie samego /data oznacza zabezpieczenie najmniej istotnej części problemu.

Baza danych jest kluczowa, ponieważ interfejs WWW nie wyświetla zawartości katalogu. Wyświetla on 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 przy pustej bazie danych skutkuje posiadaniem bajtów bez indeksu: brak użytkowników, brak udostępnień, brak plików na liście. Przywrócenie bazy danych przy pustym /data powoduje, że każdy wiersz wskazuje na nieistniejący plik.

config.php przechowuje dane uwierzytelniające do bazy danych oraz zaufane domeny. Zawiera również identyfikator instancji, który jest nazwą folderu danych aplikacji wewnątrz katalogu danych. Należy zapytać uruchomioną instancję, zamiast polegać na wartościach zapamiętanych.

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

Pierwsze polecenie wyświetla katalog danych, z którego faktycznie korzysta ta instancja, w tym przypadku /data. Ten obraz dostarcza wrapper occ dla tej ścieżki, więc należy uruchomić go bezpośrednio przez docker exec. Nie należy kopiować dłuższej formy sudo oraz php occ z podręcznika Nextcloud, która jest przeznaczona dla instalacji poza kontenerem.

Co zapełnia wolumen danych?

Podglądy oraz historia poszczególnych użytkowników znajdują się w tym samym wolumenie co pliki, a żadna z tych wartości nie jest uwzględniana w statystykach zajętości prezentowanych użytkownikowi w interfejsie WWW.

• Podglądy to wygenerowane miniatury. Znajdują się one 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 domyślnie przyjmuje wartość auto, co oznacza przechowywanie ich przez 30 dni, a po tym czasie usuwanie tylko wtedy, gdy wymagane jest zwolnienie miejsca. Usunięte pliki nadal wliczają się do limitu użytkownika, a w przypadku jego przekroczenia ustawienie retencji jest ignorowane i zawartość kosza jest usuwana, aż do momentu zmieszczenia się w limicie.
• Stare wersje plików również są zachowywane. versions_retention_obligation również domyślnie przyjmuje wartość auto. Aplikacja Versions nigdy nie zajmuje więcej niż 50% wolnego miejsca użytkownika, a podczas czyszczenia usuwa najpierw najstarsze wersje, zachowując dwie najnowsze. Wersja, której użytkownik nadał nazwę ręcznie, nigdy nie jest usuwana.

Przed usunięciem jakichkolwiek danych należy dokonać pomiarów.

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

Pierwsza linia zwraca jedną liczbę dla każdego folderu użytkownika oraz folderu danych aplikacji. Jeśli wartość dla danych aplikacji jest wysoka, przyczyną są podglądy. Poniżej udokumentowano polecenia czyszczące; każde z nich służy do celowego usuwania danych.

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, gdy użytkownicy otworzą pliki, więc odzyskane miejsce będzie wracać stopniowo, obciążając przy tym procesor. Jeśli wolumen jest tylko częścią szerszego problemu z dyskiem, stare obrazy i nieaktualna pamięć podręczna kompilacji zazwyczaj stanowią pozostałą część.

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

Ponieważ Nextcloud odczytuje pliki z pamięci podręcznej w bazie danych, a nie bezpośrednio z katalogu. Skopiowanie pliku na dysk nie tworzy odpowiedniego wpisu w bazie, więc interfejs WWW nie ma czego wyświetlić. Dokumentacja techniczna opisuje ten przypadek: po skopiowaniu plików bezpośrednio do katalogu danych wymagane jest przeprowadzenie skanowania.

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

Argument --path pokazuje również strukturę wewnątrz katalogu danych: każdy użytkownik posiada folder nazwany zgodnie z jego nazwą użytkownika, a files wewnątrz niego zawiera zawartość widoczną w interfejsie WWW. Należy przeskanować konkretną ścieżkę, jeśli wiadomo, gdzie trafiły pliki. Polecenie --all sprawdza wszystkich użytkowników i trwa długo w przypadku dużych instancji. --unscanned dotyczy tylko plików oznaczonych jako jeszcze nie w pełni przeskanowane. -v wyświetla każdy plik w trakcie przetwarzania, co pozwala odróżnić polecenie, które wygląda na zawieszone, od takiego, którego postęp można monitorować.

Uprawnienia decydują o tym, czy samo skanowanie wystarczy. Plik, do którego użytkownik kontenera nie ma uprawnień zapisu, zostanie zaindeksowany, ale operacje na nim będą odrzucane. W rezultacie lista plików wygląda poprawnie, podczas gdy próba zmiany nazwy lub usunięcia pliku z poziomu interfejsu WWW koń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?

Pobierz bazę danych oraz foldery z tego samego momentu. Tryb konserwacji (maintenance mode) blokuje logowanie, dzięki czemu żadne dane nie zostaną przesłane między zrzutem bazy a kopiowaniem plików.

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

Zwróć uwagę, czego brakuje w poleceniu zrzutu: flagi -t. TTY zmienia znaki końca linii, a zrzut SQL, który przeszedł przez ten proces, jest uszkodzony w sposób wykrywalny dopiero podczas przywracania. Zauważ również, że hasło podane w linii poleceń jest widoczne w danych wyjściowych ps podczas działania procesu, dlatego należy wczytać je do powłoki z pliku .env zamiast wpisywać je ręcznie. Starsze obrazy baz danych dostarczają mysqldump zamiast mariadb-dump, a dokumentacja techniczna opisuje oba przypadki.

Aby przywrócić dane, wczytaj zrzut do pustej bazy danych, rozpakuj oba archiwa do świeżych wolumenów, uruchom kontenery, a następnie wyłącz tryb konserwacji. Jeśli foldery i zrzut pochodzą z różnych momentów, pamięć podręczna plików i zawartość dysku będą niespójne, a occ files:scan --all naprawi tylko jeden kierunek. Narzędzie to odnajdzie pliki, które istnieją bez przypisanego wiersza w bazie, ale nie przywróci pliku, do którego odwołuje się wiersz w bazie danych.

Przechowuj kopię poza serwerem. Kopia znajdująca się na tym samym VPS ginie wraz z nim, dlatego restic do zewnętrznego repozytorium stanowi niezbędny element tego procesu, a migawka (snapshot) dostawcy to inne narzędzie niż kopia zapasowa. Jeśli dopiero budujesz stos technologiczny, pełna instalacja Nextcloud na VPS zawiera informacje o reverse proxy oraz certyfikacie TLS (transport layer security), które zostały pominięte w tym przewodniku.

FAQ

Gdzie w kontenerze Docker znajduje się katalog danych Nextcloud?

W obrazie od linuxserver.io jest to /data wewnątrz kontenera, a instalacja przy użyciu config.php znajduje się w /config. Są to ścieżki wewnątrz kontenera. Aby poznać ścieżkę na hoście, wykonaj docker inspect nextcloud i odczytaj wartość Source w sekcji Mounts lub wykonaj docker volume inspect na wolumenie i odczytaj Mountpoint. Inne obrazy Nextcloud używają innych ścieżek, dlatego należy sprawdzić dokumentację dla użytej wersji (tag) i potwierdzić za pomocą docker exec -it nextcloud occ config:system:get datadirectory.

Dlaczego pliki skopiowane do wolumenu nie są widoczne w Nextcloud?

Nextcloud wyświetla wiersze z pamięci podręcznej plików w bazie danych, zamiast odczytywać zawartość katalogu. Plik, który trafił do systemu z pominięciem Nextcloud, nie posiada wpisu w bazie i pozostaje niewidoczny. Wykonaj docker exec -it nextcloud occ files:scan --path="/alice/files/Photos" dla pojedynczego folderu lub occ files:scan --all dla wszystkich użytkowników. Jeśli pliki są widoczne, ale nie można ich przenieść ani usunąć, przyczyną jest właściciel pliku: użytkownik kontenera musi posiadać uprawnienia do zapisu.

Czy kopia wolumenu z danymi wystarczy do przywrócenia Nextcloud?

Nie. Wolumen z danymi przechowuje zawartość plików. Baza danych przechowuje indeks plików, informacje o użytkownikach oraz udostępnieniach, a config.php zawiera dane uwierzytelniające bazy danych oraz identyfikator instancji. Poprawne odtworzenie wymaga folderu z danymi, folderu z konfiguracją, bazy danych oraz folderów z niestandardowymi aplikacjami i motywami, jeśli są używane. Wszystkie elementy muszą pochodzić z tego samego momentu, ponieważ baza danych nowsza niż pliki będzie wskazywać na nieistniejące obiekty.

Dlaczego wolumen z danymi zajmuje znacznie więcej miejsca niż suma plików użytkowników?

Podglądy, usunięte pliki oraz stare wersje znajdują się w tym samym wolumenie i nie są uwzględniane w statystykach widocznych dla użytkownika. Użyj docker exec -it nextcloud sh -c 'du -sh /data/*' do pomiaru zajętości. Kosz przechowuje usunięte pliki domyślnie przez 30 dni i czyści je wcześniej tylko w przypadku braku miejsca, a aplikacja Versions może zająć do połowy wolnego miejsca użytkownika. Usuń je za pomocą occ trashbin:cleanup --all-users, occ versions:cleanup alice oraz occ preview:cleanup. Należy pamiętać, że podglądy będą generowane ponownie w miarę otwierania plików przez użytkowników.

Czy mogę przenieść katalog danych Nextcloud na inny dysk?

Zamontuj nową lokalizację w tej samej ścieżce wewnątrz kontenera, zamiast zmieniać ścieżkę zapisaną w Nextcloud. Zatrzymaj kontener, skopiuj starą zawartość na nowy dysk z zachowaniem uprawnień (cp -a lub rsync -aAX), wskaż nową lokalizację w wolumenie lub bind mount w pliku Compose, a następnie uruchom kontener ponownie. Nextcloud nadal widzi /data, więc nie ma potrzeby modyfikacji wpisów w bazie danych. Zweryfikuj poprawność za pomocą docker exec -it nextcloud occ config:system:get datadirectory i wykonaj testowe przesyłanie pliku.