Wiki.js на сервере: частые ошибки и решения

MAATRIX

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

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

Самая частая ситуация — контейнер или процесс Node.js завершается через несколько секунд после старта, а в логах либо тишина, либо обрывочное сообщение об ошибке подключения.

Если Wiki.js развёрнут через Docker Compose, первым делом смотрите логи именно приложения, а не общий статус контейнера:

docker compose logs -f wiki

Чаще всего причина в том, что контейнер wiki стартовал раньше, чем PostgreSQL успел поднять сокет и принять соединения — Wiki.js в этом случае просто падает вместо того, чтобы подождать. Решается через depends_on с условием на здоровье сервиса базы, а не просто на его запуск:

services:
  db:
    image: postgres:15-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wikijs"]
      interval: 5s
      timeout: 5s
      retries: 5
  wiki:
    image: ghcr.io/requarks/wiki:2
    depends_on:
      db:
        condition: service_healthy

Второй частый источник падения при первом запуске — недостаточно памяти. Wiki.js на Node.js стартует нормально от 512 МБ, но под нагрузкой с поиском и рендерингом Markdown комфортнее закладывать от 1 ГБ. Проверить, не убивает ли процесс OOM-killer, можно так:

sudo dmesg | grep -i "out of memory"

Если так и есть — это повод пересмотреть план сервера, а не искать баг в конфигурации.

Ошибка подключения к PostgreSQL

Wiki.js официально поддерживает только PostgreSQL как основную СУБД (MySQL и SQLite тоже заявлены, но PostgreSQL — рекомендуемый и наиболее протестированный вариант), и типичная ошибка при установке — ECONNREFUSED или password authentication failed в config.yml либо в переменных окружения контейнера.

Проверьте блок подключения в config.yml:

db:
  type: postgres
  host: db
  port: 5432
  user: wikijs
  pass: ваш_пароль
  db: wiki

Ключевой нюанс контейнерных установок — host: db должен совпадать с именем сервиса базы данных в docker-compose.yml, а не быть localhost или 127.0.0.1. Внутри контейнера Wiki.js localhost — это сам контейнер, сеть контейнеров изолирована. Создание пользователя и базы с нужными правами разобрано в статье как установить и настроить PostgreSQL на VPS.

Если Wiki.js установлен не в Docker, а напрямую на сервер, убедитесь, что PostgreSQL слушает нужный интерфейс и разрешает подключения с паролем в pg_hba.conf:

# /etc/postgresql/15/main/pg_hba.conf
local   wiki    wikijs                  md5
host    wiki    wikijs   127.0.0.1/32   md5

После правки — обязательно перезагрузить конфигурацию:

sudo systemctl reload postgresql

Wiki.js не открывается за реверс-прокси: белый экран или ошибка WebSocket

Wiki.js активно использует WebSocket для живого редактора и уведомлений в реальном времени, и это самая частая причина проблем именно за Nginx: страница вроде бы загружается, но редактор не работает, а в консоли браузера — обрыв соединения WebSocket connection failed.

Стандартный конфиг proxy_pass без явной проброски заголовков апгрейда протокола WebSocket не сработает:

server {
    listen 443 ssl;
    server_name wiki.vash-domen.ru;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Именно три строки — proxy_http_version 1.1, Upgrade и Connection "upgrade" — обычно пропускают при первой настройке прокси, потому что для обычных HTTP-запросов сайт и без них работает. Общий подход к передаче заголовков разобран в статье Nginx как реверс-прокси на Ubuntu 24.04, а типовые грабли именно с прокси — в статье Nginx как реверс-прокси: частые ошибки и решения.

Отдельно проверьте в разделе Admin → General, что указан правильный Site URL со схемой https:// — иначе часть внутренних ссылок будет генерироваться с неверным протоколом, даже если прокси настроен верно.

Синхронизация с Git не работает или расходится с содержимым

Одна из ключевых фишек Wiki.js — хранение истории страниц в Git-репозитории через встроенный модуль синхронизации (Admin → Storage → Git). На практике эта синхронизация иногда либо не запускается, либо расходится: изменения в вики не попадают в репозиторий, либо наоборот.

Первое, что стоит проверить — сама Wiki.js должна иметь доступ к git внутри контейнера или системы, и SSH-ключ (или токен) для доступа к репозиторию должен быть смонтирован и читаем именно пользователем, от которого работает процесс:

services:
  wiki:
    volumes:
      - ./ssh-key:/wiki/.ssh/id_rsa:ro

Ключ с правами 644 или доступный для чтения всем зачастую отклоняется самим SSH-клиентом как небезопасный — нужно 600:

chmod 600 ./ssh-key

Второе — модуль Git работает по расписанию (интервал задаётся в настройках хранилища), а не мгновенно при каждом сохранении. Если изменения не появляются в репозитории сразу — это ожидаемое поведение; можно запустить синхронизацию вручную через Admin → Storage → Sync Now, если кнопка доступна в вашей версии, либо дождаться следующего интервала.

Третье, и самое неприятное на практике — конфликт, когда страница правится одновременно и через веб-интерфейс, и напрямую в Git (коммитом в обход UI). Wiki.js не умеет полноценно мержить такие конфликты — проще взять актуальную версию из Git как источник правды и принудительно перечитать репозиторий через админку, чем сводить историю руками.

Не работает вход через OAuth (Google, GitHub, Microsoft)

Wiki.js поддерживает множество источников авторизации — локальные учётные записи, LDAP, OAuth2/OIDC-провайдеры (Google, GitHub, Microsoft Azure AD и другие). Типичная ошибка после настройки — redirect_uri_mismatch при попытке входа через внешний провайдер.

Причина почти всегда в том, что callback-URL, зарегистрированный у провайдера (в консоли Google Cloud, GitHub OAuth Apps и так далее), не совпадает символ в символ с тем, что генерирует Wiki.js:

https://wiki.vash-domen.ru/login/{strategy-key}/callback

Где {strategy-key} — ключ, заданный в Admin → Login → выбранная стратегия, например google или github. Частые причины расхождения:

• забытый или лишний слеш в конце URL;
• http:// вместо https:// в консоли провайдера, если Wiki.js работает за прокси с SSL;
• домен без www зарегистрирован у провайдера, а Wiki.js доступна и по www.вашдомен.ru, и без — это два разных redirect URI с точки зрения OAuth.

Если вход не проходит вообще без явной ошибки редиректа (форма логина просто перезагружается) — проверьте, что Client ID и Client Secret скопированы без пробелов, и что в самой стратегии включён тумблер Enabled, который легко забыть после ввода данных.

Поиск не находит страницы или работает медленно

По умолчанию Wiki.js использует встроенный поиск через саму базу данных (для PostgreSQL — полнотекстовый поиск на движке БД), и для небольших вики этого достаточно. Но по мере роста количества страниц поиск может начать либо не находить очевидные совпадения, либо заметно тормозить.

Первое, что нужно проверить, если поиск вообще не находит недавно добавленные страницы, — индекс поиска обновляется не мгновенно при сохранении, а требует пересборки. В Admin → Utilities → Search Engine есть кнопка полной переиндексации — если вы массово импортировали страницы через Git-синхронизацию или API, индекс нужно пересобрать вручную после импорта:

Admin → Utilities → Rebuild Search Index

Второе — для больших баз знаний (счёт страниц на тысячи) встроенный поиск через БД становится узким местом. Wiki.js умеет подключать внешние поисковые движки — Elasticsearch, Algolia. Если объём контента растёт, а поиск ощутимо просаживается, стоит рассмотреть Elasticsearch как отдельный сервис — точный порог, при котором встроенный поиск начинает тормозить, зависит от объёма текста и структуры страниц, это лишь ориентир.

Третье — если поиск работает, но медленно, а PostgreSQL используется как поисковый движок, проверьте, что база не перегружена по ресурсам: медленный поиск часто оказывается симптомом нехватки RAM у PostgreSQL, а не проблемой самого поискового модуля.

Загруженные файлы и изображения не открываются

Wiki.js хранит вложения (assets) отдельно от текста страниц, и есть несколько типовых причин, по которым загруженная картинка либо не грузится, либо потом отдаёт 404.

Если Wiki.js развёрнута в Docker, самая частая причина — том с данными не смонтирован как постоянный volume, и после пересоздания контейнера (например, при обновлении образа) все загруженные файлы вместе с базой SQLite для кеша попросту исчезают:

services:
  wiki:
    image: ghcr.io/requarks/wiki:2
    volumes:
      - wiki-data:/wiki/data
volumes:
  wiki-data:

Без явного volume для /wiki/data содержимое живёт только в слое контейнера и теряется при пересоздании (docker compose up --force-recreate или обновлении образа).

Второе — если перед Wiki.js стоит Nginx, проверьте лимит на размер тела запроса, он блокирует загрузку раньше, чем запрос доходит до приложения:

client_max_body_size 50M;

Третье — если используется внешнее S3-совместимое хранилище (настраивается в Admin → Storage), а файлы загружаются, но не открываются публично, почти всегда дело в правах bucket'а или в неверном публичном базовом URL для раздачи.

Ошибки после обновления версии

При обновлении major-версии (например, с 2.x на будущую 3.x) миграция схемы БД иногда проходит не полностью автоматически, и сайт после обновления либо не стартует, либо часть функциональности пропадает.

Порядок безопасного обновления в Docker:

# бэкап перед любым обновлением — база и файлы
docker exec wiki-db-1 pg_dump -U wikijs wiki > wiki_backup_$(date +%F).sql
docker run --rm -v wiki-data:/data -v $(pwd):/backup alpine \
  tar -czf /backup/wiki_data_backup_$(date +%F).tar.gz -C /data .

# обновление образа
docker compose pull wiki
docker compose up -d wiki

После обновления проверьте логи контейнера — Wiki.js сама выполняет миграции схемы БД при старте новой версии, и если процесс прервать (например, перезапустив контейнер посреди него), схема может остаться в промежуточном состоянии:

docker compose logs -f wiki

Если после обновления интерфейс не открывается или выдаёт ошибку про несовместимую схему — откатитесь на предыдущий тег образа и восстановите бэкап базы, а не пытайтесь чинить миграцию руками поверх текущего состояния. Общие принципы безопасного docker-compose для продакшена разобраны в статье Docker Compose для продакшена на Ubuntu 24.04.

Частые вопросы