WANITIL Server

Backend ITIL/HelpDesk-системы WANITIL на Django и PostgreSQL.

Интерактивная документация доступна после запуска сервера по адресу /api/v1/docs/. Дополнительные руководства:

• API задач;
• API изменений и бизнес-процессов;
• API напоминаний.

Первоначальная установка

Инициализация разделена на независимые этапы:

1. migrate создаёт структуру БД.
2. initialize_core создаёт обязательные системные модули и настройки.
3. bootstrap_admin создаёт или обновляет системного администратора.
4. complete_installation однократно выбирает набор данных.

Доступны три набора данных:

Режим	Содержимое
empty	Чистая система без прикладных справочников и демонстрационных данных
basic	Базовые статусы, типы, настройки и другие обязательные справочники
demo	Базовые справочники и демонстрационные данные

Если WANITIL_INSTALL_MODE не задан, сервер запускается в состоянии ожидания. Администратор может выбрать режим через API. После выбора смена режима через API запрещена, чтобы случайно не очистить рабочие данные.

Переменные окружения

Пример конфигурации находится в .env.example.

Переменная	По умолчанию	Описание
ENVIRONMENT	development	Окружение; для production требуется SECRET_KEY и параметры PostgreSQL
DEBUG	False	Режим отладки Django
SECRET_KEY	небезопасный dev-ключ	Секрет Django; обязателен в production
ALLOWED_HOSTS	localhost,127.0.0.1	Разрешённые HTTP-хосты через запятую
SECURE_SSL_REDIRECT	True в production	Перенаправлять HTTP на HTTPS
LOG_LEVEL	INFO	Уровень логирования
SQL_ENGINE	django.db.backends.postgresql	Backend базы данных
SQL_DATABASE	wanitil	Имя базы данных
SQL_USER	wanitil	Пользователь базы данных
SQL_PASSWORD	wanitilpass	Пароль базы данных
SQL_HOST	localhost	Сервер базы данных
SQL_PORT	5432	Порт базы данных
SQL_CONN_MAX_AGE	60	Время жизни соединения с БД в секундах
WANITIL_ADMIN_USERNAME	wanitil	Логин первоначального администратора
WANITIL_ADMIN_EMAIL	wanitil@wanitil.com	Email администратора
WANITIL_ADMIN_PASSWORD	wanitilpass при создании	Пароль администратора
WANITIL_ADMIN_PASSWORD_FILE	—	Файл с паролем; имеет приоритет над WANITIL_ADMIN_PASSWORD
WANITIL_SYSTEM_EMAIL	wanitil@wanitil.com	Системный email
WANITIL_INSTALL_MODE	—	Автоматический режим установки: empty, basic или demo
WANITIL_INSTALL_LANG	en	Язык начальных данных

В production пароль администратора рекомендуется передавать через Docker/Kubernetes secret с помощью WANITIL_ADMIN_PASSWORD_FILE.

Запуск как сервис

Требуются Python 3.12 и доступный PostgreSQL.

python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install .
cp .env.example .env

Отредактируйте .env, затем выполните первоначальную инициализацию:

python manage.py migrate --noinput
python manage.py initialize_core
python manage.py bootstrap_admin

Для автоматического выбора режима:

python manage.py complete_installation --mode basic --lang ru

Если режим должен быть выбран позднее через API, последнюю команду выполнять не нужно. Запуск Gunicorn:

gunicorn --bind 127.0.0.1:10000 --workers 3 --timeout 120 main.wsgi:application

Пример unit-файла /etc/systemd/system/wanitil.service:

[Unit]
Description=WANITIL application server
After=network.target postgresql.service

[Service]
Type=simple
User=wanitil
Group=wanitil
WorkingDirectory=/opt/wanitilserver
EnvironmentFile=/opt/wanitilserver/.env
ExecStartPre=/opt/wanitilserver/.venv/bin/python manage.py migrate --noinput
ExecStartPre=/opt/wanitilserver/.venv/bin/python manage.py initialize_core
ExecStartPre=/opt/wanitilserver/.venv/bin/python manage.py bootstrap_admin
ExecStart=/opt/wanitilserver/.venv/bin/gunicorn --bind 127.0.0.1:10000 --workers 3 --timeout 120 main.wsgi:application
Restart=on-failure

[Install]
WantedBy=multi-user.target

После создания файла:

sudo systemctl daemon-reload
sudo systemctl enable --now wanitil
sudo systemctl status wanitil

Запуск в контейнере

Соберите образ:

docker build -t wanitilserver .

Запуск с PostgreSQL, находящимся на db.example.internal:

docker run --name wanitilserver \
  --env-file .env \
  -p 10000:10000 \
  wanitilserver

Entrypoint автоматически выполняет миграции, initialize_core, bootstrap_admin и, если задан WANITIL_INSTALL_MODE, выбранную настройку.

Пример с Docker secret:

docker run --name wanitilserver \
  --env-file .env \
  -e WANITIL_ADMIN_PASSWORD_FILE=/run/secrets/admin_password \
  -v /secure/admin_password:/run/secrets/admin_password:ro \
  -p 10000:10000 \
  wanitilserver

API первоначальной установки

Swagger UI доступен по адресу /api/v1/docs/, OpenAPI-схема — /api/v1/schema/.

Поиск и фильтрация списков

Параметр searchstr выполняет общий поиск только по полям основной таблицы ресурса. Поля связанных моделей не включаются в общий поиск: это исключает JOIN по связям и размножение строк при пагинации, особенно при нескольких связях many-to-many.

Фильтрация по связанным объектам остаётся доступна через явно объявленные параметры endpoint, например departments__id__exact=1. Такой фильтр применяется только по явному запросу клиента. Если endpoint должен поддерживать поиск по связанному значению в searchstr, реализация должна использовать Exists или подзапрос по идентификаторам, не добавляя JOIN к основному queryset.

Получить состояние установки:

GET /api/v1/main/sys/settings/setup-status/
Authorization: Token <token>

Завершить установку:

POST /api/v1/main/sys/settings/complete-setup/
Authorization: Token <token>
Content-Type: application/json

{
  "mode": "basic",
  "lang": "ru"
}

Запрос разрешён системному администратору только до первого завершения установки. Повторный запрос через API возвращает 409 Conflict.

Повторный запуск

Команды initialize_core и bootstrap_admin идемпотентны. Если контейнер снова запущен с тем же WANITIL_INSTALL_MODE, complete_installation завершается успешно без повторной загрузки данных. Если сохранённый режим отличается от значения переменной, команда завершается ошибкой и Gunicorn не запускается. Это защищает от незаметной смены или очистки рабочего набора данных. Для исправления нужно вернуть прежнее значение переменной либо удалить WANITIL_INSTALL_MODE.

Проверка

python manage.py check
python manage.py test