Ako si v roku 2026 hostovať HedgeDoc: WebSockets, OAuth a nahrané súbory

„Spúšťanie HedgeDoc“ môže znamenať dve veci: kontajner existuje alebo služba skutočne plní svoju úlohu. Dôležitá je iba druhá možnosť. Dôkazom je vytvorenie poznámky, jej súbežná úprava v dvoch prehliadačoch, nahranie obrázka a autentifikácia cez vybraného poskytovateľa.

HedgeDoc slúži na tento účel: spolupráca na Markdown poznámkach v reálnom čase. Nasadenie musí zachovať súčasti, ktoré toto správanie umožňujú; port, volume a certifikát sú vstupy, nie výsledok.

Zálohujte stav, ktorý HedgeDoc nedokáže znovu vytvoriť

Definujte pre HedgeDoc bod obnovy a čas obnovy s ohľadom na databázu, nahrané súbory a konfiguráciu autentifikácie. Pred bootstrapom pripojte /hedgedoc/public/uploads, zapíšte neškodné testovacie údaje a nahraďte kontajner, aby ste overili, že táto cesta je skutočne persistentná. Named volume vyrieši zachovanie dát pri opätovnom nasadení, nevyrieši však kompromitáciu ani stratu servera.

Pripravte čisté prostredie na obnovu, použite rovnakú pripnutú verziu aplikácie a overte, že sa vrátia poznámky, revízie, používatelia aj nahrané súbory a že dva prehliadače dokážu spolupracovať na obnovenej poznámke. Zaznamenajte príkazy, opravy vlastníctva a uplynutý čas. Užitočným štandardom je príručka k zálohovaniu: zálohe možno dôverovať až po obnove, nie po nahraní.

Oddeľte HedgeDoc od jeho závislostí

Zdravie procesu a zdravie produktu sú v prípade HedgeDoc dve odlišné veci. Port 3000 môže odpovedať, hoci transakcia z pohľadu používateľa stále zlyháva. Sieťová zmluva pre HedgeDoc zahŕňa Postgres a voliteľných poskytovateľov OAuth a SMTP. Súkromné endpointy ponechajte v internom DNS, povoľte iba potrebné odchádzajúce volania a poskytnite HedgeDoc oprávnenia služby s obmedzeným rozsahom.

Toto overenie pripravenosti použite po významných zmenách konfigurácie: vytvorte poznámku, upravte ju súbežne v dvoch prehliadačoch, nahrajte obrázok a autentifikujte sa cez vybraného poskytovateľa. Náročné externé kontroly nepoužívajte v liveness probes, aby výpadok poskytovateľa nespôsobil slučku reštartov. Pri plánovaní kapacity sledujte WebSocket connections, database writes, uploaded media a document history — tieto metriky lepšie odrážajú skutočné zaťaženie HedgeDoc než požiadavky na stránky.

Päť kontrol silnejších než health kontajnera

Premeňte smoke test HedgeDoc na opakovateľný release príkaz alebo krátky runbook. Jeho výstup musí preukázať tento výsledok: vytvorte poznámku, upravte ju súbežne v dvoch prehliadačoch, nahrajte obrázok a autentifikujte sa cez vybraného poskytovateľa. Spolu s výsledkom zaznamenajte verziu aplikácie, digest kontajnera, hostname route a identifikátor testovacích údajov.

Rovnakú kontrolu spustite po bežnej výmene kontajnera aj po obnove databázy, nahraných súborov a konfigurácie autentifikácie na inom mieste. Obnova je úspešná vtedy, keď sa vrátia poznámky, revízie, používatelia aj nahrané súbory a dva prehliadače dokážu spolupracovať na obnovenej poznámke. Porovnajte časovanie a spotrebu súvisiacu s WebSocket connections, database writes, uploaded media a document history; výrazná zmena si zaslúži preskúmanie, aj keď posledná akcia stále prejde.

Potom otestujte bezpečné zlyhanie: dočasne odoberte testovacej identite prístup k Postgres a voliteľným poskytovateľom OAuth a SMTP. Overte, že HedgeDoc chybu zobrazí a bez deštruktívnych manuálnych zásahov sa vráti do normálneho stavu. Uchovajte iba nevyhnutný, redigovaný výpis z logu. Táto štvorčasťová kontrola pokrýva spustenie, persistence, obnovu a spracovanie zlyhaní.

Spustite HedgeDoc bez skrývania dôležitých súčastí

Minimálny príkaz je užitočný vtedy, keď odhalí, čo bude platforma neskôr spravovať.

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 tu zostáva privátny pre hostiteľa a každá požadovaná cesta je uvedená explicitne. Pridajte skontrolované nastavenia pripojenia pre Postgres a voliteľných poskytovateľov OAuth a SMTP; pre privátne služby používajte privátne názvy. Spustenie overte pomocou logov aj dôkazu špecifického pre aplikáciu: vytvorte poznámku, upravte ju súbežne v dvoch prehliadačoch, nahrajte obrázok a autentifikujte sa cez vybraného poskytovateľa. Po overení pripnite verziu image, aby bežná výmena potichu nezmenila správanie.

Nedávajte HedgeDoc prístup k celému hostiteľovi

V prípade HedgeDoc nemusí byť najcennejšou súčasťou verejne dostupná úvodná stránka. Najčastejšou chybou je použitie ukážkového session secretu alebo neúmyselné povolenie anonymného vytvárania poznámok. Zabráňte tomu zámerne: používajte stabilný session secret, rozhodnite, či je anonymné vytváranie poznámok prijateľné, a obmedzte prístup k privátnym poznámkam.

Vygenerujte CMD_SESSION_SECRET ako dlhú náhodnú hodnotu; jej rotácia zvyčajne zneplatní sessions alebo tokeny, preto plánujte vplyv na používateľov a neoznačujte ju za migráciu šifrovania. Ak to image podporuje, použite neprivilegovaného používateľa kontajnera a nepripájajte nesúvisiace prihlasovacie údaje. Na ingress aplikujte limity rýchlosti alebo veľkosti tam, kde nedôveryhodná práca môže spotrebovať WebSocket connections, database writes, uploaded media a document history.

Testujte HedgeDoc mimo servera

Konečný hostname HedgeDoc zvoľte ešte predtým, ako používatelia uložia callbacky alebo nastavenia klienta, a potom nastavte CMD_DOMAIN a CMD_PROTOCOL_USESSL pre verejnú URL. Platformová route by mala ukončiť TLS raz a smerovať na privátny port 3000.

Acceptance transakciu spustite externe. Ak sa klient k HedgeDoc vôbec nedostane, použite kontrolný zoznam na overenie SSL pre kontroly DNS a certifikátu. Ak požiadavka dosiahne HedgeDoc, ale úpravy v reálnom čase zlyhávajú, pretože WebSockets alebo nastavenia domény nie sú správne, prestaňte meniť proxy redirects a skontrolujte hranicu špecifickú pre aplikáciu.

Prevádzkujte HedgeDoc s ohľadom na jeho skutočné úzke hrdlo

Po každom nasadení použite vytvorenie poznámky, jej súbežnú úpravu v dvoch prehliadačoch, nahranie obrázka a autentifikáciu cez vybraného poskytovateľa ako smoke test HedgeDoc. Podporné metriky tvoria WebSocket connections, database writes, uploaded media a document history; upozornenia nastavte tam, kde sa tieto zdroje približujú k bodu, ktorý zhoršuje používateľskú akciu.

Hlavným rizikom zmien je, že database migrations, nastavenia OAuth a zmeny pluginov alebo rendererov v HedgeDoc vyžadujú postupné nasadenie. Bezpečné vydanie začína obnoviteľnou snapshotou a overením každej jednosmernej zmeny stavu ešte pred presmerovaním prevádzky. Keď úpravy v reálnom čase zlyhávajú, pretože WebSockets alebo nastavenia domény nie sú správne, ponechajte zlyhávajúci kontajner dostatočne dlho na prečítanie jeho konfigurácie a prvej chyby.

Kde Dockup odstraňuje prácu s HedgeDoc

Dockup môže spravovať vymeniteľné časti platformy: smerovať traffic na port 3000, vystaviť doménu a certifikát, injectovať secrets, pripojiť persistent storage a prepojiť HedgeDoc so spravovanými alebo privátne pripojenými službami. Môže to robiť na infraštruktúre Dockup alebo na serveri, ktorý pripojíte.

Acceptance pre HedgeDoc zostáva explicitná. Po one-click nasadení nastavte CMD_DOMAIN a CMD_PROTOCOL_USESSL pre verejnú URL, pripojte a otestujte Postgres a voliteľných poskytovateľov OAuth a SMTP a spustite tento scenár: vytvorte poznámku, upravte ju súbežne v dvoch prehliadačoch, nahrajte obrázok a autentifikujte sa cez vybraného poskytovateľa. Toto rozdelenie je zámerné: Dockup odstraňuje opakované nastavovanie infraštruktúry bez predstierania, že roly aplikácie, prihlasovacie údaje poskytovateľov alebo pravidlá obnovy sa zvolia samy.

Často kladené otázky

Čo HedgeDoc potrebuje na produkčné nasadenie?

Nasmerujte kontajner HedgeDoc na porte 3000 cez jeden HTTPS origin. Sieťovú podporu tvoria Postgres a voliteľní poskytovatelia OAuth a SMTP. HedgeDoc nepovažujte za pripravený, kým nedokážete vytvoriť poznámku, upraviť ju súbežne v dvoch prehliadačoch, nahrať obrázok a autentifikovať sa cez vybraného poskytovateľa.

Ktoré údaje HedgeDoc patria do zálohy?

Zachovajte /hedgedoc/public/uploads a databázu, nahrané súbory aj konfiguráciu autentifikácie zahrňte do rovnakého recovery manifestu. Čistá obnova HedgeDoc je úspešná iba vtedy, keď sa vrátia poznámky, revízie, používatelia aj nahrané súbory a dva prehliadače dokážu spolupracovať na obnovenej poznámke.

Vyžaduje HedgeDoc HTTPS za reverse proxy?

Pre verejný origin HedgeDoc používajte HTTPS a port 3000 ponechajte na internej route. Nastavenie HedgeDoc aplikujte správne: pre verejnú URL nastavte CMD_DOMAIN a CMD_PROTOCOL_USESSL. HTTPS v HedgeDoc chráni prihlasovacie údaje alebo obsah používateľov pri prenose a zachováva konzistentné správanie klienta citlivé na origin.

Ako testovať upgrade HedgeDoc?

Obnovte aktuálny stav HedgeDoc do izolovaného nasadenia, aplikujte kandidátsku verziu a zopakujte acceptance transakciu. Venujte tomu mimoriadnu pozornosť, pretože database migrations, nastavenia OAuth a zmeny pluginov alebo rendererov v HedgeDoc vyžadujú postupné nasadenie. Predchádzajúci image HedgeDoc ponechajte, kým nebudete rozumieť hranici migrácie dát a rollbacku.