hockey_new/docs/ADMIN.md

Установка и обслуживание

Подключения и запуск

HOCKEY_DATABASE_URL — удалённая PostgreSQL с хоккейными данными и сессиями. WFL_DATABASE_URL — база аккаунтов для авторизации; приложению нужен доступ чтения соответствующих учётных записей. Производственный режим не использует SQLite. Перед запуском выполните python check_remote_database.py.

Основные параметры окружения:

HOCKEY_DATABASE_URL=postgresql+psycopg://USER:PASSWORD@HOST:5432/hockey
WFL_DATABASE_URL=postgresql+psycopg://USER:PASSWORD@HOST:5432/wfl
HOCKEY_AUTH_MODE=wfl
STAT2TV_LOGIN=...
STAT2TV_PASSWORD=...

Stat2TV также может использовать существующий локальный файл credentials. Не заменяйте реальные секреты значениями из примера. Для HTTPS используйте соответствующую настройку secure-cookie и прокси с поддержкой WebSocket.

Штатная команда сервера — python -m uvicorn app:app --host 0.0.0.0 --port 8000. Используйте один worker без --reload: назначения Agent, WebSocket и очереди живут в памяти процесса. Увеличение workers требует отдельного общего брокера состояния. GET /api/health — публичная проверка процесса, не проверка всей цепочки до vMix. /api/hockey/database/status проверяет подключение БД и может требовать авторизацию.

Для существующего Linux-сервиса основной скрипт — deploy_hockey.sh; deploy.sh оставлен совместимым коротким входом. Перед использованием проверьте в скрипте адрес репозитория, каталог, имя сервиса и путь environment-файла.

Обновление и восстановление

1. Остановите эфирные команды/службу в согласованное окно.
2. Сохраните копию проекта и резервную копию PostgreSQL.
3. Сохраните .env, settings/local/ или внешний HOCKEY_UI_DATA_DIR, локальные credentials/PIN, настройки mapping, agent/agent_config.json, khl_site/data/ и пользовательские материалы.
4. Замените код, установите зависимости, проверьте БД, затем запустите сервис.
5. Проверьте авторизацию, два независимых матча, зрителя, Agent и титры vMix.

Обновление кода не требует сброса пользовательских настроек. Root-файлы settings/ui_builder_*.json — начальные значения для миграции, а не активный UI. Действующие настройки находятся в settings/local/ либо абсолютном каталоге HOCKEY_UI_DATA_DIR. Перед сменой этого каталога остановите сервер и перенесите туда содержимое текущего рабочего каталога настроек.

Для BUILD190 обязательно повторите установку python -m pip install -r requirements.txt: добавлена база часовых поясов tzdata для Windows. Agent.exe заменять не требуется. Три целочисленных поля публикации Mapping добавляются существующим механизмом миграции схемы. После запуска проверьте /api/health: версия 2026.10.21.1. Для обновления существующей VM используйте пакет только изменённых файлов; полный архив содержит снимок настроек из присланной копии и предназначен для восстановления/новой установки. Не заменяйте им более свежие настройки эфира.

История UI сохраняется при реальном изменении конфигурации, максимум 40 копий на тип после сохранения. Старые backup-файлы переносятся один раз: служебный маркер .ui_backups_migrated_v1.json предотвращает их повторное появление после удаления. Черновик и опубликованная версия восстанавливаются отдельно через редактор.

Хранение журнала

По умолчанию журнал хранится в logs/, отдельно от PostgreSQL матчей и WFL. При необходимости задайте HOCKEY_LOG_DIR абсолютным путём к постоянному диску. Процессу службы нужны права на создание/запись файлов в этом каталоге.

Файлы разделены по московским календарным месяцам. Хранятся текущий и предыдущий месяцы: в октябре — сентябрь и октябрь; с 1 ноября сентябрь удаляется. Очистка выполняется при старте и автоматически при смене даты, без перезапуска сервера. Старые файлы удаляются только внутри выделенного каталога журнала; произвольные файлы и символические ссылки не затрагиваются.

Запись идёт через ограниченную очередь отдельным потоком, чтение и выгрузка — вне основного цикла HTTP/WebSocket. В журнале показаны счётчики очереди, потерь при перегрузке и ошибок чтения/записи. При ненулевых счётчиках проверьте доступное место, права каталога и нагрузку диска. Журнал не обещает сохранение каждой записи при аварии диска/принудительном завершении процесса.

Доступ к просмотру и скачиванию требует аккаунта администратора. Время хранится в UTC, фильтры и отображение используют Europe/Moscow. Не открывайте сам каталог logs/ через веб-сервер статических файлов.

Скорость веб-интерфейса

HTML и данные API всегда обновляются. Скрипты и стили с версией в URL кэшируются браузером; при изменении сборки/содержимого URL меняется. Ответы сжимаются GZip, если браузер поддерживает его. Reverse proxy должен сохранять Content-Encoding, Vary и Cache-Control; не задавайте общий публичный кэш для API.

Независимые запросы запуска выполняются параллельно. Runtime не строит список всех полей для редактора на каждом live-обновлении, а несколько внешних обновлений данных в одном кадре объединяются в одну перерисовку. Движок таймеров и немедленные операторские команды продолжают работать отдельно.

Безопасная очистка копии VM

Остановите сервер и Agent. Сначала просмотрите план:

python cleanup_project.py --dry-run

Применение:

python cleanup_project.py --apply

Утилита удаляет только bytecode в известных пакетах, старый agent.log.1, проверенную старую неиспользуемую копию UI и резервные копии из settings/backups/, которые уже идентично перенесены в settings/local/backups/ и имеют маркер миграции. Активный agent.log, settings/local/, секреты, конфигурация Agent и данные КХЛ не удаляются. Изменённая старая копия UI автоматически сохраняется.

Исторические документы удаляются только при совпадении имени из allowlist и SHA-256 с копией в docs/history.zip. Изменённые пользователем старые инструкции сохраняются.

Одинаковые старые XML заменяются жёсткими ссылками: их имена, байты и пути в БД сохраняются. Файлы снимков после этого следует считать неизменяемыми. Если файловая система не поддерживает hardlink, соответствующий шаг пропускается. ZIP-распаковка может снова создать отдельные копии; очистку можно повторить на VM.

Новые XML сохраняются по hash, одинаковые данные не создают новые файлы. XML не удаляются по возрасту: на них ссылается история PostgreSQL. Для полного архивирования уникальных XML требуется отдельно согласованная политика БД. Автоматически чистятся только самостоятельные *_games_discovery.json: сохраняются минимум 40 последних, более старые удаляются после 30 дней.

Проверки

После обновления выполните целевые проверки mapping/прав/нескольких матчей и python -m pytest tests/test_build190_mapping_delivery.py tests/test_mapping_publications.py tests/test_program_log.py tests/test_web_observability.py tests/test_storage_maintenance.py tests/test_stage1_match_access.py tests/test_stage2_ui_storage.py. Старые тесты с жёстко заданными историческими номерами сборок требуют отдельной актуализации; результат такого теста сам по себе не доказывает сбой эфира. Живой vMix и рабочая PostgreSQL должны проверяться на отдельном прогоне перед эфиром.