A HedgeDoc saját üzemeltetése 2026-ban: WebSockets, OAuth és feltöltött fájlok

A „HedgeDoc futtatásának” két szintje van: létezik egy konténer, vagy a szolgáltatás valóban ellátja a feladatát. Csak a második számít. Ennek bizonyítéka, hogy létre tudsz hozni egy jegyzetet, két böngészőből egyidejűleg szerkesztheted, feltölthetsz egy képet, és a kiválasztott szolgáltatón keresztül hitelesíthetsz.

A HedgeDoc erre szolgál: valós idejű, közösen szerkeszthető Markdown-jegyzetek készítésére. A telepítésnek meg kell őriznie az ehhez szükséges összetevőket; egy port, egy volume és egy tanúsítvány csak bemenet, nem pedig az eredmény.

Mentsd a HedgeDoc által újra létre nem hozható állapotot

Határozd meg a HedgeDoc helyreállítási pontját és helyreállítási idejét az adatbázis, a feltöltött fájlok és a hitelesítési konfiguráció alapján. A bootstrap előtt csatold a /hedgedoc/public/uploads útvonalat, írj bele ártalmatlan mintaadatokat, majd cseréld le a konténert annak bizonyítására, hogy az útvonal valóban perzisztens. A névvel ellátott volume megoldja a redeploy utáni perzisztenciát, de nem véd egy kompromittálódás vagy a szerver elvesztése ellen.

Hozz létre egy tiszta visszaállítási környezetet, használd ugyanazt a rögzített alkalmazásverziót, és bizonyítsd, hogy a jegyzetek, revíziók, felhasználók és feltöltések visszaállnak, valamint két böngésző együtt tud működni a helyreállított jegyzeten. Rögzítsd a parancsokat, a tulajdonjog javításához szükséges lépéseket és az eltelt időt. A biztonsági mentési útmutató hasznos mércét ad: egy mentés akkor megbízható, ha sikeresen visszaállítottad, nem pedig akkor, amikor feltöltötted.

Válaszd külön a HedgeDocot és a függőségeit

A folyamat állapota és a termék állapota külön fogalom a HedgeDoc esetében. Lehet, hogy a 3000-es port válaszol, miközben a felhasználói tranzakció még mindig sikertelen. A HedgeDoc hálózati szerződésének része a Postgres, valamint opcionálisan az OAuth- és SMTP-szolgáltatók. A privát végpontokat tartsd belső DNS-en, csak a szükséges kimenő kapcsolatokat engedélyezd, és adj a HedgeDocnak korlátozott hatókörű szolgáltatási hitelesítő adatot.

Használd ezt a készenléti ellenőrzést minden jelentős konfigurációmódosítás után: hozz létre egy jegyzetet, szerkeszd egyidejűleg két böngészőből, tölts fel egy képet, és hitelesíts a kiválasztott szolgáltatón keresztül. A költséges külső ellenőrzéseket hagyd ki a liveness probe-okból, hogy egy szolgáltatói kiesés ne indítson újraindítási hurkot. A kapacitástervezés során kövesd a WebSocket-kapcsolatok, az adatbázis-írások, a feltöltött média és a dokumentumelőzmények alakulását; ez közelebb áll a HedgeDoc tényleges terheléséhez, mint az oldalbetöltések száma.

Öt, a konténerállapotnál erősebb ellenőrzés

Alakítsd át a HedgeDoc smoke tesztjét ismételhető release-paranccsá vagy rövid runbookká. A kimenetének ezt az eredményt kell bizonyítania: hozz létre egy jegyzetet, szerkeszd egyidejűleg két böngészőből, tölts fel egy képet, és hitelesíts a kiválasztott szolgáltatón keresztül. Az eredménnyel együtt rögzítsd az alkalmazásverziót, a konténer digestjét, az útvonal hosztnevét és a tesztadat azonosítóját.

Ugyanezt az ellenőrzést futtasd le egy szokásos konténercsere után, valamint az adatbázis, a feltöltött fájlok és a hitelesítési konfiguráció máshol történő visszaállítása után is. A visszaállítás akkor sikeres, ha a jegyzetek, revíziók, felhasználók és feltöltések visszatérnek, és két böngésző együtt tud működni a helyreállított jegyzeten. Hasonlítsd össze a WebSocket-kapcsolatokhoz, az adatbázis-írásokhoz, a feltöltött médiához és a dokumentumelőzményekhez kapcsolódó időzítést és erőforrás-felhasználást; egy jelentős eltérés akkor is vizsgálatot érdemel, ha a végső művelet továbbra is sikeres.

Ezután hajts végre egy biztonságos hibatesztet: ideiglenesen vond meg a tesztidentitás hozzáférését a Postgreshez, valamint az opcionális OAuth- és SMTP-szolgáltatókhoz. Ellenőrizd, hogy a HedgeDoc jelzi a hibát, majd romboló manuális módosítások nélkül visszatér normál állapotba. Csak a szükséges, kitakart naplórészletet őrizd meg. Ez a négy részből álló kapu lefedi az indítást, a perzisztenciát, a helyreállítást és a hibakezelést.

Indítsd el a HedgeDocot anélkül, hogy elrejtenéd a fontos részleteket

Egy minimális parancs akkor hasznos, ha megmutatja, mit fog később kezelni a platform.

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

Ebben a felállásban a 3000-es port csak a hoston belül érhető el, és minden szükséges útvonal explicit módon meg van adva. Add hozzá a Postgreshez, valamint az opcionális OAuth- és SMTP-szolgáltatókhoz átnézett kapcsolati beállításokat; privát szolgáltatásokhoz használj privát neveket. Az indítást a naplókkal és az alkalmazásspecifikus bizonyítékkal is ellenőrizd: hozz létre egy jegyzetet, szerkeszd egyidejűleg két böngészőből, tölts fel egy képet, és hitelesíts a kiválasztott szolgáltatón keresztül. Az ellenőrzés után rögzítsd a képfájlt verzió szerint, hogy egy szokásos csere ne módosítsa észrevétlenül a működést.

Ne adj teljes hozzáférést a hosthoz a HedgeDocnak

A HedgeDoc esetében az értékes támadási felület nem feltétlenül a nyitóoldal. A leggyakoribb hiba egy példából átvett session secret használata, illetve az anonim jegyzetlétrehozás nem szándékos engedélyezése. Ezt tudatosan előzd meg: használj stabil session secretet, döntsd el, hogy elfogadható-e az anonim jegyzetlétrehozás, és korlátozd a privát jegyzetekhez való hozzáférést.

A CMD_SESSION_SECRET értékét hosszú, véletlenszerű értékként generáld; a cseréje rendszerint érvényteleníti a sessionöket vagy tokeneket, ezért tervezd meg a felhasználói hatást, és ne titkosítási migrációként kezeld. Használj nem privilegizált konténerfelhasználót, ha a lemezkép támogatja, és ne csatolj hozzá nem kapcsolódó hitelesítő adatokat. Az ingress rétegben alkalmazz sebesség- vagy méretkorlátokat, ahol a nem megbízható műveletek WebSocket-kapcsolatokat, adatbázis-írásokat, feltöltött médiát és dokumentumelőzményeket fogyaszthatnak.

Teszteld a HedgeDocot a szerveren kívülről

A felhasználók callbackeket vagy kliensbeállításokat mentése előtt válaszd ki a végleges HedgeDoc-hosztnevet, majd állítsd be a CMD_DOMAIN és a CMD_PROTOCOL_USESSL értékét a nyilvános URL-hez. A platform útvonalának egyszer kell TLS-t terminálnia, és a privát 3000-es portra kell továbbítania a forgalmat.

Futtasd le kívülről az elfogadási tranzakciót. Ha a kliens egyáltalán nem éri el a HedgeDocot, használd az SSL-ellenőrzési ellenőrzőlistát a DNS- és tanúsítvány-ellenőrzésekhez. Ha a kérés eléri a HedgeDocot, de a valós idejű szerkesztés nem működik, mert a WebSockets vagy a domainbeállítások hibásak, ne módosítsd tovább a proxy-átirányításokat, hanem vizsgáld meg az alkalmazásspecifikus határfelületet.

A HedgeDocot a valódi szűk keresztmetszetei köré szervezd

Minden telepítés után használd a HedgeDoc smoke tesztjeként a következőt: hozz létre egy jegyzetet, szerkeszd egyidejűleg két böngészőből, tölts fel egy képet, és hitelesíts a kiválasztott szolgáltatón keresztül. A kapcsolódó mérőszámok a WebSocket-kapcsolatok, az adatbázis-írások, a feltöltött média és a dokumentumelőzmények; ott állíts be riasztást, ahol ezek az erőforrások olyan szinthez közelítenek, amely már rontja a felhasználói műveletet.

A legnagyobb változtatási kockázatot az jelenti, hogy a HedgeDoc adatbázis-migrációi, OAuth-beállításai, valamint a plugin- vagy renderer-módosítások fokozatos kiadást igényelnek. A biztonságos release visszaállítható pillanatképből indul, és a forgalom átterelése előtt ellenőrzi az egyirányú állapotváltozásokat. Ha a valós idejű szerkesztés nem működik, mert a WebSockets vagy a domainbeállítások hibásak, hagyd meg a hibás konténert annyi ideig, hogy elolvashasd a konfigurációját és az első hibaüzenetet.

Ahol a Dockup munkát vesz át a HedgeDoctól

A Dockup kezelheti a cserélhető platformösszetevőket: a forgalmat a 3000-es portra irányítja, kiadja a domaint és a tanúsítványt, beinjektálja a titkokat, csatolja a perzisztens tárolót, valamint összekapcsolja a HedgeDocot menedzselt vagy privát módon csatolt szolgáltatásokkal. Ezt a Dockup infrastruktúráján vagy egy általad csatolt szerveren is megteheti.

A HedgeDoc elfogadási tesztjeit továbbra is explicit módon kell elvégezni. Az egykattintásos telepítés után állítsd be a CMD_DOMAIN és a CMD_PROTOCOL_USESSL értékét a nyilvános URL-hez, csatlakoztasd és teszteld a Postgrest, valamint az opcionális OAuth- és SMTP-szolgáltatókat, majd futtasd le ezt a forgatókönyvet: hozz létre egy jegyzetet, szerkeszd egyidejűleg két böngészőből, tölts fel egy képet, és hitelesíts a kiválasztott szolgáltatón keresztül. Ez a felosztás szándékos: a Dockup megszünteti az ismétlődő infrastruktúra-beállításokat anélkül, hogy úgy tenne, mintha az alkalmazásszerepkörök, a szolgáltatói hitelesítő adatok vagy a visszaállítási szabályzat maguktól meghatározódnának.

Gyakran ismételt kérdések

Mire van szüksége a HedgeDocnak éles telepítéshez?

Irányítsd a HedgeDoc konténerét a 3000-es porton keresztül egyetlen HTTPS-originre. A kapcsolódó hálózati követelmény a Postgres, valamint opcionálisan az OAuth- és SMTP-szolgáltatók elérése. Ne tekintsd késznek a HedgeDocot addig, amíg nem tudsz létrehozni egy jegyzetet, két böngészőből egyidejűleg szerkeszteni, feltölteni egy képet, és a kiválasztott szolgáltatón keresztül hitelesíteni.

Mely HedgeDoc-adatok tartoznak a biztonsági mentésbe?

Tedd perzisztenssé a /hedgedoc/public/uploads útvonalat, és ugyanabba a helyreállítási manifestbe vedd fel az adatbázist, a feltöltött fájlokat és a hitelesítési konfigurációt. A tiszta HedgeDoc-visszaállítás csak akkor sikeres, ha a jegyzetek, revíziók, felhasználók és feltöltések visszatérnek, és két böngésző együtt tud működni a helyreállított jegyzeten.

Szüksége van a HedgeDocnak HTTPS-re reverse proxy mögött?

A nyilvános HedgeDoc-originhez használj HTTPS-t, a 3000-es portot pedig tartsd a belső útvonalon. Helyesen alkalmazd a HedgeDoc beállítását: állítsd be a CMD_DOMAIN és a CMD_PROTOCOL_USESSL értékét a nyilvános URL-hez. A HedgeDoc esetében a HTTPS védi a hitelesítő adatokat és a felhasználói tartalmakat az átvitel során, valamint konzisztenssé teszi az originérzékeny kliensoldali működést.

Hogyan kell tesztelni egy HedgeDoc-frissítést?

Állítsd vissza az aktuális HedgeDoc-állapotot egy elkülönített telepítésbe, alkalmazd a jelölt verziót, majd ismételd meg az elfogadási tranzakciót. Különösen figyelj arra, hogy a HedgeDoc adatbázis-migrációi, OAuth-beállításai, valamint a plugin- vagy renderer-módosítások fokozatos kiadást igényelnek. Tartsd meg az előző HedgeDoc-lemezképet addig, amíg nem érted az adat-migráció és a rollback határát.