Перейти к содержимому
M
Все статьи
Администрирование 9 мин чтения

CLI-скрипты Moodle: что лежит в admin/cli и как написать свой

Обзор консольных скриптов Moodle в admin/cli, правила запуска cron и пример собственного CLI-скрипта с cli_get_params и clilib.

Обзор консольных скриптов Moodle в admin/cli, правила запуска cron и пример собственного CLI-скрипта с cli_get_params и clilib.

В каталоге admin/cli Moodle лежит набор консольных скриптов, которые решают задачи, невозможные или неудобные через браузер: обновить базу на сайте, который не открывается, запустить cron, сменить пароль, очистить кэши, выполнить одну задачу по расписанию. Знать их полезно любому администратору, а разработчику — ещё и уметь написать свой. Сначала обзор готовых скриптов, потом пример собственного.

Зачем консоль, если есть админка

Четыре причины. Консольные скрипты не упираются в таймаут веб-сервера, поэтому долгие операции (обновление, восстановление копий) в консоли надёжнее. Они доступны, когда сайт не открывается. Их можно автоматизировать: запускать по расписанию, из скриптов развёртывания, из CI. И они воспроизводимы: команда в журнале администратора точнее фразы «нажала кнопки в админке». Запускать их нужно от имени того же пользователя, под которым работает веб-сервер, иначе в каталоге данных появятся файлы с неподходящим владельцем.

Обзор скриптов

Состав каталога немного меняется от версии к версии: список своей установки покажет ls admin/cli, а у каждого скрипта есть справка по ключу --help.

СкриптЧто делаетКогда нужен
install.php, install_database.phpустановка Moodle и таблиц базыразвёртывание нового сайта, в том числе в контейнере
upgrade.phpобновление базы после смены кодаобновление ядра и плагинов (через git)
cron.phpвыполнение всех задач по расписанию и очередиосновной вызов по системному планировщику
scheduled_task.phpсписок и запуск отдельных запланированных задачпроверка одной задачи, отладка зависаний
adhoc_task.phpзапуск задач из очереди разовых заданийразбор очереди, доп. обработчики
purge_caches.phpочистка кэшейпосле любых правок кода, настроек, обновления
maintenance.phpвключение и выключение режима обслуживанияна время обновления и работ
cfg.phpпросмотр и установка настроек сайта и плагиновизменение настройки при недоступной админке; автоматизация
reset_password.phpсброс пароля пользователяутеряны доступы администратора
uninstall_plugins.phpудаление плагинов и их данныхудаление плагина, чьи файлы уже убраны
backup.php, restore_backup.phpрезервное копирование и восстановление курсовмассовая работа с курсами
check_database_schema.phpсверка структуры базы с ожидаемойпосле неудачных обновлений, переносов
fix_course_sortorder.phpисправление порядка курсов и категорий«поехал» список курсов
mysql_collation.phpпроверка и смена кодировки таблиц MySQL/MariaDBпроблемы с регистром и символами после переноса

Cron: как запускать правильно

Moodle полагается на cron для рассылок, отчётов, синхронизаций, резервных копий, автоматических действий плагинов. Рекомендуемая схема — запуск cron.php каждую минуту системным планировщиком от имени пользователя веб-сервера:

* * * * * www-data /usr/bin/php /var/www/moodle/admin/cli/cron.php >/dev/null 2>&1

Запуск cron через браузер возможен, но для рабочего сайта плох. Если задача зависает, смотрите статью про запланированные и разовые задачи: там описано, как найти застрявшую и запустить её по отдельности:

php admin/cli/scheduled_task.php --list
php admin/cli/scheduled_task.php --execute='\core\task\session_cleanup_task'

Имя класса в примере — для иллюстрации; точное название берётся из вывода --list.

Настройки из командной строки

Скрипт cfg.php читает и меняет конфигурацию без захода в админку:

php admin/cli/cfg.php --name=debug
php admin/cli/cfg.php --component=local_myplugin --name=enabled --set=1

Это удобно для развёртывания: после установки новой копии скриптом в одну команду выставляются нужные параметры. Настройки, принудительно заданные в config.php, скриптом не изменить — они приоритетнее.

Свой скрипт: каркас

Скрипты плагина обычно кладут в его папку cli (например, local/myplugin/cli/report.php). Для разработчиков в Moodle есть вспомогательные функции разбора параметров и вывода сообщений из lib/clilib.php. Рабочий пример: выводит число активных и заблокированных пользователей и, если указан курс, число записей на него.

<?php
define('CLI_SCRIPT', true);

require(__DIR__ . '/../../../config.php');
require_once($CFG->libdir . '/clilib.php');

[$options, $unrecognised] = cli_get_params(
    ['help' => false, 'courseid' => 0],
    ['h' => 'help']
);

if ($unrecognised) {
    cli_error('Неизвестные параметры: ' . implode(', ', $unrecognised));
}

if ($options['help']) {
    cli_writeln("Использование:\n  php local/myplugin/cli/report.php [--courseid=N]");
    exit(0);
}

cli_heading('Отчёт по пользователям');
$active = $DB->count_records('user', ['deleted' => 0, 'suspended' => 0]);
$suspended = $DB->count_records('user', ['deleted' => 0, 'suspended' => 1]);
cli_writeln("Активных: {$active}, заблокированных: {$suspended}");

if ($options['courseid']) {
    $context = context_course::instance((int)$options['courseid']);
    $count = count_enrolled_users($context);
    cli_writeln("Записано на курс {$options['courseid']}: {$count}");
}

Что здесь важно. Константа CLI_SCRIPT объявляется до подключения config.php: без неё Moodle запрещает запуск из консоли. Функция cli_get_params принимает описание длинных параметров со значениями по умолчанию и соответствие коротким, и возвращает найденные значения и список нераспознанных. Для ошибок используется cli_error, которая завершает скрипт с ненулевым кодом, что важно для планировщиков и CI. Все обращения к данным идут через API Moodle ($DB, count_enrolled_users), а не через прямой SQL там, где можно.

Правила для собственных скриптов

  • Идемпотентность. Повторный запуск не должен портить данные: проверяйте, что уже сделано.
  • Пробный режим. Для разрушающих операций делайте параметр «только показать» и включайте его по умолчанию.
  • Права и безопасность. Консольный скрипт выполняется без проверки прав пользователя, поэтому ограничьте доступ к самой консоли и не принимайте произвольный SQL.
  • Журналирование. Выводите, что сделано и сколько записей затронуто; тогда по журналу cron можно разобрать, что произошло.
  • Объём. Крупные обработки разбивайте на части, чтобы не упереться в память.
  • Нужна ли задача вместо скрипта. Если действие должно выполняться регулярно и входить в экосистему Moodle, лучше оформить его запланированной задачей (scheduled task): у неё есть журнал, настройка расписания в админке и блокировки от одновременного запуска.

Где консольные скрипты выручали меня

Загрузка студентов из выгрузок 1С:Колледж идёт через собственные скрипты на Python и CSV, но создание когорт, запись в группы и проверка итоговых данных удобно делать в консоли Moodle: так видно, что именно получилось (интеграция Moodle с 1С). После переезда СДО на новый сервер именно upgrade.php, purge_caches.php и check_database_schema.php показали, что с базой всё в порядке. Для разовой правки настройки на упавшем сайте выручал cfg.php.

Параметры и коды возврата

Хороший консольный скрипт ведёт себя предсказуемо для оболочки: возвращает ноль при успехе и ненулевой код при ошибке, пишет сообщения об ошибках в поток ошибок и не требует ввода, если указан флаг неинтерактивного режима. Именно так устроены штатные скрипты (upgrade.php с ключом --non-interactive), и так же стоит писать свои. Это позволяет в скрипте развёртывания связать несколько команд через &&: если обновление базы упало, очистка кэшей и выход из режима обслуживания не выполнятся, а сайт останется закрытым и привлечёт внимание вместо того, чтобы молча работать в сломанном состоянии.

Безопасность запуска

Консоль даёт полный доступ к данным, поэтому действуют простые правила. Не запускайте скрипты Moodle от имени root: файлы кэша получат неверного владельца, и сайт начнёт падать на записи. Для запуска от нужного пользователя используйте sudo -u с именем пользователя веб-сервера. Не передавайте пароли параметрами командной строки, если можно прочитать их из окружения или файла с ограниченными правами: параметры видны другим пользователям сервера в списке процессов и остаются в истории оболочки. Для скриптов, которые вы кладёте в плагин, добавьте проверку, что они запущены именно из консоли, а не через веб; константа CLI_SCRIPT и служебная проверка ядра этим и занимаются.

sudo -u www-data php admin/cli/purge_caches.php
sudo -u www-data php admin/cli/upgrade.php --non-interactive

Что не стоит делать из консоли без подготовки

Консольные скрипты мощные, поэтому и ошибки в них дорогие. Массовое удаление курсов, смена паролей группе пользователей, изменение настроек всего сайта — всё это сначала проверяют на копии базы. Особенно осторожно относитесь к скриптам, которые меняют данные напрямую SQL-запросами, обходя API Moodle: они не вызывают события, не очищают кэши и не обновляют связанные таблицы, поэтому последствия проявляются позже и в других местах. Если задачу можно решить через штатный API Moodle, решайте так, даже когда прямой запрос короче.

Типичные задачи и команды

ЗадачаКак решить
Сайт не открывается после обновления кодаphp admin/cli/upgrade.php --non-interactive, затем очистка кэшей
Потерян пароль администратораphp admin/cli/reset_password.php с указанием пользователя (параметры смотрите в --help)
Нужно узнать значение настройкиphp admin/cli/cfg.php --name=имя (для настройки плагина добавляется --component)
Задача по расписанию не выполниласьнайти её в scheduled_task.php --list и запустить отдельно с --execute
Очередь разовых заданий растётзапустить adhoc_task.php, посмотреть журнал, найти повторяющуюся ошибку
Остались таблицы удалённого плагинаuninstall_plugins.php с нужными параметрами; сначала список через ключ справки
Подозрение на повреждение схемы базыphp admin/cli/check_database_schema.php

Таблица не заменяет справку: у каждого скрипта свои параметры, и они меняются между версиями. Привычка начинать с --help избавляет от запуска команды не с теми аргументами. А для задач, которых в каталоге нет, я пишу свой скрипт по образцу выше. Если для вашей СДО нужны регулярные выгрузки или сверки с внешними системами, обычно это короткий скрипт или запланированная задача (пример интеграции с 1С).

Если вам нужно автоматизировать рутину в вашей СДО — выгрузки, чистку, массовые операции — это типовая задача для доработки Moodle; свой скрипт обычно дешевле плагина с интерфейсом.

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.