Переменные окружения

Полный справочник. Источник истины — модели pydantic в src/core/configs/; значения по умолчанию в таблицах ниже сверены с ними.

Правила синтаксиса .env (пустое значение = ошибка, разделитель __) описаны в Конфигурации станции.

Переменные последнего раздела — уровня скриптов — устроены иначе: их читают напрямую shell-скрипты, а не pydantic.


Примечание

Разделы, помеченные «управляется с портала», владелец настраивает в форме «Настройки станции» на sonik.space — см. Конфигурацию станции. Значения из .env в них действуют, пока на портале ничего не сохранено, и остаются запасными после.

STATION — параметры станции

Единственный обязательный раздел: значений по умолчанию здесь нет.

Предупреждение

STATION__TOKEN и STATION__ID обязательны, но валидацию на старте не проходит только незаполненный STATION__ID. STATION__TOKEN= — строка, и пустое значение проходит валидацию: именно оно стоит в шаблоне client/.env. Клиент запустится, но портал не примет ни один запрос.

Переменная

Тип

По умолчанию

Описание

STATION__TOKEN

str

Обязательна. Токен авторизации на портале. Секрет. Пустое значение проходит валидацию, см. предупреждение выше.

STATION__ID

int

Обязательна. Идентификатор станции на портале.

STATION__LATITUDE

float

с портала

Широта в градусах. Не задана — берётся из документа состояния портала (координаты станции на её странице). Задана — имеет приоритет и уходит на портал в запросе расписания.

STATION__LONGITUDE

float

с портала

Долгота в градусах. То же правило.

STATION__ELEVATION

int

с портала

Высота над уровнем моря, м. То же правило.

URL — адреса портала

Переменная

Тип

По умолчанию

Описание

URL__BASE

str

https://sonik.space/api/

Базовый адрес API. Менять только для работы с тестовым порталом.

URL__JOBS_PATH

str

jobs/

Путь получения расписания проходов.

URL__OBSERVATIONS_PATH

str

observations/

Путь выгрузки данных наблюдения.

URL__STATIONS_PATH

str

v2/stations/

Путь эндпоинтов станции: <путь><STATION__ID>/status/ — публикация статуса (режимы, версия, итог применения конфигурации), <путь><STATION__ID>/state/ — документ состояния с конфигурацией.

MQTT — живой канал с порталом

Переменная

Тип

По умолчанию

Описание

MQTT__ENABLED

bool

True

Держать подключение к брокеру портала: конфигурация применяется в момент сохранения формы, портал сразу видит статус и «offline». При False или недоступном брокере то же самое происходит раз в минуту через REST.

MQTT__URL

str

wss://sonik.space/mqtt

Адрес брокера. WebSocket на 443 того же хоста — закрытым сетям ничего открывать не нужно.

API — таймауты HTTP

Переменная

Тип

По умолчанию

Описание

API__TIMEOUT_IN_SECONDS_REQUEST_DATA

int

45

Таймаут запроса расписания.

API__TIMEOUT_IN_SECONDS_SEND_DATA

int

120

Таймаут выгрузки данных. Поднимайте на медленном канале: аудио и водопад весят десятки мегабайт.

ANTENNA — поворотное устройство и трансивер

Управляется с портала. Смысл режимов и схема подключения — в Поворотном устройстве. Модель самого ротатора задаётся в docker-compose.yml сервиса rotctld и с портала не меняется.

Переменная

Тип

По умолчанию

Описание

ANTENNA__ROTATOR__ENABLED

bool

False

Включает поток слежения. При False контроллер ротатора вообще не создаётся.

ANTENNA__ROTATOR__MODEL

str

ROT_MODEL_NETROTCTL

Модель Hamlib. NETROTCTL — работа через сетевой rotctld (штатная схема compose). Список моделей: Hamlib Wiki.

ANTENNA__ROTATOR__BAUD

int

9600

Скорость последовательного порта. Игнорируется для сетевых моделей.

ANTENNA__ROTATOR__PORT

str

rotctld:4533

Адрес хост:порт для сетевых моделей или /dev/ttyUSB0 для прямого подключения.

ANTENNA__ROTATOR__THRESHOLD

float

4.0

Порог в градусах: команда на поворот отправляется, только если рассогласование больше этого значения. Защищает механику от дёрганья.

ANTENNA__ROTATOR__MODE

Normal | Flip | 250

Normal

Стратегия слежения. См. Режимы слежения.

ANTENNA__ROTATOR__MIN_ELEVATION

float

0.0

Минимальный угол места. Ниже него ротатор не опускается — полезно, если антенну задевает мачта или крыша.

ANTENNA__RIG__IP

str

rigctld

Хост rigctld (имя сервиса в compose).

ANTENNA__RIG__PORT

int

4532

Порт rigctld.

Устарело, начиная с версии 2.0: ANTENNA__ROTATOR__FLIP (булев флаг) заменён на ANTENNA__ROTATOR__MODE. Старая переменная игнорируется. FLIP=True соответствует MODE=Flip.

OBSERVATION — параметры наблюдения

Управляются с портала: SOAPY_RX_DEVICE, REMOVE_*, RUN_*_SCRIPT.

Переменная

Тип

По умолчанию

Описание

OBSERVATION__SOAPY_RX_DEVICE

str

driver=airspy,biastee=true

Строка драйвера SoapySDR либо список диапазонов <МГц_от>-<МГц_до>:<драйвер> через пробел. См. Несколько приёмников.

OBSERVATION__REMOVE_WATERFALL_RAW_FILES

bool

True

Удалять сырой .dat водопада после отрисовки PNG. Выключайте только для отладки — файлы крупные.

OBSERVATION__REMOVE_OBSERVATION_DATA

bool

True

Удалять файлы наблюдения после успешной выгрузки. При False они переезжают в complete/.

OBSERVATION__RUN_PRE_OBSERVATION_SCRIPT

bool

True

Запускать satnogs-pre перед проходом. Выключение отключает все внешние декодеры.

OBSERVATION__RUN_POST_OBSERVATION_SCRIPT

bool

True

Запускать satnogs-post после прохода.

OBSERVATION__PRE_OBSERVATION_SCRIPT

str

satnogs-pre

Имя pre-скрипта в PATH.

OBSERVATION__POST_OBSERVATION_SCRIPT

str

satnogs-post

Имя post-скрипта в PATH.

OBSERVATION__SCRIPT_TIMEOUT_IN_SECONDS

float

900

Предел работы satnogs-pre/satnogs-post. Ограничивает по-настоящему зависший процесс: декодеры и SSTV штатно идут минутами.

OBSERVATION__RIG_UPDATE_INTERVAL

float

0.1

Период обновления доплеровской коррекции, с.

OBSERVATION__ROTATOR_UPDATE_INTERVAL

float

3

Период пересчёта положения ротатора, с.

OBSERVATION__BATCH_DELAY

float

1

Задержка перед отправкой пачки декодированных кадров, с. Кадры, появившиеся за это окно, уходят одним запросом.

OBSERVATION__TIME_FORMAT_IN_FILENAME

str

%Y-%m-%dT%H-%M-%S

Формат метки времени в именах файлов.

OBSERVATION__FILENAME_TEMPLATE

str

{observation_dir}/{prefix}_{observation_id}_{timestamp}.{extension}

Шаблон имени файла наблюдения.

Служебные вложенные разделы OBSERVATION__PREFIX__*, OBSERVATION__EXTENSION__*, OBSERVATION__SENDING_KEY__* и OBSERVATION__UPLOAD_TYPES__* задают префиксы (payload, waterfall, raw_waterfall, data, metadata), расширения (ogg, png, dat, json) и имена полей выгрузки. Менять их на станции не нужно — портал ожидает именно эти значения.

FLOWGRAPH — потоковый граф SDR

Управляется с портала, кроме UDP_DUMP_*, FLOWGRAPH_DISPATCHER и DEFAULT_MODE. Каждое поле этого раздела превращается в аргумент --kebab-case=значение командной строки flowgraph_dispatcher. Поля со значением None не передаются вовсе. Подробнее — в Потоковом графе.

Переменная

Тип

По умолчанию

Описание

FLOWGRAPH__RX_SAMP_RATE

str

не задан

Частота дискретизации, допускается запись 3e6.

FLOWGRAPH__RX_BANDWIDTH

int

не задан

Полоса приёмного тракта, Гц.

FLOWGRAPH__ANTENNA

str

RX

Имя антенного входа устройства.

FLOWGRAPH__GAIN_MODE

str

Overall

Режим усиления: Overall (одно значение в RF_GAIN), Settings Field (покаскадно в OTHER_SETTINGS) или Automatic.

FLOWGRAPH__RF_GAIN

float

не задан

Общее усиление, дБ. Работает при GAIN_MODE=Overall.

FLOWGRAPH__OTHER_SETTINGS

str

не задан

Покаскадные настройки, например LNA=8,MIX=9,VGA=7. Работает при GAIN_MODE=Settings Field.

FLOWGRAPH__PPM_ERROR

float

0

Поправка опорного генератора, ppm.

FLOWGRAPH__DOPPLER_CORR_PER_SEC

int

не задан

Исторический: графы этот параметр никогда не читали, с 2026-09-12 диспетчер его принимает и отбрасывает. Задавать незачем.

FLOWGRAPH__LO_OFFSET

int

не задан

Смещение гетеродина, Гц — уводит DC-пик от полезного сигнала.

FLOWGRAPH__LO_TRANSVERTER

int

не задан

Частота гетеродина трансвертера, Гц.

FLOWGRAPH__BB_FREQ

int

не задан

Смещение по основной полосе, Гц.

FLOWGRAPH__DC_REMOVAL

bool

не задан

Подавление постоянной составляющей средствами драйвера.

FLOWGRAPH__DEV_ARGS

str

не задан

Дополнительные аргументы устройства SoapySDR.

FLOWGRAPH__STREAM_ARGS

str

не задан

Аргументы потока SoapySDR.

FLOWGRAPH__TUNE_ARGS

str

не задан

Аргументы перестройки SoapySDR.

FLOWGRAPH__ENABLE_IQ_DUMP

bool

False

Писать сырой IQ-поток в файл. Обязательно для METEOR.

FLOWGRAPH__IQ_DUMP_FILENAME

str

не задан

Путь файла IQ-дампа.

FLOWGRAPH__UDP_DUMP_HOST

str

127.0.0.1

Хост UDP-потока IQ. Единственный потребитель — grsat.py: по этому адресу поток уходит демодулятору gr_satellites.

FLOWGRAPH__UDP_DUMP_PORT

int

57356

Порт UDP-потока IQ.

FLOWGRAPH__FLOWGRAPH_DISPATCHER

str

flowgraph_dispatcher

Имя исполняемого файла диспетчера графов.

FLOWGRAPH__DEFAULT_MODE

str

FM

Режим демодуляции, если портал прислал неизвестный, пока режимы станции ему не опубликованы. После публикации такой проход не начинается.

Словари соответствия «режим портала → скрипт satnogs» (SCRIPTS и MODES) переменными окружения не являются: это константы модуля core/configs/flowgraph.py. Добавление режима описано в Потоковом графе.

WATERFALL — водопад

Переменная

Тип

По умолчанию

Описание

WATERFALL__AUTORANGE

bool

False

Подбирать границы шкалы по данным (робастная оценка уровня шума через сигма-клиппинг). При False берутся MIN_VALUE/MAX_VALUE.

WATERFALL__MIN_VALUE

int

-110

Нижняя граница шкалы, дБ. Действует при AUTORANGE=False.

WATERFALL__MAX_VALUE

int

-50

Верхняя граница шкалы, дБ. Действует при AUTORANGE=False.

WATERFALL__DEFAULT_MIN_VALUE

int

-110

Фолбэк нижней границы: AUTORANGE=True, но валидных отсчётов меньше MIN_VALID_SAMPLES. В лог уходит warning.

WATERFALL__DEFAULT_MAX_VALUE

int

-50

Фолбэк верхней границы, там же.

WATERFALL__THRESHOLD

int

-200

Нижняя отсечка отсчётов при автоподборе, дБ. Работает в дополнение к np.isfinite: isfinite убирает -inf пустых бинов, порог — заведомо нефизические уровни. Дефолт намеренно щадящий, реальный шум он не трогает.

WATERFALL__MIN_VALID_SAMPLES

int

10000

Сколько отсчётов должно пережить фильтрацию, чтобы автоподбору можно было верить. Меньше — берутся DEFAULT_MIN/MAX_VALUE. На выгрузку водопада не влияет.

WATERFALL__WIDTH

float

8.32

Ширина изображения, дюймы.

WATERFALL__HEIGHT

float

16.03

Высота изображения, дюймы.

WATERFALL__HELP_LINES

bool

False

Рисовать вспомогательную сетку поверх водопада.

WATERFALL__INTERVAL_IN_MINUTES

int

1

Шаг подписей по оси времени, мин.

WATERFALL__TIME_FORMAT

str

%H:%M

Формат подписей времени на оси.

WATERFALL__TIMESTAMP_FORMAT

str

%Y-%m-%dT%H:%M:%S.%fZ

Формат меток времени в метаданных.

WATERFALL__GRIDSPEC — раскладка полотна matplotlib; менять на станции не нужно.

LOG — логирование

Управляются с портала: LEVEL, SCRIPT_LEVEL, FLOWGRAPH_LEVEL.

Переменная

Тип

По умолчанию

Описание

LOG__LEVEL

str

INFO

Уровень логирования приложения.

LOG__SCRIPT_LEVEL

str

INFO

Уровень для вывода скриптов из scripts/.

LOG__FLOWGRAPH_LEVEL

str

INFO

Уровень для вывода потокового графа. DEBUG даёт очень много строк.

LOG__DIRECTORY

str

/var/lib/soniks-client/logs

Директория лог-файлов. В compose это именованный том, поэтому логи переживают перезапуск.

LOG__FILE_NAME

str

client.log

Имя основного лог-файла.

LOG__MAX_BYTES

int

5242880

Размер файла до ротации (5 МБ).

LOG__BACKUP_COUNT

int

5

Количество ротированных файлов.

LOG__FORMAT

str

%(asctime)s - %(name)s - %(levelname)s - %(message)s

Формат строки лога.

LOG__ENCODING

str

utf-8

Кодировка лог-файла.

SCHEDULER — планировщик заданий

Переменная

Тип

По умолчанию

Описание

SCHEDULER__JOB_REQUEST_INTERVAL_IN_MINUTES

int

1

Период опроса расписания на портале.

SCHEDULER__RESENDING_INTERVAL_IN_MINUTES

int

20

Период повторной отправки данных из incomplete/.

SCHEDULER__SAT_DATA_SYNC_INTERVAL_IN_HOURS

int

6

Период проверки sat-data bundle на портале; новая версия применяется между проходами, рестарт не нужен.

SCHEDULER__MAX_WORKERS

int

30

Размер пула потоков APScheduler.

SCHEDULER__MAX_INSTANCES

int

1

Сколько экземпляров одного задания могут выполняться одновременно.

SCHEDULER__COALESCE

bool

True

Схлопывать пропущенные запуски в один.

SCHEDULER__MISFIRE_GRACE_TIME_IN_SECOND

int

30

Допустимое опоздание запуска задания, с. Больше — задание пропускается.

SCHEDULER__LOG_LEVEL

str

WARNING

Уровень логирования самого APScheduler. На INFO очень шумно.

SDR — обследование приёмника

Поиск подключённых приёмников и калибровка усиления (soniks_client/sdr_survey.py). Итог уходит на портал ключами sdr и calibration документа статуса и показывается в форме «Настройки станции»; команды «Пересканировать» и «Откалибровать усиление» приходят блоком commands документа состояния. Приёмник открывается только вне прохода. Результаты и отметки выполненных команд — в sdr-survey.json рядом с PATHS__STATE_FILE.

Переменная

Тип

По умолчанию

Описание

SDR__SCAN_INTERVAL_IN_MINUTES

float

60

Как часто в простое перечислять приёмники заново — воткнутый или выпавший приёмник появляется на портале без перезапуска. На старте — всегда.

SDR__IDLE_WINDOW_IN_MINUTES

float

3

Сколько минут до ближайшего прохода должно оставаться, чтобы занять приёмник обследованием; меньше — откладывается до следующей сверки.

SDR__GAIN_STEP_DB

float

2

Шаг свипа по общему усилению при калибровке, дБ.

SDR__NOISE_LIFT_DB

float

10

Порог подъёма шумовой полки над минимальной: первое усиление, на котором он достигнут, рекомендуется как FLOWGRAPH__RF_GAIN. Внешний шум тогда заведомо выше собственного шума приёмника.

SDR__CALIBRATION_SAMPLES

int

65536

Выборок на одно измерение мощности.

HEALTH — состояние станции

Переменная

Тип

По умолчанию

Описание

HEALTH__PORT

int

8080

Порт GET /healthz. Слушается внутри сети compose; наружу хоста не выводится, пока в docker-compose.yml нет ports:. Тот же порт читает HEALTHCHECK образа.

AGENT — агент обновлений

Читает их soniks-agent из того же .env (см. Агент обновлений); клиент их не знает. Кроме них агенту нужны STATION__ID, STATION__TOKEN, URL__BASE и HEALTH__PORT — те же, что у клиента.

Переменная

Тип

По умолчанию

Описание

AGENT__INTERVAL_IN_SECONDS

int

60

Период сверки с порталом (GET state/, ETag).

AGENT__WINDOW_IN_MINUTES

int

5

Образ применяется и L2 гоняется, только когда проход не идёт и до ближайшего дальше этого (решение 42).

AGENT__GATE_TIMEOUT_IN_SECONDS

int

60

L1: сколько ждать 200 от /healthz после подъёма. L2: сколько крутить test-flowgraph.sh (успех — дожил до таймаута, код 124). На медленной RPi — поднять.

AGENT__RETRY_AFTER_HOURS

int

24

Провалившийся gate digest не применяется повторно раньше этого срока; новый digest в канале — сразу.

AGENT__CLIENT_SERVICE

str

soniks-client

Имя сервиса клиента в docker-compose.yml станции.

AGENT__STATE_FILE

path

/var/lib/soniks-agent/state.json

Текущий и предыдущий образ, итог последнего применения — на томе soniks-agent.

AGENT__REQUEST_TIMEOUT_IN_SECONDS

int

30

Таймаут запросов к порталу.

PATHS — размещение файлов

Переменная

Тип

По умолчанию

Описание

PATHS__BASE

str

/tmp/.soniks

Корень рабочих директорий. Директории создаются на старте. Оба compose задают /var/lib/soniks-client/data через environment: — постоянный том; значение из .env при этом перекрывается, менять корень надо в compose. Умолчание /tmp/.soniks действует только вне контейнера.

PATHS__OUTPUT_DIR

str

output

Текущие наблюдения.

PATHS__COMPLETE_DIR

str

complete

Успешно выгруженные файлы (если их не удаляют).

PATHS__INCOMPLETE_DIR

str

incomplete

Невыгруженные файлы, ждущие повторной отправки.

PATHS__STATE_FILE

str

/var/lib/soniks-client/desired-state.json

Последний полученный с портала документ состояния (конфигурация, координаты). Лежит на постоянном томе, не под PATHS__BASE: станция без связи с порталом стартует на нём.

Логика раскладки файлов по этим директориям — в Загрузке данных.

JOBS

Переменная

Тип

По умолчанию

Описание

JOBS__PREFIX

str

job_

Префикс имён заданий наблюдения в планировщике. По нему они отличаются от служебных.


Переменные уровня скриптов

Эти переменные не входят в модель настроек — их читают напрямую скрипты в scripts/, унаследованные от SatNOGS. Поэтому у них нет префикса раздела, они не валидируются на старте, а опечатка просто приводит к тому, что функция молча не работает. Что делает каждый скрипт — в Скриптах и декодерах.

Обзор диапазона в простое (bandscan)

Между проходами станция может писать широкополосный обзор диапазона.

Переменная

По умолчанию

Описание

BANDSCAN_ENABLE

выкл.

True/Yes/1 включает обзор.

BANDSCAN_FREQ

Обязательна при включении. Центральная частота, Гц. Допускается запись 435e6.

BANDSCAN_DEVICE

Обязательна при включении. Селектор устройства для rx_sdr. Отдельная переменная, а не OBSERVATION__SOAPY_RX_DEVICE: тот может содержать список «диапазон:устройство», из которого клиент выбирает приёмник по частоте прохода, и угадывать нужный в скрипте неправильно.

BANDSCAN_SAMPLERATE

из FLOWGRAPH__RX_SAMP_RATE

Частота дискретизации обзора.

BANDSCAN_DIR

/srv/bandscan

Куда складывать результат. Нужен реальный примонтированный диск.

BANDSCAN_BIN

rx_sdr

Утилита захвата.

BANDSCAN_CHANNELS

по частоте: 20 (< 300 МГц) / 50 (< 500 МГц) / 100 (выше)

Число каналов БПФ.

BANDSCAN_OUTPUT_FORMAT

CF32

Формат выхода.

BANDSCAN_INPUT_FORMAT

float

Формат входа.

APP_PATH

/tmp/.soniks

Где лежит PID-файл обзора (bandscan.pid). Совпадает с PATHS__BASE.

Скрипт также требует FLOWGRAPH__RX_SAMP_RATE и FLOWGRAPH__ANTENNA — без них он завершается с ошибкой, — и читает FLOWGRAPH__PPM_ERROR (по умолчанию 0), FLOWGRAPH__RF_GAIN (0) и FLOWGRAPH__OTHER_SETTINGS (пусто).

METEOR

Переменная

По умолчанию

Описание

METEOR_NORAD

57166 59051

Список NORAD ID через пробел, для которых запускается демодуляция METEOR из IQ-дампа. Требует FLOWGRAPH__ENABLE_IQ_DUMP=True.

Запись IQ (постобработка)

Переменная

По умолчанию

Описание

IQ_DUMP_RENAME

выкл.

Переименовывать дамп после прохода в <файл>_<id>_<samplerate>.raw.

IQ_DUMP_COMPRESS

выкл.

Сжимать переименованный дамп через zstd (исходник удаляется).

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

Управление реле GPIO

Переменная

По умолчанию

Описание

GPIO_ENABLE

выкл.

Включает gpio.py — управление реле (МШУ, выбор антенны, ротатор) через MCP2221 в зависимости от частоты прохода.

Парковка ротатора

Переменная

По умолчанию

Описание

ROT_PARK

выкл.

После прохода отправить ротатору команду парковки. Адрес берётся из ANTENNA__ROTATOR__PORT.

ROT_PARK_POSITION

180 90

Азимут и угол места парковки через пробел. Зависит от физической установки мачты, поэтому вынесено в переменную.

Декодеры gr-satellites и SSTV

Переменная

По умолчанию

Описание

GRSAT_APP

gr_satellites

Имя исполняемого файла декодера в PATH.

GRSAT_LOG_LEVEL

INFO

Уровень логирования обёртки grsat.py.

GRSAT_KEEPLOGS

False

Не удалять логи gr_satellites после прохода.

GRSAT_ZMQ_PORT

не задан

Порт ZMQ, если декодер получает поток не из файла.

SSTV_TIMEOUT

600

Предел декодирования SSTV, с. Зависит от длины прохода: по истечении процесс останавливается, остальная постобработка продолжается.