Kopia zapasowa i przywracanie serwera Gitea

Kopie zapasowe Gitea obejmują trzy dynamiczne komponenty – bazę danych, repozytoria git oraz pliki aplikacji – a od 2024 roku wbudowane polecenie gitea dump obsługuje je wszystkie w jednym przebiegu.

W poście Testowanie Gitea zainstalowaliśmy serwer Gitea. To jest jego kontynuacja: jak faktycznie tworzyć kopie zapasowe i, co ważniejsze, przywracać je, gdy coś pójdzie nie tak.

Aby zobaczyć kompletną kolekcję narzędzi developerskich, w tym przepływy Git i zarządzanie Dockerem, zobacz Narzędzia developerskie: Kompletny przewodnik po współczesnych przepływach pracy.

Jeśli konfigurujesz Gitea po raz pierwszy, sprawdź Wybór darmowego serwera git on-prem - Gitea wygrywa! po szczegóły instalacji oraz Gitea SSL z Apachem jako proxy odwróconym dla bezpiecznego wdrożenia.

Kiedy ćwiczyć tę procedurę

Teraz, jako środek ostrożności przed czymś strasznym, to dobry moment, aby przećwiczyć procedurę tworzenia kopii zapasowej i przywracania – zanim naprawdę jej potrzebujesz, a nie po tym, jak umrze dysk.

Lepiej się zabezpieczyć niż potem żałować.

Gdzie znajdują się dane

Instancja Gitea to w rzeczywistości trzy komponenty, które muszą pozostać zsynchronizowane:

• kod (repozytoria git)
• filestore (załączniki, awatary, obiekty LFS, indeksatory)
• baza danych (użytkownicy, problemy, PR-y, ustawienia)

W naszym środowisku testowym wszystkie razem zajmują nieco ponad 700 MB:

Ponieważ te trzy elementy odwołują się do siebie nawzajem, własna dokumentacja Gitea jest jednoznaczna co do spójności kopii zapasowej: instancja powinna zostać zatrzymana na czas tworzenia kopii zapasowej, w przeciwnym razie repozytorium skopiowane w trakcie migracji może się rozjeżdżać z tym, co baza danych uważa za zrobione. Przywracanie, z tego samego powodu, również musi następować jako jedna transakcja.

Łatwy sposób - gitea dump

To jest część, która uległa zmianie od poprzedniej wersji tego artykułu: zamiast ręcznego przerzucania pg_dump, tar i osobnych folderów, Gitea dostarcza pojedyncze polecenie dump, które spakuje bazę danych, repozytoria, dane LFS, załączniki i konfigurację w jedno archiwum.

gitea dump -c /sciezka/do/app.ini

Wynikiem jest plik z timestampem, np. gitea-dump-1610949662.zip, zawierający:

• app.ini - kopia pliku konfiguracyjnego
• custom/ - modyfikacje pod custom/
• data/ - załączniki, awatary, obiekty LFS, indeksatory (oraz plik SQLite, jeśli to jest Twoja baza danych)
• repos/ - pełna kopia katalogu repozytoriów
• gitea-db.sql - zrzut SQL bazy danych
• log/ - logi (niepotrzebne do przywracania)

Przydatne flagi, o których warto wiedzieć:

• --file nazwa / -f nazwa - nazwa pliku wyjściowego (- dla stdout, przydatne do bezpośredniego piping do scp lub storage obiektowego)
• --type - format wyjścia: zip (domyślnie), tar, tar.gz, tar.xz, tar.zst itd.
• --database / -d - wymuś dialektę SQL w gitea-db.sql (sqlite3, mysql, mssql, postgres) - przydatne przy migracji między silnikami baz danych
• --skip-repository / -R, --skip-lfs-data, --skip-attachment-data, --skip-package-data, --skip-log, --skip-db - ogranicz kopię zapasową do tego, czego potrzebujesz
• --tempdir / -t - miejsce, gdzie przechowywane są pliki tymczasowe (domyślnie /tmp lub $TMPDIR) - upewnij się, że ma wystarczająco dużo wolnego miejsca na całą instancję

Uruchamianie gitea dump w Dockerze

Ponieważ większość wdrożeń self-hosted uruchamia Gitea przez docker-compose, polecenie musi zostać uruchomione wewnątrz kontenera, jako użytkownik git, z katalogu tymczasowego kontenera:

cd ~/gitea-srv-local

# utwórz kopię zapasową wewnątrz działającego kontenera
sudo docker exec -u git -it -w /tmp gitea bash -c \
  '/usr/local/bin/gitea dump -c /data/gitea/conf/app.ini'

# skopiuj wynikowy plik zip z kontenera
sudo docker cp gitea:/tmp/gitea-dump-*.zip ./gitea-backups/

-w /tmp ma znaczenie: dump musi zapisać i spakować swój tymczasowy katalog roboczy, a jego uruchomienie gdziekolwiek bez uprawnień zapisu zakończy się błędem uprawnień.

Następnie, jak wcześniej, przenieś archiwum z maszyny:

scp uname@gitea-srv-ip-addr:~/gitea-srv-local/gitea-backups/gitea-dump-*.zip ~/gitea-backups/

Jeśli wolisz tworzyć kopię zapasową bazy danych za pomocą natywnych narzędzi (własna dokumentacja Gitea zaleca to dla MySQL/PostgreSQL, ponieważ zrzut SQL oparty o XORM w gitea dump ma znane problemy krawędziowe przy przywracaniu), możesz nadal to zrobić obok:

sudo docker exec -t gitea-srv-local_db_1 bash -c \
  'pg_dump gitea -U gitea --file=/var/lib/postgresql/backups/gitea-db-$(date +%Y-%m-%d).sql'

Zobacz Ściągawka PostgreSQL w celu uzyskania dodatkowych opcji pg_dump/pg_restore, oraz Ściągawka Docker Compose, jeśli jakaś z powyższych składni docker exec/docker cp wygląda na nieznajomą.

Jak - Przywracanie

Nadal nie ma polecenia jedno-stopniowego do przywracania – dokumentacja Gitea otwarcie stwierdza, że to pozostaje ręcznym procesem przemieszczania plików z powrotem na miejsce i przywracania zrzutu bazy danych. Ale! Zawsze najpierw sprawdź oryginalną dokumentację, ponieważ ścieżki i układy kontenerów zmieniają się między wersjami.

# zainstaluj/uruchom świeży gitea (tę samą wersję co kopia zapasowa), a następnie go zatrzymaj
sudo docker-compose down

# rozpakuj kopię zapasową
unzip gitea-dump-1610949662.zip -d gitea-restore
cd gitea-restore

# przywróć repozytoria i dane do woluminów używanych przez gitea
sudo cp -r repos/* ../gitea/git/
sudo cp -r data/* ../gitea/gitea/
sudo chown -R 1000:1000 ../gitea/git ../gitea/gitea

# uruchom gitea ponownie
sudo docker-compose up -d

# przywróć bazę danych
sudo docker exec -i gitea-srv-local_db_1 psql -U gitea gitea < gitea-db.sql

Jeśli skopiowałeś bazę danych osobno za pomocą pg_dump/pg_restore, przywróć ten zrzut tak, jak to robisz dla każdej innej instancji Postgres – zobacz Ściągawka PostgreSQL po dokładne polecenia.

Regeneracja hooków po przywróceniu

Jeśli przywróciłeś do innej metody instalacji (binary vs Docker) lub innej ścieżki, git hooks wbudowane w każde repozytorium nadal będą wskazywać na stare ścieżki. Napraw to za pomocą:

sudo docker exec -u git -it gitea bash -c '/usr/local/bin/gitea admin regenerate hooks'

Pominięcie tego kroku to klasyczna przyczyna niepowodzenia push bezpośrednio po przywróceniu, bez widocznego błędu w UI.

Weryfikacja przywracania

Zanim uznasz to za zakończone:

1. Zaloguj się do UI i potwierdź, że użytkownicy, problemy i ustawienia wyglądają poprawnie.
2. Sklonuj jedno repozytorium i wyślij trywialny commit, aby potwierdzić, że hooki działają.
3. Uruchom gitea doctor check (dodaj --fix, jeśli wykryje coś), aby wcześnie wychwycić niezgodności ścieżek lub uprawnień.

Przywracanie pojedynczego repozytorium - restore-repo

Drugą naprawdę nową częścią od ostatniej wersji tego artykułu jest para poleceń do kopii zapasowej i przywracania na poziomie repozytorium, osobno od całego workflow dump/przywacania instancji powyżej. Są przydatne, gdy potrzebujesz odzyskać tylko jeden projekt – powiedzmy, że ktoś usunął repozytorium na siłę – zamiast cofać cały serwer.

dump-repo wyciąga pojedyncze repozytorium (opcjonalnie wraz z jego problemami, PR-ami, wiki i innymi metadanymi) do lokalnego katalogu:

gitea dump-repo \
  --git_service gitea \
  --clone_addr https://gitea.example.com/owner/repo.git \
  --auth_token <token> \
  --repo_dir /backup/repos/owner/repo \
  --units wiki,issues,labels,releases,milestones,pull_requests,comments

restore-repo następnie odtwarza ten katalog z powrotem w instancji, do wybranego owner/repo:

gitea restore-repo \
  --repo_dir /backup/repos/owner/repo \
  --owner_name owner \
  --repo_name repo \
  --units issues,labels,milestones,pull_requests,comments

Obie listy --units są opcjonalne – pomijając je, migracja obejmuje wszystko, co jest wspierane. Ta para jest w istocie narzędziem do migracji (działa również wobec GitHub/GitLab jako źródło przez --git_service), ale pięknie służy jako lekka, per-repo alternatywa dla pełnego gitea dump, gdy pełne przywracanie byłoby zbędne.

Automatyzacja

Czynna kopia zapasowa plus kopia poza maszyną to dwu-wierszowy job cron, gdy powyższe ręczne kroki zadziałają:

# /etc/cron.d/gitea-backup
0 2 * * * root docker exec -u git -w /tmp gitea gitea dump -c /data/gitea/conf/app.ini -f - > /home/uname/gitea-backups/gitea-dump-$(date +\%F).zip 2>> /var/log/gitea-backup.log

Połącz to z czyszczeniem retencji (find ~/gitea-backups -mtime +14 -delete) i kopią off-site przez scp/rsync, tak aby awaria pojedynczego hosta nie zabrała ze sobą kopii zapasowych.

Rozwiązywanie problemów

• permission denied podczas dump – nie działasz jako użytkownik git, lub --tempdir/-w wskazuje na katalog, do którego użytkownik kontenera nie ma uprawnień zapisu.
• Przywracanie się udaje, ale git push zawodzi – hooki nie zostały zregenerowane; uruchom gitea admin regenerate hooks.
• Błędy przywracania bazy danych na dużej instancji – preferuj natywny pg_dump/mysqldump nad SQL wbudowany w zip gitea dump; jest znany z chropowatych krawędzi przy przywracaniu dla dużych lub nietypowych schematów.
• Przywrócono do nowej dużej wersji – uruchom gitea doctor check --all --fix i sprawdź noty wydania dla kroków migracji tej wersji, zanim założysz, że przywracanie jest kompletne.

Dla szybkiego odniesienia do poleceń Git, zobacz GIT Cheatsheet: Najbardziej przydatne polecenia GIT.

Przydatne linki

• Kopie zapasowe i przywracanie - Dokumentacja Gitea
• Referencja Gitea Command Line
• Ściągawka PostgreSQL
• Ściągawka Docker Compose
• Ściągawka Docker
• Gitflow Wyjaśnione: Krok po kroku, Alternatywy, Zalety i Wady