Диагностика неисправностей

Симптом → причина → решение для камер, нод, архива, доступа и TLS.

Раздел построен по симптомам. Найдите свой в нужной группе, проверьте вероятную причину и выполните действие. Если симптом относится к свежей установке — сначала пройдите Проверку после установки: она отсекает половину случаев.

С чего начать#

Пять команд, которые дают картину за минуту:

# 1. живы ли сервисы
systemctl status hastreamer-cctv-plane --no-pager      # на сервере Plane
systemctl status hastreamer-cctv-node  --no-pager      # на сервере ноды

# 2. что говорит журнал (ошибка почти всегда в последних строках)
sudo journalctl -u hastreamer-cctv-plane -n 50 --no-pager
sudo journalctl -u hastreamer-cctv-node  -n 50 --no-pager

# 3. какие порты реально слушаются
sudo ss -tlnp | grep -E 'hastreamer|:80|:443|:9080|:9443|:8554'

# 4. доступна ли камера с сервера ноды
nc -vz <адрес-камеры> 554

# 5. есть ли место на дисках
df -h /var /mnt/dvr

Журнал называет причину точнее любой таблицы

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

Камера#

Симптом	Вероятная причина	Что сделать
Камера добавлена, видео нет	Нода не лицензирована	`journalctl -u hastreamer-cctv-node \| grep -i licens`; Лицензирование
Камера добавлена, видео нет	Камера недоступна с сервера ноды	С ноды: `nc -vz <адрес-камеры> 554`; проверьте маршрутизацию и VLAN
Камера добавлена, видео нет	Неверные логин или пароль камеры	Проверьте учётные данные в настройках камеры; в журнале ноды будет ошибка авторизации RTSP
Видео появляется и пропадает	Потери в сети до камеры или перегрузка камеры	Снизьте битрейт или частоту кадров на камере; проверьте канал
Видео замирает, затем восстанавливается	Сторожевой таймер переподключил зависший поток	Норма при кратковременных сбоях; повторяется часто — проблема камеры или сети
Камера в списке, но `availability` не `ready`	Нода отключена, выключена или камера отключена	`GET /api/v1/cameras/<UUID>/play`, поле `availability`; проверьте состояние ноды
Изображение есть, звука нет	Камера отдаёт неподдерживаемый браузером кодек звука или звук выключен	Включите на камере AAC: звук в формате G.711 принимается и пишется в архив, но браузер его не воспроизводит
Камера не находится автопоиском	ONVIF отключён на камере либо другой сегмент сети	Добавьте камеру вручную по адресу RTSP — Добавление камер

# проверить поток камеры с сервера ноды, минуя систему
nc -vz <адрес-камеры> 554                     # порт RTSP открыт?
getent hosts <имя-камеры>                    # имя резолвится?

Нода#

Симптом	Вероятная причина	Что сделать
Нода в состоянии `pending`, не становится `active`	Plane не может достучаться до ноды	Проверьте `control_url`, межсетевой экран, `sudo ss -tlnp \| grep hastreamer` на ноде
Нода отвечает браузерам, но в админке `offline`	Адрес управления `http://` у ноды со своим TLS: при редиректе теряется авторизация	Приведите оба адреса к `https://`: Ноды → нода → Сеть и TLS → Адреса ноды — TLS и сертификаты
Сервис перезапускается в цикле	Ошибка в `node.conf`	`journalctl -u hastreamer-cctv-node -n 50`: сообщение содержит номер строки
Правка `node.conf` исчезла после перезапуска	Правка была внутри управляемой Plane секции	Перенесите её выше маркера `>>> MANAGED BY cctv-plane`
`stream may appear only in the plane-managed region`	Камера дописана в файл вручную	Удалите блок и добавьте камеру в админке
`managed region exists but no plane-approved snapshot is present`	Секция есть, а снимка конфигурации нет	Дайте Plane применить конфигурацию заново либо удалите секцию целиком
Изменили порт — ничего не произошло	Порты применяются только при перезапуске	`systemctl restart hastreamer-cctv-node`, затем обновите адреса ноды в Plane
Нода слушает не те порты, что вы ожидали	Слушатели выводятся из схемы и порта адреса управления	Сверьте адрес: Ноды → нода → Сеть и TLS → Адреса ноды; таблица соответствия — Порты и сеть
В API `node_unreachable`	Нода не отвечает на управляющие запросы	Проверьте сервис, порт, `control_url` и схему (`http`/`https`)
`tune: ⚠ host is not optimally tuned`	Часть параметров ядра не применилась	Производительность

Опечатка в node.conf не «деградирует», а роняет сервис

Неизвестная директива, неверное значение перечисления или число вне диапазона — это жёсткая ошибка: процесс завершается с ошибкой, systemd перезапускает его каждые 2 секунды, и получается цикл. Всегда проверяйте правку перезагрузкой конфигурации, а не перезапуском:

sudo systemctl reload hastreamer-cctv-node
sudo journalctl -u hastreamer-cctv-node -n 20 --no-pager
# config reload REJECTED: line 7: unknown directive "cors" (running config unchanged)

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

Архив#

Симптом	Вероятная причина	Что сделать
Архив не пишется совсем	Диск не инициализирован	Выполните инициализацию: Ноды → нода → Хранилища; проверьте маркер `.hastreamer-storage-identity` в каталоге
Архив не пишется у части камер	У камеры не включена запись или не выбрано хранилище	Проверьте настройки камеры — Архив (DVR)
Глубина архива меньше ожидаемой	Диск заполнен, работает вытеснение старых записей	Сверьте расчёт: Требования; добавьте ёмкость или снизьте битрейт
Записи пропали за большой период	Настроен слишком короткий срок хранения	Проверьте единицы: `m` — минуты, `mo` — месяцы; `30m` это 30 минут, а не 30 месяцев
`storage_config_not_converged` при инициализации	Нода ещё не получила конфигурацию от Plane	Подождите цикл согласования (до минуты) и повторите
«Идентификатор файловой системы не совпадает»	Том подменён или примонтирован другой диск	Проверьте `lsblk`, `df -h`, точку монтирования; DVR блокируется до устранения
Архив есть, но не проигрывается	Нет прав на архив у пользователя	Проверьте гранты — Пользователи и права
Диск заполняется скачками	Одновременно включили запись на многих камерах	Норма; убедитесь, что порог вытеснения задан и работает

# что реально на диске
mount | grep /mnt/dvr
ls -a /mnt/dvr | head             # ожидается .hastreamer-storage-identity
df -h /mnt/dvr
du -sh /mnt/dvr

Неинициализированный диск не принимает камеры с записью

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

Доступ и вход#

Симптом	Вероятная причина	Что сделать
`401` при входе в админку	Неверный логин или пароль	Сброс: `sudo hastreamer-plane --reset-superadmin /etc/hastreamer-cctv/plane.toml`
Пользователя выкидывает примерно через час	Истёк срок жизни сессии	Увеличьте `session_ttl_secs` в plane.toml и перезапустите Plane
Все пользователи разлогинены одновременно	Сменился ключ подписи сессий (восстановление без ключа или ротация)	Резервное копирование — раздел о ключе сессий
Оператор не видит камеры	Нет грантов на камеры или теги	Проверьте эффективные права — Пользователи и права
`403 not_accessible` в API	Прав на конкретную камеру нет	Тот же раздел; проверьте организацию камеры
Плеер пустой при рабочем API	Смешанное содержимое: нода заведена по `http://`, а админка по HTTPS	Приведите адреса ноды к `https://` — TLS и сертификаты
Ссылка общего доступа не открывается	Срок действия истёк или доступ отозван	Выпустите новую — Доступ по ссылке

401 от ноды при рабочем Plane — почти всегда адрес управления с http://

Нода, которая терминирует TLS, перенаправляет обычный HTTP на HTTPS. При перенаправлении браузеры и клиенты не переносят заголовок авторизации, и управляющий запрос приходит на ноду без прав — она отвечает 401, а в админке нода выглядит недоступной, хотя видео раздаёт.

Проверьте адрес: Ноды → нода → Сеть и TLS → Адреса ноды. У ноды с собственным TLS оба адреса должны быть по https:// — так их и задаёт установщик; http:// остаётся только для ноды за прокси, который сам терминирует TLS.

TLS и сертификаты#

Симптом	Вероятная причина	Что сделать
`ACME … issuance failed`	Порт 80 недоступен снаружи	Откройте порт 80 и проверьте, что его не занял другой веб-сервер
`ACME … issuance failed`	DNS не указывает на этот хост	`getent hosts cctv.example.com` и сравните с внешним IP сервера
Браузер предупреждает о сертификате	Режим `self_signed` или временный сертификат после неудачного выпуска	Перейдите на `acme` — TLS и сертификаты
`tls.hosts must include the public_url hostname`	Имя из `public_url` не указано в списке `hosts`	Добавьте его в `[tls] hosts` и перезапустите Plane
`tls.mode=off requires an http:// public_url`	За реверс-прокси выбран режим `off`	Нужен режим `external`
`Address already in use`	Порт 80 или 443 занят другим веб-сервером	Освободите порт либо переходите на `external` с прокси впереди
Сертификат ноды не выпускается	Нет TLS-слушателя, wildcard в `hosts` или порт 80 не приходит на `http`-слушатель ноды	Задайте `https`, укажите конкретное имя, пробросьте порт 80
Сертификат перестал обновляться	Порт 80 закрыли после установки	Откройте его: продление использует ту же проверку, что и выпуск

# что реально отдаёт сервер
echo | openssl s_client -connect cctv.example.com:443 -servername cctv.example.com 2>/dev/null \
  | openssl x509 -noout -issuer -dates
# доступен ли порт 80 снаружи — проверяйте с другого хоста
curl -sS -o /dev/null -w '%{http_code}\n' http://cctv.example.com/.well-known/acme-challenge/test
# любой код ответа означает, что порт открыт и слушатель отвечает;
# 000 — соединение не установилось: порт закрыт или закрыт межсетевым экраном

Порт 80 нужен постоянно, а не только при установке

Сертификат Let's Encrypt действует около трёх месяцев и продлевается автоматически той же проверкой на порту 80. Закрытый после установки порт даёт отложенный отказ: всё работает недели, а потом сайт перестаёт открываться по HTTPS.

База данных#

Симптом	Вероятная причина	Что сделать
`connection refused` при старте Plane	PostgreSQL не запущен	`systemctl status postgresql`, затем `systemctl enable --now postgresql`
`password authentication failed`	Пароль в `plane.toml` не совпадает с ролью	`sudo -u postgres psql -c "ALTER ROLE hastreamer_cctv LOGIN PASSWORD 'пароль из plane.toml'"`
То же после восстановления из копии	Восстановили `plane.toml`, но не `.dbpass`	Резервное копирование — раздел о `.dbpass`
`/health` отвечает `503`, `"db":"down"`	База недоступна или перегружена	Журнал PostgreSQL, свободное место на `/var`
Ответы API `503 db_unavailable`	Исчерпан пул подключений	`GET /api/v1/monitor/plane`: сравните `db_pool_in_use` и `db_pool_max`; увеличьте `db_pool_max`
Админка отвечает всё медленнее	База растёт (события и аудит)	Настройте срок хранения событий и аудита — События
Plane не стартует после правки конфигурации	Ошибка в `plane.toml`	`journalctl -u hastreamer-cctv-plane -n 50`; синтаксис — plane.toml

# доступность базы и её размер
sudo -u postgres psql -c "SELECT 1"
sudo -u postgres psql -c "SELECT pg_size_pretty(pg_database_size('cctv'))"
df -h /var

Если ничего не помогло#

Соберите данные до обращения в поддержку — это ускорит разбор в разы:

# версии
curl -sS "$BASE/api/v1/version" -H "Authorization: Bearer $TOKEN"
curl -sS "$BASE/api/v1/nodes"   -H "Authorization: Bearer $TOKEN"

# журналы за последние сутки
sudo journalctl -u hastreamer-cctv-plane --since '24 hours ago' --no-pager > /tmp/plane.log
sudo journalctl -u hastreamer-cctv-node  --since '24 hours ago' --no-pager > /tmp/node.log

# состояние хоста ноды
uname -a; nproc; free -h; df -h; sysctl kernel.io_uring_disabled
curl -sSk https://node.example.com/metrics > /tmp/node-metrics.txt   # -k: у ноды может быть самоподписанный сертификат

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

Переустановка поверх существующей установки безопасна и сохраняет данные, а удаление с --purge необратимо уничтожает базу вместе со всеми камерами, пользователями и событиями. Порядок действий — Обновление и удаление.