Управление через iexctl
iexctl — команда для проверки и обслуживания установленного iEXExchanger. Через неё можно проверить службы, создать резервную копию, изменить параметры Backend и Frontend, восстановить настройки, посмотреть регистрацию сервера и подготовить диагностику для поддержки.
Где выполнять команды
Подключитесь по SSH к серверу, на котором установлен продукт. Команды обслуживания выполняются от root или через sudo. В этой инструкции используется sudo; в сессии root его можно убрать.
После установки команда доступна из любого рабочего каталога. Проверьте её наличие:
command -v iexctlОсновной исполняемый файл находится в /usr/local/sbin/iexctl, глобальная команда — в /usr/local/bin/iexctl. Если оболочка не находит iexctl, используйте полный путь:
sudo /usr/local/sbin/iexctl --helpПеред изменением настроек, перезапуском служб и ручными операциями с резервными копиями завершите активное обновление или откат. Изменяющие операции используют общую блокировку с установкой и обновлением. Если команда сообщает, что блокировка занята, дождитесь завершения текущей операции.
Справка и версия команды
Открыть общую справку:
sudo iexctl --helpПосмотреть параметры нужной команды:
sudo iexctl env set --help
sudo iexctl backup operator --helpПоказать версию iexctl:
sudo iexctl --versionПолучить сведения о версии, сборке и платформе:
Это версия управляющей команды. Версия установленного продукта также выводится в отчёте iexctl doctor. Для справки и краткой версии доступны короткие флаги -h и -v.
Формат вывода и время выполнения
По умолчанию результат выводится как текст. Для обработки в скриптах доступны JSON и YAML:
services logs поддерживает только текстовый вывод. backup operator также возвращает текст: параметр --format json или --format yaml не преобразует его результат.
Параметр --timeout задаёт лимит времени выполнения операции. По умолчанию используется 2h; значение должно быть больше нуля и не превышать 24h. Для длительных проверок резервных копий можно увеличить лимит:
Ненулевой код завершения означает ошибку выполнения или непрохождение проверки. Нулевой код у команды просмотра означает, что сведения удалось получить. Готовность и предупреждения оценивайте по самому отчёту; для проверки служб используйте services verify.
Диагностика установленного продукта
doctor выполняет диагностику текущей установки. Команда не изменяет настройки и не перезапускает службы:
В отчёт входят:
сохранённое состояние установки и совместимость серверного профиля с текущими управляющими программами;
соответствие активного релиза состоянию установки и наличие отметки успешной приёмки;
проверка установленных управляющих программ и глобальной команды
iexctl;готовность служб и проверка конфигурации Nginx;
версии PHP и Node.js, обязательные расширения PHP и ionCube Loader;
наличие точной строки CRON для планировщика задач;
ответ основной базы PostgreSQL и базы Pulse на локальный запрос, доступность локального порта Redis;
наличие свободного места и inode — записей файловой системы, необходимых для создания файлов;
готовность резервного копирования, если оно включено.
Как читать результат
OK
Проверка пройдена
WARN
Есть предупреждение, которое нужно оценить отдельно
ERROR
Обязательная проверка не пройдена
Если есть ERROR, команда возвращает ненулевой код завершения. Отдельная неудачная проверка не останавливает остальные проверки отчёта.
Предупреждения о резервных копиях могут появляться при успешной общей диагностике: например, если ещё нет свежей проверки восстановления или копии находятся на одной файловой системе с приложением.
Ошибка deployment.schema означает, что серверный профиль требует штатного перехода через обновление продукта. Не исправляйте её ручной заменой служебных метаданных установки.
doctor проверяет локальную установку. Доступность сайта через публичный домен, работу внешних сервисов и фактическое выполнение каждой фоновой задачи проверяйте отдельно.
Управление службами
Команды services используют каталог служб текущей установки. Имена служб подбираются автоматически с учётом установленной версии PHP и включённого резервного копирования.
Состояние и готовность
Посмотреть состояние:
В текстовом отчёте отображаются имя службы, состояние, автозапуск, оценка работоспособности health, время работы и результат последнего выполнения.
Получить подробные сведения, включая счётчики перезапусков, время запусков и причины оценки:
Проверить готовность всех служб:
Если хотя бы одна служба не готова, verify возвращает ненулевой код завершения. status предназначен для просмотра и может завершиться успешно при наличии проблем в полученном отчёте.
Оценка health помогает отличить доступность процесса от его стабильности:
stable
Служба соответствует условиям стабильной работы
starting
Служба запускается, применяет конфигурацию или работает менее 30 секунд
unstable
Подтверждены не менее трёх аварийных завершений за последние десять минут
degraded
Служба работает, но проверить причины недавних перезапусков не удалось
stopped, disabled, failed, maintenance, unknown
Служба остановлена, отключена, завершилась ошибкой, находится в обслуживании либо её состояние не распознано
Успешный verify подтверждает готовность по текущему состоянию служб. Значения starting, unstable и degraded требуют отдельной оценки и могут присутствовать при ready=true. После перезапуска повторите просмотр состояния, когда завершится начальный период наблюдения.
Накопленный счётчик перезапусков сам по себе не означает аварию. Штатная смена версии Update Agent также может увеличивать этот счётчик; оценка нестабильности учитывает подтверждённые аварийные завершения.
Служба iex-scheduler.service выполняется однократно. Состояние inactive после успешного выполнения для неё нормально. Ежеминутный запуск задач обеспечивает CRON; состояние проверочной службы не является историей всех запусков планировщика.
Перезапуск группы
Выберите одну группу:
frontend
Перезапуск клиентского сайта
backend
Перезапуск PHP-FPM, Horizon, Reverb и служб Pulse, затем проверочный запуск планировщика
all
Действия для Backend и Frontend
Перезапустить Frontend:
Перезапустить Backend:
Перезапустить обе группы:
После действий команда проверяет все службы управляемого каталога. Проблема с другой службой этого каталога также может привести к неуспешному результату. PostgreSQL, Redis и Nginx в эти группы перезапуска не входят.
Перезапуск может кратковременно прервать работу соответствующей части продукта.
Просмотр журналов
Последние 200 строк журнала Frontend:
Журналы Backend за последние 30 минут:
Доступные цели:
frontend
Frontend
backend
PHP-FPM, Horizon, Reverb и обе службы Pulse
horizon
Обработка очередей
reverb
Reverb
pulse
Обе службы Pulse
scheduler
Проверочная служба планировщика
backup
Служба и таймер резервного копирования, если оно включено
update-agent
Update Agent
all
Все службы доступного управляемого каталога
Выбрать журнал Update Agent:
--lines принимает значение от 1 до 10 000; по умолчанию — 200. --since задаёт начало периода в формате journalctl. Оба параметра можно использовать вместе.
Команда выводит полученные записи журнала. Отсутствие записей за выбранный период не подтверждает работоспособность службы: проверьте её через services status и services verify.
Резервное копирование
Команды backup работают с резервным копированием, включённым при установке. Репозиторий Restic — хранилище управляемых резервных копий — определяется по состоянию установки. Произвольный репозиторий через эти команды выбрать нельзя.
Если управляемое резервное копирование отключено, команды этой группы сообщат об этом.
Проверка состояния
Отчёт показывает состояние службы и таймера, последнюю копию, её возраст, следующий запуск и результат оценки восстановления.
Получить подробные сведения о копиях и последней проверке восстановления:
Готовность резервного копирования требует подтверждённого успешного запуска, включённого постоянного расписания, будущего времени следующего запуска и свежей управляемой копии. Наличие загруженной службы или старой копии само по себе недостаточно.
Копия считается устаревшей после 36 часов. Проверка восстановления считается устаревшей после 31 дня. Отсутствие свежей проверки восстановления выводится как предупреждение и учитывается отдельно от готовности ежедневного копирования.
Если служба, таймер или свежая копия не готовы, backup status возвращает ненулевой код завершения.
Если репозиторий находится на одной файловой системе с приложением, отказ этого хранилища затронет и продукт, и локальные копии. Для защиты от отказа сервера храните резервные копии также вне него.
Создание копии вручную
Команда запускает ту же службу, которую использует расписание. Успех подтверждается завершением резервного копирования и появлением новой управляемой копии.
При необходимости команда обновляет служебную конфигурацию подтверждения результата и восстанавливает включение таймера. Затем повторно проверяет готовность резервного копирования.
Список копий
По умолчанию показываются последние 20 копий с идентификатором, временем создания и именем сервера. Список выводится от новых копий к старым.
Изменить количество записей:
--limit принимает значение от 1 до 1000.
Проверка целостности
Обычная проверка структуры и согласованности репозитория:
Полная проверка с чтением 100% сохранённых данных:
Проверка также требует наличия управляемой копии. Полный режим может выполняться долго и создавать заметную нагрузку на диски; при необходимости увеличьте --timeout и выберите время с меньшей нагрузкой на продукт.
Проверка восстановления
Команда извлекает последнюю управляемую копию в закрытый временный каталог внутри /var/tmp. Для этого должно хватать свободного места под извлечённые данные.
Проверка подтверждает наличие восстановленных каталогов общих данных и настроек, а также наличие и читаемость дампов основной базы PostgreSQL и базы Pulse. После проверки временные данные удаляются, а успешный результат сохраняется для последующих отчётов backup status и doctor.
Сохранённое подтверждение относится к проверенному репозиторию и выполненной проверке. Создание следующей копии не запускает новый restore-test автоматически.
Экспорт баз данных через backup operator
backup operator позволяет отдельно проверить конфигурацию экспорта и сохранить дампы основной базы и базы Pulse. Утилита продукта запускается от пользователя приложения, а готовые файлы публикуются в закрытом каталоге.
Проверить конфигурацию и подключения:
Экспортировать базы с меткой операции:
backup — синоним export. Вместо предыдущей команды можно выполнить:
before-manual-change — метка этого экспорта. При необходимости замените её своей меткой.
Глобальные параметры iexctl, включая --timeout, указывайте перед backup или перед operator. Параметры после export, backup или config-check передаются утилите экспорта. Переопределять --env, --config, --profile и --output через эту команду нельзя.
Результат сохраняется внутри /var/backups/iexexchanger/operator-db. Команда выводит путь созданного каталога. Файлы экспорта содержат данные баз и доступны только root.
Этот экспорт сохраняет базы данных отдельно. Он не создаёт полную управляемую копию файлов и настроек продукта; для неё используйте backup run.
Управление параметрами Backend и Frontend
Команды env работают с двумя файлами настроек:
backend
/etc/iexexchanger/backend.env
frontend
/etc/iexexchanger/frontend.env
Перед фактическим изменением сохраняется закрытая копия исходного файла. Запись выполняется атомарно, с сохранением владельца, группы и прав доступа.
В командах ниже замените PARAM_NAME точным именем параметра, а VALUE — требуемым значением. Используйте параметры, предусмотренные продуктом: запись произвольного имени сама по себе не добавляет новую настройку.
Просмотр параметров
Получить список имён:
Показать значения несекретных параметров:
Прочитать один параметр:
Значения параметров, которые распознаны как секретные, заменяются на <скрыто>, в том числе при --show-values и выводе в JSON или YAML. Классификация учитывает имя параметра: например, наличие PASSWORD, SECRET, TOKEN или KEY.
Добавление или изменение параметра
Выберите ровно один источник значения: --value, --stdin или --value-file. Значение должно быть однострочным, без символа NUL, размером не более 1 MiB.
Несекретное значение
--value предназначен для несекретных значений. Для параметра, распознанного как секретный, команда отклонит такой способ передачи.
Значение из стандартного ввода
После запуска введите одну строку значения, нажмите Enter, затем Ctrl+D. Значение не попадает в историю команд оболочки.
--stdin не отключает отображение вводимых символов в терминале. Для секретов используйте защищённый источник ввода или заранее подготовленный файл с доступом только для root. Не вставляйте секрет в команды echo или printf: он может остаться в истории оболочки.
Значение из файла
Подготовьте обычный файл /root/iex-env-value с одной строкой значения, владельцем root и правами 0600. Если используете другое расположение, укажите полный абсолютный путь.
Команда читает значение из файла и не передаёт его аргументом процесса.
Удаление параметра
Удалить параметр Backend:
Удалить параметр Frontend:
Удаляется указанное присваивание. Перед изменением сохраняется копия всего исходного файла.
Применение изменений в процессах
Без --restart команда сохраняет файл и не перезапускает процессы. Чтобы применить настройки в работающих процессах, используйте этот флаг либо отдельно выполните services restart для соответствующего компонента.
--restart перезапускает службы и проверяет их готовность. Очистка и пересборка кеша Laravel в эту операцию не входят.
Если параметр уже имеет требуемое значение, повторная команда не переписывает файл и не создаёт новую запись изменения. При явно заданном --restart службы всё равно перезапускаются и проверяются.
Если изменение файла выполнено, а последующий перезапуск или проверка служб завершились ошибкой, сохранённое значение остаётся в файле. Проверьте службы и их журналы. После исправления причины можно повторить команду с --restart или перезапустить нужную группу отдельно.
История изменений
В истории отображаются идентификатор операции, время, действие, имя параметра либо источник восстановления и статус. Значения параметров в историю вывода не включаются.
По умолчанию показываются 20 записей. Для каждого компонента сохраняются последние 50 операций вместе с копиями файлов. Показать всю сохраняемую историю:
--limit принимает значения от 1 до 50. Значение 0 также выводит всю сохранённую историю.
Статус completed означает завершённое изменение файла; not-applied — что после прерванной операции подтверждено отсутствие её применения. Восстановление доступно из записей completed.
Перед новой записью и восстановлением проверяется целостность сохранённой истории. Повреждённая запись или неполная пара записи и резервного файла блокируют операцию.
Сведения об отдельном изменении
Замените RECEIPT_ID идентификатором из истории нужного компонента:
receipt показывает сведения об операции: действие, статус, время, путь резервной копии и SHA-256 файла до и после изменения. Содержимое настроек не выводится.
Восстановление файла настроек
Восстановление возвращает файл к состоянию до выбранной операции.
Проверка плана
Сначала получите план для нужного компонента:
Для Frontend:
План показывает источник восстановления, его время, контрольные суммы текущего и целевого файлов и признак наличия изменений. Значения параметров не выводятся. В текстовом результате также приводится команда применения.
Применение восстановления
Замените RECEIPT_ID тем же идентификатором операции, а CURRENT_SHA256 — точным значением currentSha256 из только что полученного плана:
Для Frontend замените backend на frontend и используйте план этого компонента.
--confirm должен точно совпадать с идентификатором операции. --expected-current-sha256 защищает от применения устаревшего плана: если файл изменился после планирования, восстановление останавливается до записи. В этом случае заново получите и проверьте план.
Восстанавливается весь файл настроек, поэтому последующие изменения этого компонента будут отменены. Перед заменой текущего файла создаётся новая резервная копия и новая запись истории.
Без --restart восстановится только файл. С этим флагом также выполняются перезапуск и проверка соответствующих служб.
Регистрация сервера
Регистрация связывает установленный экземпляр продукта с лицензией в кабинете iEXExchanger. Её выполняет Update Agent при запуске, затем штатно повторяет подтверждение связи каждые три часа.
Просмотр состояния
Команда читает локальное состояние без сетевого запроса. Она показывает статус, идентификаторы установки и сервера, количество последовательных ошибок, время последней успешной связи и код последней ошибки.
Подробные сведения, включая время попытки и регистрации:
unregistered
Регистрация ещё не подтверждена
registered
Последнее подтверждение связи выполнено успешно
retrying
Последняя попытка завершилась ошибкой; причину показывает lastErrorCode
reauth_required
Следующая синхронизация должна заново подтвердить регистрацию
Статус registered описывает последний сохранённый результат. Для оценки актуальности связи учитывайте время последнего успешного запроса.
Лицензионный ключ и секрет регистрации в вывод не включаются.
Немедленная синхронизация
Команда выполняет одну попытку: первичную регистрацию либо подтверждение связи уже зарегистрированного сервера. При ошибке возвращается ненулевой код завершения, а результат попытки сохраняется.
После завершённого обновления или отката можно выполнить sync, чтобы сразу передать сведения о текущей версии, не дожидаясь очередной фоновой синхронизации.
Для первичной регистрации сервер должен иметь публичный IP-адрес на активном сетевом интерфейсе. Адрес прокси или CDN не заменяет адрес сервера.
Причины ошибок регистрации
В структурированном выводе код находится в lastErrorCode; текстовый отчёт выводит его как код последней ошибки.
remote_retryable
Временная ошибка удалённого сервиса или ограничение запросов; дождитесь автоматического повтора
transport_or_local_error
Проверьте сетевой доступ и локальные данные установки; подробности есть в ошибке команды и журнале Update Agent
unauthorized, not_found
Следующий sync повторно подтвердит регистрацию установленной лицензией
credential_unavailable
Проверьте доступность локального секрета регистрации; ошибка прав или повреждение файла требуют проверки оператора
remote_rejected
Проверьте статус лицензии и разрешение на подключение этого экземпляра
registration_conflict
Проверьте привязку лицензии и IP; при переносе используйте штатную процедуру смены сервера
transfer_pending
Заявка на смену сервера ожидает решения; после подтверждения повторите подключение в разделе «Обновления»
Временные ошибки связи автоматически повторяются с увеличением паузы примерно от одной до пятнадцати минут. Отказ в допуске, конфликт привязки и ожидающая заявка требуют решения причины.
registration sync не создаёт заявку на смену сервера и не изменяет разрешённый IP лицензии. Перенос оформляется через раздел «Обновления» на новом сервере.
Ресурсы сервера и прогноз
Команды resources показывают фактические замеры и прогноз по сохранённой истории. Update Agent собирает первый замер при запуске, затем повторяет сбор каждый час.
Текущий замер
Собрать и сохранить внеплановый замер:
В замере учитываются свободное место и inode основной файловой системы, суммарный размер основной базы и базы Pulse, доступная оперативная память и область подкачки, количество доступных логических процессоров и средняя нагрузка за минуту. При включённом резервном копировании также учитывается свободное место файловой системы репозитория.
Текстовый вывод содержит основные показатели. Полный замер доступен в структурированном формате:
Команда выполняет новый замер и сохраняет его в историю. Если нужный каталог или база недоступны, команда сообщает об ошибке.
История замеров
По умолчанию выводятся последние 24 замера в порядке их сбора. Выбрать другое количество:
--limit принимает значение от 1 до 2160. Сохраняются последние 2160 замеров — примерно 90 дней при штатном ежечасном сборе. Ручные замеры также входят в этот лимит.
Прогноз заполнения
Прогноз рассчитывается по сохранённой истории. Чтобы учесть текущее состояние, перед ним выполните resources sample.
Для оценки будущего роста нужны минимум три замера, охватывающие не менее шести часов. Рассчитываются суточные темпы роста занятого места основной и резервной файловых систем и объёма PostgreSQL.
Безопасный порог для прогноза — 85% заполнения файловой системы.
insufficient_history
Данных пока недостаточно для прогноза роста
stable
Расчётный запас превышает 30 дней либо положительный рост до порога не выявлен
warning
Порог ожидается более чем через 7, но не позднее чем через 30 дней
critical
Порог уже достигнут или ожидается не позднее чем через 7 дней
Уже достигнутый порог отмечается как critical, даже если ещё нет достаточной истории или рост отсутствует. После изменения ёмкости диска прогноз использует только замеры для новой ёмкости; историю до расширения не смешивают с новой серией.
Получить полный результат, включая расчётные сроки:
Прогноз служит рекомендацией по запасу места. Он не меняет конфигурацию сервера и не заменяет требования к продукту из статьи «Системные требования». История ресурсов остаётся на сервере.
Диагностический комплект для поддержки
Создать комплект:
Команда сохраняет диагностический архив и файл контрольной суммы внутри /var/lib/iexexchanger/support. В результате выводятся путь архива, SHA-256, путь файла контрольной суммы, размер и количество файлов.
Комплект содержит сведения об установке и версиях, результаты диагностики, состояния служб и резервного копирования, состояние регистрации, прогноз ресурсов, сведения о последних операциях установки, обновления и отката, а также диагностику Update Agent.
Если отдельный источник диагностики недоступен, это отражается внутри комплекта. Успешное создание архива само по себе не подтверждает исправность всех компонентов.
В комплект не включаются содержимое файлов настроек, пароли и ключи, дампы баз, строки таблиц и необработанные журналы служб. Свободный текст причины ручной паузы обновлений также исключается.
Архив и контрольная сумма доступны только root. Комплект содержит технические сведения об установке и доменах; передавайте его поддержке по согласованному защищённому каналу.
Проверка после обслуживания
После изменения настроек или перезапуска выполните:
При включённом резервном копировании дополнительно проверьте:
Проверьте готовность служб и их оценку health, отсутствие обязательных ошибок диагностики и наличие свежей резервной копии. Предупреждения о восстановлении и расположении копий оцените отдельно.
Откройте клиентский сайт и административную панель. Если меняли параметры конкретной функции, проверьте её фактическую работу: локальная готовность служб не подтверждает доставку почты, работу платёжного подключения или доступность сайта через публичный домен.
Последнее обновление
Это было полезно?