Справочник CLI

versola — консольная утилита, которая разворачивает и запускает выпущенную версию Versola через Docker на одной машине. Эта страница описывает каждую команду и флаг versola-cli 0.3.1; пошаговый деплой на сервер — в разделе Деплой на VPS.

CLI намеренно тонкий. Он проверяет машину, работает с Docker и запускает версионированный образ ghcr.io/versolauth/versola-tools:<version>, который генерирует все, что зависит от устройства конкретного релиза Versola: конфигурацию, Compose-файлы, админ-консоль, миграции. Поэтому у versola-cli и у Versola разные номера версий: версия CLI — то, что печатает versola version, а версия Versola — <version>, которую вы передаете в configure/bootstrap.

Установка и обновление

macOS и Linux:

curl -fsSL https://raw.githubusercontent.com/versolauth/versola-cli/main/install.sh | sh

Скрипт ставит CLI в ~/.local/bin/versola без sudo. В Windows (PowerShell) скрипт ставит CLI в %LOCALAPPDATA%\versola:

iwr https://raw.githubusercontent.com/versolauth/versola-cli/main/install.ps1 -useb | iex

Чтобы позже перейти на новую версию CLI, выполните versola upgrade (см. ниже).

У тегов релизов CLI нет префикса v (у релизов до v0.2.5 он был). Каждый релиз публикует эти файлы и ничего больше:

Сборки для Linux ARM64 нет: на этой платформе установщик завершится ошибкой, потому что файла не существует.

Проверка контрольной суммы. Релизный workflow пишет checksums.txt (формат sha256sum) рядом с бинарниками. Установщики и versola upgrade скачивают его и сравнивают SHA-256 бинарника; при несовпадении установка прерывается. Если checksums.txt отсутствует, недоступен или не содержит записи для нужного файла, они печатают предупреждение и продолжают без проверки. Чтобы проверить вручную, скачайте файл и checksums.txt со страницы релиза и выполните sha256sum -c --ignore-missing checksums.txt.

Чтобы обновить установленный CLI, выполните versola upgrade. Он заменяет бинарник на месте и не трогает dev-сборки.

Таргеты

Таргет — это место, где работает деплой. Он идет первым аргументом configure и bootstrap.

На машине одновременно активен только один деплой: повторный configure заменяет запись о предыдущем. Команды на vps, которые что-то меняют, спрашивают Continue? [y/N] на стандартном вводе. У configure, migrate, up и replica флага --yes нет; пустой ответ или конец ввода прерывает команду с ненулевым кодом выхода. rollout, uninstall и upgrade принимают -y.

Каталог состояния

Все, что хранит CLI, лежит в ~/.versola:

versola uninstall удаляет ~/.versola/active, но не трогает ~/.versola/openbao.

Реверс-прокси на vps

CLI генерирует конфигурацию nginx для реверс-прокси Versola. На vps важны три детали.

• Поколения конфигурации. Прокси не монтирует файлы из бандла. Каждое изменение (configure, добавление или удаление реплики, шаг rollout) собирает полную новую конфигурацию в ~/.versola/active/proxy-vps/gen-<n>/, nginx проверяет ее в одноразовом контейнере, затем переключается ссылка current и nginx перезагружается. Если перезагрузку отклонили, ссылка возвращается. Контейнер прокси для нового бандла не пересоздается, поэтому запросы не теряются.
• Внутренние listener’ы идут через прокси. На vps прокси слушает 127.0.0.1:8082 (listener Account Settings у auth, APORT), 127.0.0.1:8083 (mutual-TLS listener у auth, MPORT) и 127.0.0.1:8090 (фронт central) и балансирует их между всеми репликами. Собственные listener’ы auth сдвинуты на 1000 портов вверх (9082 и 9083, и еще на 100 на каждый слот), listener’ы central — на 20000 вверх (28090 и 28091). edge сохраняет свои адреса. auth, edge и админ-консоль по-прежнему обращаются к central по 127.0.0.1:8090 — теперь это адрес прокси, поэтому rollout может заменить central без простоя. Mutual-TLS-соединение проходит как TCP, поэтому TLS по-прежнему завершает сам auth своим сертификатом.
• Клиентский сертификат от вызывающего не принимается. Прокси ставит заголовку ssl-client-cert пустое значение в каждом пересылаемом запросе, так что вызывающий не может подставить клиентский сертификат этим заголовком. Сертификат принимается только там, где его проверили: на собственном mutual-TLS listener’е auth или через TLS-терминатор, который вы сами настроили выставлять этот заголовок.

Проверка

versola doctor

versola doctor [--target local|vps]

Проверяет, есть ли на машине все, что нужно Versola. Ничего не устанавливает. Если Docker отсутствует, предлагает открыть страницу установки в браузере и делает это только после вашего подтверждения.

Проверки печатаются строками [ok] или [!!]:

Код выхода ненулевой, если хоть одна проверка не прошла. Для сервера всегда указывайте --target vps: значение по умолчанию применяет не то правило для памяти.

Деплой

Три шага деплоя можно выполнить вместе (bootstrap) или по одному. Запускайте их отдельно, когда миграции должны быть самостоятельным шагом, который можно проверить.

versola bootstrap

versola bootstrap <local|vps> <version> [flags]

Выполняет configure, migrate и up по порядку; на vps подтверждение запрашивается один раз в начале. <version> — тег релиза Versola без префикса v.

--proxy, --acme-staging, --postgres-db и --postgres-ca для local отклоняются.

На vps первый запуск с пустым OpenBao генерирует пароль роли Postgres. Тогда bootstrap останавливается перед migrate с ненулевым кодом выхода, потому что у роли еще нет этого пароля: выполните команду, которую напечатал configure (она передает psql SQL-файл ~/.versola/openbao/vps-postgres-role.sql), затем versola migrate и versola up.

versola bootstrap vps 0.7.2 --auth-url https://id.example.com --postgres-host 127.0.0.1:5432

versola configure

versola configure <local|vps> <version> [flags]

Готовит деплой, не запуская его. Проверяет машину, тянет versola-tools:<version>, генерирует бандл (конфигурацию, Compose-файлы, админ-консоль, конфигурацию прокси), при необходимости запускает OpenBao и разрешает все секреты через него. Ни один сервис Versola не запускается, база не затрагивается, поэтому команду безопасно повторять. На vps она просит подтверждение, потому что заменяет запись этой машины об активном деплое.

Флаги те же, что у bootstrap, кроме --no-browser. configure не запоминает --auth-url, --postgres-host, --proxy, --acme-staging и --setup-openbao: передавайте одни и те же значения при каждом запуске, включая --proxy external, иначе режим прокси вернется к nginx. --postgres-db и --postgres-ca — исключение: они записываются (файл CA копируется рядом с state.json), следующий configure без флага сохраняет записанное значение, а повторно переданный флаг его переопределяет. Им нужен релиз versola-tools, который читает POSTGRES_DB и POSTGRES_CA_FILE (0.7.1 и новее); более старый их игнорирует.

Прежде чем записать любой секрет, configure вычисляет, что можно сделать с каждым (тот же план печатает secrets plan), и останавливается, ничего не записав, если какой-то секрет выглядит потерянным. См. Секреты.

versola configure vps 0.7.2 --auth-url https://id.example.com --postgres-host db.example.com:5432 --postgres-db versola --postgres-ca /etc/ssl/db-ca.pem

Генерация секретов, которые план отклоняет

--generate-missing NAME[,NAME...] подтверждает, что указанные секреты можно сгенерировать, даже если план остановился бы на них (секрет выглядит потерянным или установка неизвестного происхождения). Имена, которых нет в схеме релиза, считаются проблемой — скорее всего, это опечатки. Пара ключей генерируется, только если названы все члены ее группы: половина пары бесполезна. Генерация замены для секрета, к которому привязаны данные, делает эти данные нечитаемыми; используйте флаг, только чтобы восстановиться после потери значения, от которого точно ничего не зависит.

--allow-legacy-secrets относится к релизу, чей versola-tools не пишет secrets.schema.json. Без схемы CLI не отличает новый секрет от потерянного, поэтому на vps отказывается работать, если в OpenBao уже есть секреты или записан деплой. С флагом применяется старое правило: все, чего нет в OpenBao, генерируется, потеряно оно или нет. При пустом OpenBao и отсутствии записи терять нечего, и флаг не нужен. local не отклоняется никогда.

versola migrate

versola migrate [--dry-run] [--service auth|central|edge]

Выполняет миграции базы каждого сервиса для того, что configure подготовил последним, в одном одноразовом контейнере versola-tools. Ни один сервер не запускается. На vps сначала просит подтверждение и напоминает, что миграции нельзя откатить (down-миграций нет): перед ответом «да» сделайте бэкап базы.

Код выхода ненулевой, если миграция упала, так что скрипт или шаг пайплайна могут на него полагаться. С --dry-run релизы до 0.6.2 включительно сообщают о миграциях, которые просто еще не применены, как об ошибке проверки; это баг образа versola-tools тех релизов, в 0.7.0 он исправлен.

Сервисы сами не мигрируют: они стартуют с RUN_MIGRATIONS=false, проверяют схему и отказываются стартовать на устаревшей.

versola up

versola up [--no-browser]

Запускает стек, подготовленный configure, и ждет, пока он начнет обслуживать трафик: сначала central (auth и edge синхронизируют с ним конфигурацию), затем фронт прокси перед central (по этому адресу к нему обращаются auth и edge), затем auth и edge; в конце ждет, пока заработает весь прокси, и делает запрос через него к auth. Предполагается, что migrate уже выполнен. На vps просит подтверждение, потому что заменяет то, что сейчас обслуживает трафик. central стартует только после того, как step-ca и одноразовый контейнер mtls-init выпустят сертификаты, которые он читает (бандлы 0.7.1 и новее); это часть первого шага.

На vps печатает адрес и файл с ADMIN_BOOTSTRAP_PASSWORD. Этот пароль временный, действует 24 часа, а первый вход с ним требует задать новый.

Эксплуатация

versola status

versola status

Печатает версию и таргет деплоя, время последних миграций, реплики и вывод docker compose ps для проекта. Если ничего не развернуто, сообщает об этом и завершается с кодом 0.

Deployed version: 0.7.2 (target: vps)
Migrations applied: 2026-10-14 17:11:51
Replicas: auth x1 (slot 1), edge x1 (slot 1)

versola down

versola down [--volumes] [--force]

Останавливает контейнеры деплоя, включая OpenBao и прокси, сохраняя данные и образы. Том Postgres таргета local сохраняется, если не передать --volumes, — этот флаг удаляет и тома стека. На vps Postgres ваш, и команда его никогда не трогает. Пока rollout не завершен, down отказывается работать, если не передать --force.

versola uninstall

versola uninstall [-y|--yes]

Останавливает стек с --volumes, удаляет Docker-образы, которые скачал Versola, и очищает ~/.versola/active. Перечисляет, что удалит, и просит подтверждение, если не указан -y. На vps оставляет том OpenBao (versola-openbao-file-vps) и том сертификатов (versola-acme-vps) и печатает команды docker volume rm. Если Docker недоступен, сохраняет ~/.versola/active, чтобы деплой потом все же можно было остановить. Бинарник versola не удаляет, а печатает его путь.

versola replica

versola replica add <auth|edge> [count]
versola replica remove <auth|edge> [count]

Запускает больше одной копии auth или edge за реверс-прокси Versola, который распределяет запросы между ними. central не реплицируется. Реплики записываются, поэтому versola up их восстанавливает, а versola status их показывает. Флагов нет; count по умолчанию 1.

add запускает count новых реплик по одной в наименьших свободных слотах (всего не больше 9). Каждую дожидается готовности и только потом добавляет в upstream’ы прокси. Реплика, которая не поднялась, удаляется; запущенные до нее остаются. У каждого слота свое имя контейнера (versola-auth-2), порты сдвинуты на 100 на слот.

remove останавливает слоты с наибольшими номерами по одному: сначала прокси перестает слать реплике запросы и ждет завершения текущих, затем реплика останавливается. Последнюю реплику сервиса удалить нельзя.

Деплой должен быть запущен (versola up) из последнего configure. На vps обе команды просят подтверждение и обе отказываются работать, пока rollout не завершен.

На vps add сначала проверяет, что у Postgres хватает клиентских соединений для пулов новых реплик плюс 3 запасных, а если нет — отказывается и называет числа: увеличьте max_connections или добавляйте меньше реплик.

versola replica add edge 2

versola rollout

versola rollout <version> --assume-compatible [flags]
versola rollout --abort [flags]

Переводит работающий деплой vps на другую версию Versola, не останавливая его. Новая версия готовится рядом с работающей (versola-tools и план секретов), база мигрирует, central переходит через временную вторую реплику (central-2, за фронтом прокси на 127.0.0.1:8090), затем каждая реплика auth и edge заменяется по одной за временной дополнительной репликой, и в конце прокси переключается на новую конфигурацию. Если команду прервали (ошибка, Ctrl-C, обрыв SSH-сессии), та же команда продолжает: прогресс читается из state.json и контейнеров. Работает только для деплоя vps, сделанного этим CLI; local настраивается и запускается заново. Команда в контексте — в разделе Деплой на VPS.

Перед запуском временной реплики rollout проверяет свободную память (около 1,13 ГиБ) и что у Postgres хватает соединений для пула новой реплики плюс 3. Если чего-то не хватает, он отказывается, называет числа и ничего не меняет; --no-surge не требует ни того ни другого. Если деплой сделан до того, как прокси встал перед central, первый rollout переводит central на месте — как с --no-surge.

--abort снова делает активной прежнюю конфигурацию и возвращает то, что уже перешло на новую версию, начиная с временной реплики. Реплики, которые с прежней версии не уходили, не пересоздаются. Если прежней конфигурации уже нет, прежняя версия настраивается заново и пересоздаются все реплики; для релиза без схемы секретов нужен --allow-legacy-secrets. Миграции и секреты назад не возвращаются, подтверждение совместимости не спрашивается. Если rollout требовал --no-surge, передайте его и в abort. После завершенного rollout отменять нечего: выкатите прежнюю версию тем же способом.

Пока rollout или abort не завершен, configure, up и replica отказываются работать, как и down, если не передать --force. Перед запуском сделайте бэкап базы и скопируйте ~/.versola/active/state.json. Все проверки и короткие перерывы, которые у rollout остаются, перечислены в README versola-cli.

versola rollout 0.7.2 --dry-run

versola version

versola version

Печатает versola-cli <version> (<go version>, <os>/<arch>). versola --version печатает то же самое.

versola upgrade

versola upgrade [-y|--yes]

Проверяет последний релиз versola-cli на GitHub; если он отличается от версии этого бинарника, скачивает файл для вашей платформы, сверяет его с checksums.txt и заменяет запущенный исполняемый файл на месте. Просит подтверждение, если не указан -y. Версию Versola в деплое не меняет: для этого — configure с новой <version>. dev-сборки не трогает никогда.

Секреты

Эти команды управляют доступом машины к OpenBao и показывают, что сделал бы configure. Что такое секреты и как их ротировать — в разделе Секреты. После каждого перезапуска сервера OpenBao поднимается запечатанным: перед входом (configure, rollout, secrets plan, secrets test, secrets login) CLI распечатывает его ключом из ~/.versola/openbao/<target>-admin.json и отправляет этот ключ только на локальный адрес. С --setup-openbao сохраненного ключа нет, и CLI останавливается с командой bao operator unseal, которую нужно выполнить вручную.

versola secrets login

versola secrets login <target> <address> <role-id>

Сохраняет учетные данные AppRole для таргета в ~/.versola/openbao/<target>.json после проверки входом. Secret ID запрашивается отдельным скрытым вводом (или читается из стандартного ввода, если это не терминал), поэтому не попадает ни в историю shell, ни в список процессов. Нужна с --setup-openbao или когда машина потеряла файл с учетными данными.

versola secrets login vps http://127.0.0.1:8200 <role-id>

versola secrets test

versola secrets test <target>

Входит с сохраненными учетными данными, записывает тестовое значение в versola/<target>/_secrets-test, читает его обратно и сообщает, работают ли учетные данные и движок KV v2. Секретов сервисов не касается. При любой ошибке завершается с ненулевым кодом.

versola secrets plan

versola secrets plan <target> <version> [--json] [--generate-missing NAME[,NAME...]]

Печатает, что configure сделал бы с каждым секретом, ничего не делая. Читает, что хранится в OpenBao, запускает versola-tools:<version> во временном каталоге, чтобы узнать секреты релиза и значения-кандидаты, и для каждого секрета печатает: сохранить, создать или остановить запуск. Нужны сохраненные учетные данные (secrets login), запущенный OpenBao и Docker. В OpenBao и в деплой ничего не пишется. Значения секретов не печатаются никогда.

Код выхода ненулевой, если в плане есть проблемы. В JSON-отчете поля version, ok, target, state, schemaRevision, deployedRevision (когда есть запись), actions и problems. Формат описан вместе с правилами плана в разделе Секреты.

Обслуживание

Типовые задачи сводятся к командам выше:

Дальше

• Деплой на VPS: те же команды по порядку на настоящем сервере.
• Секреты: что configure делает с каждым секретом и как ротировать один из них.
• Конфигурация: что находится в сгенерированных файлах конфигурации.