Инструкция по установке экземпляра программного обеспечения «Индивидуальная образовательная траектория для образовательной платформы»

1 Общие сведения

1.1 Наименование программного обеспечения
Полное наименование программного обеспечения — «Индивидуальная образовательная траектория для образовательной платформы» (далее — Программа). Сокращённое наименование, применяемое в технической документации, — U1 ИОТ. Альтернативные наименования отсутствуют. Правообладателем программного обеспечения является Общество с ограниченной ответственностью «УМ Первый» (ОГРН 1231600043454, ИНН 1655497466).

1.2 Назначение программного обеспечения
Программа предназначена для персонализации образовательного пути клиента на образовательной платформе: формирования индивидуального учебного маршрута по цели обучения и уровню подготовки клиента, выдачи учебного материала по событиям расписания занятий и предоставления пользователям платформы средств корректировки маршрута. Целями разработки Программы являются: удовлетворение индивидуальных потребностей обучающихся в интеллектуальном, нравственном и художественно-эстетическом развитии; выявление, развитие и поддержка обучающихся, проявивших выдающиеся способности; удовлетворение иных образовательных потребностей и интересов обучающихся, не противоречащих законодательству Российской Федерации, осуществляемое за пределами федеральных государственных образовательных стандартов и федеральных государственных требований; повышение качества освоения образовательных программ (полностью либо частично) с применением дистанционных образовательных технологий с учётом баланса времени труда и отдыха обучающихся; повышение уровня контроля за своевременностью и полнотой освоения образовательных программ обучающимися.

1.3 Состав программного обеспечения
В состав Программы входят следующие программные компоненты:
– iot-service — серверный компонент (микросервис), реализующий бизнес-логику формирования и ведения образовательных траекторий, обработку входящих событий расписания, публикацию исходящих доменных событий и программные интерфейсы;
– модули ИОТ веб-приложения platform-one — клиентский компонент, реализующий пользовательские интерфейсы репетитора и методиста. Программа реализована как самостоятельный микросервис с собственным хранилищем данных, что позволяет выполнять её развёртывание, масштабирование и обновление независимо от интегрируемых образовательных платформ.

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

1.5 Термины, определения и сокращения

2 Системные требования

2.1 Требования к серверной части
Минимальные требования к вычислительным ресурсам для развёртывания серверного компонента в контуре разработки и тестирования приведены в таблице 2. Для продуктивного контура объём ресурсов определяется исходя из фактической нагрузки и количества запускаемых экземпляров процессов.

2.2 Требования к клиентской части
Установка программного обеспечения на рабочее место пользователя не требуется. Требования к рабочему месту приведены в таблице 3.

2.3 Обеспечивающее программное обеспечение
Для установки и работы Программы необходимо следующее обеспечивающее программное обеспечение:

• Python версии 3.13 и выше;
• менеджер пакетов uv;
• PostgreSQL версии 13 и выше;
• PgBouncer — пул соединений с базой данных (для продуктивного контура);
• Redis или Valkey версии 6 и выше;
• доступ к кластеру брокера сообщений Apache Kafka с поддержкой защищённого соединения;
• Node.js версии LTS — для сборки клиентского компонента;
• Docker и средства оркестрации контейнеров — при контейнерном развёртывании;
• обратный прокси-сервер (Nginx или контроллер входящего трафика кластера) — для терминирования TLS и публикации клиентского компонента.

3 Описание установочного пакета

3.1 Состав установочного пакета
Установочный пакет Программы включает:

• исходный код серверного компонента с файлами описания зависимостей и миграциями базы данных;
• исходный код модулей клиентского компонента в составе веб-приложения платформы;
• файл описания контейнерного образа и файл описания состава служб для локального развёртывания;
• образец файла переменных окружения и документацию по их назначению;
• эксплуатационную документацию.

3.2 Основные компоненты
Перечень компонентов, разворачиваемых при установке, приведён в таблице 4.

4 Установка серверного компонента

4.1 Подготовка окружения
Установить общесистемное программное обеспечение и менеджер пакетов uv:

Вместо локальной установки СУБД и хранилища задач допускается использование управляемых сервисов контура заказчика.

Результат: в системе установлены интерпретатор Python, менеджер пакетов uv, СУБД и хранилище задач.

4.2 Получение исходного кода и установка зависимостей

Установка зависимостей выполняется в соответствии с зафиксированным файлом блокировки версий, что обеспечивает воспроизводимость состава окружения.

Результат: в каталоге проекта создано виртуальное окружение с установленными зависимостями.

4.3 Создание базы данных
Создать пользователя и базу данных Программы:

Результат: создана база данных Программы и учётная запись для подключения к ней.

4.4 Настройка переменных окружения
Создать файл переменных окружения на основе поставляемого образца и заполнить значения параметров:

Все переменные Программы имеют префикс IOT_. Обязательному заполнению подлежат группы параметров, приведённые в таблице 5; полный перечень переменных приведён в приложении А. Корневой путь приложения определяется контуром эксплуатации: во всех контурах, кроме локального, используется значение /iot-service.

Ключ подписи маркеров доступа должен совпадать со значением, используемым системой аутентификации образовательной платформы. При запуске в предпродуктивном и продуктивном контурах приложение проверяет, что значения маркеров доступа служебного интерфейса и параметров брокера сообщений отличаются от значений по умолчанию, и прекращает запуск при обнаружении несоответствия.

Результат: сформирован файл конфигурации, соответствующий параметрам контура эксплуатации.

4.5 Применение миграций

Изменение структуры базы данных выполняется исключительно средствами системы миграций. Прямое изменение схемы не допускается.

Результат: в базе данных созданы таблицы Программы и перечислимые типы; версия схемы соответствует установленной версии Программы.

4.6 Запуск процессов приложения
Процессы Программы используют общий образ приложения; режим работы определяется командой запуска. Запуск процесса программного интерфейса в контуре разработки:

Запуск процесса программного интерфейса в продуктивном контуре:

Запуск фонового обработчика задач и планировщика:

Запуск обработчика событий расписания:

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

Результат: запущены процессы программного интерфейса, обработчика событий, фонового обработчика задач и планировщика.

4.7 Установка в контейнерной среде
Для контейнерного развёртывания предусмотрен файл описания образа. Сборка образа:

Процесс в контейнере выполняется от имени непривилегированного пользователя. Один и тот же образ используется для всех процессов Программы; режим работы задаётся командой запуска контейнера. Для локального развёртывания полного состава служб предусмотрен файл описания состава служб:

При развёртывании в кластере оркестрации контейнеров процессы разворачиваются отдельными группами с независимым масштабированием, а параметры конфигурации передаются из значений развёртывания контура.

5 Установка клиентского компонента

5.1 Настройка адресов программных интерфейсов
Модули ИОТ входят в состав веб-приложения платформы. Перед сборкой необходимо задать переменные окружения сборки, определяющие адрес программного интерфейса Программы и путь проксирования запросов в контуре разработки. Значения задаются в файле переменных окружения приложения.

Результат: клиентский компонент настроен на обращение к установленному экземпляру серверного компонента.

5.2 Сборка и публикация приложения

1. Получить исходный код веб-приложения платформы и установить зависимости средствами менеджера пакетов Node.js.
2. Выполнить сборку приложения в режиме продуктивной сборки.
3. Разместить полученный набор статических файлов на обратном прокси-сервере контура.
4. Настроить маршрутизацию запросов к программному интерфейсу Программы на обратном прокси-сервере.

Результат: веб-приложение опубликовано, разделы ИОТ доступны пользователям с соответствующими ролями.

Отображение разделов ИОТ управляется признаком функциональной готовности на стороне платформы; порядок его включения определяется администратором платформы.

6 Проверка установки

6.1 Проверка серверного компонента
Выполнить последовательно следующие проверки:

1. Запросить состояние сервиса по служебному адресу /health/ — возвращаются признак работоспособности, наименование и версия сервиса.
2. Запросить готовность сервиса по адресу /health/ready — дополнительно проверяется подключение к базе данных.
3. Запросить жизнеспособность процесса по адресу /health/live.
4. Запросить состояние базы данных по адресу /health/db.
5. Открыть интерактивную документацию программного интерфейса по адресам /docs и /redoc и убедиться в её доступности (доступ защищён базовой аутентификацией).
6. Запросить метрики приложения по адресу /metrics и убедиться в их формировании.

Результат: все проверки возвращают положительный результат, программный интерфейс доступен.

Служебные адреса /private/healthcheck и /private/readiness используются средствами контроля контура эксплуатации.

6.2 Проверка интеграций

1. Убедиться в наличии подключения к брокеру сообщений по защищённому каналу и в отсутствии нарастающего отставания группы потребителей.
2. Направить тестовое событие расписания и убедиться, что оно обработано, а сведения о маршруте изменены.
3. Убедиться в формировании записей в таблицах исходящих событий, в их публикации фоновым обработчиком задач и в открытии темы с ТВЛ на стороне контентной части платформы по опубликованному событию.
4. Проверить доступность контентной части платформы и сервиса расписания с использованием заданных ключей доступа; синхронные запросы применяются для получения справочных сведений и отзыва доступа к исключённой подарочной ТВЛ.
5. Убедиться в отсутствии записей в хранилище необрабатываемых сообщений либо проанализировать причины их появления.

Результат: обмен данными с внешними системами платформы выполняется штатно.

6.3 Проверка клиентского компонента

1. Выполнить вход в личный кабинет под учётной записью с ролью «репетитор» и открыть учебный маршрут клиента.
2. Убедиться в отображении перечня тем, показателей выдачи и просмотра, заметки целеполагания.
3. Выполнить вход под учётной записью с ролью «методист» и открыть раздел шаблонных траекторий.

Результат: интерфейсы Программы доступны, данные отображаются корректно.

7 Дополнительные настройки

7.1 Настройка защищённого соединения
На внешнем периметре платформы обязательна настройка протокола TLS на обратном прокси-сервере или контроллере входящего трафика. Сертификаты выпускаются и обновляются средствами контура заказчика. Дополнительно следует задать перечень разрешённых источников кросс-доменных запросов, ограничив его адресами веб-приложения платформы.

7.2 Настройка мониторинга и журналирования
Для продуктивного контура рекомендуется:

• установить машиночитаемый формат записей журнала и уровень детализации не ниже информационного;
• настроить сбор метрик приложения средствами системы сбора метрик и их визуализацию;
• задать параметры передачи сведений об ошибках в систему регистрации ошибок с указанием контура эксплуатации;
• настроить контроль отставания обработчика событий и объёма неотправленных исходящих событий;
• настроить проверки работоспособности и готовности на основании служебных адресов, приведённых в подразделе 6.1.

7.3 Настройка резервного копирования
Резервное копирование базы данных Программы выполняется средствами контура эксплуатации. Рекомендуемая периодичность полного копирования — ежедневно. Файлы конфигурации развёртывания хранятся в системе контроля версий. Восстановление выполняется в следующем порядке: развёртывание экземпляра базы данных из резервной копии, применение миграций до версии, соответствующей устанавливаемой версии Программы, запуск процессов приложения и выполнение проверок, приведённых в разделе 6.

7.4 Поэтапное включение функциональности
Обработка событий расписания включается поэтапно по парам «предмет — класс». По умолчанию обработка выключена для всех реальных пар: события принимаются, но бизнес-логика не выполняется. Это позволяет вводить Программу в эксплуатацию ограниченными группами клиентов. Для включения обработки следует указать перечень пар в соответствующей переменной окружения и перезапустить процесс обработчика событий.

8 Обновление программного обеспечения

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

1. Создать резервную копию базы данных.
2. Получить новую версию исходного кода либо контейнерного образа.
3. Обновить состав зависимостей командой uv sync (при установке из исходного кода).
4. Применить миграции базы данных командой uv run alembic upgrade head.
5. Перезапустить процессы программного интерфейса, обработчика событий, фонового обработчика задач и планировщика.
6. Выполнить проверки, приведённые в разделе 6 настоящего документа.

Результат: установлена новая версия Программы, работоспособность подтверждена проверками.

Обновление клиентского компонента выполняется средствами процесса непрерывной интеграции и доставки веб-приложения платформы. Откат версии выполняется переключением на предыдущий контейнерный образ с учётом совместимости схемы данных. При наличии несовместимых изменений схемы откат выполняется с восстановлением базы данных из резервной копии.

9 Устранение неполадок

Перечень типовых неполадок, их причин и способов устранения приведён в таблице 6.

При анализе неполадок следует использовать записи журнала приложения, содержащие идентификатор запроса, а также сведения системы регистрации ошибок и системы сбора метрик.

10 Контакты и техническая поддержка

При возникновении вопросов, связанных с установкой и настройкой Программы, следует обратиться в службу технической поддержки по адресу электронной почты support@umschool.one.

В обращении необходимо указать:

• наименование и версию устанавливаемой Программы;
• контур эксплуатации и параметры окружения (без указания значений секретов);
• этап установки, на котором возникла неполадка;
• текст сообщения об ошибке и соответствующие записи журнала приложения;
• сведения о выполненных действиях по устранению неполадки.

Приложение А. Перечень переменных окружения

Перечень основных переменных окружения серверного компонента приведён в таблице А.1. Полный перечень с описанием допустимых значений приведён в документации, входящей в состав установочного пакета.

© 2026 ООО «УМ Первый». Все права защищены.