Установка на один сервер: install.sh

install.sh ставит Kvalli на чистый Linux-сервер вместе с PostgreSQL, HTTPS (Caddy с сертификатом Let's Encrypt) и первым администратором. Под капотом это обычная установка через docker compose, только все шаги сделаны за вас.

Требования к серверу — в разделе Способы и требования.

Скачать скрипт

curl -fsSLO https://kvalli.ai/install.sh
chmod +x install.sh

Установить

Starter, бесплатно, без токена:

sudo ./install.sh install \
  --domain kvalli.acme.com --email qa-lead@acme.com \
  --image ghcr.io/kvalli-ai/kvalli-starter:2.3.0

Pro или Enterprise — полный образ, токен на чтение и ключ, которые мы выдали:

sudo ./install.sh install \
  --domain kvalli.acme.com --email qa-lead@acme.com \
  --image ghcr.io/kvalli-ai/kvalli:2.3.0 \
  --registry-user <github-user> --registry-token <токен на чтение> \
  --license-file ./acme.license

Скрипт:

1. ставит Docker, если его нет;
2. создаёт /opt/kvalli с docker-compose.yml, Caddyfile и .env (читать его может только root);
3. генерирует пароль базы, ENCRYPTION_KEY и JWT_SECRET;
4. запускает PostgreSQL, Kvalli и Caddy и ждёт, пока Kvalli ответит;
5. печатает пароль администратора — один раз.

После этого пароль удаляется из .env. Войдите и смените его.

Параметры

Параметр	Что делает
--domain, --email	Имя сервера и адрес для Let's Encrypt. Обязательны при каждом запуске install
--image	Образ и версия
--registry-user, --registry-token	Доступ к закрытому образу полной редакции
--image-archive	Образ из файла, для сервера без доступа к реестру (см. ниже)
--license-file	Лицензионный ключ. Без него работает Starter
--tls internal	Без публичного имени: сертификат от собственного центра сертификации Caddy. Браузеры попросят ему доверять
--telemetry on	Раз в час отправлять отчёт телеметрии. По умолчанию выключено. См. Телеметрия
--backup daily, --backup-keep, --backup-copy-to	Ночные резервные копии. См. Резервные копии
--auto-update patch	Ставить патч-выпуски автоматически. См. Обновления
--dir	Ставить не в /opt/kvalli
--skip-docker-install	Не ставить Docker: без него установка остановится с ошибкой

Все параметры проверяются до того, как что-либо записано, и порты 80 и 443 должны быть свободны. Неверный --license-file, --telemetry, --backup-copy-to или занятый порт останавливают установку, ничего не изменив.

Повторный запуск

Повторный install применяет то, что изменилось: домен, лицензию, телеметрию, образ. Секреты, данные и администратор сохраняются. Выбор TLS тоже сохраняется: установка с --tls internal остаётся на нём, пока --tls auto не переключит её на Let's Encrypt.

Если первая установка остановилась после записи .env (например, не запустился контейнер), запустите ту же команду ещё раз: администратор будет создан тогда, и пароль напечатается один раз. Файл /opt/kvalli/.admin-created отмечает, что администратор уже создан.

Тома прежней установки

Если в том же каталоге остались Docker-тома прежней установки, новая предупредит об этом. Их база помнит старый пароль, и новая установка не сможет к ней подключиться. Верните старый .env или удалите тома (docker volume rm …), чтобы начать с нуля.

Без доступа к реестру

Там, где можно скачивать образы:

docker pull ghcr.io/kvalli-ai/kvalli:2.3.0
docker save ghcr.io/kvalli-ai/kvalli:2.3.0 -o kvalli-2.3.0.tar

Перенесите файл на сервер и передайте его в --image-archive вместо --registry-*.

Настройки

Всё остальное задаётся в /opt/kvalli/.env, по одной строке KEY=value: единый вход, ключи моделей, бюджеты токенов и лимиты, HSTS. Полный список — в разделе Переменные окружения.

Чтобы применить изменение, выполните в /opt/kvalli:

docker compose up -d app

или запустите install ещё раз. Не правьте сгенерированный docker-compose.yml — install его перезаписывает.

Несколько значений задаёт сама эта схема установки, и они важнее .env: NODE_ENV, PORT, DATABASE_URL, KVALLI_AUTH_MODE=enforced, ALLOWED_ORIGINS (публичный адрес), TRUST_PROXY_HOPS=1 (Caddy), каталоги данных и агентов, LOG_LEVEL.

Браузерный воркер

Браузер, в котором Агент 2 проходит стенд (модуль browser), install.sh пока не ставит. В Docker Compose из исходников это профиль browser:

docker compose --profile browser up -d

и в .env — KVALLI_BROWSER_URL=http://browser:3300 и один и тот же KVALLI_BROWSER_TOKEN для обоих контейнеров. В Kubernetes — browser.enabled в чарте, см. Kubernetes.

Команды

Скрипт копирует себя в /opt/kvalli/install.sh — дальше пользуйтесь этой копией.

Команда	Что делает
status	Контейнеры и /api/health
backup	Резервная копия. См. Резервные копии
restore <каталог>	Восстановление из копии
upgrade --image …	Обновление с резервной копией и автоматическим откатом. См. Обновления
rollback	Отменить последнее обновление
auto-update	То, что запускает cron при включённом автообновлении
reset-admin --email …	Новый пароль администратора (см. ниже)

Забыли пароль администратора

sudo /opt/kvalli/install.sh reset-admin --email admin@acme.com

Аккаунт получает новый пароль (он печатается один раз) и роль администратора, а если аккаунта нет — создаётся. Все его сеансы завершаются, сброс записывается в журнал аудита. Команду можно запускать сколько угодно раз.

KVALLI_ADMIN_EMAIL и KVALLI_ADMIN_PASSWORD для этого не подходят: они действуют, только пока в установке нет ни одного администратора. Если есть другой администратор, пароль можно сбросить и в Настройки → Пользователи.