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

Повечето бележки за инсталиране на Wiki.js приключват при първото зареждане на страницата. Това е твърде рано: DB_HOST е localhost вътре в контейнера или липсват proxy headers за TLS. Полезният production тест е по-взискателен — завършете настройката, създайте и редактирайте страница, качете медия, потърсете я и прегледайте историята на версиите след рестарт.

Ролята на Wiki.js е ясна: Markdown wiki с versioning и модерен редактор. Оперативната му граница включва повече от web процеса, затова зависимостта, съхраняваното състояние и публичният route трябва да бъдат описани изрично, преди да постъпят реални данни.

Очертайте runtime границата на Wiki.js

Най-малката отговорна топология за Wiki.js съдържа един частен listener на 3000, ingress route и документирана граница на състоянието. Мрежовият договор за Wiki.js е достъпна Postgres, MySQL, MariaDB, MSSQL или SQLite база данни. Поддържайте частните endpoint-и във вътрешен DNS, разрешете само необходимите изходящи заявки и предоставете на Wiki.js service credential с ограничен обхват.

Валидирайте топологията, като накарате чист клиент да завърши настройката, да създаде и редактира страница, да качи медия, да я потърси и да прегледа историята на версиите след рестарт. Наблюдавайте времето за отговор на базата данни, search indexing, media storage и latency на authentication provider-а по време на теста. Резултатът ще покаже дали следващото подобрение трябва да бъде в memory, storage, networking или отделен worker, вместо да насърчава произволно оразмеряване на контейнера.

Проектирайте възстановяването на Wiki.js преди старта

В стандартния image на Wiki.js не се очаква writable application state. Запазете базата данни, всички локални uploads и custom assets, както и pinned digest-а и прегледаната route конфигурация, вместо да архивирате празната filesystem на контейнера.

Създайте Wiki.js от нулата на друг host и проверете дали страниците, историята, потребителите, групите, медиите и навигацията се възстановяват, както и дали известна страница остава searchable. Ако добавите отделна база данни, room server или authentication layer, определете за този компонент собствен отговорник за възстановяването. Ръководството от Git до production показва как възпроизводим artifact заменя backup на контейнер.

Запишете командата за rebuild и теста с очакван резултат заедно с release-а. Stateless планът за възстановяване е успешен, когато възпроизвежда поведението от надеждни входни данни; той не трябва да зависи от копирането на непрозрачен работещ контейнер.

Изберете trust boundary за Wiki.js

Сигурното deployment-ване на Wiki.js започва с премахване на излишните права. Не оставяйте екрана за setup публично достъпен, след като първият администратор е създаден; вместо това премахнете публичния достъп до setup, ограничете администрацията и предоставете на wiki базата данни собствени credentials.

Третирайте DB_PASS според ролята му в Wiki.js: пазете чувствителните стойности извън Git, документирайте ефектите от rotation и никога не заменяйте публичен пример в production. Ограничете administrative routes, използвайте private DNS за зависимостите и прегледайте всеки bind mount. Когато logs се изпращат централно, филтрирайте secrets и private content, преди да напуснат сървъра.

Какво трябва да премине, преди да постъпят реални данни в Wiki.js

Production gate за Wiki.js трябва да може да бъде изпълнен от човек, който не е изградил deployment-а. Дайте на този човек pinned версията, non-sensitive test account и следната задача: да завърши настройката, да създаде и редактира страница, да качи медия, да я потърси и да прегледа историята на версиите след рестарт. Ако инструкциите изискват недокументиран shell достъп, услугата все още не е готова за production от оперативна гледна точка.

Повторете gate-а, като замените само контейнера. След това възстановете базата данни, всички локални uploads и custom assets в празна инфраструктура и докажете, че страниците, историята, потребителите, групите, медиите и навигацията се възстановяват, както и че известна страница остава searchable. Измервайте времето за отговор на базата данни, search indexing, media storage и latency на authentication provider-а по време на двата успешни теста; неочакваните разлики често разкриват липсващ cache, index, worker или data mount.

Добавете failure drill: временно откажете на test identity достъп до достъпна Postgres, MySQL, MariaDB, MSSQL или SQLite база данни. Wiki.js трябва да изведе полезна грешка, да запази съществуващото състояние и да се възстанови, когато валидното условие се върне. Запазете timestamp-ите и съответните log редове със заличени secrets. Тези доказателства ще станат референция за следващата промяна на 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, потребителя на контейнера и ownership-а на mount-овете. Следете application log-а през целия тест — завършете настройката, създайте и редактирайте страница, качете медия, потърсете я и прегледайте историята на версиите след рестарт — и отбележете всички migrations, преди да поставите route-а зад production traffic.

Поддържайте ясна граница между вътрешните и външните URL адреси

Третирайте външния URL адрес на Wiki.js като конфигурация, която трябва да се запази при redeploy. Първо конфигурирайте site URL, след като прекарате услугата през HTTPS; след това насочете hostname-а към порт 3000, като запазите оригиналните host и scheme.

Checklist-ът за reachability на deployment-а може да докаже, че заявките влизат в контейнера. След това известният проблем — DB_HOST е localhost вътре в контейнера или липсват proxy headers за TLS — трябва да се разследва в Wiki.js, неговото състояние или workload-а, а не в certificate automation.

Наблюдавайте workload-а, а не само контейнера

Изградете dashboards около времето за отговор на базата данни, search indexing, media storage и latency на authentication provider-а. CPU графика без този workload контекст не може да обясни защо Wiki.js е бавен. Добавете synthetic или scheduled check, който използва безвредни test data и се опитва да завърши настройката, да създаде и редактира страница, да качи медия, да я потърси и да прегледа историята на версиите след рестарт.

Преди upgrade отчетете следния специфичен за приложението риск: database migrations и authentication modules на Wiki.js трябва да бъдат staged, преди да преминете към друга release line. Възстановете скорошен backup в изолиран deployment, изпълнете migrations там и сравнете поведението. Ако DB_HOST е localhost вътре в контейнера или липсват proxy headers за TLS, проверете съответната граница — public origin, storage или dependency — преди да променяте несвързани настройки.

Поддържайте Wiki.js изричен, докато Dockup управлява routing-а

Routing, certificates, service replacement и attached storage са подходящи цели за automation. Dockup се грижи за тях за Wiki.js и може да provision-не съответната managed database или да се свърже с услуги на собствения сървър на клиента.

Това, което не трябва да измисля, е trust policy-то на Wiki.js. След deployment конфигурирайте site URL, след като прекарате услугата през HTTPS, наложете тази граница — премахнете публичния достъп до setup, ограничете администрацията и предоставете на wiki базата данни собствени credentials — и проверете резултата от следния сценарий: завършете настройката, създайте и редактирайте страница, качете медия, потърсете я и прегледайте историята на версиите след рестарт. Резултатът е инфраструктура с deployment с едно кликване и application-specific acceptance test.

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

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

Насочете контейнера на Wiki.js на порт 3000 през един HTTPS origin. Поддържащото мрежово изискване е достъпна Postgres, MySQL, MariaDB, MSSQL или SQLite база данни. Не приемайте Wiki.js за готов, докато не можете да завършите настройката, да създадете и редактирате страница, да качите медия, да я потърсите и да прегледате историята на версиите след рестарт.

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

Стандартният image на Wiki.js няма задължителен mount за application data. Запазете deployment конфигурацията му и архивирайте всяко свързано state отделно; възстановяването е успешно, когато страниците, историята, потребителите, групите, медиите и навигацията се върнат и известна страница остане searchable.

Изисква ли Wiki.js HTTPS зад reverse proxy?

Използвайте HTTPS за публичния Wiki.js origin и оставете порт 3000 във вътрешния route. Приложете правилно настройката на Wiki.js: конфигурирайте site URL, след като прекарате услугата през HTTPS. При Wiki.js HTTPS защитава credentials или user content при пренос и поддържа последователно поведението на клиента, чувствително към origin-а.

Как трябва да се тества upgrade на Wiki.js?

Възстановете текущото състояние на Wiki.js в изолиран deployment, приложете candidate версията и повторете acceptance transaction-а. Обърнете специално внимание, защото database migrations и authentication modules на Wiki.js трябва да бъдат staged, преди да преминете към друга release line. Запазете предишния Wiki.js image, докато границата на data migration и rollback не бъде изяснена.