Аварийное восстановление CLI

CLI (интерфейс командной строки) позволяет запускать административные команды в терминале. Системный администратор может с его помощью восстановить доступ к существующей учётной записи с ролью администратора приложения, если её владелец не может войти в панель.

Это отдельная процедура для системного администратора. Роль «Администратор» в приложении относится к восстанавливаемой учётной записи. CLI не запускает веб-сервис и не применяет миграции. База данных должна работать, а схема — быть подготовлена.

Подготовка подключения

Для каждой команды укажите --database-target TARGET и ровно один источник URL с паролем: --database-url-stdin или --database-url-file PATH. Для admin unlock также укажите --login LOGIN — имя входа администратора приложения. Оно не связано с user в URL: там указывается имя пользователя PostgreSQL. CLI не использует DATABASE_URL, .env или YAML для выбора базы. Переменные PGSERVICE, PGSERVICEFILE и PGPASSFILE должны быть пустыми или отсутствовать.

--database-target содержит адрес узла, порт, имя базы и пользователя без пароля. URL, переданный через stdin или файл, содержит пароль и должен совпадать с целью по этим четырём значениям. CLI принимает в URL только названия параметров host, port, database/dbname, user, password, sslmode/ssl. Не добавляйте pool_max_conns, application_name и другие параметры.

Например, для стандартного Compose-сервиса postgres можно использовать такую пару значений:

Цель:       postgres://salary@postgres:5432/salary_slip?sslmode=disable
URL-файл:   postgres://salary:EXAMPLE%2FREPLACE_WITH_URL_ENCODED_PASSWORD@postgres:5432/salary_slip?sslmode=disable

Это синтетический пример, а не учётные данные. Замените EXAMPLE%2FREPLACE_WITH_URL_ENCODED_PASSWORD на пароль, закодированный для URL; см. правило кодирования пароля. Значение sslmode=disable подходит только для стандартного Compose-сервиса без TLS. Если PostgreSQL в вашей установке использует TLS, укажите в обоих URL подходящий явный режим TLS. CLI не принимает sslmode=prefer и sslmode=allow, потому что они допускают альтернативные попытки подключения. Не ослабляйте установленный режим TLS, чтобы обойти ошибку.

Создайте защищённый файл /secure/salary-slip-database-url на Docker-хосте. Поместите в него только одну строку URL, без DATABASE_URL= и без остальных строк из .env. Не показывайте пароль командой echo, не вставляйте его в аргументы или историю терминала.

Для --database-url-stdin оболочка читает файл на Docker-хосте и передаёт его CLI через стандартный ввод. Для --database-url-file PATH CLI читает файл по указанному пути там, где запущена команда; в контейнере нужен путь внутри контейнера. Файл с URL не требуется монтировать, если используется stdin.

Запуск в Docker Compose

Команды ниже приведены для Bash-совместимой оболочки на Docker-хосте: обратная косая черта (\) продолжает команду на следующей строке, а < передаёт файл через стандартный ввод. Запускайте их из каталога нужного Compose-проекта, чтобы команда обратилась к правильной установке.

Используйте один из этих способов для admin list, разблокировки и любого сброса:

  • docker compose exec -T salary-slip /app/salary-slip <команда> запускает CLI в работающем контейнере сервиса salary-slip.
  • docker compose run --rm --no-deps -T salary-slip <команда> создаёт разовый контейнер, если контейнер salary-slip остановлен. Compose использует настроенную точку запуска, поэтому не добавляйте /app/salary-slip после имени сервиса.

При обоих способах база PostgreSQL должна уже работать. Параметр --no-deps не запускает её автоматически. Команды ниже показывают вариант exec; если контейнер приложения остановлен, замените начало команды на вариант run и не указывайте бинарный файл.

Выбор операции

Ситуация Команда Результат
Неизвестно имя для входа admin list Показывает UUID, имя для входа и состояние каждой неудалённой учётной записи администратора приложения.
Заблокированы попытки входа admin unlock Сбрасывает счётчики неудачных попыток входа по паролю и TOTP и связанную блокировку. Пароль, настройка TOTP и сеансы не меняются.
Администратор приложения забыл пароль admin unlock --reset-password Выдаёт временный пароль для обязательной смены при входе и отзывает сеансы. Настройка TOTP остаётся.
Утеряно приложение с кодами admin unlock --reset-totp --reason 'Причина' Сбрасывает настройку и историю использованных кодов TOTP, отзывает сеансы. Пароль остаётся; при следующем входе нужно настроить и подтвердить TOTP заново.
Утрачены оба фактора admin unlock --reset-password --reset-totp --reason 'Причина' Сбрасывает пароль и TOTP и отзывает сеансы. При входе нужно сменить временный пароль, затем настроить и подтвердить TOTP.

Команда выполняется сразу: отдельного подтверждения или флага --confirm нет. Сброс учётных данных и запись в аудит сохраняются вместе в одной транзакции. Команды admin unlock работают только для существующей неудалённой учётной записи с ролью администратора приложения. Они не создают учётные записи, не восстанавливают удалённые записи, не меняют роли или разрешённые сети и не включают отключённую учётную запись.

Аудиторы и сотрудники этими командами не поддерживаются. Если потерявший доступ пользователь имеет роль аудитора, сначала восстановите доступ администратора приложения, затем сбросьте пароль или TOTP аудитора в разделе Пользователи.

Сброс после ротации ключа шифрования

После ротации проверьте её состояние командой admin encryption-key status. Она показывает текущую фазу и не требует ключевого файла:

docker compose exec -T salary-slip /app/salary-slip admin encryption-key status \
  --database-target 'postgres://salary@postgres:5432/salary_slip?sslmode=disable' \
  --database-url-stdin < /secure/salary-slip-database-url

Строка phase=normal означает, что ротация сейчас не выполняется. При остальных условиях можно переходить к сбросу. Значения phase=draining и phase=awaiting_new_nodes означают, что ротация ещё не завершена; сбрасывать пароль или TOTP нельзя. Сначала завершите ротацию по её штатной процедуре. Если команда не вернула состояние, устраните причину ошибки и повторите проверку. Не запускайте сброс, пока состояние не подтверждено.

После завершённой ротации добавьте --encryption-key-file PATH к --reset-password, --reset-totp или их совместному применению. Сброс возможен, только когда ротация завершена и система вернулась в обычное состояние.

Ключевой файл должен содержать текущую строку ENCRYPTION_KEY в формате Base64, декодируемую ровно в 32 байта. Допускается завершающий перевод строки; максимальный размер файла — 256 байт. До первой ротации этот файл не нужен. Если файл указан, CLI проверит ключ даже до первой ротации. Переменные ENCRYPTION_KEY, .env и YAML CLI для этой проверки не использует. Не передавайте ключ аргументом команды.

Создайте файл текущего ключа на Docker-хосте в /secure/salary-slip-current-key. Его содержимое — только строка текущего ключа, с которым запущены узлы после завершённой ротации; это не пароль и не секрет TOTP. Не выводите ключ в терминал и не делайте файл доступным всем пользователям.

В разовый контейнер примонтируйте файл только для чтения. UID 10001 — это пользователь Linux внутри контейнера; задайте права на Docker-хосте так, чтобы он мог прочитать файл, а другие пользователи — нет. В параметре --encryption-key-file укажите путь внутри контейнера. Пример ниже применяет run к сбросу пароля; для сброса TOTP или обоих факторов замените только соответствующие аргументы операции.

docker compose run --rm --no-deps -T --volume /secure/salary-slip-current-key:/run/secrets/salary-slip-current-key:ro salary-slip admin unlock \
  --login 'admin' --reset-password \
  --encryption-key-file /run/secrets/salary-slip-current-key \
  --database-target 'postgres://salary@postgres:5432/salary_slip?sslmode=disable' \
  --database-url-stdin < /secure/salary-slip-database-url

Список администраторов приложения

Запустите admin list, если не знаете имя для входа. Команда выводит три поля через табуляцию, без строки заголовка: UUID, имя для входа и состояние. Пароль и TOTP она не показывает.

docker compose exec -T salary-slip /app/salary-slip admin list \
  --database-target 'postgres://salary@postgres:5432/salary_slip?sslmode=disable' \
  --database-url-stdin < /secure/salary-slip-database-url

В примере salary — имя пользователя PostgreSQL из deploy/compose.yaml. Статус active означает, что учётная запись не отключена; статус disabled — что она отключена. Список не показывает блокировку попыток входа и другие требования при входе и не подтверждает результат сброса.

Разблокировка попыток входа

Сверьте имя для входа по списку и выполните admin unlock без флагов сброса. Команда сбросит счётчики неудачных попыток входа по паролю и TOTP и связанную блокировку. Она не удаляет записи аудита и не меняет пароль, настройку TOTP или текущие сеансы.

docker compose exec -T salary-slip /app/salary-slip admin unlock \
  --login 'admin' \
  --database-target 'postgres://salary@postgres:5432/salary_slip?sslmode=disable' \
  --database-url-stdin < /secure/salary-slip-database-url

Если учётная запись отключена (disabled), команда её не включит.

Сброс пароля

Передайте --reset-password, если администратор приложения забыл пароль. Команда создаст случайный временный пароль и покажет его в стандартном выводе только после сохранения изменений. При следующем входе администратору нужно сменить пароль; настройка TOTP останется прежней.

docker compose exec -T salary-slip /app/salary-slip admin unlock \
  --login 'admin' --reset-password \
  --database-target 'postgres://salary@postgres:5432/salary_slip?sslmode=disable' \
  --database-url-stdin < /secure/salary-slip-database-url

Сохраните показанный пароль и передайте его администратору приложения по согласованному защищённому каналу. Повторно получить его нельзя. Если пароль потерян, выполните новый сброс.

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

Сброс TOTP

Передайте --reset-totp и кратко укажите причину через --reason. Этот флаг допустим только вместе со сбросом TOTP. Причина попадёт в аудит, поэтому не включайте в неё пароль, код или другие секреты. Ограничение длины — 256 байт; причина не должна начинаться или заканчиваться пробелом и не должна содержать управляющие символы.

docker compose exec -T salary-slip /app/salary-slip admin unlock \
  --login 'admin' --reset-totp --reason 'Утеряно приложение с кодами' \
  --database-target 'postgres://salary@postgres:5432/salary_slip?sslmode=disable' \
  --database-url-stdin < /secure/salary-slip-database-url

Команда не выводит секрет TOTP. Пароль остаётся прежним. При следующем входе администратору приложения нужно настроить и подтвердить TOTP заново.

Совместный сброс пароля и TOTP

Выберите совместный сброс, только если утрачены оба фактора. Команда отзовёт сеансы и покажет временный пароль после сохранения изменений. При следующем входе администратору приложения нужно сменить пароль, затем настроить и подтвердить новый TOTP.

docker compose exec -T salary-slip /app/salary-slip admin unlock \
  --login 'admin' --reset-password --reset-totp \
  --reason 'Утрачены пароль и приложение с кодами' \
  --database-target 'postgres://salary@postgres:5432/salary_slip?sslmode=disable' \
  --database-url-stdin < /secure/salary-slip-database-url

Сохраните временный пароль сразу. Команда не включает отключённую учётную запись.

Проверка доступа после восстановления

Чтобы проверить восстановление, войдите в панель с восстановленной учётной записью. После сброса пароля смените временный пароль. После сброса TOTP настройте и подтвердите приложение с кодами. Если сброшены оба фактора, выполните эти действия по порядку.

Предупреждение warning: emergency action notification signal unavailable может появиться после сохранения операции. Оно не отменяет сохранённое действие и не подтверждает доставку письма.

Если команда сообщает о проблеме с подключением, проверьте цель и URL: узел, порт, имя базы и пользователя, соответствие настроек TLS, доступность PostgreSQL и подготовленной схемы. Не передавайте пароль базы в аргументах команды. Эти команды не сработают, если учётная запись отсутствует, удалена или не имеет роли администратора приложения.