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_LOG_LEVEL - уровень логирования, например info, debug, warn.

Поля с паролями, токенами, ключами и заголовками авторизации удаляются из снимков запросов и ответов. Один снимок ограничен 16 КиБ; более крупное значение хранится в усечённом виде с исходным размером.

Пример:

CRANK_LOG_LEVEL=info