Инструкция по установке

Состав программы. Программа «Автоматизированная информационная система „Тренировочное тестирование для подготовки к НОК в сфере ЖКХ“» (альтернативное наименование — АИС «Тренировочное тестирование для подготовки к НОК в сфере ЖКХ»), версия 1.0.1, состоит из двух частей, которые поставляются вместе в одном дистрибутиве:

1. Серверная часть — веб-приложение, планировщик заданий, схема базы данных, сценарии установки и обслуживания. Устанавливается на сервер под управлением Linux.
2. Модуль обмена (aiszkh_export) — передаёт серверной части сведения из внешней системы АИС ОК ЖКХ. Устанавливается на сервер системы АИС ОК ЖКХ её владельцем или с его согласия и обращается к её базе данных только на чтение.

В состав программы не входят банк экзаменационных вопросов и ответов, настройки экзаменационных тестов и сведения о соискателях. Это данные лицензиата, которые он получает из системы АИС ОК ЖКХ на основании собственных прав. Не входят также операционная система, СУБД, веб-сервер и интерпретатор Python: они устанавливаются из репозиториев операционной системы.

Способы предоставления: интернет-сервис и установка на сервер лицензиата.

Для промышленной эксплуатации нужны: сервер Linux с СУБД MariaDB и веб-сервером nginx; доменное имя и сертификат TLS (работа только по HTTPS); модуль обмена на сервере системы АИС ОК ЖКХ и защищённый канал до него; почтовый сервер для уведомлений.

Демонстрационный режим: модуль обмена работает со встроенным набором вымышленных данных вместо базы системы АИС ОК ЖКХ; письма не отправляются. В этом режиме можно проверить все функции программы без доступа к системе АИС ОК ЖКХ.

1. Состав поставки

Платформа поставляется архивом дистрибутива oqzhkh-<версия>.tar.gz с контрольной суммой oqzhkh-<версия>.tar.gz.sha256. В архиве:

Проверка целостности архива:

sha256sum -c oqzhkh-1.0.1.tar.gz.sha256

2. Требования к серверу

Системные компоненты (MariaDB, nginx, Python, шрифты DejaVu) не входят в поставку: сценарий устанавливает их из репозиториев операционной системы. Библиотеки Python ставятся из каталога wheelhouse/ комплекта поставки.

3. Установка

1. Скопировать архив на сервер и распаковать:

tar -xzf oqzhkh-1.0.1.tar.gz cd oqzhkh-1.0.1

2. Запустить сценарий установки:

sudo bash install.sh

Сценарий выполняет:

• установку системных пакетов: python3, python3-venv, nginx, mariadb-server, fonts-dejavu-core;
• копирование Платформы в каталог /opt/test_aiszkh_app;
• создание виртуального окружения Python и установку библиотек из wheelhouse/;
• создание файла настроек /opt/test_aiszkh_app/.env из .env.example с генерацией секретного ключа, ключей шифрования персональных данных и пароля базы данных;
• создание базы данных test_aiszkh и её пользователя в MariaDB;
• создание таблиц базы данных (миграции);
• регистрацию служб systemd test_aiszkh (веб-приложение), test_aiszkh_scheduler (планировщик) и таймера резервного копирования aiszkh-backup.timer.

3. Создать учётную запись администратора:

cd /opt/test_aiszkh_app sudo -u www-data bash -c 'set -a; . ./.env; set +a; venv/bin/python manage.py create-admin admin admin@example.ru'

Пароль администратора вводится с клавиатуры (не короче 8 символов).

4. Запустить службы:

sudo systemctl start test_aiszkh test_aiszkh_scheduler

5. Настроить веб-сервер (раздел 5) и открыть Платформу в браузере.

4. Настройка

Настройки хранятся в файле /opt/test_aiszkh_app/.env. После изменения — перезапуск служб: sudo systemctl restart test_aiszkh test_aiszkh_scheduler.

Параметры почтового сервера (SMTP) задаются администратором в интерфейсе: «Почта → Настройки».

5. Веб-сервер

Промышленная эксплуатация — только по HTTPS с действующим сертификатом TLS; в .env BASE_URL=https://… и SESSION_COOKIE_SECURE=1.

sudo cp /opt/test_aiszkh_app/nginx_ratelimit.conf /etc/nginx/conf.d/ratelimit.conf
sudo cp /opt/test_aiszkh_app/nginx_test_aiszkh.conf /etc/nginx/sites-available/test_aiszkh
sudo ln -s /etc/nginx/sites-available/test_aiszkh /etc/nginx/sites-enabled/

В файле /etc/nginx/sites-available/test_aiszkh указать доменное имя (server_name) и пути к сертификату и ключу TLS (ssl_certificate, ssl_certificate_key). Затем выполнить sudo nginx -t && sudo systemctl reload nginx.

Работа по HTTP допускается только для демонстрационного стенда в изолированной сети или виртуальной машине без реальных данных (раздел 7).

6. Подключение к системе АИС ОК ЖКХ

Модуль обмена устанавливается на сервере системы АИС ОК ЖКХ (Windows Server, PostgreSQL):

1. Установить Python 3.12 и скопировать каталог aiszkh_export/ в C:\app\aiszkh_export.
2. Выполнить от имени администратора сценарий aiszkh_export\deploy_windows.ps1. Он создаёт виртуальное окружение, устанавливает зависимости и регистрирует автозапуск модуля. Модуль слушает только адрес 127.0.0.1:8789.
3. Создать в PostgreSQL учётную запись только для чтения и указать её в файле .env.export модуля. Порядок описан в aiszkh_export/README.md.
4. На сервере Платформы настроить зашифрованный канал (SSH-туннель):

sudo apt install autossh sudo ssh-keygen -t ed25519 -f /root/.ssh/aiszkh_tunnel -N '' # открытый ключ /root/.ssh/aiszkh_tunnel.pub добавить на сервере АИС ОК ЖКХ echo 'AISZKH_TUNNEL_TARGET=<пользователь>@<адрес сервера АИС ОК ЖКХ>' | sudo tee /etc/default/aiszkh_tunnel echo 'AISZKH_TUNNEL_KEY=/root/.ssh/aiszkh_tunnel' | sudo tee -a /etc/default/aiszkh_tunnel sudo cp /opt/test_aiszkh_app/aiszkh_tunnel.service /etc/systemd/system/ sudo systemctl daemon-reload && sudo systemctl enable --now aiszkh_tunnel

5. В .env Платформы указать AISZKH_API_URL=http://127.0.0.1:8789/api/v1, AISZKH_BUNDLE_URL=http://127.0.0.1:8789/bundle/ и ключи доступа, заданные в модуле.
6. Выполнить первичную загрузку:

cd /opt/test_aiszkh_app sudo -u www-data bash -c 'set -a; . ./.env; set +a; \ venv/bin/python manage.py aiszkh-dict-sync && \ venv/bin/python manage.py aiszkh-bank-sync --force && \ venv/bin/python manage.py aiszkh-sync'

Далее обмен выполняется планировщиком автоматически.

7. Демонстрационный стенд

Для ознакомления и проверки Платформа разворачивается с демонстрационными данными, без подключения к системе АИС ОК ЖКХ. Модуль обмена работает в демонстрационном режиме на том же сервере и отдаёт вымышленные заявления, ЦОК, СПК и вопросы. Письма не отправляются.

sudo bash install.sh
sudo bash scripts/demo_stand.sh

Пароль администратора стенда не передаётся в командной строке (он сохранился бы в истории команд и был бы виден в списке процессов): сценарий запрашивает его с клавиатуры. Для запуска без терминала пароль передаётся переменной окружения — sudo --preserve-env=ADMIN_PASSWORD bash scripts/demo_stand.sh — либо, если она не задана, генерируется и выводится один раз в конце работы сценария.

По завершении сценарий выводит адрес стенда и учётные записи для входа:

Второй экземпляр на том же сервере. Демонстрационный стенд можно развернуть рядом с рабочим экземпляром: отдельный каталог, база данных, порты и службы задаются переменными окружения.

sudo APP_DIR=/opt/test_zhkh_demo SERVICE=test_zhkh_demo APP_PORT=5100 WORKERS=2 \
     DB_NAME=test_zhkh_demo DB_USER=test_zhkh_demo_user bash install.sh
sudo APP_DIR=/opt/test_zhkh_demo SERVICE=test_zhkh_demo EXPORT_PORT=8799 \
     MOCK_SERVICE=test_zhkh_demo_export BASE_URL=https://demo.<домен> NGINX=0 \
     bash scripts/demo_stand.sh

Веб-сервер для такого экземпляра настраивается отдельным блоком server с его доменным именем (пример — nginx_demo_test_zhkh.conf).

8. Проверка работоспособности

systemctl status test_aiszkh test_aiszkh_scheduler
curl -s http://127.0.0.1:5000/health          # {"status": "ok"}

Открыть в браузере адрес Платформы, войти под администратором, открыть «Отчёты → Платформа → Сводка по платформе».

9. Резервное копирование и восстановление

Таймер aiszkh-backup.timer ежесуточно в 02:30 сохраняет в /var/backups/test_aiszkh дамп базы данных (db-<дата>.sql.gz) и копию файла настроек .env (env-<дата>) с ключами шифрования. Копии хранятся 30 дней. Рекомендуется дополнительно переносить их на внешнее хранилище.

Восстановление:

sudo systemctl stop test_aiszkh test_aiszkh_scheduler
sudo cp /var/backups/test_aiszkh/env-<дата> /opt/test_aiszkh_app/.env
set -a; . /opt/test_aiszkh_app/.env; set +a
gunzip -c /var/backups/test_aiszkh/db-<дата>.sql.gz | mysql -u "$AISZKH_DB_USER" -p"$AISZKH_DB_PASSWORD" "$AISZKH_DB_NAME"
sudo systemctl start test_aiszkh test_aiszkh_scheduler

10. Обновление версии

1. Распаковать архив новой версии.
2. Скопировать файлы поверх /opt/test_aiszkh_app, сохранив .env и каталог media/.
3. Установить библиотеки: sudo -u www-data /opt/test_aiszkh_app/venv/bin/pip install --no-index --find-links wheelhouse -r requirements.txt.
4. Применить миграции: venv/bin/python migrate.py up.
5. Перезапустить службы.