crank/docs/runtime-config.md

Настройки окружения

Crank настраивается через переменные окружения. Один и тот же набор переменных используется при запуске из исходников и при запуске готовых Docker-образов.

PostgreSQL

Обязательные параметры:

• POSTGRES_HOST
• POSTGRES_PORT
• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD

Параметры пула соединений:

• POSTGRES_MAX_CONNECTIONS, по умолчанию 20;
• POSTGRES_MIN_CONNECTIONS, по умолчанию 2;
• POSTGRES_ACQUIRE_TIMEOUT_MS, по умолчанию 5000;
• POSTGRES_IDLE_TIMEOUT_MS, по умолчанию 600000;
• POSTGRES_MAX_LIFETIME_MS, по умолчанию 1800000.

Если используется PgBouncer, укажите его адрес в POSTGRES_HOST и порт в POSTGRES_PORT.

HTTP-сервисы

• CRANK_ADMIN_BIND - адрес admin-api, например 0.0.0.0:3001.
• CRANK_MCP_BIND - адрес mcp-server, например 0.0.0.0:3002.
• CRANK_PUBLISH_BIND - адрес публикации портов в Docker Compose.
• CRANK_BASE_URL - публичный URL веб-интерфейса.

Для сервера за reverse proxy обычно подходит:

CRANK_PUBLISH_BIND=127.0.0.1

Если reverse proxy работает на другом host:

CRANK_PUBLISH_BIND=0.0.0.0

Авторизация администратора

• CRANK_SESSION_SECRET - ключ подписи браузерных сессий.
• CRANK_PASSWORD_PEPPER - дополнительный секрет для хэширования паролей.
• CRANK_SESSION_TTL_HOURS - срок жизни сессии в часах.
• CRANK_BOOTSTRAP_ADMIN_EMAIL - email первого пользователя.
• CRANK_BOOTSTRAP_ADMIN_PASSWORD - пароль первого пользователя.
• CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME - отображаемое имя первого пользователя.

Первый пользователь создается или обновляется при старте admin-api.

Шифрование секретов

• CRANK_MASTER_KEY - ключ шифрования сохраненных секретов.

Этот ключ нужен admin-api и mcp-server. Если изменить ключ без миграции данных, ранее сохраненные секреты нельзя будет расшифровать.

Демо-данные

• CRANK_DEMO_SEED=true создает пример Frankfurter при старте.
• CRANK_DEMO_SEED=false отключает demo seed.

Demo seed идемпотентный: повторный старт не создает дубликаты. В стандартном примере создаются upstream Frankfurter, операция frankfurter_latest_rate, агент currency-rates и пример API-ключа.

MCP

• CRANK_MCP_REFRESH_MS - как часто mcp-server обновляет опубликованный каталог инструментов.
• CRANK_MCP_RATE_LIMIT_RPS - лимит запросов в секунду.
• CRANK_MCP_RATE_LIMIT_BURST - допустимый короткий всплеск запросов.

Admin API

• CRANK_ADMIN_RATE_LIMIT_RPS - лимит запросов в секунду.
• CRANK_ADMIN_RATE_LIMIT_BURST - допустимый короткий всплеск запросов.

Runtime limits

• CRANK_RUNTIME_MAX_CONCURRENT_UNARY
• CRANK_RUNTIME_MAX_CONCURRENT_WINDOW
• CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS
• CRANK_RUNTIME_MAX_CONCURRENT_JOBS

Эти настройки ограничивают параллельное выполнение операций и служебных задач.

Исходящие HTTP-запросы

По умолчанию Crank обращается только к публичным IP-адресам. Локальные, частные, служебные и link-local сети блокируются после разрешения DNS-имени. Автоматические HTTP-перенаправления и системный прокси отключены.

• CRANK_OUTBOUND_ALLOWED_HOSTS - исключения для разрешённых внутренних узлов через запятую. Публичные узлы разрешены независимо от этого списка. Для внутреннего API укажите его имя или IP явно. Поддерживаются маски вида *.example.internal.
• CRANK_OUTBOUND_DENIED_HOSTS - список узлов, запрещённых независимо от списка разрешённых.
• CRANK_OUTBOUND_MAX_RESPONSE_BYTES - максимальный размер ответа внешнего API; по умолчанию 4194304 байт.

Пример доступа только к двум внутренним API:

CRANK_OUTBOUND_ALLOWED_HOSTS=crm.example.internal,192.168.1.50
CRANK_OUTBOUND_DENIED_HOSTS=metadata.example.internal
CRANK_OUTBOUND_MAX_RESPONSE_BYTES=4194304

Одинаковые значения должны передаваться в admin-api и mcp-server: первый проверяет операции при сохранении, второй применяет политику при каждом соединении. Максимальный execution_config.timeout_ms операции равен 300000 мс.

Кэш

По умолчанию Crank работает без внешнего кэша:

CRANK_CACHE_BACKEND=memory

Для Valkey или Redis:

CRANK_CACHE_BACKEND=valkey
CRANK_CACHE_URL=redis://valkey:6379/0
CRANK_CACHE_DEFAULT_TTL_MS=60000

Внешний кэш используется для служебного краткоживущего состояния: rate limiting, replay guard и опубликованные каталоги MCP-инструментов.

Логи

• CRANK_ENVIRONMENT - короткая метка окружения. При локальном запуске по умолчанию используется development, Community deployment явно передаёт production.
• CRANK_LOG_LEVEL - фильтр tracing, например info, debug, warn или admin_api=debug,tower_http=info.

admin-api и mcp-server пишут в stdout по одному JSON-объекту на строку. Поля с паролями, токенами, ключами, cookie, authorization, query, полным телом или результатом очищаются до сериализации.

Пример:

CRANK_ENVIRONMENT=development
CRANK_LOG_LEVEL=info

Внешний сборщик журналов не обязателен. Его отсутствие не влияет на /health и /ready.

CRANK_INVOCATION_LOG_RETENTION_DAYS задаёт срок хранения подробной истории вызовов в днях. Допустимый диапазон: от 1 до 36500, значение по умолчанию: 30. Значение вне диапазона останавливает запуск до создания фоновой задачи очистки.

Критические ошибки

• CRANK_SENTRY_DSN — DSN внешнего Sentry-совместимого приёмника.

Пустое или отсутствующее значение отключает канал. Неверное непустое значение останавливает запуск безопасной ошибкой без вывода DSN. Оба сервиса используют одно значение, но передают собственные service, release и environment.

CRANK_SENTRY_DSN=

Community не разворачивает GlitchTip или другой приёмник. Подробный состав события и правила очистки приведены в документе о наблюдаемости.

Prometheus

• CRANK_METRICS_ENABLED — включает отдельные listener-ы, по умолчанию true;
• CRANK_ADMIN_METRICS_BIND — адрес показателей admin-api, по умолчанию 127.0.0.1:9464;
• CRANK_MCP_METRICS_BIND — адрес показателей mcp-server, по умолчанию 127.0.0.1:9465;
• CRANK_METRICS_BEARER_TOKEN — отдельный токен, обязательный для любого non-loopback bind.

Значения проверяются до запуска рабочих listener-ов. Для отключения поверхности:

CRANK_METRICS_ENABLED=false

Подробная модель доступа, список показателей и пример настройки сборщика приведены в документе о наблюдаемости.

Распределённые трассы OTLP

Crank экспортирует через OTLP только трассы. Метрики остаются в Prometheus, а эксплуатационные журналы — в stdout. Если оба endpoint пусты, tracer provider и фоновый экспортёр не создаются.

• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT — полный HTTP endpoint трасс; имеет приоритет;
• OTEL_EXPORTER_OTLP_ENDPOINT — общий endpoint, к которому Crank добавляет /v1/traces;
• OTEL_EXPORTER_OTLP_TRACES_PROTOCOL и резервный OTEL_EXPORTER_OTLP_PROTOCOL — только http/protobuf;
• OTEL_EXPORTER_OTLP_TRACES_TIMEOUT и резервный OTEL_EXPORTER_OTLP_TIMEOUT — предел HTTP-запроса экспорта в миллисекундах;
• OTEL_EXPORTER_OTLP_TRACES_HEADERS — заголовки только для трасс;
• OTEL_EXPORTER_OTLP_HEADERS — резервные общие заголовки;
• OTEL_BSP_MAX_QUEUE_SIZE — конечная очередь spans, по умолчанию 2048;
• OTEL_BSP_MAX_EXPORT_BATCH_SIZE — пакет, по умолчанию 512, не больше очереди;
• OTEL_BSP_SCHEDULE_DELAY — период отправки в миллисекундах, по умолчанию 5000;
• OTEL_BSP_EXPORT_TIMEOUT — совместимый предел пакетного экспортёра в миллисекундах, по умолчанию 30000.

Фактический HTTP-запрос экспорта ограничивается более строгим из OTEL_EXPORTER_OTLP_TRACES_TIMEOUT/OTEL_EXPORTER_OTLP_TIMEOUT и OTEL_BSP_EXPORT_TIMEOUT. Это сохраняет оба верхних предела при работе стабильного потокового BatchSpanProcessor.

Допустимы только HTTP/HTTPS URL без учётных данных, query и fragment. Некорректная явно заданная конфигурация останавливает запуск безопасной типизированной ошибкой, не содержащей значений окружения.

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.example.com/v1/traces
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TIMEOUT=10000

Заголовки обычно содержат токен приёмника. В production их следует хранить в OpenBao как OTEL_EXPORTER_OTLP_TRACES_HEADERS; CD передаёт значение в runtime .env, но не выводит его в журнал. Не записывайте токен в репозиторий или Compose.