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

Описание

Система автоматического обновления MmoWeb Client реализует механизм безопасного развёртывания новых версий приложения через GitHub Releases API. Система поддерживает автоматическое резервное копирование, поэтапное применение изменений и отслеживание прогресса обновления в реальном времени.

Архитектура системы

Основные компоненты

UpdateService (Class/Services/UpdateService.php)
- Центральный сервис управления обновлениями
- Отвечает за скачивание, распаковку и применение релизов
Repository (Class/GitHub/Repository.php)
- Абстракция работы с GitHub API
- Обработка запросов к репозиторию и релизам
ApiController (Controllers/ApiController.php)
- HTTP endpoints для удалённого управления обновлениями
- Методы: updater_check_connection, install_update, get_version, get_updater_process_progress
Cache система
- Хранилище состояния процесса обновления
- Кеширование прогресса выполнения

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

1. Инициализация

Вызов API endpoint

POST /api/install_update
Content-Type: application/x-www-form-urlencoded

hash={HMAC_SHA256_SIGNATURE}&tag=v1.2.3

Валидация

Проверка версии PHP (только 7.4.33)
Проверка соединения с GitHub API
Проверка конфигурации версии
Проверка отсутствия активного процесса обновления

Генерация процесса

Создаётся уникальный process_key (SHA256 хеш)
Устанавливается статус CREATED
Возвращается process_key клиенту

Файл: UpdateService.php:82-104

2. Создание директории процесса

Расположение: Files/update/{process_key}/

Структура директории:

Files/update/{process_key}/
├── backup.zip          # Полный бекап текущей версии
└── {tag}.zip          # Скачанный релиз с GitHub

Файл: UpdateService.php:106-127

3. Создание резервной копии

Параметры бекапа

Путь: Files/update/{process_key}/backup.zip
Метод: Рекурсивная архивация через ZipArchive
Исключения:
- Директория Files/update/ (любые процессы обновления)
- Архивы: .zip, .rar, .7z, .tar, .gz, .bz2, .xz, .tgz
- Символические ссылки
- Нечитаемые файлы

Алгоритм

Сканирование всех файлов от ROOT_DIR
Фильтрация по критериям исключения
Добавление файлов и директорий в ZIP с сохранением структуры
Проверка целостности (размер > 0 байт)

Время выполнения: зависит от размера проекта (обычно 5-30 секунд)

Файл: UpdateService.php:233-312

4. Загрузка релиза

Источник

URL: {release.zipball_url} из GitHub API
Таймаут: 2100 секунд (35 минут)

Механизм загрузки

curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 2100);
curl_setopt($ch, CURLOPT_FAILONERROR, true);

Путь сохранения

Files/update/{process_key}/{tag}.zip

Файл: UpdateService.php:129-179

5. Анализ изменений коммита

Получение списка файлов

Система запрашивает все файлы из коммита релиза через GitHub API:

GET /repos/{owner}/{repo}/commits/{sha}?page={N}

Пагинация

Обрабатываются все страницы (max 50)
Паузы между запросами: 250ms (usleep(250000))

Типы изменений файлов

added - новый файл
modified - изменённый файл
renamed - переименованный файл (обрабатывается как копирование)
removed - удалённый файл (логируется, но НЕ удаляется локально)

Файл: UpdateService.php:345-390

6. Применение изменений

Процесс обработки файлов

Для каждого файла из коммита:
1. Определить путь в архиве: {releaseFolder}/{filename}
2. Проверка ZIP Slip атак (путь не должен содержать `..` или абсолютные пути)
3. Применить операцию согласно статусу
4. Обновить progress
5. Отправить прогресс в Global API (каждые 3 секунды)

Метод извлечения файла

Атомарная операция:

Создание временного файла {targetPath}.tmp
Копирование потока из ZIP в временный файл
Установка прав 0644
Атомарная замена через rename()

Безопасность:

Автоматическое создание директорий с правами 0755
Откат при ошибке (удаление .tmp)

Файл: UpdateService.php:604-631

7. Завершение процесса

При успешном обновлении

Статус устанавливается в COMPLETED

Обновляется конфигурация version.json:

{
    "tag": "v1.2.3",
    "timestamp": "2026-01-15T12:34:56Z",
    "release_id": 123456
}

Очистка кеша (если DEBUG = false):
- update_progress_{process_key}
- update

Файл: UpdateService.php:548-563

При ошибке

Статус устанавливается в FAILED
Запись в лог с полным трейсом ошибки
Отправка ошибки в Global API
Бекап остаётся нетронутым в Files/update/{process_key}/backup.zip

Файл: UpdateService.php:565-574

Логирование

Расположение логов

Директория: Files/logs/

Формат имени:

update_{Y-m-d_H-i}_{first_8_chars_of_process_key}.log

Пример:

update_2026-02-14_15-30_115abb9f.log

Содержимое логов

Стандартная информация

Начало установки релиза
Создание директории процесса
Загрузка ZIP файла
SHA коммита релиза
Создание бекапа
Обработка каждого файла (статус и путь)
Прогресс обновления (% выполнения)
Окончание процесса

Debug информация (если DEBUG = true)

Системная информация:

=== System information ===
[PHP]
Version: 8.1.2
SAPI: fpm-fcgi

[Environment]
OS: Linux
Architecture: 64-bit

[Limits]
Memory limit: 256M
Max execution time: 1800
Upload max filesize: 2M
Post max size: 8M

[Extensions]
- Core: unknown
- date: 8.1.2
- zip: 1.20.0
...
==========================

Файл: UpdateService.php:633-639, 314-343

Критические ошибки

Обработчик Shutdown

Регистрируется на старте обновления и отлавливает фатальные ошибки:

E_ERROR
E_PARSE
E_CORE_ERROR
E_COMPILE_ERROR
E_USER_ERROR

При фатальной ошибке:

Пишется в лог с префиксом FATAL ERROR:
Кеш устанавливается в FAILED
Уведомление отправляется в Global API

Файл: UpdateService.php:182-231

Управление состоянием

Кеширование статуса

Ключ кеша: update

Структура:

[
    'status' => 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'CREATED',
    'process_key' => '{SHA256_HASH}'
]

TTL: 1800 секунд (30 минут)

Файл: UpdateService.php:92-104

Кеширование прогресса

Ключ кеша: update_progress_{process_key}

Значение: Float (0.00 - 100.00)

TTL: 600 секунд (10 минут)

Обновление: При обработке каждого файла

Пример файла: cache/update_progress_{hash}.txt

a:3:{
    s:4:"time";i:1770805760;
    s:3:"ttl";i:600;
    s:4:"data";d:100;  // progress = 100.0
}

Файл: UpdateService.php:532-533

API Endpoints

1. Проверка соединения

Endpoint: POST /api/updater_check_connection

Проверки:

Валидность конфигурации версии
PHP = 7.4.33
Соединение с GitHub API

Ответы:

// Успех
{
    "result_code": "CHECK_SUCCESS",
    "metadata": {}
}

// Ошибка версии PHP
{
    "result_code": "PHP_VERSION_ERROR",
    "metadata": {
        "current_version": "7.3.0",
        "minimum_version": "7.4.33"
    }
}

Файл: ApiController.php:432-475

2. Установка обновления

Endpoint: POST /api/install_update

Параметры:

tag (required) - тег релиза (например, v1.2.3)
process_key (optional) - ключ процесса при продолжении

Двухэтапный процесс:

Этап 1: Создание процесса

POST /api/install_update
tag=v1.2.3

Ответ:

{
    "result_code": "PROCESS_CREATED",
    "metadata": {
        "process_key": "115abb9f3a36cfbb5d8988ed6ac7bb74d930af6572e26bbdb23c964f8f5b453e"
    }
}

Этап 2: Выполнение обновления

POST /api/install_update
tag=v1.2.3&process_key=115abb9f...

Ответ при успехе:

{
    "result_code": "INSTALL_SUCCESS",
    "metadata": {}
}

Ответ при ошибке:

{
    "result_code": "INSTALL_FAILED",
    "metadata": {
        "error": "Failed to open ZIP file..."
    }
}

Файл: ApiController.php:477-572

3. Получить текущую версию

Endpoint: POST /api/get_version

Ответ:

{
    "result_code": "CURRENT_VERSION",
    "metadata": {
        "version": "v1.2.3"
    }
}

Файл: ApiController.php:574-590

4. Получить прогресс обновления

Endpoint: GET /api/get_updater_process_progress?process_key={key}

Ответ:

{
    "result_code": "PROGRESS_RETRIEVED",
    "metadata": {
        "progress": 45.67
    }
}

Файл: ApiController.php:592-630

Обработка ошибок и recovery

Типовые ошибки

1. Обновление уже запущено

Статус: 423 Locked

{
    "result_code": "UPDATE_IN_PROGRESS",
    "metadata": {}
}

Решение: Дождаться завершения текущего процесса или проверить статус в кеше

2. Тег уже установлен

Exception: The specified tag is already installed.

Решение: Проверить текущую версию через /api/get_version

3. Проблемы с GitHub API

Возможные причины:

Неверный токен авторизации
Rate limiting
Таймаут соединения
Несуществующий релиз/тег

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

Проверить логи Debug/github.log
Проверить конфигурацию Library/configs/github.json
Тест соединения: /api/updater_check_connection

Файл: Repository.php:53-115

4. Ошибка создания бекапа

Возможные причины:

Недостаточно места на диске
Нет прав на запись в Files/update/
Исчерпана память PHP (memory_limit)

Решение:

Проверить свободное место: df -h
Проверить права: ls -la Files/
Увеличить memory_limit в php.ini (по умолчанию устанавливается 256M)

Файл: UpdateService.php:233-312

5. Битый ZIP файл

Exception: Failed to open ZIP file... The file may be corrupted.

Решение:

Проверить файл вручную: unzip -t Files/update/{process_key}/{tag}.zip
Удалить процесс и повторить обновление
Проверить стабильность сетевого соединения

Файл: UpdateService.php:449-451

6. ZIP Slip атака

Exception: ZIP Slip detected: invalid path: ...

Причина: Попытка записи файла за пределы ROOT_DIR

Защита: Проверка на наличие .. или абсолютных путей в именах файлов

Файл: UpdateService.php:492-497

Восстановление из бекапа

Автоматическое восстановление

При ошибке процесс останавливается, но откат не производится автоматически.

Ручное восстановление

Найти директорию последнего обновления:
```
ls -lt Files/update/ | head -n 2
```
Проверить наличие бекапа:
```
ls -lh Files/update/{process_key}/backup.zip
```

Распаковать бекап:

# НЕ ИСПОЛЬЗУЙТЕ unzip напрямую в продакшене!
# Создайте скрипт восстановления:

cd /path/to/project
unzip -o Files/update/{process_key}/backup.zip

Проверить права доступа:

find . -type f -exec chmod 644 {} \;
find . -type d -exec chmod 755 {} \;

Очистить кеш обновления:
```
rm -f Files/cache/update*
```

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

Аутентификация API (клиентская часть)

Все API endpoints используют HMAC-SHA256 подпись:

// Генерация подписи
ksort($_POST);
$signature = hash_hmac('sha256', json_encode($_POST), API_KEY);
$_POST['hash'] = $signature;

Константа: API_KEY из Config.php

Файл: ApiController.php:14-44

Защита от атак

1. ZIP Slip Protection

Проверка всех путей файлов на наличие:

.. (выход за пределы директории)
Абсолютных путей (/, \, C:)

2. Игнорирование пользовательского прерывания

ignore_user_abort(true);

3. Ограничения выполнения

Таймаут: 1800 секунд (30 минут)
Память: 256MB
Umask: 0022 (права по умолчанию)

Файл: UpdateService.php:395-400

Конфигурация GitHub

Файл: Library/configs/github.json

{
    "api_base_uri": "https://api.github.com",
    "repository_path": "PlaygridDev/playgrid-client",
    "token": "",
    "timeout": 15
}

Файл: Repository.php:21-36

Производительность

Таймауты

Операция

Таймаут

Конфигурация

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

1800 сек (30 мин)

PROCESS_EXECUTE_TIMEOUT

Загрузка ZIP с GitHub

2100 сек (35 мин)

CURLOPT_TIMEOUT

GitHub API запрос

15 сек

Repository->timeout

Пауза между запросами коммитов

250 мс

usleep(250000)

Оптимизация

1. Прогресс-репортинг с дебаунсом

Отправка прогресса в Global API происходит не чаще 1 раза в 3 секунды:

if ($sendedProgressTime === 0 || (time() - $sendedProgressTime) >= 3) {
    $this->globalApi->sendUpdaterProcessProgress($this->processKey, $progress);
    $sendedProgressTime = time();
}

Файл: UpdateService.php:536-539

2. Потоковая обработка файлов

Использование stream_copy_to_stream() вместо загрузки в память:

$stream = $zip->getStream($archivePath);
stream_copy_to_stream($stream, $out);

Файл: UpdateService.php:607-617

Мониторинг

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

// Проверить активность процесса
$status = Cache::get('update');
if ($status['status'] === 'IN_PROGRESS') {
    $processKey = $status['process_key'];
    $progress = Cache::get('update_progress_' . $processKey);
    echo "Прогресс: {$progress}%";
}

Проверка логов

# Найти последние логи обновлений
ls -lt Files/logs/update_* | head -n 5

# Просмотр активного процесса
tail -f Files/logs/update_2026-02-14_15-30_115abb9f.log

# Поиск ошибок
grep -i "error\|exception\|fatal" Files/logs/update_*.log

Конфигурационные файлы

version.json

{
    "tag": "v1.2.3",
    "timestamp": "2026-01-15T12:34:56Z",
    "release_id": 123456
}

Расположение: Library/configs/version.json

github.json

{
    "api_base_uri": "https://api.github.com",
    "repository_path": "PlaygridDev/playgrid-client",
    "token": "ghp_xxxxxxxxxxxxxx",
    "timeout": 15
}

Расположение: Library/configs/github.json

Troubleshooting

Проблема: Обновление зависло

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

Проверить статус процесса:
```
php -r "var_dump(Cache::get('update'));"
```
Проверить PHP процессы:
```
ps aux | grep php
```
Проверить последний лог:
```
tail -50 Files/logs/update_*.log | tail -n 50
```

Решение:

Если процесс завис > 30 минут - очистить кеш вручную
Проверить доступность GitHub API
Повторить обновление

Проблема: Недостаточно прав доступа

Симптомы:

Failed to create update process directory
Failed to add file to backup
Failed to replace file

Решение:

# Установить правильного владельца
chown -R www-data:www-data /path/to/project

# Установить права
find . -type f -exec chmod 644 {} \;
find . -type d -exec chmod 755 {} \;
chmod 775 Files/
chmod 775 Files/update/
chmod 775 Debug/
chmod 775 cache/

Проблема: GitHub API rate limit

Симптомы:

GitHub API returned error code 403: API rate limit exceeded

Решение:

Используйте Personal Access Token

Authenticated requests: 5000 req/hour
Unauthenticated: 60 req/hour

hashtagОписание

hashtagАрхитектура системы

hashtagОсновные компоненты

hashtagПроцесс обновления

hashtag1. Инициализация

hashtag2. Создание директории процесса

hashtag3. Создание резервной копии

hashtag4. Загрузка релиза

hashtag5. Анализ изменений коммита

hashtag6. Применение изменений

hashtag7. Завершение процесса

hashtagЛогирование

hashtagРасположение логов

hashtagСодержимое логов

hashtagКритические ошибки

hashtagУправление состоянием

hashtagКеширование статуса

hashtagКеширование прогресса

hashtagAPI Endpoints

hashtag1. Проверка соединения

hashtag2. Установка обновления

hashtag3. Получить текущую версию

hashtag4. Получить прогресс обновления

hashtagОбработка ошибок и recovery

hashtagТиповые ошибки

hashtagВосстановление из бекапа

hashtagБезопасность

hashtagАутентификация API (клиентская часть)

hashtagЗащита от атак

hashtagКонфигурация GitHub

hashtagПроизводительность

hashtagТаймауты

hashtagОптимизация

hashtagМониторинг

hashtagПроверка статуса обновления

hashtagПроверка логов

hashtagКонфигурационные файлы

hashtagversion.json

hashtaggithub.json

hashtagTroubleshooting

hashtagПроблема: Обновление зависло

hashtagПроблема: Недостаточно прав доступа

hashtagПроблема: GitHub API rate limit

hashtagРекомендации для специалистов

hashtagPre-deployment checklist

hashtagPost-deployment checklist

Описание

Архитектура системы

Основные компоненты

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

1. Инициализация

2. Создание директории процесса

3. Создание резервной копии

4. Загрузка релиза

5. Анализ изменений коммита

6. Применение изменений

7. Завершение процесса

Логирование

Расположение логов

Содержимое логов

Критические ошибки

Управление состоянием

Кеширование статуса

Кеширование прогресса

API Endpoints

1. Проверка соединения

2. Установка обновления

3. Получить текущую версию

4. Получить прогресс обновления

Обработка ошибок и recovery

Типовые ошибки

Восстановление из бекапа

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

Аутентификация API (клиентская часть)

Защита от атак

Конфигурация GitHub

Производительность

Таймауты

Оптимизация

Мониторинг

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

Проверка логов

Конфигурационные файлы

version.json

github.json

Troubleshooting

Проблема: Обновление зависло

Проблема: Недостаточно прав доступа

Проблема: GitHub API rate limit

Рекомендации для специалистов

Pre-deployment checklist

Post-deployment checklist