Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

156 Commits

Folders and files

Repository files navigation

Schedule Parse Service

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

api

Стек технологий

  1. Java
  2. Spring: Web, Data, Security, Actuator
  3. ApachePOI
  4. PostgreSQL
  5. Redis
  6. MinIO
  7. Open Telemetry
  8. Micrometer
  9. ClickHouse
  10. Docker

Установка и настройка

  1. Клонируйте репозиторий:

    git clone https://github.com/simadimonyan/schedule-parse-system.git -b production
    cd schedule-parse-service
    
  2. Отредактируйте .env и application.properties. Для production дополнительно настройте grafana.ini и compose.yaml. Следуйте комментариям в коде. При наличии доменного имени указывать его по url в соответствии с комментариями.

  3. Если используется HTTP, закомментируйте строки для nginx в compose.yaml. Для HTTPS (если у вас нет сертификатов):

  4. Создайте сертификаты через bash init-certs.sh

  5. Отредактируйте конфигурационный файл journald (для предотвращения переполнения памяти диска):

sudo nano /etc/systemd/journald.conf
  1. Найдите и измените (или добавьте) строку:
[Journal]
SystemMaxUse=100M

сервис

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

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

Переменная Описание
POSTGRES_USER Имя пользователя для подключения к PostgreSQL
POSTGRES_PASSWORD Пароль пользователя PostgreSQL
POSTGRES_DB Имя базы данных PostgreSQL
REDIS_USER_PASSWORD Пароль для подключения к Redis
MINIO_ROOT_USER Имя root-пользователя MinIO
MINIO_ROOT_PASSWORD Пароль root-пользователя MinIO (должен содержать цифры, спецсимволы и буквы разных регистров)
MINIO_WEBHOOK_AUTH_TOKEN Токен авторизации для вебхука MinIO (используется для интеграции с сервисом)
PGADMIN_DEFAULT_EMAIL Email для входа в pgAdmin
PGADMIN_DEFAULT_PASSWORD Пароль для входа в pgAdmin
CLICKHOUSE_USER Имя пользователя ClickHouse
CLICKHOUSE_PASSWORD Пароль пользователя ClickHouse
HYPERDX_API_URL URL для подключения к HyperDX API (заменить на доменное имя в production)
HYPERDX_API_PORT Порт HyperDX API
HYPERDX_APP_URL URL для подключения к приложению HyperDX (заменить на доменное имя в production)
HYPERDX_APP_PORT Порт приложения HyperDX
FRONTEND_URL URL фронтенда (указать доменное имя в production)
MINIO_SERVER_URL URL сервера MinIO
MINIO_BROWSER_REDIRECT_URL URL для доступа к веб-интерфейсу MinIO (/console для production)
GF_SECURITY_ADMIN_USER Имя администратора Grafana
GF_SECURITY_ADMIN_PASSWORD Пароль администратора Grafana

Образ MinIO

Образ не тянется из Docker Hub — он лежит локально в ./images и загружается скриптом. Перед первым запуском (и после docker system prune):

./minio-image.sh load

Подробности — раздел MinIO.

Запуск

./minio-image.sh load
sudo docker compose up

При проблемах с правами доступа, где pgAdmin и grafana бесконечно перезапускаются, выполните:

sudo chmod -R 777 ./volumes

Настройка MinIO и приложения

  1. docker exec -it minio /bin/sh

  2. bash minio-generate-keys.sh (адрес сервера: http://minio:9000)

  3. Перейдите в /src/main/resources

  4. Отредактируйте application.properties с новыми ключами.

  5. Перезапустите приложение: docker restart app

  6. Дождитесь запуска сервиса app

  7. docker exec -it minio /bin/sh

  8. bash minio-manual-init-webhook.sh (повторять с шага 7-8 при перезапуске app)

  9. Для того, чтобы защитить сервер от переполнения памяти необходимо настроить первичные данные для скрипта перезагрузки и очистки сервисов (очищает volume clickhouse и кеш docker контейнеров):

# 1. Добавьте сгенирированные на шаге 2 MinIO ключи по переменным MINIO_ACCESS_KEY и MINIO_SECRET_KEY на строчках 11 и 12
# 2. Добавьте ваш URL с subpath к сервису для функции wait_for_service на строчках 146 и 147
nano restart-services.sh
  1. Настройте автоочистку и перезапуск через crontab. Откройте файл crontab. Выполните следующую команду в терминале:
crontab -e
  1. Это откроет файл crontab в текстовом редакторе. Добавьте строку. В самом низу файла добавьте команду для cron автоочистки и перезапуска сервисов каждые 12 часов (начиная с 01:00):
0 1,12 * * * /usr/bin/bash /root/schedule-parse-system/restart-services.sh  
  1. Вместе со стеком скрипт поднимает и сервисы ботов (репозиторий schedule-bot-service): в конце restart-services.sh идёт docker compose up -d --build в их папке — по умолчанию /root/schedule-bot-service, переопределяется переменной BOTS_DIR. Там же лежит их .env (токены Telegram и MAX, BOTS_API_TOKEN = schedule.access.token, BOTS_API_URL=http://app:8080/schedule). Нет папки — шаг пропускается с предупреждением, на стек это не влияет.

Важно: чистка намеренно не трогает контейнер guard — это сторож, который следит за стеком снаружи и должен пережить перезапуск, чтобы о нём рассказать. Поэтому скрипт останавливает только свои сервисы (docker compose down) и контейнер bots, а вместо docker system prune -a --volumes делает container/image/builder prune без томов: иначе прунер сносил бы и сторожа вместе с его памятью.

Настройка API

Инициализируйте четность недели через Swagger:

POST /api/v1/configuration/week/swap
Authorization: Bearer <access-token> (application.properties)

Body:
Bearer <admin-token> (application.properties)

Настройка pgAdmin

db

  • Подключитесь к базе данных через интерфейс pgAdmin. (адрес: app_db)

Настройка HyperDX

logs

  • Измените доменное имя в .env.
  • Подключите ClickHouse. (адрес: http://clickhouse:8123)
  • При ошибках подключения к базе — перезапустите сервис clickhouse.

Настройка Grafana для работы с subpath (production)

monitor

  1. Откройте файл configs/grafana/grafana.ini.
  2. Найдите и отредактируйте параметры:
    • Установите параметр root_url с subpath /grafana
    • Убедитесь, что serve_from_sub_path = true.
  3. Для production:
    • Откройте compose.yaml.
    • Удалите строки с портами, чтобы исключить прямой доступ и повысить безопасность соединений.
  • Добавьте плагин ClickHouse.
  • Добавьте datasource (адрес: clickhouse)
  • Импортируйте дашборд из /configs/grafana/MonitorDashboard.json.
  • При ошибках подключения — перезапустите сервис базы clickhouse.

MinIO

Объектное хранилище, через которое в сервис попадает расписание: загружаешь .xlsx в бакет schedule — MinIO дёргает вебхук приложения — парсер разбирает файл и раскладывает пары по базе. Плюс это же хранилище отдаёт файлы обратно по API.

Откуда берётся образ

Docker Hub репозиторий minio/minio закрыт: registry отвечает 401, docker pull не работает ни с тегом, ни с digest. Официальный источник образа теперь — quay.io/minio/minio, а в проекте лежит его локальная копия, чтобы прод не зависел от внешнего registry вовсе:

compose.yaml → image: local/minio:RELEASE.2025-09-07T16-13-09Z
               pull_policy: never        # ходить за образом некуда и незачем
images/minio-RELEASE.2025-09-07T16-13-09Z-amd64.tar.gz    64 МБ  ← сервер
images/minio-RELEASE.2025-09-07T16-13-09Z-arm64.tar.gz    59 МБ  ← Mac (Apple Silicon)

Архивы не в git. На новую машину их завозят руками:

scp images/minio-RELEASE.2025-09-07T16-13-09Z-amd64.tar.gz \
    root@server:/root/schedule-parse-system/images/

Установка

./minio-image.sh load     # распаковать образ в docker (сам выберет amd64/arm64)
./minio-image.sh check    # что есть локально: образ, архивы, архитектура
docker compose up -d minio
docker logs minio | tail -5      # должно быть: API :9000, WebUI :9001

load идемпотентен: если образ уже в docker, он ничего не делает. Скрипт вызывается из restart-services.sh автоматически — там перед стартом идёт docker system prune -a, который образы стирает, а заново их взять неоткуда.

Если образа нет и архива нет (чистый сервер, забыли scp):

./minio-image.sh save     # тянет обе платформы с quay.io и кладёт в ./images

Настройка

Переменные в .env (описаны в разделе Переменные окружения): MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, MINIO_WEBHOOK_AUTH_TOKEN, MINIO_SERVER_URL, MINIO_BROWSER_REDIRECT_URL.

Данные и сертификаты — на bind-mount'ах ./volumes/minio/data и ./volumes/minio/certs, поэтому пересоздание контейнера и смена образа бакеты не трогают.

Ключи для приложения и вебхук настраиваются один раз — по шагам из Настройка MinIO и приложения: minio-generate-keys.sh создаёт access/secret для пользователя, они прописываются в application.properties (minio.access.key, minio.secret.key), затем minio-manual-init-webhook.sh заводит бакет schedule, регистрирует notify_webhook:1 на /minio-webhook приложения и вешает событие put.

Использование

Веб-интерфейс — http://localhost:9001 (на проде https://admin.myimsit.ru/console/), логин/пароль — MINIO_ROOT_USER / MINIO_ROOT_PASSWORD. Туда же кладут файл расписания, если делают это руками.

Консольный клиент mc уже внутри образа — отдельно ставить не нужно:

docker exec -it minio /bin/sh
mc alias set myminio http://minio:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"

mc ls myminio/schedule                     # что лежит в бакете
mc cp raspisanie.xlsx myminio/schedule/    # залить файл → сработает парсер
mc event list myminio/schedule             # вебхук на месте?
mc admin config get myminio notify_webhook # куда он стучится
mc admin info myminio                      # состояние хранилища

Событие приходит только на put в бакет schedule; всё остальное парсер игнорирует.

Обновление образа

./minio-image.sh save    # поднимет свежий релиз с quay.io в ./images

Затем поменять тег RELEASE.* в compose.yaml и в шапке minio-image.sh, загрузить и пересоздать контейнер:

./minio-image.sh load && docker compose up -d --force-recreate minio

Публично на quay сейчас лежат RELEASE.2025-09-07T16-13-09Z (последний обычный релиз) и более свежие сборки с суффиксом .hotfix.*.

Если что-то не так

Симптом Причина и что делать
Error response from daemon: No such image: local/minio:… образ не загружен → ./minio-image.sh load
нет архива images/…-amd64.tar.gz архив не доехал на сервер → scp или ./minio-image.sh save
exec format error при старте загружен архив чужой платформы (arm64 на сервере) → взять -amd64
контейнер healthy, но расписание не парсится слетел вебхук после перезапуска app → bash minio-manual-init-webhook.sh
docker pull minio/minio отвечает 401 так и должно быть, Hub закрыт — образ берётся локально

Опросы с обратной связью

/api/v1/quizzes — опросы для студентов: клиенты (приложение, боты) показывают открытые опросы и отправляют анкеты, администратор создаёт опросы и смотрит итоги. Все запросы — с ключом доступа в Authorization: Bearer …. Административные ручки принимают служебный ключ schedule.admin.token в теле ({"token": {"token": "Bearer <admin>"}} в publish/edit, {"token": "Bearer <admin>"} в остальных) либо токен диспетчера из кабинета ИСУЭР в заголовке X-User-Token: Bearer <jwt> (AdminAccess, роль dispatcher). Таблицы (quiz_table, question_table, answer_table, submission_table, application_table, quiz_group_table) и новые колонки (quiz_table.recurrence, submission_table.period) создаёт ddl-auto=update, новых ключей настроек нет.

Метод и путь Кто Что делает
GET /search?group=&respondent= клиент открытые сейчас опросы: для всех и для группы; с respondent — без уже пройденных (ежемесячные — без пройденных в этом месяце)
GET /{id} клиент опрос с вопросами (черновик → 404)
POST /submit клиент анкета; ответ — {quizId, message} с благодарностью из опроса
POST /publish админ создать опрос (published: false — черновик) → 201
PATCH /edit/{id} админ правка; null-поля не меняются; вопросы — только пока нет ответов (иначе 409)
DELETE /remove/{id} админ удалить опрос вместе с анкетами
POST /admin/search админ все опросы, включая черновики и завершённые
POST /{id}/results?group=&period= админ итоги: доли вариантов, распределение и средняя оценка, свободные ответы; period=yyyy-MM — только анкеты месяца
POST /admin/export админ выгрузить опросы в переносимый JSON
POST /admin/import?draft= админ создать опросы из такого JSON (всё или ничего)

Типы вопросов: SINGLE и MULTIPLE (варианты в answers, минимум два), TEXT (до 2000 символов), RATING (оценка 1..scale, scale 2–10, по умолчанию 5). required по умолчанию true. Даты — yyyy-MM-dd (начало/конец дня) или yyyy-MM-ddTHH:mm по Москве, пустая граница — без ограничения. Статус опроса (draft, scheduled, active, closed) считается из published и дат.

POST /api/v1/quizzes/publish
{
  "token": {"token": "Bearer <admin>"},
  "name": "Как вам новое расписание?",
  "completionMessage": "Спасибо! Учтём к следующему семестру.",
  "groups": ["24-СПО-ИСиП-01"],
  "endDate": "2026-10-31",
  "recurrence": null,
  "questions": [
    {"label": "Удобно ли смотреть расписание?", "type": "SINGLE", "answers": [{"label": "Да"}, {"label": "Нет"}]},
    {"label": "Оцените приложение", "type": "RATING", "scale": 5},
    {"label": "Что улучшить?", "type": "TEXT", "required": false}
  ]
}

POST /api/v1/quizzes/submit
{
  "quizId": 1, "respondent": "tg:934458920", "group": "24-СПО-ИСиП-01",
  "answers": [
    {"questionId": 2, "answerId": 3},
    {"questionId": 5, "value": "4"},
    {"questionId": 6, "value": "Пуш за 10 минут до пары"}
  ]
}

Для MULTIPLE — по строке на каждый выбранный вариант. respondent — устойчивый id клиента (tg:<id>, max:<id>, android:<uuid>, ios:<uuid>): повторная анкета → 409. В базе лежит только SHA-256 от пары «опрос + respondent», поэтому из итогов не узнать, кто что ответил. Ошибки анкеты (нет ответа на обязательный вопрос, чужой вариант, оценка вне шкалы, опрос не для этой группы) → 400 с текстом, который можно показать пользователю; опрос завершён или ещё не начался → 409.

Повтор раз в месяц

recurrence в QuizRequest/QuizResponse: null — опрос проходят один раз, "monthly" — раз в каждом календарном месяце по Москве (регистр не важен, другое значение → 400). При правке null — не менять, "" — снова сделать опрос разовым. В QuizResponse ещё period: у monthly — текущий месяц ("2026-10"), иначе null. У monthly-опроса в хеш респондента входит месяц (respondent@yyyy-MM), а в анкете хранится period: search прячет опрос, только если на него ответили в текущем месяце, submit даёт 409 лишь при повторе в том же месяце, итоги можно смотреть по месяцу (?period=2026-10). У разовых опросов хеш прежний, старые анкеты продолжают ловить повтор.

Экспорт и импорт

Описание опросов без id вопросов/вариантов и без анкет — для переноса между стендами.

POST /api/v1/quizzes/admin/export
{"token": "Bearer <admin>", "ids": [1, 2]}          // ids пусто или нет — все опросы

→ {"format": "isuer.quizzes", "version": 1, "exportedAt": "2026-10-14T12:00:00",
   "quizzes": [{"name": "…", "description": null, "completionMessage": "…", "groups": [],
                "recurrence": "monthly", "startDate": null, "endDate": null, "published": true,
                "questions": [{"label": "…", "description": null, "type": "SINGLE", "required": true,
                               "scale": null, "answers": [{"label": "Да"}, {"label": "Нет"}]}]}]}

POST /api/v1/quizzes/admin/import?draft=true|false принимает тот же документ плюс "token": "Bearer <admin>" и отвечает {"quizzes": [созданные QuizResponse]}. Опросы всегда создаются заново; всё или ничего — при первой же ошибке ничего не сохраняется и приходит 400 с текстом «Опрос N: причина» (N с единицы). Чужой format или version ≠ 1 → 400. draft=true — все опросы импортируются черновиками. Опрос по умолчанию «Как вам «Моя Академия»?» лежит в docs/quizzes/feedback-monthly.json:

jq '. + {token: "Bearer <admin>"}' docs/quizzes/feedback-monthly.json |
  curl -X POST "$BASE/api/v1/quizzes/admin/import?draft=false" \
       -H "Authorization: Bearer <access>" -H "Content-Type: application/json" -d @-

URL

Адреса для production (пример: myimsit.ru)

Адреса для теста

Безопасность

  • Запросы с одного IP: 10 r/s
  • TCP соединения с одного IP: 2
  • Кеширование ответов с кодом 200: 10 минут
  • Время хранения логов, метрик и трассировок: 12 часов

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages