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 обычно подходит:

```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_INVOCATION_LOG_RETENTION_DAYS` задаёт срок хранения подробной истории
вызовов в днях. Допустимый диапазон: от `1` до `36500`, значение по умолчанию:
`30`. Значение вне диапазона останавливает запуск до создания фоновой задачи
очистки.

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

- `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.