В каталоге 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; свой скрипт обычно дешевле плагина с интерфейсом.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.