Применение изменений

Три класса изменений конфигурации, проверка файла до перезапуска, разница между reload и restart, судьба сессий зрителей и откат к прошлой версии.

Изменение в hastreamer.conf попадает в один из трёх классов. Класс определяет, что произойдёт после systemctl reload: изменение применится немедленно, будет записано в файл, но дождётся systemctl restart, либо перезапустит один поток, не тронув остальные.

Сервер классифицирует каждое изменение сам и пишет вердикт в журнал — угадывать не нужно.

Порядок безопасного изменения#

# 1. Сохраните копию — откат из файла всегда быстрее откатa через API.
sudo cp /etc/hastreamer/hastreamer.conf /root/hastreamer.conf.bak

# 2. Отредактируйте файл.
sudo -e /etc/hastreamer/hastreamer.conf

# 3. Проверьте синтаксис и правила БЕЗ применения.
sudo hastreamer --validate /etc/hastreamer/hastreamer.conf

# 4. Примените горячую часть. Ошибочный файл будет отвергнут,
#    работающая конфигурация останется прежней.
sudo systemctl reload hastreamer

# 5. Прочитайте вердикт: что применилось, что ждёт перезапуска.
sudo journalctl -u hastreamer -n 30 --no-pager

# 6. Только если в вердикте есть строки о перезапуске.
sudo systemctl restart hastreamer

Три класса изменений#

Горячие изменения#

Применяются сразу и без разрыва соединений. Политика доступа перечитывается на каждый запрос, даже внутри уже открытого keep-alive-соединения, поэтому включение, отключение и ротация авторизации не требуют перезапуска.

Изменения, требующие перезапуска#

Двадцать три параметра привязаны к моменту запуска процесса: порты слушателей, раскладка по ядрам, глобальные параметры приёма и раздачи. Их новое значение попадает в файл сразу, но применяется только на systemctl restart.

Перезапуск отдельного потока#

Блоки stream, template, storage и vod сверяются по одному. Перезапускается только тот поток, чей отпечаток изменился; остальные сохраняют аптайм, буферы и сессии.

Отпечаток потока — это весь его блок, кроме labels. Отсюда правила:

Тот же перезапуск можно вызвать без правки конфигурации — например, чтобы переподключить зависший источник:

curl -sS -X POST "https://media.example.com/api/v1/streams/cam1/restart" \
  -H "Authorization: Bearer $TOKEN"

{"path":"cam1","restarted":true}

Проверка файла до применения#

hastreamer --validate разбирает файл, прогоняет все правила и завершается, ничего не запуская и ничего не меняя.

sudo hastreamer --validate /etc/hastreamer/hastreamer.conf

/etc/hastreamer/hastreamer.conf: OK (2 streams)

При ошибке разбора печатается номер строки:

parse /etc/hastreamer/hastreamer.conf: line 3: unknown directive "cors"

При ошибке правил валидатор накапливает все ошибки и печатает их через ; — чинить файл можно за один проход, а не по одной ошибке за попытку:

invalid config /etc/hastreamer/hastreamer.conf: stream "cam": needs `source` or a non-empty `sources` chain; http_port and rtsp_port must be non-zero; http_port and rtsp_port must differ (both 0); stream "cam" has an empty source

Коды завершения:

Флаг -j печатает каноническую JSON-форму конфигурации вместо строки OK. Это ровно то тело, которое принимает PUT /api/v1/config:

sudo hastreamer --validate /etc/hastreamer/hastreamer.conf -j | head -20

Ту же проверку можно выполнить по сети, не имея доступа к оболочке сервера. POST /api/v1/config/validate разбирает переданный текст и возвращает классификацию, ничего не записывая:

curl -sS -X POST "https://media.example.com/api/v1/config/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(python3 -c 'import json,sys; print(json.dumps({"text": open("/etc/hastreamer/hastreamer.conf").read()}))')"

{
  "classification": {
    "added": ["cam2"],
    "removed": [],
    "respawn": ["cam1"],
    "restart_required": ["HLS/API listener (http_port 8080 → 80)"],
    "untouched": 7
  },
  "ok": true
}

reload против restart#

Вердикт reload пишется в журнал одной из трёх строк:

config reload: applied epoch 9 (hash 4a186afe976f6ef3)
config reload: no change
config reload REJECTED: <текст ошибок> (running config unchanged)

Что происходит с сессиями зрителей#

Различие принципиальное. Опросные протоколы (HLS, LL-HLS, DASH) не держат соединения: после перезапуска потока плеер, который повторяет запрос плейлиста, продолжит воспроизведение с нового живого края сам. Постоянные соединения (MSE-WS, HTTP-TS, RTSP, WebRTC) закрываются, и повторное подключение — задача плеера; встроенный плеер это делает, сторонний может не делать.

Чтение уже записанного архива и файлов VoD от перезапуска потока не зависит: запись на диск и её раздача — независимые пути.

История конфигурации и откат#

Каждое принятое изменение записывается в журнал версий рядом с файлом конфигурации:

/etc/hastreamer/hastreamer.conf
/etc/hastreamer/hastreamer.conf.history/
    index.jsonl     — по строке на версию
    1.conf          — точные байты версии 1
    2.conf
    …

Журнал пополняется при любом принятом применении. Поле via называет источник изменения, поле actor — кто его сделал:

Прочитать историю:

curl -sS "https://media.example.com/api/v1/config/history" \
  -H "Authorization: Bearer $TOKEN"

[{"epoch":1,"hash":"d9b4d2d2a819ff24","shared_hash":"85851d2f59d9e592",
  "ts_ms":1786787600937,"actor":"system","via":"boot"}]

Откатиться к записанной версии:

curl -sS -X POST "https://media.example.com/api/v1/config/rollback" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"epoch": 7}'

{"epoch":10,"hash":"85851d2f59d9e592","changed":true,"rolled_from":7}

Версии старше 32 последних в журнале уже нет — откат к ней вернёт 404 {"title":"version not found"}. Если вам нужен долгий архив конфигураций, копируйте файл во внешнее хранилище: см. Резервное копирование.

Та же история доступна в панели управления: Конфигурация → История, с кнопкой отката у каждой записи. См. Веб-интерфейс.

Запрет изменений через API#

Создайте файл .locked рядом с конфигурацией — и любой изменяющий вызов API вернёт 423 Locked:

sudo touch /etc/hastreamer/hastreamer.conf.locked

{"type":"about:blank","title":"config locked","status":423,
 "detail":"the config is locked (/etc/hastreamer/hastreamer.conf.locked exists) — remove that file to enable edits via the API/UI"}

Чтение конфигурации, перезапуск службы и правка файла вручную продолжают работать — блокируются только записи через API и панель. Снимается удалением файла.

Что дальше#

• hastreamer.conf — все директивы — какой класс у конкретной директивы указан в колонке «Применение».
• Порты и сеть — что придётся согласовать с межсетевым экраном при смене порта.
• Диагностика неисправностей — если после применения поток не поднялся.