Обновление KaevCMS

Способ обновления зависит от среды и типа установочного пакета. Не используйте ZIP обновления вместо полного архива установки.

Перед обновлением

1. Запишите точную установленную версию (например, из системной информации).
2. Откройте релизы KaevCMS.
3. Проверьте диапазон поддерживаемых исходных версий в манифесте пакета.
4. Сделайте резервную копию файлов, базы CMS, .env, public/uploads и других пользовательских данных.
5. По возможности проверьте обновление на отдельной копии проекта.
6. Сверьте SHA-256 архива с опубликованной контрольной суммой.

Установка и проверка Update Agent

Этот шаг нужен только для запуска обновлений из административной панели. Агент не устанавливается автоматически и не требуется для ручного обновления через SSH.

Выполните одну команду:

cd /var/www/kaevcms
bash deployment/vds/install-update-agent.sh

Больше выбирать ничего не требуется. Скрипт сам:

• запросит sudo, если текущей учётной записи не хватает прав;
• определит владельца проекта;
• определит пользователя и группу PHP-FPM;
• настроит systemd-службу от владельца проекта;
• восстановит безопасные права программных и runtime-файлов;
• проверит, что PHP-FPM читает приложение и может записывать пакеты обновлений.

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

Только для нестандартной конфигурации значения можно указать вручную:

bash deployment/vds/install-update-agent.sh \
    --project-user kaevcms \
    --web-user www-data \
    --web-group www-data

Переменные KAEVCMS_DEPLOY_USER, KAEVCMS_WEB_USER, KAEVCMS_WEB_GROUP и KAEVCMS_PHP_BINARY также поддерживаются.

Скрипт записывает числовые UID/GID, оставляет исходный код доступным PHP-FPM только на чтение, создаёт групповые runtime-каталоги с правами записи и сохраняет резервные копии базы доступными только владельцу. Агент не открывает сетевой порт.

Проверьте состояние:

cd /var/www/kaevcms
php artisan kaevcms:update-agent:status

Ожидаемый результат: State: ready и Ready: yes. Повторный запуск той же команды безопасно обновляет unit-файлы, регистрацию и права. После этого релиза ожидается версия контракта агента 3.

Для удаления агента:

cd /var/www/kaevcms
sudo bash deployment/vds/remove-update-agent.sh

Удаление блокируется, пока в каталоге агента есть ожидающий запрос обновления.

Обновление KaevCMS на Ubuntu / VDS

Обновление через административную панель

Для первого перехода с версии ниже 0.47.0 используйте ручной CLI Updater: старые версии ещё не содержат агент. После установки 0.47.0 установите агент один раз, и следующие совместимые обновления можно будет запускать из панели.

Для этого способа должен быть установлен агент из раздела «Установка и проверка Update Agent» выше. Если агент отсутствует, KaevCMS покажет сообщение «Агент обновлений VDS не установлен» и готовую команду установки. Загружать и проверять ZIP можно без агента, но запуск установки будет недоступен, пока агент не готов.

1. Откройте Настройки → Система → Обновления системы.
2. Загрузите актуальный кумулятивный Update ZIP.
3. Проверьте целевую версию, manifest, SHA256 и preflight.
4. Подтвердите, что доверяете источнику архива. Владелец сайта отвечает за выбранный пакет: обновление может заменять программные файлы KaevCMS.
5. Введите текущий пароль владельца и нажмите «Отправить агенту VDS».

Сайт создаёт локальный запрос в защищённом runtime-каталоге. systemd.path запускает одноразовый агент от владельца файлов проекта. Агент повторно проверяет архив и права, создаёт резервные копии файлов и базы, включает технический режим, применяет файлы и миграции, очищает кеши и перезапускает очередь. При ошибке используется существующий автоматический откат.

Пока запрос ожидает агента, страница обновляется автоматически. После запуска агента технический режим и журнал показывают подготовку, замену файлов, миграции, завершение или ошибку. Не удаляйте ZIP и не запускайте второе обновление, пока текущий запрос не завершён.

Диагностика агента:

cd /var/www/kaevcms
php artisan kaevcms:update-agent:status --json
sudo journalctl -u 'kaevcms-update-agent-*.service' -n 100 --no-pager

Если агент зарегистрирован неверно или unit-файлы были удалены, повторно выполните:

cd /var/www/kaevcms
bash deployment/vds/install-update-agent.sh

После изменения владельца проекта или группы PHP-FPM повторно выполните bash deployment/vds/install-update-agent.sh. Установщик восстанавливает как runtime-каталоги Web Update, так и чтение файлов приложения группой веб-сервера, не предоставляя PHP-FPM права записи на исходный код.

Резервное обновление через SSH

Ручной CLI Updater остаётся доступным без агента. Запускайте его от SSH-пользователя, которому принадлежит /var/www/kaevcms, а не от www-data:

sudo systemctl stop kaevcms-queue
cd /var/www/kaevcms
php artisan kaevcms:update /tmp/KaevCMS-update.zip
sudo systemctl start kaevcms-queue
rm -f /tmp/KaevCMS-update.zip

Команда показывает manifest, исходную и целевую версии, preflight-проверки и запрашивает подтверждение. Для автоматизированного запуска после собственной проверки пакета можно добавить --yes:

php artisan kaevcms:update /tmp/KaevCMS-update.zip --yes

Устанавливать промежуточные версии по очереди не нужно: пакет должен поддерживать диапазон от текущей версии до целевой.

Если релиз меняет Composer-зависимости, используйте полный релиз и composer install по поставленному composer.lock. Никогда не запускайте composer update на production-сервере.

Если обновление зависло: kaevcms:update-recover

После перезагрузки VDS, аварийного завершения процесса или сбоя Update Agent обновление может остаться незавершённым: сайт находится в режиме обслуживания, а новые обновления заблокированы. Для восстановления откройте SSH-консоль сервера:

cd /var/www/kaevcms
owner="$(stat -c '%U' artisan)"
sudo -u "$owner" php artisan kaevcms:update-recover

Замените /var/www/kaevcms фактическим путём к проекту. Переменная owner определяет владельца файла artisan. Команду обязательно выполнять от владельца файлов проекта, а не от www-data. Для проекта под root запускайте её от root. Запуск другим пользователем отклоняется.

Команда определяет ситуацию и запрашивает подтверждение:

• Обновление прервалось во время установки — восстанавливает базу данных и файлы из проверенной резервной копии, возвращает прежнюю версию и снимает режим обслуживания.
• Update Agent не начал обработку запроса — отменяет ожидающую заявку, возвращает пакет в подготовленное состояние, после чего его можно запустить повторно или удалить через админку.
• Зависших обновлений нет, но сайт в режиме обслуживания — предлагает вернуть сайт в работу.

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

sudo -u "$owner" php artisan kaevcms:update-recover UUID

Флаг --yes снимает интерактивный запрос подтверждения; используйте его только для заранее проверенных автоматизированных запусков. Без --yes команда в неинтерактивном режиме откажется выполнять действие. Если проверенной резервной копии нет или откат завершился ошибкой, сайт останется в режиме обслуживания. Изучите журнал обновления в storage/logs; не снимайте режим обслуживания вручную после неудачного отката.

Доступность команды

Команда добавлена в исходники KaevCMS коммитом c443b62 и отсутствует в старых установленных версиях. Проверить её наличие можно командой php artisan list | grep kaevcms:update-recover. Инструкция предназначена для VDS с SSH, не для виртуального хостинга без доступа к консоли.

Первоначальная инструкция в KaevCMS.

После обновления: очереди

После обновления KaevCMS перезапускайте worker:

sudo -u www-data /usr/bin/php8.3 /var/www/kaevcms/artisan queue:restart
sudo systemctl restart kaevcms-queue

Виртуальный хостинг

Для совместимых версий используется кумулятивный Web Updater в административной панели. Поддержка прямого перехода определяется содержимым конкретного Update ZIP, а не просто его названием.

После обновления

• Проверьте версию CMS, состояние миграций и системную диагностику.
• Проверьте публичный сайт, вход в кабинет и доступность игровых баз.
• Убедитесь, что пользовательские данные и настройки сохранились.
• Посмотрите журнал обновления; сохраните бэкап до окончания проверки.

DANGER

Нельзя публиковать .env, пароли, APP_KEY или резервные копии в GitHub Issues и публичных чатах.

Техническая документация обновления