# Настройки окружения 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 обычно подходит: ```env CRANK_PUBLISH_BIND=127.0.0.1 ``` Если reverse proxy работает на другом host: ```env 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: ```env 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 работает без внешнего кэша: ```env CRANK_CACHE_BACKEND=memory ``` Для Valkey или Redis: ```env 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, полным телом или результатом очищаются до сериализации. Пример: ```env CRANK_ENVIRONMENT=development CRANK_LOG_LEVEL=info ``` Внешний сборщик журналов не обязателен. Его отсутствие не влияет на `/health` и `/ready`. ## Критические ошибки - `CRANK_SENTRY_DSN` — DSN внешнего Sentry-совместимого приёмника. Пустое или отсутствующее значение отключает канал. Неверное непустое значение останавливает запуск безопасной ошибкой без вывода DSN. Оба сервиса используют одно значение, но передают собственные `service`, `release` и `environment`. ```env CRANK_SENTRY_DSN= ``` Community не разворачивает GlitchTip или другой приёмник. Подробный состав события и правила очистки приведены в [документе о наблюдаемости](observability.md). ## 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-ов. Для отключения поверхности: ```env CRANK_METRICS_ENABLED=false ``` Подробная модель доступа, список показателей и пример настройки сборщика приведены в [документе о наблюдаемости](observability.md). ## Распределённые трассы 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. Некорректная явно заданная конфигурация останавливает запуск безопасной типизированной ошибкой, не содержащей значений окружения. ```env 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.