Как установить и настроить Wiki.js на VPS

MAATRIX

Корпоративная база знаний рано или поздно упирается в выбор: тяжёлый и капризный в настройке MediaWiki, устаревший визуально DokuWiki или подписочный SaaS вроде Notion и Confluence, где данные лежат не у вас. Wiki.js закрывает это пространство — современная self-hosted вики на Node.js с приятным редактором, версионированием через Git и гибкой авторизацией. Разберём установку на VPS через Docker Compose: от подготовки сервера до подключения Git-хранилища и внешних источников входа.

Что такое Wiki.js и когда она нужна

Wiki.js — это веб-приложение на Node.js, которое хранит структуру и метаданные страниц в базе данных (PostgreSQL, MySQL, MariaDB, SQLite или MSSQL), а содержимое страниц можно параллельно синхронизировать в Git-репозиторий. Редактор поддерживает Markdown, визуальный WYSIWYG-режим и ещё несколько форматов разметки на выбор — можно завести отдельные редакторы под разные разделы вики. Есть встроенный поиск (базовый на самой БД, либо подключаемый Elasticsearch/Algolia для больших баз), система прав на уровне страниц и разделов, комментарии, история версий с диффами.

По сравнению с MediaWiki (движком Википедии) Wiki.js заметно легче в развёртывании и современнее выглядит из коробки, но проигрывает в зрелости экосистемы расширений — если нужна прямо википедийная функциональность с сотнями плагинов, MediaWiki всё ещё вне конкуренции. По сравнению с DokuWiki, который вообще не требует базы данных, Wiki.js тяжелее по требованиям к ресурсам, зато даёт полноценную ролевую модель и человеческий интерфейс администратора. Если нужна база знаний команды на 5–500 человек с современным UI, нормальным поиском и без ежемесячной платы за место в облаке — Wiki.js на своём VPS закрывает эту задачу целиком.

Подготовка VPS

Wiki.js на Node.js сам по себе нетребователен, но вместе с PostgreSQL и под нагрузкой от нескольких активных редакторов комфортнее работает с запасом. Для команды до 20–30 человек хватает 1–2 vCPU и 2 ГБ RAM; если планируете включать полнотекстовый поиск через Elasticsearch или обслуживать сотни одновременных читателей — закладывайте 4 ГБ и больше. Диск много не нужен, если вики текстовая, но при активной загрузке изображений и вложений берите SSD с запасом.

Разворачивать будем через Docker, поэтому сначала ставим его:

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
apt install -y docker-compose-plugin

Создайте рабочий каталог проекта — в нём будут лежать compose-файл и данные контейнеров:

mkdir -p /opt/wikijs/data/db
cd /opt/wikijs

Локацию сервера выбирайте по тому, откуда чаще всего заходят в вики: для команды в России логичнее RU-сервер с минимальным пингом, а для распределённой команды или доступа из-за рубежа подойдёт US или UK. В MAATRIX доступны все три локации, оплата картой российского банка, СБП или криптовалютой — иностранная карта не понадобится.

Установка через Docker Compose

Официальный образ Wiki.js — requarks/wiki, база — PostgreSQL 11 и новее. Оба сервиса удобно поднять одним compose-файлом. Создайте docker-compose.yml:

services:
  db:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wikijs
      POSTGRES_PASSWORD: ЗамениНаСвойПароль
    volumes:
      - ./data/db:/var/lib/postgresql/data

  wiki:
    image: requarks/wiki:2
    depends_on:
      - db
    restart: unless-stopped
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: ЗамениНаСвойПароль
      DB_NAME: wiki
    ports:
      - "127.0.0.1:3000:3000"

Пароль в двух местах должен совпадать — это не переменная окружения одного контейнера, а общий секрет для базы и приложения. Порт намеренно привязан к 127.0.0.1: наружу Wiki.js будет отдавать реверс-прокси с HTTPS, а не сам контейнер напрямую. Если у вас уже есть отдельный управляемый инстанс PostgreSQL (например, вынесенный по инструкции как установить и настроить PostgreSQL на VPS), можно убрать сервис db из compose-файла и указать в DB_HOST адрес внешней базы — так проще централизованно бэкапить и тюнить СУБД для нескольких сервисов сразу.

Поднимите стек и проверьте логи:

docker compose up -d
docker compose logs -f wiki

Дождитесь строки о готовности сервера (обычно занимает от нескольких секунд до минуты — Wiki.js применяет миграции схемы при первом запуске). Каталог ./data/db — единственное, что нужно регулярно бэкапить наравне с самой базой; если предпочитаете снимать резервные копии на уровне Docker-томов, а не через pg_dump, пригодится инструкция как установить и настроить бэкап Docker volume на VPS.

Первый запуск и администратор

Пока домен не подключён, откройте http://IP-сервера:3000 — если файрвол закрывает порт снаружи, удобнее пробросить его через SSH-туннель: ssh -L 3000:127.0.0.1:3000 user@server и открыть http://127.0.0.1:3000 локально.

Мастер первичной настройки попросит: название сайта, email и пароль администратора, а также спросит про отправку анонимной телеметрии — при желании отключается. После создания учётки вы попадаете в админ-панель. Первым делом стоит зайти в раздел Admin → General и проверить название сайта, язык интерфейса по умолчанию и часовой пояс — эти мелочи потом сложнее менять массово, когда в базе уже есть контент от нескольких авторов.

Домен и HTTPS через реверс-прокси

Отдавать Wiki.js напрямую по HTTP из контейнера — плохая идея: нет шифрования, а совместная работа над страницами использует WebSocket (Socket.io) для живых обновлений, который тоже нужно правильно прокинуть. Настройте Nginx перед контейнером — общий подход для VPS разобран в статье как установить и настроить Nginx как реверс-прокси на VPS, для Wiki.js конфиг такой:

server {
    listen 80;
    server_name wiki.example.com;

    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;
    }
}

Строки Upgrade/Connection "upgrade" обязательны — без них живое обновление курсоров соавторов и уведомлений в интерфейсе просто отвалится, хотя сама вика будет открываться нормально, и найти причину не сразу очевидно. Домен wiki.example.com заранее направьте A-записью на IP сервера, затем выпустите сертификат — подробный разбор есть в статье как установить и настроить Let's Encrypt SSL на VPS:

certbot --nginx -d wiki.example.com

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

Git-репозиторий: версионирование страниц

Сильная сторона Wiki.js — необязательная, но мощная синхронизация контента с Git. Помимо истории версий внутри самой БД, можно настроить зеркалирование каждой страницы в реальный репозиторий: полноценные коммиты, дифы, возможность смотреть историю через GitHub или GitLab и держать копию контента, не зависящую от состояния базы данных.

Настраивается в Admin → Storage, раздел Git. Нужен SSH-ключ для доступа к репозиторию — проще всего сгенерировать его внутри контейнера, чтобы он сохранился в примонтированном томе:

docker compose exec wiki ssh-keygen -t ed25519 -f /wiki/data/ssh/wikijs -N ""
docker compose exec wiki cat /wiki/data/ssh/wikijs.pub

Публичный ключ добавьте в репозиторий как deploy key с правом записи (в GitHub — Settings → Deploy keys, в GitLab — Settings → Repository → Deploy keys). В настройках Git-хранилища в самой Wiki.js укажите SSH-адрес репозитория, ветку, путь до приватного ключа внутри контейнера и режим синхронизации: по каждому сохранению страницы или по расписанию.

Здесь стоит честно оговорить нюанс: в Git синхронизируется контент страниц (Markdown/разметка и метаданные), а вложенные бинарные файлы — картинки, документы — по умолчанию хранятся отдельно и не всегда попадают в тот же репозиторий в зависимости от настроенного хранилища ассетов. Если вам критична полная переносимость вместе с картинками, проверьте это в своей версии и при необходимости настройте отдельное S3-совместимое или локальное хранилище для загрузок с собственным бэкапом.

Источники авторизации: Local, LDAP, OAuth/OIDC

Вторая сильная сторона — множество источников авторизации, которые можно включать одновременно, а не выбирать один. Настройка — в Admin → Login, там список стратегий: локальные учётки с email и паролем, LDAP/Active Directory, Google, GitHub, Microsoft Azure AD, а также универсальный OAuth2/OpenID Connect для любого совместимого провайдера (Keycloak, Authentik, свой корпоративный SSO).

Для LDAP понадобятся стандартные параметры: адрес сервера, Bind DN и пароль служебной учётки для поиска, search base, фильтр поиска пользователей и соответствие атрибутов (email, отображаемое имя). Для generic OAuth2/OIDC — Client ID и секрет, URL авторизации, токена и userinfo, набор scope.

Практический совет: пока настраиваете внешний провайдер, не отключайте локальную стратегию — если конфигурация LDAP или OIDC окажется неверной, вы рискуете остаться без доступа в собственную вику до правки записей прямо в базе данных. Отключайте Local только после того, как убедитесь, что вход через SSO работает у тестового пользователя. Дополнительно в Admin → Security можно включить обязательную двухфакторную аутентификацию (TOTP) для локальных и части внешних учёток — не лишняя мера для базы знаний с чувствительными внутренними документами.

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