Тема
Переменные окружения
Kvalli настраивается переменными окружения. Где их задавать:
- install.sh —
/opt/kvalli/.env, применить:docker compose up -d appв/opt/kvalli; - Docker Compose —
.envрядом сdocker-compose.yml, он целиком передаётся в контейнер; - Kubernetes — нечувствительные под
envвvalues.yaml, чувствительные подsecretEnvили в свой Secret.
Подключения к моделям, Git-провайдерам, трекерам и Confluence задаются не здесь, а в интерфейсе: Настройки → Подключения.
Как читаются булевы значения
Написание важно, и правила у переменных разные:
- большинство включается значением
trueили1, любое другое непустое значение выключает; KVALLI_AUTO_MIGRATEиKVALLI_PASSWORD_LOGINвыключает только точноеfalse, всё остальное оставляет включённым;COOKIE_SECUREвключает только точноеtrue, а любое другое непустое значение — даже1— выключает.
Пустое значение всегда означает «не задано», то есть значение по умолчанию.
Обязательные
| Переменная | Что задаёт |
|---|---|
DATABASE_URL | Строка подключения к PostgreSQL. Без неё сервер в production не запускается. В Docker Compose и Helm собирается сама |
POSTGRES_PASSWORD | Пароль встроенного PostgreSQL (Docker Compose) |
ENCRYPTION_KEY | Ключ шифрования учётных данных, 32+ случайных байта: openssl rand -hex 32. Храните вместе с резервными копиями |
JWT_SECRET | Ключ подписи сеансов, 32+ случайных байта |
KVALLI_IMAGE | Образ для Docker Compose, например ghcr.io/kvalli-ai/kvalli:2.3.0 |
Первый запуск
| Переменная | Что задаёт |
|---|---|
KVALLI_ADMIN_EMAIL, KVALLI_ADMIN_PASSWORD | Администратор, который создаётся, пока в установке нет ни одного пользователя. Удалите пароль после первого входа |
Лицензия и телеметрия
| Переменная | Что задаёт |
|---|---|
KVALLI_LICENSE | Лицензионный ключ. См. Лицензия |
KVALLI_LICENSE_FILE | Путь к файлу с ключом вместо значения |
KVALLI_TELEMETRY | true — отчёт раз в час; false — ничего, включая анонимный пинг. См. Телеметрия |
KVALLI_TELEMETRY_ENDPOINT | Свой коллектор вместо нашего |
Вход
| Переменная | Что задаёт |
|---|---|
KVALLI_PASSWORD_LOGIN | false — только единый вход (работает, только если SSO лицензирован) |
KVALLI_OIDC_* | Единый вход. См. Единый вход |
APP_BASIC_AUTH_USER, APP_BASIC_AUTH_PASSWORD | Общий пароль HTTP Basic перед всем рабочим пространством. CI с API-ключом и вошедшие пользователи проходят без него |
Сеть и прокси
| Переменная | Что задаёт | По умолчанию |
|---|---|---|
KVALLI_PUBLIC_URL | Публичный адрес, который открывают пользователи. Нужен для единого входа | — |
ALLOWED_ORIGINS | Origin через запятую, которым разрешено обращаться к API с cookie сеанса. Включите туда публичный адрес | — |
TRUST_PROXY_HOPS | Сколько прокси перед Kvalli учитывать при определении IP клиента. 1 за одним прокси | 0 |
COOKIE_SECURE | Пусто — по NODE_ENV (в production cookie Secure); true — всегда Secure; другое — нет. Выключайте, только если пользователи ходят по обычному HTTP | — |
KVALLI_HSTS | Заголовок Strict-Transport-Security. Не задано — отправляется, если KVALLI_PUBLIC_URL начинается с https:// | — |
KVALLI_PORT | Порт хоста, который публикует docker compose | 3000 |
POSTGRES_PORT | Порт хоста встроенного PostgreSQL, только на loopback | 5432 |
LOG_LEVEL | trace, debug, info, warn, error | info |
База данных
| Переменная | Что задаёт | По умолчанию |
|---|---|---|
KVALLI_AUTO_MIGRATE | Применять миграции при запуске. false — применять самим | true |
KVALLI_DB_STATEMENT_TIMEOUT_MS | Сколько миллисекунд может выполняться один запрос к базе. 0 — без ограничения. На миграции не действует | 300000 |
Модели
| Переменная | Что задаёт | По умолчанию |
|---|---|---|
GEMINI_API_KEY | Ключ Gemini по умолчанию. Остальные провайдеры — в настройках | — |
KVALLI_LLM_DAILY_TOKENS | Токенов на проект в сутки по UTC. Токен из кэша промпта провайдера считается как десятая часть | без лимита |
KVALLI_LLM_RETRIES | Сколько раз повторять вызов модели после кратковременного сбоя (429, 5xx, обрыв). Не больше 5 | 2 |
KVALLI_LLM_RETRY_DELAY_MS | Первая пауза перед повтором, дальше удваивается | 1000 |
KVALLI_LLM_CALL_LOG_DAYS | Сколько дней хранить промпты и ответы моделей для разбора, почему агент поступил так. Промпты содержат то, что читали агенты: источники, код, навыки. 0 — не хранить | 7 |
Браузерный воркер
| Переменная | Что задаёт | По умолчанию |
|---|---|---|
KVALLI_BROWSER_URL | Адрес воркера, например http://browser:3300. Пусто — Агент 2 пишет тесты по кейсу и репозиторию, без браузера | — |
KVALLI_BROWSER_TOKEN | Общий токен приложения и воркера, от 32 символов | — |
KVALLI_BROWSER_SESSIONS | Сколько браузеров воркер держит открытыми одновременно. С пулом стендов — хотя бы по одному на копию | 2 |
Лимиты и хранение
Все значения — положительные целые. Не задано, пусто, 0 или не число — значение по умолчанию.
| Переменная | Что ограничивает | По умолчанию |
|---|---|---|
KVALLI_MAX_PROJECTS | Проектов на установку | 200 |
KVALLI_MAX_API_KEYS_PER_PROJECT | API-ключей на проект | 50 |
KVALLI_MAX_SHARES_PER_PROJECT | Действующих ссылок на отчёты на проект | 200 |
KVALLI_REVISIONS_PER_CASE | Хранимых версий одного кейса | 200 |
KVALLI_MAX_IMPORT_CASES | Кейсов за один импорт. Больше — файл просят разбить; импорт из Allure TestOps пишет частями этого размера | 4000 |
KVALLI_MAX_WORKFLOWS_PER_PROJECT | Воркфлоу на проект | 50 |
KVALLI_MAX_WORKFLOW_TEMPLATES | Шаблонов воркфлоу организации | 100 |
KVALLI_MAX_ATTACHMENTS_PER_CASE | Вложений на кейс | 50 |
KVALLI_MAX_ATTACHMENTS_PER_RESULT | Вложений на результат прогона | 50 |
KVALLI_MAX_ATTACHMENT_MB_PER_PROJECT | Мегабайт вложений на проект, кейсы и прогоны вместе | 20480 |
KVALLI_TESTOPS_MAX_LIST_PAGES, KVALLI_TESTOPS_MAX_CASES | Импорт из Allure TestOps: страниц списка и кейсов | 2000, 100000 |
KVALLI_TESTOPS_MAX_LAUNCHES | Запусков, которые переносит один импорт истории из Allure TestOps; сверх — берутся самые новые | 3000 |
MAX_ACTIVE_AGENT_JOBS | Заданий агентов одновременно на всю установку, сверх 3 на проект | 20 |
KVALLI_MAX_STREAMS_PER_VIEWER | Потоков прогресса, открытых одним пользователем | 12 |
KVALLI_MAX_REPORT_RESULTS, KVALLI_MAX_LISTED_RESULTS | Результатов, которые читает отчёт или дашборд, и список прогонов. Сверх — самые старые прогоны не входят, и отчёт об этом говорит. Замер: дашборд по 200 000 результатов — около 2,5 с; при 250 запусках CI в день это примерно неделя | 200000, 50000 |
KVALLI_RUN_RETENTION_DAYS | Сколько дней хранить прогоны, загруженные из CI. Потом ежедневная чистка кладёт их в корзину. Ручные прогоны и прогоны майлстоуна или тест-плана не трогаются. Пусто или 0 — хранить всё | 0 |
KVALLI_CHAT_RETENTION_DAYS | Сколько дней хранить чат без новых сообщений. Потом он удаляется безвозвратно | 180 |
Удалённые кейсы и прогоны лежат в корзине 30 дней.
Сроки хранения, которые не настраиваются:
- запуски воркфлоу — 90 дней после завершения;
- обработанные события воркфлоу — 7 дней;
- записи об истёкших ссылках на отчёты — 90 дней (сама страница отчёта удаляется сразу, как ссылка истекла);
- завершённые задания агентов — 7 дней.
Резервные копии install.sh
Эти переменные пишет install.sh из --backup-keep и --backup-copy-to, и читает его команда backup, а не сервер.
| Переменная | Что задаёт | По умолчанию |
|---|---|---|
KVALLI_BACKUP_KEEP | Сколько копий хранить | 14 |
KVALLI_BACKUP_COPY_TO | Каталог на другом диске или NAS для копий | — |
Хранилище
Обычно менять не нужно: образ и чарт задают их сами.
| Переменная | Что задаёт |
|---|---|
KVALLI_DATA_DIR | Каталог данных: вложения, доказательства прогонов, кэш репозиториев |
KVALLI_QA_AGENTS_DIR | Каталог старых файлов агентов |
KVALLI_DEMO_MODE | Демо-режим с примерами данных. В production выключен, на установке с настоящими данными не включайте |