138 lines
11 KiB
Markdown
138 lines
11 KiB
Markdown
# Установка и обслуживание
|
||
|
||
## Подключения и запуск
|
||
|
||
`HOCKEY_DATABASE_URL` — удалённая PostgreSQL с хоккейными данными и сессиями.
|
||
`WFL_DATABASE_URL` — база аккаунтов для авторизации; приложению нужен доступ чтения
|
||
соответствующих учётных записей. Производственный режим не использует SQLite.
|
||
Перед запуском выполните `python check_remote_database.py`.
|
||
|
||
Основные параметры окружения:
|
||
|
||
```env
|
||
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. Сначала просмотрите план:
|
||
|
||
```bash
|
||
python cleanup_project.py --dry-run
|
||
```
|
||
|
||
Применение:
|
||
|
||
```bash
|
||
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 должны проверяться на отдельном прогоне перед эфиром.
|