Настройка Wiki.js — начинаем знакомиться с возможностями этой Вики: что тут можно сделать, как лучше и связанные моменты.
В прошлой статье установили Wiki.js на Ubuntu, теперь дело за настройкой. Лучше открыть эту статью в отдельной вкладке браузера, чтобы было нагляднее и понятнее.
Казалось бы натыкал галок в интерфейсе и готово. Да? С одной стороны это так, но есть "приколы нашего городка". О них хотел рассказать.
Задачи
Что вообще от этой Вики нужно, говорилось в части про установку. Проверим эти возможности на практике. Так ли они хороши. Одно дело заявлено "на бумаге", другое в работе.
Исходим из того, что это закрытая Вики. Доступ к информации должен быть только у зарегистрированных пользователей. Далее будем проверять по порядку основное:
- Установка сертификата для веб;
- Настройка прав доступа;
- Настройка доменной аутентификации;
- Общая настройка;
- Проверка возможностей оформления;
- Обновление.
И дополнительно ещё два вопроса:
- Двухфакторка 2FA;
- Картинки в Assets.
Установка сертификата
Раз у нас Вики для корпоративного использования, значит есть Active Directory и доменный Certificate Authority. Последний и нужен для генерации сертификата.
Сертификат может быть прописан в конфиге Вики либо в виде двух файлов:
format: pem key: path/to/key.pem cert: path/to/cert.pem passphrase: null dhparam: null
Либо в виде одного:
format: pfx pfx: path/to/cert.pfx passphrase: null dhparam: null
Мне администратор AD выдал в формате PFX с парольной фразой и приколы начались. Закидываем сертификат в /opt/wiki с помощью WinSCP. Прописываем в конфиге путь к файлу, парольную фразу, рестартуем сервис:
# cd /opt/wiki # vim config.yml ssl: enabled: true port: 443 provider: custom format: pfx pfx: /opt/wiki/cert-wiki.pfx # Passphrase when using encrypted PEM / PFX keys (default: null): passphrase: pass dhparam: null # systemctl restart wiki
И.. ничего не работает.
В общем, если парольной фразы нет, то конфиге просто null, а если есть, то парольная фраза ожидается в апострофах 'pass'. 🙂 Может я плохо смотрел, но что-то про это нигде не написано. Проверка на запароленность:
# openssl rsa -check -in file.key
Наконец всё запустилось, идём в вебе Вики на закладку SSL и там:
Видим провайдера сертификата, порты, включаем редирект. Какие тут ещё моменты:
- Маппинг портов, который сделали в прошлой статье, работает и для 443 порта при старте сервиса от системного пользователя;
- Корневой сертификат CA в домене раскидывается на все доменные машины политикой по умолчанию. Ничего дополнительно делать не надо, на всех доменных компьютерах сертификат нашей Вики будет валидным.
Настройка прав доступа
Идём на закладку Groups, здесь две группы: Administrators, Guests. Нам никакие гости не нужны, Вики закрытая, поэтому для группы Guests удаляем все Permissions, все Page Rules переводим в Deny.
И тут второй прикол. Если на закладке General загрузить своё лого для Вики, то оно будет относиться к категории Assets. Поскольку мы запретили для гостей чтение Assets, то никто на странице логина это лого не увидит. Вместо лого чёрный квадрат. Почему? Пока пользователь не аутентифицирован, он относится к группе Guests.
Если же разрешить гостям доступ к чтению Assets, тогда дыра в безопасности. Зная имя картинки, пишешь URL Вики, это имя и всё открывается. Поэтому оставил лого по умолчанию.
Создаем свою группу, например IT. Даём права:
read:pages,write:pages,manage:pages;read:source;read:history;read:assets,write:assets;read:comments,write:comments.
И Page Rules:
Это очень условно. Можно сделать более гранулированные права с указанием путей.
В любом случае давать права на удаление контента не самая лучшая идея. Это задача владельца сервиса корпоративной Вики. И такой владелец должен быть. Тот кто станет присматривать и администрировать.
Не питайте иллюзий, сама по себе Вики развиваться не будет, сама не взлетит. Если же раздать всем все права, кроме хаоса ничего не получится. Задача пользователей Вики: работать с Вики, получать нужную информацию, писать контент и править его.
Разделяем права
Пришло время поделить Вики для двух групп пользователей. Это будут отдел Кибербезопасности и отдел Телекома. Деление не из соображений "запретить доступ", ведь каких-то конфиденциальных данных в Вики нет. А скорее из соображений удобства. Чтобы ненужные страницы не мозолили глаза.
Страницы для Кибербезопасности лежат по пути /kib. Они видны только этой группе и тут максимальные права на изменение. Страницы Телекома cоответственно /telecom. Общие страницы по пути /share. Здесь возможность правки немного ограничена для обоих групп. Чтобы не случился хаос.
И наконец пути из корня /. Последнее важно по двум причинам. Первая, если такой доступ не прописать, то на всех страницах не подпадающих под /kib, /telecom, /share, не будет картинок. В частности на главной странице. Второе, эти страницы (не подпадающие которые) доступны на редактирование только админам. Что удобно. Мне не надо чтобы кто-то правил главную страницу или страницу правил пользования Вики, которую я сам же и написал.
Для второй группы зеркально.
Настройка доменной аутентификации
Самый вкусный пункт, ради него эта статья и создана по большей части. На закладке Autentification добавляем стратегию LDAP / Active Directory. Смысл тут такой: при аутентификации пользователя в соответствии с этой стратегией, делается LDAP запрос к AD. Важно чтобы запрос был верным и ответ на этот запрос правильно интерпретировался. Для этого:
- LDAP URL, должен разрешаться в адрес домен контроллера/контроллеров;
- Admin Bind DN, Admin Bind Credentials, выдаёт ваш администратор AD. Это просто пользователь домена с неистекающим паролем, поэтому пароль должен быть сложным. Любой пользователь домена может делать LDAP запрос. Пусть домен
msk.my.company, тогда примерно что-то такое:
CN=svc-wiki,OU=Restricted,OU=IT,DC=msk,DC=my,DC=company - поле admin bind kmHQNj2Mk?QZ9gl|iXFb - поле кредитов
- Search Base, где в AD искать пользователей, примерно следующее:
DC=msk,DC=my,DC=company
- Search Filter, как искать, важный пункт, если не работает LDAP аутентификация, скорее всего из-за неправильной настройки этого пункта:
sAMAccountName={{username}}*
или
(|(sAMAccountName={{username}}*) (userPrincipalName={{username}}*))
- Unique ID Field Mapping, имя входа пользователя:
sAMAccountName
- Email Field Mapping, почта пользователя, должна быть заполнена в учётной записи AD, для того чтобы подтянулась в Вики:
userPrincipalName
Почитать подробнее что это за имена, расширить кругозор, можно здесь.
- Use TLS, пока отключаем и пробуем стандартный порт 389.
Когда всё заработает, можно попробовать включить и порт для LDAPS (LDAP over Secure Sockets Layer) поменять на 636. У меня заработало только на 389 (и ещё на 3268) порту с включённым TLS. Не уверен используется ли на самом деле в этом случае LDAPS, так как по документашке порт там строго 636. Момент для уточнения.
Если пользователи находятся в разных доменах, как это у меня, то скорее всего сделать вход для них всех одной стратегией не получится. Тогда добавляем столько стратегий LDAP / Active Directory, сколько у нас разных доменов. Называем их соответственно и пользователь при логине выбирает свою стратегию. Ну а локальной записью у нас остаётся только администратор Вики:
Самое главное тут: для каждой стратегии LDAP / Active Directory необходимо включить Allow self-registration и указать в какую группу добавлять пользователей (IT). Не предусмотрено маппинга группы из AD в группу Вики (ждём выхода версии 3).
Поэтому сделать нужно так, разослать всем целевым пользователям Вики письма, когда они зарегистрируются выключить Allow self-registration. Прочекать кто там зарегался, лишних удалить/заблокировать.
Общая настройка
Здесь всё предельно просто:
- General, заполняем все поля, включаем комментарии к страницам;
- Locale, подгружаем русский, затем включаем Multiligual Namespacing;
- Rendering, включаем что предполагается использовать для визуализации. Включил всё;
- Search Engine, дефолтный Database-Basic совсем плохенький. Включаем Database-PostgreSQL, Dictionary Language выбираем
russian. Чтобы хорошо искало время от времени делаем Rebuild Index; - Storage, это необходимый пункт. Без него начнутся траблы с отображением картинок. Выбираем Local File System, активируем этот Storage, включаем ежедневную архивацию в целевую папку
/opt/backup:
# mkdir /opt/backup # chown -R wiki:wiki /opt/backup/
После этого нужно обязательно проверить работу архивации, Create Backup-Run. Если всё нормально, появится сообщение об успешной архивации, а в папке появится архив:
# ls /opt/backup/ _manual # ls /opt/backup/_manual/ wiki-20220509-172547.tar.gz
- Mail, учётную запись для отправки почты выдает администратор Exchange. Затем отправляем тестовое письмо.
Вот в общем-то и вся настройка.
Проверка возможностей оформления
Честно говоря ожидал большего. В WordPress, на котором крутится этот сайт, возможностей на порядок больше. Нажимаем на лого Wiki.js в верхнем левом углу, будет предложено создать домашнюю страницу.
И тут два возможности: Visual Editor и Markdown. Пользуюсь визуальным редактором в основном, а если нужно создать на странице диаграмму, то тогда Markdown. Путь страницы лучше создавать через онлайн-транслитератор из названия страницы. Тогда он получается внятным и читаемым.
Navigation, тут мы создаём основное меню. Структуру этого меню лучше продумать сразу и потом изменять незначительно. Так проще для пользователей Вики. И сама Вики будет изначально правильно структурирована.
Первым или одним из первых пунктов меню должен стать "Правила работы в Вики". Эти правила лучше продумать заранее. Иначе каждый начнёт лепить такую отсебятину, что на Вики в результате без слёз не взглянешь. Это из опыта работы.
К каждому линку в меню можно и нужно сделать свою пиктограмму. Использую Material Design Icons, ссылка на их страничку с огромным выбором пиктограмм есть прямо на странице создания линка. К названию пиктограммы обязательно добавлять mdi-. Не все пиктограммы почему-то подтягиваются, но нужные мне подтянулись и удалось настроить красиво.
Обновление
Просто и доступно рассказано на странице проекта. Как раз вышло очередное обновление. Пусть это и минорная версия, всё равно круто, значит проект развивается:
Сохраняем конфиг и сертификат, останавливаем сервис.
# cp /opt/wiki/config.yml /opt/backup # cp /opt/wiki/cert-wiki.pfx /opt/backup # systemctl stop wiki
Удаляем текущие файлы Вики, скачиваем и добавляем новые, удаляем скаченный архив.
# rm -rf /opt/wiki/* # wget https://github.com/Requarks/wiki/releases/latest/download/wiki-js.tar.gz # tar xzf wiki-js.tar.gz -C /opt/wiki/ # rm wiki-js.tar.gz
Восстанавливаем конфиг и сертификат.
# cp /opt/backup/config.yml /opt/wiki/ # cp /opt/backup/cert-wiki.pfx /opt/wiki/
Восстанавливаем права для системного пользователя на файлы папки Вики, стартуем сервис.
# chown -R wiki:wiki /opt/wiki/ # systemctl start wiki
Двухфакторка 2FA
Когда всё будет готово, меню и основные страницы созданы, пользователи зарегистрированы, то на вкладке Security можно включить Enforce 2FA. Это двойная аутентификация через мобильное приложение (типа Яндекс Ключ), вишенка на торте.
Более отказоустойчивый вариант включить 2FA в профиле каждого пользователя, кроме администратора. Выбираю его.
Картинки в Assets
Куда загружаются картинки? Их нет в явном виде в директории Вики.
# find / | grep head.png /opt/backup/head.png - зато файл картинки сразу появляется в Local Storage и это неслучайно
Вспомним процесс обновления, а именно тот момент что мы удаляем всю директорию Вики, сохраняя лишь конфиг и сертификат. Логичный вывод только один: в директории Вики нет данных, там лежат скрипты и файлы кэша, а все данные хранятся в PostgreSQL.
Картинки изначально именно в кэше. Почему я так решил? Если обратиться к скрипту assets.js, то там:
..getAssetFromCache.. ..getAssetFromStorage.. ..getAssetFromDb..
Крайне важный тут момент: в пункте про архивацию указывать полный путь к целевой папке. Прям так и написано:
Absolute path without a trailing slash (e.g. /home/wiki/backup, C:\wiki\backup)
Если этого не сделать (например, в случае развёртывания в Docker) и указать относительный путь от папки Вики (./backup), то архивация работает, но при очистке кэша в Вики перестанут отображаться все загруженные картинки. Они не смогут подтянуться из Storage. А в логе при этом будет:
2022-05-21T13:03:39.612Z [MASTER] error: path must be absolute or specify root to res.sendFile
Кэш очищается при перезапуске контейнера и Docker Compose. Кроме этого его можно очистить руками в пункте меню Utilites-Flush Cache. Обобщаю: без правильной настройки Local Storage нормально работать с Вики не получится.
И последнее, вот моя шапка к домашней странице. Можете пользоваться.
Приглашаю поделиться мнением в Tелеграм канал