Конфигурация Callbox

Callbox настраивается переменными окружения. Пять переменных обязательны: DATABASE_DSN, LIVEKIT_SERVER_URL, LIVEKIT_CLIENT_URL, LIVEKIT_API_KEY и LIVEKIT_API_SECRET.

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

Основные параметры

Переменная	По умолчанию	Описание
PORT	8081	Порт HTTP-сервера Callbox.
BASE_PATH	/callbox	Базовый путь интерфейса и API. Значение нормализуется с ведущим / и без завершающего /.
APP_VERSION	1.0.0	Версия в health-check и регистрации Discovery. Для ветки Oak используйте 1.11.0.
LOG_LEVEL	info	Уровень логирования: debug, info, warn или error.
JWT_SECRET	qwe123	Секрет проверки JWT NextBox. В production задайте тот же стойкий секрет, которым подписываются пользовательские токены.
JWT_COOKIE_NAME	access_token	Имя cookie с JWT.

Секреты по умолчанию

Значения вида qwe123, devkey и devsecret допустимы только для локального стенда. Для production сгенерируйте отдельные стойкие секреты и не храните их в репозитории.

PostgreSQL

Переменная	По умолчанию	Описание
DATABASE_DSN	—	Обязательная. DSN базы Callbox, например postgres://nextbox:secret@postgresql:5432/callbox?sslmode=disable.
DATABASE_MAX_OPEN_CONNS	20	Максимальное число открытых соединений; должно быть больше нуля.
DATABASE_MAX_IDLE_CONNS	10	Максимальное число простаивающих соединений; не больше DATABASE_MAX_OPEN_CONNS.
DATABASE_CONN_MAX_IDLE_TIME	5m	Максимальное время простоя соединения; 0 отключает ограничение.
DATABASE_CONN_MAX_LIFETIME	30m	Максимальное время жизни соединения; 0 отключает ограничение.

База callbox должна существовать до запуска. Миграции схемы выполняются автоматически при старте приложения.

LiveKit

Переменная	По умолчанию	Описание
LIVEKIT_SERVER_URL	—	Обязательная. Внутренний URL LiveKit для Callbox, например http://livekit:7880.
LIVEKIT_CLIENT_URL	—	Обязательная. URL LiveKit, доступный клиентам: ws://host:7880 для HTTP-стенда или wss://calls.example.com для production.
LIVEKIT_API_KEY	—	Обязательная. API-ключ LiveKit.
LIVEKIT_API_SECRET	—	Обязательная. API-секрет LiveKit.

Ключ и секрет должны совпадать в Callbox, livekit.yaml, egress.yaml и BEARER_TOKEN сервиса egress-files. LiveKit webhook должен отправляться на http://callbox:8081/callbox/api/egress/webhook при BASE_PATH=/callbox.

NextBox, Discovery и уведомления

Переменная	По умолчанию	Описание
NEXTBOX_API_URL	пусто	Внутренний базовый URL NextBox, например http://gateway:6005. Можно менять во время работы.
NEXTBOX_PUBLIC_URL	внешний origin запроса	Публичный URL NextBox для ссылок в браузере, например https://nextbox.example.com. При установке Callbox под /callbox на том же reverse proxy можно не задавать.
USERS_API_BASE_URL	пусто	Устаревший fallback для NEXTBOX_API_URL; используйте только для совместимости.
USERS_API_TIMEOUT	5s	Timeout запросов к API пользователей и групп.
DISCOVERY_URL	пусто	URL Discovery, например http://discovery:6011. При пустом значении регистрация отключена.
SERVICE_TOKEN	пусто	Общий service token NextBox. Также защищает health-check и metrics.
SERVICE_NAME	Nextbox Calls	Имя экземпляра в Discovery.
SERVICE_ROUTE_NAME	callbox	Имя маршрута в Discovery.
SERVICE_BACK_URL	пусто	Внутренний origin Callbox без BASE_PATH, например http://callbox:8081.
SERVICE_INSTANCE_NUMBER	1	Номер экземпляра сервиса.
NEXTBOX_NOTIFICATIONS_ENABLED	false	Публикация событий Callbox в систему уведомлений NextBox.
RABBITMQ_URL	пусто	AMQP URL NextBox, например amqp://nextbox:secret@rabbitmq:5672/nextbox.

Если NEXTBOX_NOTIFICATIONS_ENABLED=true, одновременно обязательны RABBITMQ_URL, DISCOVERY_URL и SERVICE_TOKEN; иначе Callbox завершит запуск с ошибкой.

Контракт Discovery

Discovery всегда обращается к корневому /api/health-check origin и отбрасывает path из SERVICE_BACK_URL. Поэтому указывайте только origin без /callbox. Callbox публикует служебный health endpoint в корне независимо от BASE_PATH.

Redis

Переменная	По умолчанию	Описание
REDIS_URL	пусто	Redis Callbox, например redis://redis:6379/0. При пустом значении распределённый cache отключён.
REDIS_KEY_PREFIX	callbox:v1	Префикс ключей без начального и конечного :.

Callbox, LiveKit и Egress используют общий сервис Redis. Callbox подключается к DB 0, а LiveKit и Egress — к DB 1. В livekit.yaml и egress.yaml должны совпадать адрес redis:6379 и значение db: 1.

Файлы и canvas

Переменная	По умолчанию	Описание
FILE_STORAGE_PATH	./data/files	Локальный каталог файлов комнат и записей. В контейнере рекомендуется /var/callbox/files.
CANVAS_STORAGE_PATH	./data/canvases	Локальный каталог данных canvas. В контейнере рекомендуется /var/callbox/canvases.
FILE_MAX_SIZE	1073741824	Максимальный размер загружаемого файла в байтах, по умолчанию 1 ГБ. Можно менять во время работы.

Оба каталога должны быть постоянными volumes с правом записи для процесса Callbox.

Запись звонков

Переменная	По умолчанию	Описание
RECORDING_ENABLED	false	Показывает управление записью и разрешает запуск Egress. Можно менять во время работы.
EGRESS_FILES_URL	пусто	Внутренний URL временных файлов, например http://egress-files:9100. Можно менять во время работы.

URL шаблона Room Composite Egress Callbox формирует автоматически из NEXTBOX_API_URL, BASE_PATH и /static/egress. При NEXTBOX_API_URL=http://gateway:6005 убедитесь, что этот внутренний адрес маршрутизирует /callbox; иначе используйте адрес reverse proxy внутри Docker-сети.

Сервис egress-files настраивается отдельно:

Переменная	По умолчанию	Описание
DATA_DIR	/data	Общий с Egress каталог результатов.
PORT	9100	HTTP-порт сервиса.
BEARER_TOKEN	пусто	Bearer-токен скачивания. Для Callbox задайте значение LIVEKIT_API_KEY.
MAX_AGE	60m	Срок хранения временного файла до удаления.
CLEANUP_INTERVAL	10m	Интервал фоновой очистки.

Транскрибация

Переменная	По умолчанию	Описание
WHISPER_URL	пусто	Базовый URL сервиса распознавания, например http://whisper:8000.
TRANSCRIPTION_ENABLED	по наличию WHISPER_URL	Явно включает или выключает функцию. Для true требуется непустой WHISPER_URL.
WHISPER_SPEED_FACTOR	1.0	Начальная оценка отношения времени обработки к длительности записи.
WHISPER_MAX_TIMEOUT	2h	Максимальная длительность одного HTTP-запроса.
TRANSCRIPTION_WORKER_CONCURRENCY	1	Число параллельных задач worker в экземпляре Callbox.
TRANSCRIPTION_MAX_ATTEMPTS	3	Максимальное число попыток обработки задачи.
TRANSCRIPTION_HISTORY_RETENTION_DAYS	180	Срок хранения технической истории в днях; 0 отключает очистку.

Callbox ожидает GET /health и POST /v1/transcribe. Недоступность сервиса транскрибации не делает Callbox unready.

Локальный сервис можно запускать на CPU или NVIDIA CUDA. Модели храните в постоянном volume, подключённом к /data/models.

Переменная сервиса Whisper	По умолчанию	Описание
TRANSCRIPTION_ENGINE	whisperx	Движок распознавания: whisperx или gigaam.
DEVICE	cpu	Устройство: cpu или cuda.
COMPUTE_TYPE	int8	Тип вычислений; для CUDA обычно используется float16.
MODEL_SIZE	large-v3	Модель WhisperX.
WHISPER_LANGUAGE	пусто	Фиксированный язык или автоматическое определение при пустом значении.
HF_TOKEN	пусто	Токен Hugging Face для загрузки моделей pyannote и разделения по спикерам.
HF_HOME	/data/models	Каталог cache моделей.

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

AI-сводки записей

Переменная	По умолчанию	Описание
AI_SUMMARY_API_URL	пусто	URL OpenAI-совместимого API, например http://ollama:11434/v1.
AI_SUMMARY_API_KEY	пусто	API-ключ; заголовок Authorization не отправляется при пустом значении.
AI_SUMMARY_MODEL	пусто	Имя модели.
AI_SUMMARY_ENABLED	по наличию URL и модели	Явно включает или выключает функцию.
AI_SUMMARY_TIMEOUT	5m	Timeout одного запроса.
AI_SUMMARY_MAX_ATTEMPTS	3	Максимальное число попыток.

Для сводки сначала должна быть готова транскрипция записи.

Push-уведомления

Переменная	По умолчанию	Описание
VAPID_PUBLIC_KEY	пусто	Публичный VAPID-ключ Web Push.
VAPID_PRIVATE_KEY	пусто	Приватный VAPID-ключ Web Push.
PUSH_PROXY_URL	облачный proxy Callbox	URL proxy для APNs/FCM. Для собственного proxy задайте его внутренний или внешний URL.
PUSH_PROXY_TOKEN	встроенное значение образа	Токен proxy. Рекомендуется явно задавать секрет из вашей установки.

Пару VAPID-ключей можно создать встроенной утилитой Callbox или совместимым генератором Web Push. Приватный ключ не публикуйте.

Feedback, аналитика и ссылки на клиенты

Переменная	По умолчанию	Описание
FEEDBACK_ENABLED	true	Включает отправку обратной связи. Можно менять во время работы.
FEEDBACK_URL	https://next-box.ru	Базовый URL сервиса обратной связи.
UMAMI_SCRIPT_URL	пусто	URL скрипта Umami.
UMAMI_WEBSITE_ID	пусто	Website ID Umami.
OPENREPLAY_PROJECT_KEY	пусто	Project key OpenReplay.
OPENREPLAY_INGEST_URL	пусто	URL ingest OpenReplay.
MACOS_UPDATE_FEED_URL	встроенный feed	Appcast для обновления macOS-клиента.
MACOS_DMG_DOWNLOAD_URL	пусто	Прямая ссылка на DMG.
WINDOWS_UPDATE_FEED_URL	встроенный feed	Appcast для Windows-клиента.
LINUX_UPDATE_FEED_URL	встроенный feed	Zsync feed Linux-клиента.
ANDROID_DOWNLOAD_URL	RuStore	Ссылка на Android-клиент.

HTTP timeouts

Переменная	По умолчанию	Описание
HTTP_READ_HEADER_TIMEOUT	5s	Чтение заголовков запроса.
HTTP_READ_TIMEOUT	15m	Чтение запроса, включая большие загрузки.
HTTP_WRITE_TIMEOUT	15m	Запись ответа.
HTTP_IDLE_TIMEOUT	2m	Keep-alive timeout.
HEALTH_CHECK_TIMEOUT	3s	Общий timeout зависимостей health-check.

Сетевые порты

Для конфигурации из установщика используются следующие порты:

Порт	Протокол	Назначение
8081	TCP	Callbox API; можно оставить только во внутренней сети, если доступ идёт через reverse proxy.
7880	TCP	LiveKit HTTP/WebSocket signaling.
7881	TCP	WebRTC TCP fallback.
5349	TCP	TURN over TLS, если включён встроенный TURN.
3478	UDP	TURN UDP; порт можно изменить в установщике.
50100-50200	UDP	RTP/RTCP медиапотоки LiveKit.

egress-files:9100, PostgreSQL, Redis и RabbitMQ наружу не публикуются.