Как разместить Wiki.js на собственном сервере в 2026 году: настройка базы данных, TLS и тесты восстановления

Большинство инструкций по установке Wiki.js заканчиваются на первом открытии страницы. Это слишком рано: DB_HOST внутри контейнера указывает на localhost или отсутствуют заголовки TLS-прокси. Полноценный production-тест требует большего — завершить настройку, создать страницу и внести в неё изменения, загрузить медиафайл, найти его через поиск и проверить историю версий после перезапуска.

Роль Wiki.js понятна: это Markdown-вики с версионированием и современным редактором. Но её эксплуатационная граница охватывает не только web-процесс, поэтому до появления реальных данных нужно явно определить зависимости, сохраняемое состояние и публичный маршрут.

Определите границу среды выполнения Wiki.js

Минимальная ответственная топология Wiki.js включает один приватный listener на порту 3000, маршрут ingress и документированную границу состояния. Сетевой контракт Wiki.js — это доступная база данных Postgres, MySQL, MariaDB, MSSQL или SQLite. Держите приватные endpoints во внутреннем DNS, разрешите только необходимые исходящие подключения и выдайте Wiki.js service credential с ограниченными правами.

Проверьте топологию, попросив чистый клиент завершить настройку, создать страницу и внести в неё изменения, загрузить медиафайл, найти его через поиск и проверить историю версий после перезапуска. Во время проверки отслеживайте время ответа базы данных, индексацию поиска, хранилище медиафайлов и latency провайдера аутентификации. Результат покажет, относится ли следующее улучшение к памяти, хранилищу, сети или отдельному worker, вместо того чтобы побуждать вас произвольно увеличивать размер контейнера.

Спроектируйте восстановление Wiki.js до запуска

В стандартном образе Wiki.js не предполагается наличие изменяемого состояния приложения. Сохраняйте базу данных, локальные загрузки и custom assets, а также зафиксированный digest и проверенную конфигурацию маршрута, вместо того чтобы создавать резервную копию пустой файловой системы контейнера.

Разверните Wiki.js с нуля на другом хосте и убедитесь, что восстановились страницы, история, пользователи, группы, медиафайлы и навигация, а известная страница по-прежнему находится через поиск. Если добавляется отдельная база данных, room server или слой аутентификации, назначьте для этого компонента отдельного ответственного за восстановление. В руководстве по переносу Git в production показано, как воспроизводимый артефакт заменяет резервную копию контейнера.

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

Выберите границу доверия Wiki.js

Безопасное развертывание Wiki.js начинается с сокращения полномочий. Не оставляйте экран настройки доступным после создания первого администратора: закройте публичный доступ к настройке, ограничьте административные возможности и используйте для базы данных вики отдельные учётные данные.

Обращайтесь с DB_PASS с учётом его роли в Wiki.js: храните чувствительные значения вне Git, документируйте последствия ротации и никогда не подставляйте публичный пример в production. Ограничьте административные маршруты, используйте приватный DNS для зависимостей и проверьте каждый bind mount. При централизованной отправке логов отфильтруйте секреты и приватное содержимое до их передачи за пределы сервера.

Что должно пройти до появления реальных данных Wiki.js

Production-gate для Wiki.js должен быть выполним человеком, который не создавал это развертывание. Передайте ему зафиксированную версию, не содержащую чувствительных данных тестовую учётную запись и следующую задачу: завершить настройку, создать страницу и внести в неё изменения, загрузить медиафайл, найти его через поиск и проверить историю версий после перезапуска. Если инструкции требуют не задокументированного shell-доступа, сервис ещё не готов к эксплуатации.

Повторите проверку, заменив только контейнер. Затем восстановите базу данных, локальные загрузки и custom assets в пустой инфраструктуре и докажите, что восстановились страницы, история, пользователи, группы, медиафайлы и навигация, а известная страница по-прежнему находится через поиск. Измеряйте время ответа базы данных, индексацию поиска, хранилище медиафайлов и latency провайдера аутентификации во время обоих успешных запусков; неожиданные различия часто указывают на отсутствующий cache, index, worker или mount данных.

Добавьте проверку отказоустойчивости: временно запретите тестовой identity доступ к доступной базе данных Postgres, MySQL, MariaDB, MSSQL или SQLite. Wiki.js должен выдавать понятную ошибку, сохранять существующее состояние и восстанавливаться после возврата корректного условия. Сохраните временные метки и относящиеся к делу строки логов, предварительно удалив секреты. Эти данные станут эталоном для следующего изменения образа или конфигурации.

Запускайте Wiki.js, не скрывая важные детали

Сделайте первоначальный запуск Wiki.js достаточно воспроизводимым, чтобы его можно было проверить в pull request.

docker run -d \
  --name wiki-js \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e DB_PASS=replace-with-a-long-random-value \
  -e DB_TYPE=postgres \
  -e DB_HOST=postgres.internal \
  -e DB_PORT=5432 \
  -e DB_USER=wiki \
  -e DB_NAME=wiki \
  ghcr.io/requarks/wiki:2

Не полагайтесь на latest после появления реальных данных. Зафиксируйте рабочий digest, пользователя контейнера и владельца mount. Проследите за логом приложения во время полного теста — завершите настройку, создайте страницу и внесите в неё изменения, загрузите медиафайл, найдите его через поиск и проверьте историю версий после перезапуска — и отметьте все migrations, прежде чем направлять на маршрут production-трафик.

Разделяйте внутренние и внешние URL

Считайте внешний URL Wiki.js конфигурацией, которая должна сохраняться при redeploy. Сначала настройте URL сайта после перевода сервиса за HTTPS; затем направьте hostname на порт 3000, сохранив исходные host и scheme.

Чеклист доступности развертывания поможет доказать, что запросы попадают в контейнер. После этого известную проблему — DB_HOST внутри контейнера указывает на localhost или отсутствуют заголовки TLS-прокси — следует искать в Wiki.js, его состоянии или workload, а не в автоматизации сертификатов.

Отслеживайте workload, а не только контейнер

Стройте dashboards на основе времени ответа базы данных, индексации поиска, хранилища медиафайлов и latency провайдера аутентификации. График CPU без контекста workload не объяснит, почему Wiki.js работает медленно. Добавьте synthetic или запланированную проверку, которая с использованием безвредных тестовых данных пытается завершить настройку, создать страницу и внести в неё изменения, загрузить медиафайл, найти его через поиск и проверить историю версий после перезапуска.

Перед обновлением учтите следующую специфическую для приложения опасность: migrations базы данных Wiki.js и модули аутентификации следует протестировать заранее, до перехода на другую ветку release. Восстановите свежую резервную копию в изолированном развертывании, выполните migrations и сравните поведение. Если DB_HOST внутри контейнера указывает на localhost или отсутствуют заголовки TLS-прокси, сначала проверьте соответствующую границу — публичный origin, хранилище или dependency, — и только потом изменяйте несвязанные настройки.

Пусть Wiki.js остаётся явным, а Dockup занимается маршрутизацией

Маршрутизация, сертификаты, замена сервисов и подключаемое хранилище — разумные цели для автоматизации. Dockup занимается этим для Wiki.js, а также может развернуть связанную managed database или подключиться к сервисам на собственном сервере клиента.

Но политика доверия Wiki.js не должна выдумываться автоматически. После развертывания настройте URL сайта после перевода сервиса за HTTPS, обеспечьте соблюдение этой границы — закройте публичный доступ к настройке, ограничьте административные возможности и используйте для базы данных вики отдельные учётные данные — и проверьте следующий сценарий: завершить настройку, создать страницу и внести в неё изменения, загрузить медиафайл, найти его через поиск и проверить историю версий после перезапуска. В результате вы получаете инфраструктуру в один клик с приёмочным тестом, специфичным для приложения.

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

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

Направьте контейнер Wiki.js на порту 3000 через один HTTPS-origin. Поддерживающее сетевое требование — доступная база данных Postgres, MySQL, MariaDB, MSSQL или SQLite. Не считайте Wiki.js готовой, пока не сможете завершить настройку, создать страницу и внести в неё изменения, загрузить медиафайл, найти его через поиск и проверить историю версий после перезапуска.

Какие данные Wiki.js должны входить в резервную копию?

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

Нужен ли Wiki.js HTTPS за reverse proxy?

Используйте HTTPS для публичного origin Wiki.js, а порт 3000 оставьте во внутреннем маршруте. Корректно примените настройку Wiki.js: настройте URL сайта после перевода сервиса за HTTPS. Для Wiki.js HTTPS защищает передаваемые учётные данные и пользовательское содержимое, а также обеспечивает согласованное поведение клиентов, зависящее от origin.

Как тестировать обновление Wiki.js?

Восстановите текущее состояние Wiki.js в изолированном развертывании, примените candidate-версию и повторите приёмочный сценарий. Уделите этому особое внимание, поскольку migrations базы данных Wiki.js и модули аутентификации следует протестировать заранее, до перехода на другую ветку release. Сохраняйте предыдущий образ Wiki.js, пока не будут понятны границы миграции данных и rollback.