CLI identity — справочник команд

Справочник команд, которые входят в комплект Zentro Identity: схема базы, первый администратор и восстановление доступа, лицензия, ключи подписи, обслуживание аудита. Как запустить команду в вашем способе установки — раздел Как запускать.

В образе и в комплекте для ВМ три программы: identity-migrate, identity-server, identity-worker. Команды работают в том же окружении, что и сервис: те же переменные DB_*, SECRETS_BACKEND, VAULT_*, PII_DET_KEY (справочник переменных — deploy/prod/.env.example комплекта).

identity-migrate

Без аргументов печатает список команд. version работает без базы. Остальные команды при ENV=prod сначала проверяют конфигурацию и не запускаются, перечислив все ошибки. Подключение к базе — DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD (или DB_PASSWORD_FILE), DB_SSLMODE. Команды выполняются от имени владельца схемы, а не учётной записи приложения identity_app_login.

Схема базы

Команда	Что делает
up	применяет изменения схемы (запускается сама перед сервером и воркером). При ENV=prod на новой базе включает шифрование персональных данных. Если база новее этой версии — отказ (код 3): откат — rollback.sh --restore-db. Пишет историю версий установки
upgrade-check [--json]	может ли эта версия работать с базой: схема базы и сборки, какие изменения будут применены; status = fresh / up_to_date / upgrade / db_newer (код 3). Используют upgrade.sh и rollback.sh
history	история версий установки: когда, какая версия, откуда обновились, схема до и после, пометка
status	применённые и ожидающие изменения схемы
fetch-kit --version X [--arch amd64|arm64] > kit.tar.gz	скачивает архив версии с сервера лицензий Zentro (нужны LICENSING_URL и регистрация установки). С 0.7.4 upgrade.sh её не использует — качает с сайта Zentro
verify-kit --sig "$(cat SHA256SUMS.sig)" < SHA256SUMS	проверяет подпись комплекта ключом Zentro, вшитым в установленную версию. Используется в upgrade.sh

Возврат к прежней схеме в рабочей установке — откатом с восстановлением базы из резервной копии (Установка сервера).

Администратор

Команда	Что делает
bootstrap-admin <email>	первый запуск: ключ подписи токенов, системные роли и один администратор с временным паролем. Пароль печатается один раз, при первом входе его нужно сменить. Email можно задать и переменной BOOTSTRAP_ADMIN_EMAIL. Если активный администратор уже есть, команда ничего не делает. Алгоритм ключа — SIGNING_ALG (по умолчанию RS256)
setup-code	новый код установки для первого запуска в панели: прежний гасится, новый печатается один раз и действует 24 часа (10 неверных вводов — сгорает). Сервер сам печатает код в журнал при старте, пока администратора нет; команда нужна, если журнал потерян или код истёк. Если администратор уже есть — отказ
admin-list	администраторы: email, статус, число факторов второго фактора, последний вход
admin-recover <email>	одним действием: снимает блокировки, возвращает роль администратора, выдаёт временный пароль (печатается один раз), завершает все сессии
admin-recover <email> --reset-mfa	то же и удаляет второй фактор и доверенные устройства (потерян телефон или ключ)

Все действия попадают в журнал аудита. Доступ к этим командам равен доступу к серверу и паролю владельца базы. Пользователь, который входит только через внешний каталог (без пароля Zentro), восстанавливается в самом каталоге.

Лицензия

Команда	Что делает
license-register --org <организация> --email <email> [--hostname <имя>]	бесплатная регистрация установки у Zentro без панели (то же, что мастер первого запуска). Нужен LICENSING_URL. Уже лицензированная установка не меняется, повтор безопасен. Сервер подхватывает лицензию в течение минуты, перезапуск не нужен. Ошибки печатаются понятным текстом, код выхода 1
license-status	состояние лицензии: статус, тариф (или встроенный Free), идентификатор установки, владелец, срок

Ввод ключа лицензии и вставка токена для закрытого контура — в панели, раздел Лицензия.

Ключи подписи и аудит

Команда	Что делает
jwks-rotate	новый ключ подписи становится основным, прежний продолжает проверять уже выданные токены. Обычно ключи меняют в панели (Настройки → Безопасность → Ключи подписи)
audit-chain	достраивает цепочку хешей журнала аудита и подписывает её (тариф Корпоративный; подпись — при Vault). Если цепочку ведёт воркер, пропускает
audit-partitions	создаёт хранилище журнала аудита на месяцы вперёд и удаляет записи старше срока хранения (AUDIT_RETENTION, по умолчанию 8760h), кроме удерживаемых

audit-chain и audit-partitions воркер выполняет сам по расписанию. Вручную их запускают для диагностики или когда воркер остановлен.

Служебные

Команда	Что делает
backfill-search-ngrams	заново строит индекс поиска пользователей. Нужен после восстановления базы из копии и после включения шифрования персональных данных. Повторный запуск безопасен
version	версия сборки

identity-server и identity-worker

Команда	Что делает
identity-server	сервер: HTTP HTTP_ADDR (по умолчанию :8080), gRPC GRPC_ADDR (по умолчанию :9090)
identity-server healthcheck	проверка /healthz изнутри контейнера: код 0 — работает, 1 — нет. Используется в healthcheck Compose и Swarm (в образе нет shell и curl)
identity-worker	фоновые задачи: чистка устаревших записей, журнал аудита, уведомления о выходе. Должен быть запущен всегда
identity-server version · identity-worker version	версия сборки

Как запускать

Подставьте команду вместо <cmd> (например, admin-list или admin-recover you@example.com --reset-mfa).

Установка	Запуск
Docker Compose (deploy/prod/)	docker compose run --rm migrate <cmd> или docker compose exec worker /identity-migrate <cmd>
docker run	docker run --rm $COMMON $OWNER --entrypoint /identity-migrate $IMG <cmd> или docker exec identity-worker /identity-migrate <cmd>
Docker Swarm	docker exec -it $(docker ps -q -f name=identity_worker | head -1) /identity-migrate <cmd>
ВМ (systemd)	sudo identity-cli <cmd> — то же окружение, пользователь и песочница, что у сервисов

Подробно о каждом способе установки — Установка сервера. Обновление и откат одной командой — скрипты deploy/upgrade/ (upgrade.sh, rollback.sh), там же.