Як самостійно розгорнути Wiki.js у 2026 році: налаштування бази даних, TLS і тести відновлення

Більшість інструкцій зі встановлення Wiki.js закінчуються на першому завантаженні сторінки. Це зарано: DB_HOST усередині контейнера вказує на localhost або відсутні заголовки TLS proxy. Корисний production-тест має бути вимогливішим — завершити налаштування, створити й відредагувати сторінку, завантажити медіафайл, знайти його та перевірити історію версій після перезапуску.

Роль Wiki.js проста: Markdown-вікі з версіюванням і сучасним редактором. Її operational boundary охоплює більше, ніж лише вебпроцес, тому залежність, збережений стан і публічний маршрут потрібно чітко визначити до того, як з’являться реальні дані.

Визначте runtime boundary Wiki.js

Мінімальна відповідальна топологія Wiki.js містить один приватний listener на порту 3000, ingress-маршрут і задокументовану межу стану. Мережева вимога Wiki.js — доступна база даних Postgres, MySQL, MariaDB, MSSQL або SQLite. Залишайте приватні endpoint-и у внутрішньому DNS, дозволяйте лише необхідні вихідні з’єднання та надайте Wiki.js service credential з обмеженими правами.

Перевірте топологію, попросивши чистий клієнт завершити налаштування, створити й відредагувати сторінку, завантажити медіафайл, знайти його та перевірити історію версій після перезапуску. Під час виконання стежте за часом відповіді бази даних, індексацією пошуку, сховищем медіа та затримкою authentication provider. Результат покаже, чи потрібно наступне покращення в memory, storage, networking або окремому worker, замість того щоб довільно збільшувати ресурси контейнера.

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

У стандартному image Wiki.js не передбачається writable application state. Зберігайте базу даних, а також локальні uploads і custom assets, включно із зафіксованим digest та перевіреною конфігурацією маршруту, замість резервного копіювання порожньої файлової системи контейнера.

Створіть Wiki.js з нуля на іншому хості та перевірте, що сторінки, історія, користувачі, групи, медіа й навігація відновилися, а відома сторінка залишається доступною для пошуку. Якщо додається окрема база даних, room server або authentication layer, призначте цьому компоненту окремого відповідального за відновлення. У посібнику від Git до production показано, як відтворюваний artifact замінює резервну копію контейнера.

Зафіксуйте команду відновлення та тест із наперед відомим результатом разом із release. Stateless-план відновлення працює завдяки відтворенню поведінки з надійних вхідних даних; він не має залежати від копіювання непрозорого запущеного контейнера.

Визначте trust boundary Wiki.js

Безпечне розгортання Wiki.js починається з мінімізації повноважень. Не залишайте екран налаштування відкритим після створення першого адміністратора: натомість приберіть публічний доступ до setup, обмежте адміністративні функції та надайте wiki окремі облікові дані для бази даних.

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

Що має пройти до появи реальних даних Wiki.js

Production gate для Wiki.js має бути виконуваним людиною, яка не створювала це розгортання. Передайте їй зафіксовану версію, тестовий обліковий запис без чутливих даних і таке завдання: завершити налаштування, створити й відредагувати сторінку, завантажити медіафайл, знайти його та перевірити історію версій після перезапуску. Якщо інструкції вимагають undocumented shell access, сервіс ще не готовий до експлуатації.

Повторіть gate після заміни лише контейнера. Потім відновіть базу даних, а також локальні uploads і custom assets у порожню інфраструктуру та доведіть, що сторінки, історія, користувачі, групи, медіа й навігація відновилися, а відома сторінка залишається доступною для пошуку. Вимірюйте час відповіді бази даних, індексацію пошуку, сховище медіа та затримку authentication provider під час обох успішних запусків; несподівані відмінності часто виявляють відсутній cache, index, worker або data mount.

Додайте drill для відмови: тимчасово забороніть тестовій identity доступ до доступної бази даних Postgres, MySQL, MariaDB, MSSQL або SQLite. Wiki.js має видати зрозумілу помилку, зберегти наявний стан і відновити роботу після повернення коректної умови. Збережіть часові позначки та відповідні рядки логів, попередньо замаскувавши секрети. Ці докази стануть еталоном для наступної зміни image або конфігурації.

Запускайте 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 traffic.

Не плутайте внутрішні та зовнішні URL

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

Чекліст доступності deployment допоможе довести, що запити потрапляють у контейнер. Після цього відому проблему — DB_HOST усередині контейнера вказує на localhost або відсутні заголовки TLS proxy — слід досліджувати у Wiki.js, його state або workload, а не в автоматизації сертифікатів.

Відстежуйте workload, а не лише контейнер

Побудуйте dashboards навколо часу відповіді бази даних, індексації пошуку, сховища медіа та затримки authentication provider. Графік CPU без контексту цього workload не пояснить, чому Wiki.js працює повільно. Додайте synthetic або scheduled check, який із нешкідливими тестовими даними намагається завершити налаштування, створити й відредагувати сторінку, завантажити медіафайл, знайти його та перевірити історію версій після перезапуску.

Перед оновленням врахуйте специфічний для цього застосунку ризик: database migrations і authentication modules Wiki.js потрібно перевірити на staging до переходу на іншу release line. Відновіть свіжу резервну копію в ізольованому deployment, виконайте migrations там і порівняйте поведінку. Якщо DB_HOST усередині контейнера вказує на localhost або відсутні заголовки TLS proxy, спочатку перевірте відповідну boundary — public origin, storage або dependency — перш ніж змінювати сторонні налаштування.

Залишайте Wiki.js явним, а маршрутизацію доручіть Dockup

Маршрутизація, сертифікати, заміна сервісів і підключене сховище — цілком доречні цілі для automation. Dockup обробляє це для Wiki.js і може provision-ити пов’язану managed database або підключатися до сервісів на власному сервері клієнта.

Водночас Dockup не має вигадувати trust policy Wiki.js. Після deployment налаштуйте site URL після прокладання маршруту сервісу через HTTPS, забезпечте цю boundary — приберіть публічний доступ до setup, обмежте адміністративні функції та надайте wiki окремі облікові дані для бази даних — і перевірте результат такого сценарію: завершити налаштування, створити й відредагувати сторінку, завантажити медіафайл, знайти його та перевірити історію версій після перезапуску. Результат — інфраструктура в один клік із application-specific acceptance test.

Поширені запитання

Що потрібно Wiki.js для production deployment?

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

Які дані Wiki.js потрібно включати до резервної копії?

Стандартний image Wiki.js не має обов’язкового mount для application data. Збережіть конфігурацію deployment і створюйте резервні копії кожного підключеного state окремо; відновлення можна вважати успішним, коли сторінки, історія, користувачі, групи, медіа й навігація повернулися, а відома сторінка залишається доступною для пошуку.

Чи потрібен Wiki.js HTTPS за reverse proxy?

Використовуйте HTTPS для публічного origin Wiki.js, а порт 3000 залишайте у внутрішньому маршруті. Правильно застосуйте налаштування Wiki.js: налаштуйте site URL після прокладання маршруту сервісу через HTTPS. Для Wiki.js HTTPS захищає облікові дані або користувацький вміст під час передавання та забезпечує узгоджену поведінку клієнта, чутливу до origin.

Як тестувати оновлення Wiki.js?

Відновіть актуальний state Wiki.js в ізольованому deployment, застосуйте candidate version і повторіть acceptance transaction. Зверніть особливу увагу, оскільки database migrations і authentication modules Wiki.js потрібно перевірити на staging до переходу на іншу release line. Зберігайте попередній image Wiki.js, доки не буде зрозумілою межа міграції даних і rollback.