Jak hostować HedgeDoc samodzielnie w 2026 roku: WebSockets, OAuth i przesyłane pliki

Istnieją dwa warianty „uruchamiania HedgeDoc”: kontener działa albo usługa faktycznie realizuje swoje zadanie. Liczy się tylko ten drugi. Dowodem jest utworzenie notatki, jednoczesna edycja w dwóch przeglądarkach, przesłanie obrazu i uwierzytelnienie za pomocą wybranego dostawcy.

HedgeDoc służy do tworzenia współdzielonych notatek Markdown w czasie rzeczywistym. Wdrożenie musi zachować elementy odpowiedzialne za to działanie; port, volume i certyfikat to dane wejściowe, a nie rezultat.

Twórz backupy stanu, którego HedgeDoc nie potrafi odtworzyć

Określ RPO i RTO dla HedgeDoc, uwzględniając bazę danych, przesłane pliki i konfigurację uwierzytelniania. Zamontuj /hedgedoc/public/uploads przed bootstrapem, zapisz nieszkodliwe dane testowe i wymień kontener, aby potwierdzić, że ta ścieżka rzeczywiście jest trwała. Named volume rozwiązuje problem trwałości danych przy ponownym wdrożeniu, ale nie chroni przed przejęciem ani utratą serwera.

Przygotuj czyste środowisko odtwarzania, użyj tej samej przypiętej wersji aplikacji i potwierdź, że wracają notatki, rewizje, użytkownicy i przesłane pliki oraz że dwie przeglądarki mogą współpracować nad odtworzoną notatką. Zapisz komendy, poprawki właściciela i czas wykonania. Dobrym standardem jest poradnik dotyczący backupów: backup zyskuje zaufanie po odtworzeniu, a nie po przesłaniu.

Oddziel HedgeDoc od jego zależności

Stan procesu i stan produktu to w przypadku HedgeDoc dwie różne kwestie. Port 3000 może odpowiadać, mimo że transakcja widoczna dla użytkownika nadal kończy się błędem. Kontrakt sieciowy HedgeDoc obejmuje Postgres oraz opcjonalnych dostawców OAuth i SMTP. Prywatne endpointy trzymaj w wewnętrznym DNS, zezwalaj tylko na wymagane połączenia wychodzące i nadaj HedgeDoc ograniczone uprawnienia do korzystania z usług.

Po istotnych zmianach konfiguracji wykonuj ten test gotowości: utwórz notatkę, edytuj ją jednocześnie w dwóch przeglądarkach, prześlij obraz i uwierzytelnij się za pomocą wybranego dostawcy. Nie umieszczaj kosztownych testów zewnętrznych w sondach liveness, aby awaria dostawcy nie powodowała pętli restartów. Prace nad wydajnością powinny uwzględniać połączenia WebSocket, zapisy do bazy danych, przesłane multimedia i historię dokumentów, ponieważ lepiej odzwierciedlają one rzeczywiste obciążenie HedgeDoc niż żądania stron.

Pięć testów skuteczniejszych niż healthcheck kontenera

Zamień smoke test HedgeDoc w powtarzalną komendę uruchamianą przy wydaniu albo w krótki runbook. Wynik musi potwierdzać następujący scenariusz: utwórz notatkę, edytuj ją jednocześnie w dwóch przeglądarkach, prześlij obraz i uwierzytelnij się za pomocą wybranego dostawcy. Dołącz do wyniku wersję aplikacji, digest obrazu, hostname routingu i identyfikator danych testowych.

Uruchom ten sam test po standardowej wymianie kontenera oraz po odtworzeniu bazy danych, przesłanych plików i konfiguracji uwierzytelniania w innym miejscu. Odtwarzanie zakończyło się powodzeniem, gdy wracają notatki, rewizje, użytkownicy i przesłane pliki oraz gdy dwie przeglądarki mogą współpracować nad odtworzoną notatką. Porównaj czas i zużycie zasobów związane z połączeniami WebSocket, zapisami do bazy danych, przesłanymi multimediami i historią dokumentów; duża zmiana zasługuje na analizę, nawet jeśli końcowa operacja nadal się udaje.

Następnie przeprowadź bezpieczny test awarii: tymczasowo odbierz testowej tożsamości dostęp do Postgres oraz opcjonalnych dostawców OAuth i SMTP. Potwierdź, że HedgeDoc sygnalizuje problem i wraca do normalnego działania bez destrukcyjnych ręcznych zmian. Zachowaj tylko niezbędny, zanonimizowany fragment logu. Ten czteroczęściowy test obejmuje uruchamianie, trwałość danych, odtwarzanie i obsługę awarii.

Uruchom HedgeDoc bez ukrywania elementów infrastruktury

Minimalna komenda jest przydatna, gdy pokazuje, czym platforma będzie później zarządzać.

docker run -d \
  --name hedgedoc \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v hedgedoc-data:/hedgedoc/public/uploads \
  -e CMD_SESSION_SECRET=replace-with-a-long-random-value \
  -e CMD_DOMAIN=app.example.com \
  -e CMD_PROTOCOL_USESSL=true \
  -e CMD_DB_URL=postgres://hedgedoc:replace-password@postgres.internal:5432/hedgedoc \
  quay.io/hedgedoc/hedgedoc:latest

Port 3000 pozostaje tu prywatny dla hosta, a każda wymagana ścieżka jest jawnie określona. Dodaj sprawdzone ustawienia połączeń dla Postgres oraz opcjonalnych dostawców OAuth i SMTP; dla usług prywatnych używaj prywatnych nazw. Zweryfikuj uruchomienie zarówno za pomocą logów, jak i dowodu specyficznego dla aplikacji: utwórz notatkę, edytuj ją jednocześnie w dwóch przeglądarkach, prześlij obraz i uwierzytelnij się za pomocą wybranego dostawcy. Po pomyślnej weryfikacji przypnij wersję obrazu, aby standardowa wymiana kontenera nie zmieniła po cichu sposobu działania.

Nie dawaj HedgeDoc dostępu do całego hosta

W przypadku HedgeDoc cenna powierzchnia niekoniecznie ogranicza się do strony startowej. Najczęstszym błędem jest użycie przykładowego session secret albo niezamierzone zezwolenie na anonimowe tworzenie notatek. Przeciwdziałaj temu świadomie: użyj stabilnego session secret, zdecyduj, czy anonimowe tworzenie notatek jest akceptowalne, i ogranicz dostęp do prywatnych notatek.

Wygeneruj CMD_SESSION_SECRET jako długą losową wartość; jej rotacja zwykle unieważnia sesje lub tokeny, dlatego zaplanuj wpływ na użytkowników, zamiast traktować ją jako migrację szyfrowania. Używaj nieuprzywilejowanego użytkownika kontenera, jeśli obraz to obsługuje, i nie montuj niezwiązanych z usługą danych uwierzytelniających. Stosuj limity rate lub rozmiaru na ingressie, gdzie niezaufane operacje mogą zużywać połączenia WebSocket, zapisy do bazy danych, przesłane multimedia i historię dokumentów.

Testuj HedgeDoc spoza serwera

Wybierz docelowy hostname HedgeDoc, zanim użytkownicy zapiszą callbacki lub ustawienia klienta, a następnie skonfiguruj CMD_DOMAIN i CMD_PROTOCOL_USESSL dla publicznego URL-a. Routing platformy powinien kończyć TLS raz i kierować ruch na prywatny port 3000.

Uruchom transakcję akceptacyjną z zewnętrznego środowiska. Jeśli klient w ogóle nie dociera do HedgeDoc, skorzystaj z checklisty walidacji SSL, aby sprawdzić DNS i certyfikat. Jeśli żądanie dociera do HedgeDoc, ale edycja w czasie rzeczywistym nie działa, ponieważ WebSockets lub ustawienia domeny są nieprawidłowe, przestań zmieniać przekierowania proxy i sprawdź granicę specyficzną dla aplikacji.

Obsługuj HedgeDoc z uwzględnieniem rzeczywistego wąskiego gardła

Po każdym wdrożeniu używaj scenariusza „utwórz notatkę, edytuj ją jednocześnie w dwóch przeglądarkach, prześlij obraz i uwierzytelnij się za pomocą wybranego dostawcy” jako smoke testu HedgeDoc. Monitoruj połączenia WebSocket, zapisy do bazy danych, przesłane multimedia i historię dokumentów; ustaw alerty tam, gdzie te zasoby zbliżają się do poziomu pogarszającego działanie użytkownika.

Największe ryzyko zmian polega na tym, że migracje bazy danych HedgeDoc, ustawienia OAuth oraz zmiany pluginów lub renderera wymagają wdrożenia etapowego. Bezpieczne wydanie zaczyna się od snapshotu, który można odtworzyć, i obejmuje walidację każdej jednokierunkowej zmiany stanu przed przełączeniem ruchu. Gdy edycja w czasie rzeczywistym nie działa, ponieważ WebSockets lub ustawienia domeny są nieprawidłowe, zachowaj niesprawny kontener wystarczająco długo, aby odczytać jego konfigurację i pierwszy błąd.

Jak Dockup ogranicza nakład pracy przy HedgeDoc

Dockup może przejąć zarządzanie wymiennymi elementami platformy: kierować ruch na port 3000, wystawiać domenę i certyfikat, wstrzykiwać sekrety, dołączać trwały storage oraz łączyć HedgeDoc z usługami zarządzanymi lub prywatnie podłączonymi. Może robić to w infrastrukturze Dockup albo na podłączonym przez Ciebie serwerze.

Testy akceptacyjne HedgeDoc pozostają jawnie po Twojej stronie. Po wdrożeniu jednym kliknięciem skonfiguruj CMD_DOMAIN i CMD_PROTOCOL_USESSL dla publicznego URL-a, połącz i przetestuj Postgres oraz opcjonalnych dostawców OAuth i SMTP, a następnie uruchom ten scenariusz: utwórz notatkę, edytuj ją jednocześnie w dwóch przeglądarkach, prześlij obraz i uwierzytelnij się za pomocą wybranego dostawcy. Ten podział jest zamierzony: Dockup usuwa powtarzalną konfigurację infrastruktury, nie udając, że role aplikacji, dane dostępowe dostawców czy zasady odtwarzania wybierają się same.

Najczęściej zadawane pytania

Czego HedgeDoc potrzebuje do wdrożenia produkcyjnego?

Kieruj kontener HedgeDoc na porcie 3000 przez jeden origin HTTPS. Wymagania sieciowe obejmują Postgres oraz opcjonalnych dostawców OAuth i SMTP. Nie uznawaj HedgeDoc za gotowy, dopóki nie możesz utworzyć notatki, edytować jej jednocześnie w dwóch przeglądarkach, przesłać obrazu i uwierzytelnić się za pomocą wybranego dostawcy.

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

Zachowaj /hedgedoc/public/uploads i uwzględnij bazę danych, przesłane pliki oraz konfigurację uwierzytelniania w tym samym manifeście odtwarzania. Czyste odtworzenie HedgeDoc można uznać za udane dopiero wtedy, gdy wracają notatki, rewizje, użytkownicy i przesłane pliki oraz gdy dwie przeglądarki mogą współpracować nad odtworzoną notatką.

Czy HedgeDoc wymaga HTTPS za reverse proxy?

Używaj HTTPS dla publicznego originu HedgeDoc, a port 3000 pozostaw na wewnętrznym routingu. Poprawnie zastosuj ustawienie HedgeDoc: skonfiguruj CMD_DOMAIN i CMD_PROTOCOL_USESSL dla publicznego URL-a. W przypadku HedgeDoc HTTPS chroni dane uwierzytelniające i treści użytkowników podczas przesyłania oraz zapewnia spójne działanie klienta zależne od originu.

Jak testować aktualizację HedgeDoc?

Odtwórz aktualny stan HedgeDoc w odizolowanym wdrożeniu, zastosuj wersję kandydującą i powtórz transakcję akceptacyjną. Zwróć szczególną uwagę na to, że migracje bazy danych HedgeDoc, ustawienia OAuth oraz zmiany pluginów lub renderera wymagają wdrożenia etapowego. Zachowaj poprzedni obraz HedgeDoc, dopóki nie poznasz granic migracji danych i rollbacku.