Как да хоствате HedgeDoc самостоятелно през 2026 г.: WebSockets, OAuth и качени файлове

Има две версии на „стартиране на HedgeDoc“: съществува контейнер или услугата изпълнява реалната си задача. Важна е само втората. Тук доказателството е да създадете бележка, да я редактирате едновременно от два браузъра, да качите изображение и да се удостоверите чрез избрания provider.

HedgeDoc е предназначен именно за това: Markdown бележки за съвместна работа в реално време. Deployment-ът трябва да съхрани компонентите зад това поведение; портът, volume-ът и сертификатът са входни данни, а не крайният резултат.

Създайте backup на състоянието, което HedgeDoc не може да възстанови самостоятелно

Определете recovery point и recovery time за HedgeDoc по отношение на database, качените файлове и authentication конфигурацията. Монтирайте /hedgedoc/public/uploads преди bootstrap, запишете безвредни примерни данни и заменете контейнера, за да докажете, че този path действително е persistent. Named volume решава persistence при redeploy; не решава проблеми при компрометиране или загуба на сървъра.

Изградете чиста restore среда, използвайте същата фиксирана версия на приложението и докажете, че бележките, ревизиите, потребителите и качените файлове се възстановяват и че два браузъра могат да работят съвместно по възстановената бележка. Запишете командите, корекциите на ownership-а и изминалото време. Ръководството за backup е полезен стандарт: на backup се има доверие след restoration, а не след upload.

Разделете HedgeDoc от зависимостите му

Здравето на процеса и здравето на продукта са различни неща при HedgeDoc. Порт 3000 може да отговаря, докато транзакцията от гледна точка на потребителя все още се проваля. Мрежовият договор за HedgeDoc включва Postgres плюс незадължителни OAuth и SMTP providers. Дръжте private endpoints във вътрешен DNS, разрешете само необходимите outbound заявки и дайте на HedgeDoc service credential с ограничен обхват.

Използвайте това readiness упражнение след съществени промени в конфигурацията: създайте бележка, редактирайте я едновременно от два браузъра, качете изображение и се удостоверете чрез избрания provider. Не включвайте скъпи външни проверки в liveness probes, за да не предизвиква прекъсване на provider-а restart loop. При capacity work следете WebSocket connections, database writes, качените медийни файлове и историята на документите — това е по-близо до реалното натоварване на HedgeDoc, отколкото заявките към страниците.

Пет проверки, по-надеждни от health проверката на контейнера

Превърнете smoke теста на HedgeDoc в повторяема release команда или кратък runbook. Резултатът му трябва да демонстрира следното: създайте бележка, редактирайте я едновременно от два браузъра, качете изображение и се удостоверете чрез избрания provider. Съхранявайте с резултата версията на приложението, container digest-а, hostname-а на route-а и идентификатора на тестовите данни.

Изпълнете същата проверка след стандартна подмяна на контейнера и след възстановяване на database, качените файлове и authentication конфигурацията на друго място. Restore-ът е успешен, когато бележките, ревизиите, потребителите и качените файлове се възстановят и два браузъра могат да работят съвместно по възстановената бележка. Сравнете времето и потреблението, свързани с WebSocket connections, database writes, качените медийни файлове и историята на документите; значителна промяна заслужава проучване, дори когато последното действие все още преминава успешно.

След това изпълнете безопасен failure тест: временно забранете на тестовата identity достъпа до Postgres плюс незадължителните OAuth и SMTP providers. Потвърдете, че HedgeDoc показва грешката и се връща към нормална работа без разрушителни ръчни промени. Запазете само необходимия, редактиран откъс от log-а. Този gate от четири части обхваща startup, persistence, recovery и обработката на failures.

Стартирайте HedgeDoc, без да скривате компонентите

Минималната команда е полезна, когато показва какво ще управлява платформата по-късно.

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

Тук порт 3000 остава private за host-а и всеки необходим path е зададен изрично. Добавете прегледаните connection settings за Postgres плюс незадължителните OAuth и SMTP providers; използвайте private имена за private services. Проверете startup-а както чрез logs, така и чрез специфичното за приложението доказателство: създайте бележка, редактирайте я едновременно от два браузъра, качете изображение и се удостоверете чрез избрания provider. След като потвърдите работата, фиксирайте версията на image-а, за да не промени рутинната подмяна поведението незабелязано.

Не давайте на HedgeDoc целия host

При HedgeDoc ценната attack surface не е непременно landing page-ът. Основната грешка е да използвате примерен session secret или неволно да разрешите създаването на анонимни бележки. Противодействайте целенасочено: използвайте стабилен session secret, решете дали създаването на анонимни бележки е приемливо и ограничете достъпа до private notes.

Генерирайте CMD_SESSION_SECRET като дълга random стойност; обикновено rotating-ът му инвалидира sessions или tokens, затова планирайте влиянието върху потребителите, вместо да го наричате encryption migration. Използвайте непривилегирован container user, когато image-ът го поддържа, и не монтирайте несвързани credentials. Прилагайте rate или size limits на ingress нивото, където непроверената работа може да изразходва WebSocket connections, database writes, качени медийни файлове и история на документите.

Тествайте HedgeDoc извън сървъра

Изберете крайния hostname на HedgeDoc, преди потребителите да запазят callbacks или client settings, след което задайте CMD_DOMAIN и CMD_PROTOCOL_USESSL за public URL. Platform route-ът трябва да прекратява TLS веднъж и да насочва към private port 3000.

Изпълнете acceptance транзакцията отвън. Ако client-ът изобщо не достига HedgeDoc, използвайте checklist-а за SSL validation за проверки на DNS и сертификата. Ако заявката достига HedgeDoc, но редактирането в реално време не работи, защото WebSockets или domain settings са грешни, спрете да променяте proxy redirects и проверете специфичната за приложението boundary вместо това.

Експлоатирайте HedgeDoc според реалното му bottleneck-о

Използвайте създаването на бележка, едновременното ѝ редактиране от два браузъра, качването на изображение и удостоверяването чрез избрания provider като smoke тест на HedgeDoc след всяко deployment. Поддържащите metrics са WebSocket connections, database writes, качените медийни файлове и историята на документите; настройте alert там, където тези ресурси се доближават до ниво, което влошава потребителското действие.

Основният риск при промени е, че database migrations на HedgeDoc, OAuth settings и промените по plugins или renderers изискват staged release. Безопасният release започва от snapshot, който може да бъде възстановен, и валидира всяка еднопосочна промяна на състоянието, преди да насочи traffic-а. Когато редактирането в реално време не работи, защото WebSockets или domain settings са грешни, запазете неуспешния контейнер достатъчно дълго, за да прочетете конфигурацията му и първата грешка.

Как Dockup премахва част от работата при HedgeDoc

Dockup може да поеме заменяемите platform компоненти: да насочи traffic-а към port 3000, да издаде domain и certificate, да инжектира secrets, да прикачи persistent storage и да свърже HedgeDoc с managed или private attached services. Това може да се направи върху инфраструктурата на Dockup или върху сървър, който прикачите.

Acceptance работата за HedgeDoc остава изрично ваша. След one-click deployment задайте CMD_DOMAIN и CMD_PROTOCOL_USESSL за public URL, свържете и тествайте Postgres плюс незадължителните OAuth и SMTP providers и изпълнете този сценарий: създайте бележка, редактирайте я едновременно от два браузъра, качете изображение и се удостоверете чрез избрания provider. Това разделение е умишлено: Dockup премахва повтарящата се infrastructure настройка, без да се преструва, че application roles, provider credentials или restore policy се избират сами.

Често задавани въпроси

Какво е необходимо на HedgeDoc за production deployment?

Насочете контейнера на HedgeDoc през port 3000 към един HTTPS origin. Поддържащото мрежово изискване е Postgres плюс незадължителните OAuth и SMTP providers. Не обявявайте HedgeDoc за готов, докато не можете да създадете бележка, да я редактирате едновременно от два браузъра, да качите изображение и да се удостоверите чрез избрания provider.

Кои данни на HedgeDoc трябва да бъдат включени в backup?

Запазвайте /hedgedoc/public/uploads и включвайте database, качените файлове и authentication конфигурацията в един и същ recovery manifest. Чистият restore на HedgeDoc е успешен само когато бележките, ревизиите, потребителите и качените файлове се възстановят и два браузъра могат да работят съвместно по възстановената бележка.

Необходим ли е HTTPS за HedgeDoc зад reverse proxy?

Използвайте HTTPS за public origin-а на HedgeDoc и оставете port 3000 във вътрешния route. Приложете правилно настройката на HedgeDoc: задайте CMD_DOMAIN и CMD_PROTOCOL_USESSL за public URL. При HedgeDoc HTTPS защитава credentials или потребителското съдържание при пренос и поддържа consistent поведение на client-а, чувствително към origin-а.

Как трябва да се тества upgrade на HedgeDoc?

Възстановете текущото състояние на HedgeDoc в изолирано deployment, приложете candidate версията и повторете acceptance транзакцията. Обърнете специално внимание, защото database migrations на HedgeDoc, OAuth settings и промените по plugins или renderers изискват staged release. Запазете предишния HedgeDoc image, докато не изясните границите на data migration и rollback.