Как разместить HedgeDoc самостоятельно в 2026 году: WebSockets, OAuth и загруженные файлы

Есть два варианта «запустить HedgeDoc»: контейнер существует или сервис действительно выполняет свою задачу. Важен только второй вариант. Проверка здесь заключается в том, чтобы создать заметку, одновременно отредактировать ее в двух браузерах, загрузить изображение и пройти аутентификацию через выбранного провайдера.

HedgeDoc предназначен именно для этого: совместных Markdown-заметок в реальном времени. При развертывании нужно сохранить все компоненты, обеспечивающие такое поведение; порт, volume и сертификат — это исходные данные, а не результат.

Создайте резервную копию состояния, которое HedgeDoc не может восстановить самостоятельно

Определите точку и время восстановления HedgeDoc с учетом базы данных, загруженных файлов и конфигурации аутентификации. Подключите /hedgedoc/public/uploads до bootstrap, запишите безвредные тестовые данные и замените контейнер, чтобы убедиться, что этот путь действительно сохраняется. Именованный volume обеспечивает сохранность данных при повторном развертывании, но не защищает от компрометации или потери сервера.

Подготовьте чистое окружение для восстановления, используйте ту же зафиксированную версию приложения и убедитесь, что заметки, ревизии, пользователи и загруженные файлы восстановились, а два браузера могут совместно редактировать восстановленную заметку. Зафиксируйте команды, исправления владельцев и затраченное время. Руководство по резервному копированию предлагает полезный стандарт: резервной копии можно доверять после восстановления, а не после загрузки.

Отделяйте HedgeDoc от его зависимостей

Для HedgeDoc работоспособность процесса и работоспособность продукта — разные вещи. Порт 3000 может отвечать, пока пользовательская операция по-прежнему завершается ошибкой. Сетевой контракт HedgeDoc включает Postgres, а также опциональных провайдеров OAuth и SMTP. Держите приватные endpoints во внутреннем DNS, разрешайте только необходимые исходящие вызовы и выдавайте HedgeDoc учетные данные сервисной учетной записи с ограниченными правами.

Используйте эту проверку готовности после существенных изменений конфигурации: создайте заметку, одновременно отредактируйте ее в двух браузерах, загрузите изображение и пройдите аутентификацию через выбранного провайдера. Не включайте дорогостоящие внешние проверки в liveness probes, чтобы сбой провайдера не приводил к циклическому перезапуску. При планировании ресурсов отслеживайте WebSocket-соединения, записи в базе данных, загруженные медиафайлы и историю документов — это точнее отражает реальную нагрузку HedgeDoc, чем запросы страниц.

Пять проверок надежнее, чем healthcheck контейнера

Превратите smoke test HedgeDoc в повторяемую release-команду или короткий runbook. Результат должен подтверждать следующее: заметка создается, одновременно редактируется в двух браузерах, изображение загружается, аутентификация через выбранного провайдера проходит успешно. Вместе с результатом сохраняйте версию приложения, digest контейнера, hostname маршрута и идентификатор тестовых данных.

Запускайте ту же проверку после обычной замены контейнера и после восстановления базы данных, загруженных файлов и конфигурации аутентификации в другом окружении. Восстановление считается успешным, когда заметки, ревизии, пользователи и загруженные файлы возвращаются, а два браузера могут совместно редактировать восстановленную заметку. Сравнивайте время выполнения и потребление ресурсов, связанных с WebSocket-соединениями, записями в базе данных, загруженными медиафайлами и историей документов; существенное изменение требует расследования, даже если итоговая операция по-прежнему завершается успешно.

Затем проверьте безопасный сценарий сбоя: временно запретите тестовой учетной записи доступ к Postgres, а также опциональным провайдерам OAuth и SMTP. Убедитесь, что HedgeDoc отображает ошибку и возвращается в нормальное состояние без разрушительных ручных изменений. Сохраните только необходимый фрагмент лога с удаленными чувствительными данными. Этот четырехэтапный gate охватывает запуск, сохранение данных, восстановление и обработку сбоев.

Запускайте 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 остается доступным только с хоста, а все необходимые пути указаны явно. Добавьте проверенные параметры подключения к Postgres, а также к опциональным провайдерам OAuth и SMTP; для приватных сервисов используйте приватные имена. Проверьте запуск по логам и с помощью проверки, специфичной для приложения: создайте заметку, одновременно отредактируйте ее в двух браузерах, загрузите изображение и пройдите аутентификацию через выбранного провайдера. После проверки зафиксируйте версию образа, чтобы обычная замена не привела к незаметному изменению поведения.

Не предоставляйте HedgeDoc доступ ко всему хосту

Для HedgeDoc ценной поверхностью атаки не обязательно является главная страница. Основная ошибка — использовать пример session secret или непреднамеренно разрешить анонимное создание заметок. Противодействуйте этому целенаправленно: используйте стабильный session secret, решите, допустимо ли анонимное создание заметок, и ограничьте доступ к приватным заметкам.

Сгенерируйте CMD_SESSION_SECRET как длинное случайное значение; его ротация обычно делает сессии или токены недействительными, поэтому заранее спланируйте влияние на пользователей, а не называйте это миграцией шифрования. Используйте непривилегированного пользователя контейнера, если образ это поддерживает, и не подключайте посторонние учетные данные. Применяйте ограничения скорости или размера на ingress, где недоверенные операции могут потреблять WebSocket-соединения, записи в базе данных, загруженные медиафайлы и историю документов.

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

Выберите итоговый hostname HedgeDoc до того, как пользователи сохранят callback URL или настройки клиента, затем задайте CMD_DOMAIN и CMD_PROTOCOL_USESSL для публичного URL. Маршрут платформы должен завершать TLS один раз и направлять трафик на приватный порт 3000.

Запустите acceptance transaction извне. Если клиент вообще не достигает HedgeDoc, используйте чеклист проверки SSL для диагностики DNS и сертификата. Если запрос доходит до HedgeDoc, но изменения в реальном времени не работают из-за неправильных WebSockets или настроек домена, прекратите менять redirects прокси и проверьте границу, специфичную для приложения.

Эксплуатируйте HedgeDoc с учетом его реального узкого места

Используйте создание заметки, ее одновременное редактирование в двух браузерах, загрузку изображения и аутентификацию через выбранного провайдера как smoke test HedgeDoc после каждого развертывания. Отслеживайте связанные с ним показатели: WebSocket-соединения, записи в базе данных, загруженные медиафайлы и историю документов; устанавливайте alert там, где использование этих ресурсов приближается к уровню, ухудшающему пользовательскую операцию.

Основной риск изменений связан с тем, что миграции базы данных HedgeDoc, настройки OAuth, а также изменения plugin или renderer требуют поэтапного release. Безопасный release начинается с восстанавливаемого snapshot и проверки любых однонаправленных изменений состояния до переключения трафика. Если изменения в реальном времени не работают из-за неправильных WebSockets или настроек домена, не удаляйте неисправный контейнер, пока не изучите его конфигурацию и первую ошибку.

Как Dockup упрощает работу с HedgeDoc

Dockup может взять на себя заменяемые компоненты платформы: направить трафик на порт 3000, выпустить домен и сертификат, передать секреты, подключить постоянное хранилище и соединить HedgeDoc с управляемыми или подключенными приватными сервисами. Это можно сделать на инфраструктуре Dockup или на подключенном вами сервере.

Приемочные проверки HedgeDoc по-прежнему должны выполняться явно. После развертывания в один клик задайте CMD_DOMAIN и CMD_PROTOCOL_USESSL для публичного URL, подключите и протестируйте Postgres, а также опциональных провайдеров OAuth и SMTP, затем выполните этот сценарий: создайте заметку, одновременно отредактируйте ее в двух браузерах, загрузите изображение и пройдите аутентификацию через выбранного провайдера. Такое разделение намеренно: Dockup убирает повторяющуюся настройку инфраструктуры, не делая вид, что роли приложения, учетные данные провайдеров или политика восстановления выбираются сами собой.

Часто задаваемые вопросы

Что нужно HedgeDoc для production-развертывания?

Направьте контейнер HedgeDoc через порт 3000 на один HTTPS origin. Сетевые зависимости включают Postgres, а также опциональных провайдеров OAuth и SMTP. Не считайте HedgeDoc готовым, пока не сможете создать заметку, одновременно отредактировать ее в двух браузерах, загрузить изображение и пройти аутентификацию через выбранного провайдера.

Какие данные HedgeDoc нужно включать в резервную копию?

Сохраняйте /hedgedoc/public/uploads и включайте базу данных, загруженные файлы и конфигурацию аутентификации в один manifest восстановления. Чистое восстановление HedgeDoc считается успешным только тогда, когда заметки, ревизии, пользователи и загруженные файлы возвращаются, а два браузера могут совместно редактировать восстановленную заметку.

Требуется ли HedgeDoc HTTPS за reverse proxy?

Используйте HTTPS для публичного origin HedgeDoc, а порт 3000 оставьте во внутреннем маршруте. Правильно примените настройку HedgeDoc: задайте CMD_DOMAIN и CMD_PROTOCOL_USESSL для публичного URL. Для HedgeDoc HTTPS защищает учетные данные и пользовательский контент при передаче и обеспечивает согласованное поведение клиента, зависящее от origin.

Как тестировать обновление HedgeDoc?

Восстановите текущее состояние HedgeDoc в изолированном развертывании, примените candidate-версию и повторите acceptance transaction. Уделите особое внимание тому, что миграции базы данных HedgeDoc, настройки OAuth, а также изменения plugin или renderer требуют поэтапного release. Сохраняйте предыдущий образ HedgeDoc, пока не будут понятны границы миграции данных и отката.