Jak hostować Gitea samodzielnie w 2026 roku: repozytoria, SSH i bezpieczne aktualizacje

Jeśli próbujesz już hostować Gitea samodzielnie, prawdopodobnie znasz ten frustrujący stan: interfejs działa, ale ROOT_URL generuje linki klonowania z localhost albo port SSH nie jest przekazywany. Ponowne utworzenie kontenera rzadko rozwiązuje konflikt między adresami URL, stanem i zależnościami.

Ten poradnik opiera się na jednym konkretnym kryterium ukończenia — sklonuj repozytorium przez HTTPS i SSH, wypchnij commit oraz obiekt LFS, otwórz issue i uruchom jedno zadanie na osobno zarejestrowanym runnerze Actions. Każda decyzja konfiguracyjna jest oceniana względem tego kryterium, a nie na podstawie zielonej plakietki kontenera.

Znajdź każdy trwały bajt w Gitea

Zanim powstanie pierwszy rzeczywisty rekord, zidentyfikuj cały stan: repozytoria, obiekty LFS, załączniki, konfigurację i bazę danych. Zamontuj /data przed bootstrapem, zapisz nieszkodliwe przykładowe dane i zastąp kontener, aby potwierdzić, że ta ścieżka rzeczywiście jest trwała. Potwierdź poprawność mountu, zapisując nieszkodliwe dane, zastępując Gitea i odczytując je ponownie.

Snapshoty są przydatne do szybkiego rollbacku, ale gdy host lub volume zniknie, potrzebny jest niezależny backup. Odtwórz dane w pustym środowisku z przypiętym obrazem i sprawdź, czy repozytoria przechodzą fsck, obiekty LFS można pobrać, a issues, releases i uprawnienia użytkowników odpowiadają stanowi sprzed backupu. Użyj persistent volumes i snapshotów, aby zachować rozdział między tymi dwoma mechanizmami odzyskiwania.

Zbuduj wymienialny kontener Gitea

Poniższe polecenie pokazuje granicę kontenera bez udawania, że konfiguruje każdą zewnętrzną usługę.

docker run -d \
  --name gitea \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v gitea-data:/data \
  -e GITEA__security__SECRET_KEY=replace-with-a-long-random-value \
  gitea/gitea:latest

Przed otwarciem ingressu sprawdź rozstrzygnięte zmienne środowiskowe, mounty i listener. W przypadku większej instalacji dodaj zweryfikowane ustawienia połączenia z Postgres lub MySQL oraz trasę SSH, jeśli jest potrzebna; dla prywatnych usług używaj prywatnych nazw. Pomyślne uruchomienie kończy się dopiero wtedy, gdy możesz sklonować repozytorium przez HTTPS i SSH, wypchnąć commit oraz obiekt LFS, otworzyć issue i uruchomić jedno zadanie na osobno zarejestrowanym runnerze Actions — a nie wtedy, gdy docker ps wyświetla Up.

Oddziel Gitea od zależności

Dla Gitea zdrowie procesu i zdrowie produktu to dwie różne kwestie. Port 3000 może odpowiadać, podczas gdy transakcja użytkownika nadal kończy się niepowodzeniem. Kontrakt sieciowy Gitea obejmuje Postgres lub MySQL w przypadku większej instalacji oraz trasę SSH, jeśli jest potrzebna. Prywatne endpointy utrzymuj w wewnętrznym DNS, zezwalaj tylko na wymagane połączenia wychodzące i przydziel Gitea ograniczone uprawnieniami dane uwierzytelniające usługi.

Po istotnych zmianach konfiguracji wykonaj następujące ćwiczenie gotowości: sklonuj repozytorium przez HTTPS i SSH, wypchnij commit oraz obiekt LFS, otwórz issue i uruchom jedno zadanie na osobno zarejestrowanym runnerze Actions. Nie umieszczaj kosztownych zewnętrznych testów w sondach liveness, aby awaria dostawcy nie powodowała pętli restartów. Prace nad capacity powinny uwzględniać liczbę repozytoriów, pakowanie obiektów Git, storage LFS, opóźnienia bazy danych i obciążenie runnera, a nie zwykłe żądania stron, ponieważ lepiej odzwierciedla to rzeczywiste obciążenie Gitea.

TLS jest proste, wygenerowane URL-e już nie

Udostępnij Gitea pod jednym hostem HTTPS, a surowy port 3000 pozostaw prywatny. Ustaw ROOT_URL i SSH_DOMAIN na adresy, których użytkownicy faktycznie używają do klonowania. Dzięki temu przeglądarki i klienci API nie poznają dwóch konkurencyjnych adresów.

Z czystego klienta wykonaj znaną, poprawnie działającą transakcję i sprawdź pierwsze żądanie, które kończy się niepowodzeniem. Jeśli problem dotyczy DNS lub TLS, skorzystaj z poradnika dotyczącego własnej domeny. Potraktuj komunikat „ROOT_URL generuje linki klonowania z localhost albo port SSH nie jest przekazywany” jako osobną diagnozę aplikacji, gdy trasa została już potwierdzona.

Przetestuj wdrożenie Gitea od początku do końca

Nie używaj ruchu pierwszego użytkownika jako testu akceptacyjnego Gitea. Przygotuj nieszkodliwy przykładowy stan i wykonaj pełną akcję „sklonuj repozytorium przez HTTPS i SSH, wypchnij commit oraz obiekt LFS, otwórz issue i uruchom jedno zadanie na osobno zarejestrowanym runnerze Actions”. Zanotuj dokładny publiczny URL, wynik, referencję obrazu i przedział logów powiązany z wykonaniem.

Zastąp kontener i powtórz test bez odbudowywania danych. Następnie odtwórz środowisko na pustym hoście; warunkiem odzyskania jest to, aby repozytoria przechodziły fsck, obiekty LFS można było pobrać, a issues, releases i uprawnienia użytkowników odpowiadały stanowi sprzed backupu. Przy każdym przejściu obserwuj liczbę repozytoriów, pakowanie obiektów Git, storage LFS, opóźnienia bazy danych i obciążenie runnera zamiast zwykłych żądań stron oraz definiuj alert dotyczący pogorszenia działania transakcji, a nie bezczynnych metryk kontenera.

Jedno z końcowych sprawdzeń powinno celowo zakończyć się niepowodzeniem: tymczasowo odbierz testowej tożsamości dostęp do Postgres lub MySQL w przypadku większej instalacji oraz do trasy SSH, jeśli jest potrzebna. Sprawdź, czy wynikający z tego komunikat Gitea wskazuje właściwą granicę zamiast uruchamiać usuwanie danych lub niekończący się restart. Przywróć poprawny stan i potwierdź, że ta sama przykładowa transakcja kończy się powodzeniem. Uwzględnij to krótkie ćwiczenie na checkliście release.

Przećwicz ryzykowną zmianę w Gitea

W przypadku Gitea monitoruj transakcję, a nie proces: klonowanie przez HTTPS i SSH, wypchnięcie commita oraz obiektu LFS, otwarcie issue i uruchomienie jednego zadania na osobno zarejestrowanym runnerze Actions. Połącz jej opóźnienie i współczynnik błędów z liczbą repozytoriów, pakowaniem obiektów Git, storage LFS, opóźnieniami bazy danych i obciążeniem runnera zamiast ze zwykłymi żądaniami stron, aby alert wskazywał ograniczony zasób.

Próba aktualizacji musi uwzględniać fakt, że migracje schematu, repository hooks, packages i third-party runners wymagają etapowej aktualizacji Gitea. Odtwórz dane, wykonaj migrację i uruchom transakcję przed zastąpieniem środowiska produkcyjnego. Jeśli ROOT_URL generuje linki klonowania z localhost albo port SSH nie jest przekazywany, nie usuwaj danych tylko po to, aby uzyskać zielony status uruchomienia; porównaj kolejno wersję, zmienne, mounty i dostępność zależności.

Chroń najcenniejszą część Gitea

Po pierwszym logowaniu sprawdź, co może zrobić anonimowy odwiedzający, zwykły użytkownik i administrator. Problemu z Gitea, którego należy unikać, jest pozostawienie instalatora lub pierwszego konta administratora dostępnych dłużej, niż jest to konieczne. Docelowa polityka zakłada zamknięcie instalatora po bootstrapie, ograniczenie administracji serwisem i stosowanie krótkotrwałych tokenów rejestracji runnerów.

Traktuj GITEA__security__SECRET_KEY zgodnie z jego rolą w Gitea: przechowuj wrażliwe wartości poza Gitem, dokumentuj skutki rotacji i nigdy nie zastępuj produkcyjnej wartości publicznym przykładem. Konta zależności trzymaj oddzielnie od kont użytkowników, w miarę możliwości blokuj nieużywany egress i ograniczaj pracę zależną od liczby repozytoriów, pakowania obiektów Git, storage LFS, opóźnień bazy danych i obciążenia runnera zamiast zwykłych żądań stron.

Co Dockup powinien automatyzować dla Gitea

W przypadku Gitea Dockup może utworzyć trasę i certyfikat TLS, zachować mounty, dostarczyć sekrety oraz umieścić Postgres lub MySQL w przypadku większej instalacji i trasę SSH, jeśli jest potrzebna, w prywatnej sieci, wdrażając rozwiązanie w Dockup lub na dołączonych serwerach.

Bramką release nadal jest konkretna transakcja Gitea: klonowanie przez HTTPS i SSH, wypchnięcie commita oraz obiektu LFS, otwarcie issue i uruchomienie jednego zadania na osobno zarejestrowanym runnerze Actions. Sprawdź również warunek odzyskania — repozytoria przechodzą fsck, obiekty LFS można pobrać, a issues, releases i uprawnienia użytkowników odpowiadają stanowi sprzed backupu. Te dwa testy pokazują, czy wdrożenie działa i czy można je odtworzyć.

Często zadawane pytania

Czego Gitea potrzebuje do wdrożenia produkcyjnego?

Przekieruj kontener Gitea na porcie 3000 przez jedno źródło HTTPS. Wymaganie sieciowe dla obsługi to Postgres lub MySQL w przypadku większej instalacji oraz trasa SSH, jeśli jest potrzebna. Nie uznawaj Gitea za gotową, dopóki nie możesz sklonować repozytorium przez HTTPS i SSH, wypchnąć commita oraz obiektu LFS, otworzyć issue i uruchomić jednego zadania na osobno zarejestrowanym runnerze Actions.

Które dane Gitea powinny znaleźć się w backupie?

Utrwal /data i uwzględnij repozytoria, obiekty LFS, załączniki, konfigurację i bazę danych w tym samym manifeście odzyskiwania. Poprawne odtworzenie Gitea ma miejsce tylko wtedy, gdy repozytoria przechodzą fsck, obiekty LFS można pobrać, a issues, releases i uprawnienia użytkowników odpowiadają stanowi sprzed backupu.

Czy Gitea wymaga HTTPS za reverse proxy?

Używaj HTTPS dla publicznego źródła Gitea, a port 3000 pozostaw na wewnętrznej trasie. Poprawnie zastosuj ustawienie Gitea: ustaw ROOT_URL i SSH_DOMAIN na adresy, których użytkownicy faktycznie używają do klonowania. W przypadku Gitea HTTPS chroni dane uwierzytelniające lub treści użytkowników podczas transmisji i zapewnia spójne zachowanie klienta zależne od originu.

Jak testować aktualizację Gitea?

Odtwórz bieżący stan Gitea w odizolowanym wdrożeniu, zastosuj wersję kandydującą i ponownie wykonaj transakcję akceptacyjną. Zwróć szczególną uwagę na to, że migracje schematu, repository hooks, packages i third-party runners wymagają etapowej aktualizacji Gitea. Zachowaj poprzedni obraz Gitea do czasu zrozumienia granicy migracji danych i rollbacku.