Deep Dive: Nextcloud na K3s – pody PHP, bazy danych na hoście i Office w przeglądarce
Nextcloud to duża aplikacja PHP z zadaniami w tle, powiadomieniami push, podglądami, pakietem biurowym i dziesiątkami aplikacji. Jak jej części współpracują tu na dwóch serwerach, co utrzymuje je w szybkości, jakie ostrzeżenia są spodziewane – i błędy, które nauczyły najwięcej.

🌐 Także w: English · Deutsch · Français · Español · Italiano · Português · Nederlands
Deep Dive z serii wokół Ansible Tour. Tour objaśnia role, deep dives technologię pod spodem: jak działa, dlaczego jest tu używana w ten sposób i co poszło nie tak po drodze.
W tym setupie działają dwa serwery Nextcloud – jeden dla organizacji z około 150 kontami i prawie 400 GB plików, drugi dla małej grupy. Oba są budowane z tych samych ról (część 4 touru). Ten post wyjaśnia, jak zbudowany jest Nextcloud, jak elementy są rozdzielone między hosta i klaster i czego dotąd nauczyło jego utrzymanie.
Spis treści
🧭 Jak działa Nextcloud
Jedna aplikacja PHP, wiele punktów wejścia
Nextcloud to PHP. Każda strona w przeglądarce, każde żądanie WebDAV klienta synchronizacji i każde wywołanie API aplikacji mobilnych to żądanie PHP przez nginx do PHP-FPM. Same pliki leżą w katalogu danych; baza danych zna każdy plik dzięki tabeli file cache – nazwa, rozmiar, ETag, uprawnienia – więc listowanie nigdy nie musi dotykać dysku.
Blokady i cache
Gdy dwóch klientów zmienia ten sam plik, o tym, kto wygrywa, decyduje transactional file locking. Blokady muszą być widoczne dla wszystkich procesów PHP jednocześnie, dlatego trzymane są w Redisie. Obok tego APCu cache’uje w obrębie procesu, a Redis między procesami.
Zadania w tle
Sprzątanie, wygaszanie kosza i wersji, powiadomienia, sprawdzanie aktualizacji aplikacji, wstępne generowanie podglądów – Nextcloud prowadzi kolejkę zadań w bazie danych. Coś musi regularnie uruchamiać cron.php, żeby ją przerabiać; Nextcloud zaleca co pięć minut.
Push, podglądy, office
- notify_push to mały daemon w Ruście dostarczany wewnątrz aplikacji. Klienci trzymają z nim otwarty WebSocket i dowiadują się o zmianach od razu, zamiast pytać co 30 sekund.
- Podglądy to miniatury, generowane przy pierwszym wyświetleniu albo z wyprzedzeniem przez aplikację Preview Generator, i zapisywane w folderze danych aplikacji.
- Nextcloud Office to aplikacja richdocuments plus serwer Collabora Online. Przeglądarka ładuje edytor z Collabory; Collabora pobiera i zapisuje dokument w Nextcloud przez protokół WOPI, z tokenem na sesję.
Aplikacje i occ
Prawie wszystko poza plikami jest aplikacją – kalendarz, kontakty, Talk, group folders. occ to narzędzie wiersza poleceń do całej administracji: status, aktualizacje, tryb konserwacji, konfiguracja, skanowanie plików, naprawy bazy danych.
🛡️ Dlaczego jest tutaj
- Pliki, kalendarze, kontakty i office w jednym miejscu, dla ludzi, którzy nie powinni musieć wiedzieć, czym jest WebDAV.
- Dane zostają na własnych serwerach organizacji. Żaden dostawca nie decyduje o dostępie, cenach ani funkcjach.
- Ekosystem. Aplikacje na prawie każdą potrzebę, klienci na każdą platformę, duża społeczność.
🔧 Co robi to repozytorium
Co działa gdzie
| Komponent | Gdzie | Rola |
|---|---|---|
| nginx + PHP-FPM + exporter | Pod nextcloud | next_k3s_deploy |
| notify_push | Własny Deployment, ten sam obraz | next_k3s_deploy |
| Collabora Online | Własny Deployment | next_k3s_deploy |
| Zadania w tle | CronJob co 5 min | next_k3s_deploy |
| MariaDB | Host, mysqld_t | next_mariadb |
| Redis | Host, redis_t | next_redis |
| Ustawienia, aplikacje, WOPI, polityka haseł | przez occ | next_config |
Ciężkie, cenne komponenty – baza danych i dane – żyją na hoście, z pełnym sandboxem systemd i własnymi domenami SELinux. Te wymienialne – PHP, Collabora, daemon push – działają w klastrze. Services Kubernetesa bez selektorów, wskazujące na IP węzła, udostępniają podom MariaDB i Redis pod nazwami mariadb i redis; nftables dopuszcza ten port tylko z sieci podów. Kod PHP (/srv/nextcloud-www) i dane (/data) to wolumeny hostPath z własnymi etykietami SELinux.
Konfiguracja warstwami
Nextcloud czyta config.php, a potem każdy *.config.php w katalogu konfiguracji w kolejności alfabetycznej, przy czym późniejsze pliki wygrywają. Repozytorium z tego korzysta: custom.config.php z ConfigMapy niesie ustawienia (cache, podglądy, proxy, logowanie), redis.config.php z Secretu niesie hasło do Redisa. Oba są montowane przez subPath, który w działającym podzie nigdy się nie aktualizuje; suma kontrolna wszystkiego, co zamontowane, jest adnotacją na podzie, więc zmiana powoduje jego ponowne wdrożenie. Pierwotnie ta suma obejmowała tylko ConfigMapy – nowe ustawienie podglądów siedziało kiedyś dzień w ConfigMapie, podczas gdy pod wciąż używał starego pliku. Od tej serii obejmuje także Secret, po tym jak deep dive o Redisie wykazał, że zrotowane hasło nie dotarłoby do poda.
Collabora
TLS kończy się na ingressie, więc Collabora działa za nim po zwykłym HTTP i jest o tym poinformowana. num_prealloc_children utrzymuje tyle procesów dokumentów uruchomionych z wyprzedzeniem; otwarcie dokumentu zużywa jeden, a jeśli żaden nie jest gotowy, użytkownik czeka, aż wystartuje nowy. Sporadyczne „nie udało się załadować, ponowna próba działa” tuż po restarcie Collabory to właśnie to. Większy serwer trzyma dziesięć gotowych, mniejszy sześć. next_config ustawia allowlistę WOPI na sieć podów – tylko Collabora może wywoływać endpointy WOPI – i każe Nextcloud ponownie wczytać dokument discovery Collabory po każdej zmianie Collabory.
Jeden szczegół instalacji kosztował całe popołudnie: occ app:install richdocuments w powtarzalny sposób obcinał przy rozpakowywaniu jeden plik aplikacji, a kontrola integralności potem się nie udawała. Dlatego rola sama pobiera tarball ze sklepu z aplikacjami, rozpakowuje go przez tar i weryfikuje podpisy aplikacji za pomocą occ integrity:check-app.
Wniosek: Ostrzeżenie o integralności po instalacji jest prawdziwe. Tutaj przyczyną było narzędzie, które przy rozpakowywaniu obcięło plik, a nie aplikacja.
Aktualizacje dwóch rodzajów
Zmiana wersji to nowy tag obrazu w versions.yml i uruchomienie głównego playbooka; entrypoint kontenera wykonuje przy starcie occ upgrade. Sam Nextcloud odmawia przeskoczenia wersji major, więc skok z 32 na 34 to dwa kroki. Przebudowane obrazy – Docker Hub przebudowuje niezmienione tagi z poprawkami obrazu bazowego, a K3s nigdy sam z siebie nie pobiera ich ponownie – to zadanie nextcloud-update.yml. Odmawia on działania bez --limit (jeden serwer naraz), odmawia startu na instancji w trybie konserwacji lub z oczekującą aktualizacją bazy, restartuje tylko Deploymenty, których obraz naprawdę się zmienił, wykonuje occ upgrade jako siatkę bezpieczeństwa, aktualizuje aplikacje, restartuje drugi raz (OPcache nie sprawdza znaczników czasu, patrz deep dive o PHP-FPM) i sprawdza status. Jeśli coś się nie uda, blok rescue zbiera stan do ręcznej decyzji. Oba serwery działają na Nextcloud 34.
Od 26 października 2026 pod Nextcloud jest wymieniany bez przestoju, o ile obraz pozostaje ten sam – przy zmianach konfiguracji i przebudowach tego samego tagu: nowy pod staje się gotowy, potem stary się zatrzymuje. Gdy obraz się zmienia, zostaje Recreate. Entrypoint kopiuje wtedy nowy kod do /var/www/html i wykonuje occ upgrade, a w tym czasie żaden stary pod nie może serwować stron z tego samego katalogu.
Wniosek: Rolling update jest bezpieczny tylko wtedy, gdy dwie wersje mogą działać jednocześnie. Podczas zmiany wersji Nextcloud nie mogą.
Izolacja
- NetworkPolicy pozwala Collaborze rozmawiać tylko z Nextcloud i DNS oraz przyjmować połączenia tylko od Nextcloud i węzła. Pod Nextcloud i daemon push jeszcze żadnej nie mają – inaczej niż na blogu, gdzie każdy pod jest izolowany. W klastrze, w którym nie ma nic innego, to nie są otwarte drzwi, ale brakuje jednej warstwy; znalezione podczas pisania tego artykułu i zaproponowane.
- Admission policy dopuszcza tylko obrazy z allowlisty rejestrów – łącznie z obrazem solvera ACME z cert-managera, który działa w tej przestrzeni nazw; na blogu jego brak zostawił kiedyś żądanie certyfikatu w zawieszeniu bez żadnego błędu.
- Żadnych tokenów service account w podach – nic w nich nie rozmawia z API Kubernetesa.
- ClamAV skanuje pliki w tle o 04:30, z wykluczeniem podglądów i formatów multimedialnych – przed tą zmianą skan był przyczyną serwera, który bez widocznego powodu pokazywał się jako „zajęty”.
📊 Zmierzone
| Nextcloud A | Nextcloud B | |
|---|---|---|
| Wersja | 34.0.5 | 34.0.5 |
| Konta / aktywne w ostatnich 7 dniach | 152 / 27 | 26 / 1 |
| Dane | 388 GB | 16 GB |
| Wpisy w file cache | 73 061 | 7 415 |
| Aplikacje włączone / wyłączone | 43 / 22 | 61 / 8 |
| Przebieg zadań w tle (cron.php) | 8–16 s co 5 min | 6–8 s co 5 min |
| Najdłuższe pojedyncze zadanie | 133 s (sprawdzanie aktualizacji) | 59 s (sprawdzanie aktualizacji) |
| Przegląd administracyjny | wszystkie kontrole zielone | jeden błąd w logu, spodziewany (patrz niżej) |
File cache większego serwera miał po migracji ze starego serwera ponad dziesięć razy więcej wpisów: przywrócona baza wciąż zawierała cały indeks plików starego serwera, a occ files:cleanup nic nie robił, dopóki istniał wiersz storage starej ścieżki. Ćwierć tego, co zostało, należała do pozostałości wcześniej używanej aplikacji biurowej. Oba zostały usunięte – po kopii zapasowej i po policzeniu żywych wierszy, bo dane wyłączonych aplikacji z zasady są zachowywane, na wypadek gdyby ktoś chciał je z powrotem.
Wniosek: Przywrócona baza danych przynosi ze sobą indeks plików starego serwera. occ files:cleanup usuwa go dopiero wtedy, gdy wpis starego storage zostanie skasowany.
🧰 Codzienna administracja
occ() { k3s kubectl -n nextcloud exec deploy/nextcloud -c nextcloud-fpm -- \
runuser -u www-data -- php /var/www/html/occ "$@"; }
occ status
occ setupchecks # the admin overview, on the command line
occ maintenance:mode --on # before anything that touches data
occ files:scan --path="/alice/files" # after files were changed outside Nextcloud
occ db:add-missing-indices
occ background-job:list --limit=20
occ app:list --disabled
Spodziewane ostrzeżenia
- „Błędy w logu” na mniejszym serwerze: jeden błąd bazy o 03:30 – nocny reboot, podczas którego pod zadania w tle nie mógł rozwiązać nazwy
mariadb. Nieszkodliwe, ale zostaje w przeglądzie, dopóki log się nie zrotuje. - „Office nie załadował się, ponowna próba działa” tuż po restarcie: Collabora nie miała jeszcze żadnego wstępnie uruchomionego procesu.
- Ostrzeżenia o integralności po ręcznej zmianie w katalogu aplikacji są prawdziwe: Nextcloud podpisuje swój kod i każdy edytowany plik wychodzi na jaw. Nigdy nie edytuj kodu aplikacji na miejscu.
Kopie zapasowe i odtwarzanie
Co noc maszyna backupowa pobiera przez SSH zrzut bazy, config.php i katalog danych, i przechowuje ich wersje przez 365 dni. Odtworzenie to proces odwrotny plus occ maintenance:data-fingerprint, który informuje klientów synchronizacji, że stan serwera się zmienił, żeby nie skasowali tego, co uważają za nowe.
🆘 Ściąga: objaw → polecenie
Krótka wersja tego artykułu na moment, gdy coś jest nie tak. Uruchamiaj na hoście jako root; <…> to placeholdery. occ i wp to funkcje powłoki z deep dives o Nextcloud i WordPressie.
| Objaw | Polecenie |
|---|---|
| Pierwsze spojrzenie | occ statusocc setupchecks |
| Utknął w trybie konserwacji | occ maintenance:mode --off |
| Brakuje plików zmienionych poza Nextcloud | occ files:scan --path="/<user>/files" |
| Stary kod po aktualizacji aplikacji | k3s kubectl -n nextcloud rollout restart deployment/nextcloud |
| Zadania w tle się spóźniają | occ background-job:list --limit=20k3s kubectl -n nextcloud get cronjob nextcloud-cron |
| Dokumenty Office się nie otwierają | k3s kubectl -n nextcloud logs deploy/collabora --tail=50occ richdocuments:activate-config |
| Klienci nie synchronizują od razu | occ notify_push:self-testk3s kubectl -n nextcloud logs deploy/notify-push --tail=20 |
| Podglądy zjadają dysk | occ preview:cleanup # never rm: previews live in the database |
| Ostrzeżenia po aktualizacji | occ db:add-missing-indicesocc app:list --disabled |
| Po odtworzeniu kopii zapasowej | occ maintenance:data-fingerprint |
🎯 Wnioski
- To, co cenne – baza danych i dane – należy na hosta, to, co wymienialne, do klastra.
- Konfiguracja warstwami: późniejsze pliki
*.config.phpwygrywają, notify_push czyta tylkoconfig.php. - Po
occ upgradelubapp:updatezrestartuj poda, inaczej dalej działa stary bytecode. - Rolling update tylko tam, gdzie dwie wersje mogą działać jednocześnie.
- Po migracji posprzątaj stary indeks plików.
⚖️ Alternatywy – i dlaczego Nextcloud
| Opcja | Mocna strona | Dlaczego nie tutaj |
|---|---|---|
| Seafile | Dużo szybsza synchronizacja, przechowywanie na poziomie bloków | Mniej funkcji groupware, dane nie są przechowywane jako zwykłe pliki. |
| ownCloud Infinite Scale | Go, bez PHP, bez bazy danych | Inna architektura, mniejszy ekosystem aplikacji, oznaczałoby migrację wszystkiego. |
| Chmura własnościowa | Nic do utrzymywania | O danych i dostępie decyduje dostawca – przeciwieństwo celu. |
| Nextcloud | Funkcje, aplikacje, klienci, społeczność, istniejące dane | Wybrany. |
Nextcloud nie jest trudny do zainstalowania; wymagające jest dobre utrzymanie go, bo to tuzin usług udających jedną. Podział według kryterium „cenne czy wymienialne” – baza danych i pliki na hoście, PHP i office w klastrze – sprawił, że o każdej części łatwiej myśleć. Błędy z tego posta pojawiły się prawie wszystkie na styku między nimi.
