# Эксплуатация

## Запуск и остановка

Все команды выполняются из директории станции — там, где лежат
`docker-compose.yml` и `.env`.

```bash
docker compose up -d      # запуск
docker compose down       # остановка
docker compose restart    # перезапуск
```

## Обновление

```bash
docker compose pull
docker compose up -d
```

Тег `latest-addons` обновляется только на релизах. Чтобы закрепить конкретную
версию, замените тег образа в `docker-compose.yml` на
`sonikspace/soniks-client:<версия>` — версионные теги публикуются вместе с
`latest-addons`.

Освободить диск от старых образов:

```bash
docker image prune -af
```

Определения спутников обновлять отдельно не нужно: контейнер забирает свежий
sat-data bundle с портала при каждом старте и кэширует его на постоянном томе,
см. [Поддерживаемые спутники](satellites.md).

## Логи

```bash
docker compose logs -f                  # всё разом
docker compose logs -f soniks-client    # только клиент
docker compose logs --since 1h soniks-client
```

Логи также пишутся в файл `/var/lib/soniks-client/logs/client.log` внутри
контейнера — это именованный том, поэтому они переживают перезапуск и
обновление образа. Ротация: 5 файлов по 5 МБ.

```bash
docker compose exec soniks-client tail -f /var/lib/soniks-client/logs/client.log
```

Уровни логирования настраиваются раздельно — приложение, скрипты, потоковый
граф и планировщик, см.
[переменные `LOG__*`](#log-vars).

## Что искать в логе

Нормальная работа выглядит так:

| Строка | Значение |
|---|---|
| Сообщение о следующем наблюдении с временем | Расписание получено, проход запланирован. |
| Старт наблюдения, запуск `satnogs-pre` | Проход начался. |
| Строки от потокового графа | Идёт приём. |
| Отправка данных | Кадры уходят на портал прямо во время прохода. |

Типовые проблемы:

| Симптом | Причина |
|---|---|
| Клиент падает сразу после старта со списком `STATION__*` | Не заполнены обязательные параметры в `.env`. |
| Ошибка валидации pydantic с именем поля | Пустое значение у типизированной переменной — см. [синтаксис `.env`](configuration.md#синтаксис-env). |
| `NoCompatibleRxDeviceError` | Частота прохода не попала ни в один диапазон `OBSERVATION__SOAPY_RX_DEVICE`. |
| Наблюдения планируются, но приёма нет | SDR не виден контейнеру: проверьте udev-правила и blacklist, см. [Установку](install.md#2-правила-udev-и-blacklist-драйверов). |
| Файлы копятся в `incomplete/` | Портал недоступен или токен неверен. Повторная отправка идёт раз в 20 минут. |

## Здоровье станции

```bash
docker inspect --format '{{.State.Health.Status}}' soniks-client
docker compose exec soniks-client wget -qO- http://127.0.0.1:8080/healthz
```

Ответ показывает, жив ли планировщик, когда станция последний раз сверила
расписание с порталом, сколько наблюдений ждёт в `incomplete/`, идёт ли проход
и когда следующий.

`unhealthy` — это **сигнал, а не автолечение**: `restart: unless-stopped`
перезапускает упавший контейнер, но не больной, Docker так не умеет. Первым
делом смотреть логи. Станция, у которой обновился `docker-compose.yml`, но не
обновился образ, тоже покажет `unhealthy` — старый образ `/healthz` не отдаёт;
лечится `docker compose pull`.

## Диагностика

**Консоль контейнера:**

```bash
docker compose exec -it soniks-client bash
```

**Виден ли SDR:**

```bash
docker compose exec soniks-client SoapySDRUtil --find
```

Если список пуст — проблема на уровне хоста (udev, blacklist, кабель), а не
в конфигурации клиента.

**Ручной прогон потокового графа** без ожидания прохода — скрипт
`test-flowgraph.sh` в контейнере. Это единственный способ проверить связку
SDR + GNU Radio вне расписания.

**Рабочие файлы наблюдений:**

```bash
docker compose exec soniks-client ls -la \
  /var/lib/soniks-client/data/output /var/lib/soniks-client/data/incomplete
```

Каталог задан `PATHS__BASE` в compose. Это постоянный том, поэтому очередь
`incomplete/` с невыгруженными данными переживает перезапуск контейнера.

## Запись IQ

Включается парой переменных, см.
[Конфигурацию](configuration.md#запись-iq). Дополнительно доступна
постобработка дампа после прохода:

```ini
IQ_DUMP_RENAME=True       # переименовать в <файл>_<id>_<samplerate>.raw
IQ_DUMP_COMPRESS=True     # сжать zstd, исходник удалить
```

Скрипт переименования читает `FLOWGRAPH__ENABLE_IQ_DUMP` и
`FLOWGRAPH__IQ_DUMP_FILENAME` — те же переменные, что включают саму запись,
никаких дополнительных задавать не нужно.

## Дополнительные декодеры

Все они отключены по умолчанию и включаются переменными уровня скриптов
(см. [справочник](environment_variables.md#переменные-уровня-скриптов)):

* **METEOR** (`METEOR_NORAD`) — демодуляция METEOR 2-3 / 2-4 из файла IQ-дампа.
  Требует включённой записи IQ.
* **Обзор диапазона** (`BANDSCAN_ENABLE`) — широкополосная запись между
  проходами. Нужен реальный примонтированный диск под `BANDSCAN_DIR`.
* **Реле GPIO** (`GPIO_ENABLE`) — переключение МШУ и антенн через MCP2221
  в зависимости от частоты прохода.

Что именно делает каждый — в [Скриптах и декодерах](../development/scripts.md).