Межрелизные патчи и обращение в поддержку

Это руководство описывает полный цикл работы с исправлениями сервера LSUS между релизами: как собрать диагностические логи при возникновении проблемы, куда направить обращение, как получить и применить патч через веб-админку, и что делать, если веб-админка недоступна — применение через терминал.

Когда нужен патч¶

Типовые ситуации, когда вендор выпускает межрелизный патч:

• После обновления сервера до нового релиза проявилась регрессия (медленнее работает вкладка, ошибки, зависания).
• Обнаружена ошибка в текущей версии, исправление которой не дождётся следующего релиза.
• Требуется оперативное устранение проблемы производительности или доступности сервера.

В таких случаях вендор готовит патч .lsuspatch под конкретную версию сервера и передаёт его через портал поддержки.

Шаг 1. Собрать диагностические логи¶

При обращении в поддержку обычно требуются логи сервера. LSUS умеет собирать их в один архив.

Через веб-админку¶

1. Откройте Администрирование → Поддержка.
2. Найдите блок «Диагностика и логи».
3. Нажмите кнопку «Скачать логи за сутки».

Сервер соберёт ZIP-архив с логами за последние 24 часа, и скачивание начнётся автоматически. Имя файла — вида lsus-master-diagnostics-<дата>-<время>.zip.

Что входит в архив:

• логи приложения (lsus-server.log, lsus-server-errors.log);
• access-логи админки и клиентских запросов;
• логи фонового worker-процесса и репликации;
• логи nginx (access и error);
• сводка переменных окружения LSUS_* (значения ключей, содержащих PASSWORD/SECRET/TOKEN, замаскированы — конфиденциальные данные не попадают в архив);
• метаданные: роль сервера, время сбора, настройки логирования.

Через терминал (если веб-админка недоступна)¶

Если веб-админка не отвечает, соберите логи вручную. Логи сервера хранятся в /var/log/lsus-server/ внутри контейнера, что на хосте Docker соответствует /opt/lsus-docker/data/master/log/.

# Архив логов сервера (на хосте Docker)
sudo tar -czf /tmp/lsus-logs-$(date +%Y%m%d).tar.gz \
    -C /opt/lsus-docker/data/master/log .

# Логи контейнеров (stdout/stderr) за последние сутки
sudo docker logs --since 24h lsus-master > /tmp/lsus-master-stdout.log 2>&1
sudo docker logs --since 24h lsus-master-worker > /tmp/lsus-worker-stdout.log 2>&1

# Дополнительно: версия сервера и состояние контейнеров
sudo docker ps --format '{{.Names}}\t{{.Status}}' > /tmp/lsus-containers.txt
curl -sk https://localhost/api/v1/health >> /tmp/lsus-containers.txt

Затем упакуйте всё вместе и передайте в поддержку.

Шаг 2. Обратиться в поддержку¶

Обращения обрабатываются через портал поддержки LSUS.

1. Перейдите на портал: https://portal.lsus.ru.
2. Создайте обращение, описав проблему: что произошло, при каких действиях, версия сервера (видна в шапке админки LSUS или по запросу /api/v1/health).
3. Прикрепите диагностический архив, собранный на шаге 1.

Поддержка проанализирует логи, воспроизведёт проблему и подготовит патч .lsuspatch под вашу версию сервера. Файл патча вернётся через тот же портал.

Шаг 3. Применить патч через веб-админку¶

Получив файл .lsuspatch от поддержки, примените его. Основной способ — через веб-админку.

Загрузка патча¶

1. Откройте Администрирование → Поддержка.
2. В блоке «Патчи сервера» нажмите «Обзор» и выберите файл .lsuspatch.
3. Нажмите «Загрузить».

Сервер проверит подпись патча, манифест и соответствие версии. Если патч подходит — он появится в таблице ниже со статусом «загружен». Если патч не подходит для текущей версии сервера — загрузка будет отклонена с понятным сообщением об ошибке.

Применение патча¶

1. В таблице патчей найдите загруженный патч.
2. Нажмите кнопку «Применить».
3. Подтвердите применение и перезапуск сервера.

Сервер применит патч (заменит файлы приложения, при необходимости выполнит SQL-миграции) и перезапустит стек. После перезапуска исправление вступит в силу.

Проверка¶

После перезапуска откройте Администрирование → Поддержка → Патчи сервера — применённый патч должен иметь статус «применён». Проверьте, что проблема устранена.

Откат патча (если исправление не помогло)¶

Если патч не решил проблему или вызвал новые неполадки, его можно отключить:

1. В таблице патчей найдите применённый патч.
2. Нажмите кнопку «Отключить».
3. Подтвердите отключение и перезапуск.

Сервер восстановит оригинальные файлы из резервной копии (созданной при применении) и перезапустит стек. Система вернётся к состоянию до патча.

Удаление патча¶

Чтобы удалить патч из списка — сначала отключите его, затем нажмите «Удалить». Удалить можно только отключённый (неприменённый) патч.

Шаг 4. Применить патч через терминал¶

Если веб-админка недоступна (сервер не отвечает, ошибка 500, контейнер не поднимается), патч можно применить из терминала на хосте сервера LSUS.

Основной способ — скрипт patch-offline-apply.sh¶

LSUS поставляется со скриптом офлайн-применения. Скачайте файл .lsuspatch от поддержки на хост сервера и выполните:

sudo bash /opt/lsus/scripts/patches/patch-offline-apply.sh /path/to/патч.lsuspatch

Что скрипт делает автоматически:

1. Кладёт архив в общий каталог данных (staged/, виден из всех контейнеров мастера).
2. В каждом контейнере стека (lsus-master, lsus-master-worker, lsus-master-replication) проверяет подпись, версию и накладывает файлы патча.
3. Перезапускает контейнеры — при старте применится SQL-часть патча и загрузится новый код.
4. Выводит состояние всех патчей.

Если нужно применить патч без перезапуска (например, чтобы перезапустить позже вручную):

sudo bash /opt/lsus/scripts/patches/patch-offline-apply.sh /path/to/патч.lsuspatch --no-restart

Если контейнеры остановлены¶

Если стек вообще не поднимается, скрипт запустит остановленные контейнеры, дождётся их инициализации и затем применит патч.

Если стек не поднимается даже после этого — положите архив .lsuspatch вручную в каталог staged/ на хосте (/opt/lsus-docker/data/master/patches/staged/) и поднимите стек с переменной LSUS_PATCH_OFFLINE_ENABLE=1 в файле .env. Активация патча произойдёт автоматически при старте контейнеров.

# 1. Положить архив в staged
sudo cp патч.lsuspatch /opt/lsus-docker/data/master/patches/staged/

# 2. Включить офлайн-активацию в .env
#    (добавьте или раскомментируйте строку)
#    LSUS_PATCH_OFFLINE_ENABLE=1

# 3. Поднять стек
cd /opt/lsus-docker
sudo docker compose -f docker-compose.yml --env-file .env --profile master up -d

Прямые команды в контейнере (для диагностики)¶

Для проверки содержимого патча без применения или ручного управления:

# Проверить патч (подпись, версию, состав) без изменений
sudo docker exec lsus-master python3 /app/patch_apply.py inspect /path/to/патч.lsuspatch

# Список всех патчей на сервере
sudo docker exec lsus-master python3 /app/patch_apply.py list

Как работает патч при применении¶

Чтобы понимать, что произойдёт с сервером, полезно знать механику:

1. Проверка безопасности. Перед применением проверяется цифровая подпись патча (Ed25519), корректность манифеста и соответствие версии сервера. Патч от стороннего источника или для другой версии применён не будет.
2. Замена файлов. Файлы из патча копируются поверх файлов приложения (например, модули Python, шаблоны, статика). Оригиналы сохраняются в резервную копию — для возможности отката.
3. SQL-миграции (если есть в патче) — выполняются однократно, под блокировкой, с защитой от повторного наката.
4. Перезапуск. Контейнеры/сервис перезапускаются, подхватывая новый код и миграции.

Применение идемпотентно: повторное применение уже активного патча ничего не ломает.

Где хранятся патчи¶

На хосте Docker-развёртывания патчи находятся в каталоге данных мастера:

/opt/lsus-docker/data/master/patches/
├── staged/      # загруженные, но ещё не применённые (.lsuspatch)
├── enabled/     # активированные патчи (накатываются при старте)
├── backup/      # резервные копии оригинальных файлов (для отката)
└── disabled/    # архивы отключённых патчей

Этот каталог примонтирован во все контейнеры мастера, поэтому патч, загруженный через веб-админку или скрипт, виден из каждого контейнера.

Журнал действий¶

Все операции с патчами фиксируются в журнале аудита сервера: загрузка, применение, отключение, удаление. Журнал доступен в разделе Администрирование → Журнал. Это позволяет отследить, кто и когда применил или откатил патч.

Частые вопросы¶

Связанные страницы¶

• Обновление системы LSUS — обновление сервера до нового релиза.
• Docker и образы — состав контейнеров сервера.
• Справочник портов и переменных — переменные окружения, включая LSUS_PATCH_OFFLINE_ENABLE.