ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Теневые модули и постепенный переход

Tip

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

Что вы узнаете: пять уровней изоляции теневых модулей, способ сопоставления поведения (diff), процесс одобренного перехода (promote) и автоматического отката при сбое, а также границы, которые не могут быть пересечены фреймворком.

В этой статье не рассматриваются: общие механизмы горячей перезагрузки и управления принадлежностью модулей (см. систему владельцев (owner)).

Теневой модуль = новая версия того же модуля, которая параллельно работает с текущей версией под отдельным владельцем (например, roll_shadow), получая копии реальных событий и перехватывая исходящие действия для учета, а не отправляя их наружу. Сравнение поведения двух версий происходит в shadow_diff. После подтверждения, что новая версия безопасна, можно выполнить promote, чтобы сразу принять её как основную, или dismiss, чтобы отказаться от неё в любой момент. Код модуля не изменяется, вся работа осуществляется с помощью API во время выполнения: такие же операции, как load / unload / reload, можно вызывать через Dashboard или пользовательские модули управления, без необходимости писать какие-либо конфигурационные параметры.

{!--< tips >!--}

  1. Запуск: await sdk.module.shadow_start("roll", source="путь/к/v2") — новая версия кода работает параллельно со старой под отдельным владельцем (по умолчанию имя владельца берется из пути)
  2. Теневой модуль не участвует в реальной маршрутизации и графе зависимостей: команды с одинаковыми именами выполняются в директории теневого модуля, маршрутизация регистрируется, но не привязывается, тихая трансляция жизненного цикла, module.call и разрешение зависимостей по-прежнему указывают на v1
  3. Принятие решения о переходе всегда осуществляется человеком: await sdk.module.promote_shadow("roll"), при сбое происходит автоматический откат к старой версии; dismiss_shadow позволяет в любой момент отказаться от теневого модуля {!--< /tips >!--}

Быстрый старт

# Код v2: обычный модуль, без теневого режима (любой каталог, например downloads/roll_v2/)
# В онлайн-боте (через Dashboard / модуль управления), запуск грейд-теста одной строкой:
await sdk.module.shadow_start("roll", source="downloads/roll_v2")
# → Теневой модуль с отдельным owner "roll_v2" параллельно работает с v1, исходящие сообщения перехватываются и записываются

# Сравнение поведения во время тестирования:
report = sdk.module.shadow_diff("roll")
# {"shadow_owner": "roll_v2", "count": 3, "aligned": [...]}
  • v1 фактическая отправка: из бот-таймлайна в инбоксе (transcript)
  • v2 предполагаемая отправка: теневой отчёт (запись в исходящем трафике о "что хотели отправить")
  • Оба сопоставляются по trace_id — для одного и того же сообщения, почему один и другой вариант сработали/не сработали, что хотели отправить/что отправили — всё видно

После проверки без ошибок:

await sdk.module.promote_shadow("roll")   # Промоутить, при ошибке автоматически откатить к v1
await sdk.module.dismiss_shadow("roll")   # Или отменить теневой режим

Пять изолирующих барьеров

Барьер Механизм
Копия события Теневой обработчик получает независимую копию события (с меткой shadow) — изменения / признание / остановка распространения теневого события влияют только на копию, не затрагивая оригинальную цепочку событий
Выходная дверь Все вызовы DSL Send и Api теневого события перехватываются и регистрируются (возвращается фиктивный ответ), событие не отправляется наружу — теневой обработчик не будет повторно отвечать
Слой перекрытия хранилища Запись KV теневого события происходит в слое перекрытия в памяти и не сохраняется в базу данных; чтение сначала проверяет слой перекрытия, при неудаче — обращается к реальной базе данных (灰度 процесс работает с реальными данными); удаление помечается как "могильный камень"
Блокировка маршрутизации HTTP/WS/SSE маршруты теневого события регистрируются, но не подключаются; команды с тем же именем записываются в каталог теневых команд, методы платформенных событий запрещены к вставке
Тихий жизненный цикл Теневой обработчик не транслирует собственные события жизненного цикла и не участвует в экосистемной зависимости (вызовы module.call и разрешение зависимостей по-прежнему указывают на v1, чтобы избежать зависимости от незавершённого продукта)

Наследование конфигурации: теневой обработчик по умолчанию наследует конфигурационные разделы оригинального модуля (иначе серая версия будет отличаться от оригинала), после перевода в основной режим конфигурация применяется на месте.

Честные границы (не остановить)

  • Отправка / API / хранилище KV / единый HTTP-клиент через фреймворк всё можно остановить; модули, обходящие фреймворк, запускают aiohttp напрямую, создают потоки и пишут во внешние системы — фреймворк не может остановить
  • Чтение и запись ORM не входят в область покрытия (по строкам overlay невозможно реализовать чисто на уровне SQL) — в период теневого режима рекомендуется избегать зависимости от ORM для обеспечения изоляции
  • Источник теневого режима — локальный путь: новая версия кода импортируется по пути, загружается отдельным владельцем; один и тот же пакет PyPI в одном и том же интерпретаторе ограничен ключом sys.modules, не позволяя одновременно использовать две версии
  • Аудитор утечек (sdk.module.audit) видит принадлежность теневых ресурсов; побочные эффекты от обхода фреймворка по крайней мере не будут бесшумными

Промоут и откат

Процесс promote: создание снимка текущей версии (включая каскадные зависимости) → полное удаление → регистрация теневого экземпляра с настоящим именем
При сбое на любом этапе происходит автоматический откат, старый экземпляр продолжает обслуживать запросы (гарантируется семантика "по возможности": необратимые побочные эффекты, выполненные в on_unload, не могут быть отменены, после отката старый экземпляр находится в состоянии завершения). Промоутированные ресурсы теневого экземпляра утилизируются, связь разрывается; конфигурационный раздел оригинального модуля применяется на месте.

Напоминание о сохранении: promote — это переключение в режиме выполнения — после перезапуска будет использоваться v2, необходимо сохранить новую версию (установка новой версии с помощью pip install -U / замена файла плагина). Переключение в режиме выполнения не заменяет управление пакетами. Панель управления "Промоутить и сохранить" автоматически установит загруженный whl-файл после успешного промоута, автоматизируя этот процесс; обычный promote не сохраняет файлы.

Три жёстких границы

Граница Описание
pip-исключительность В теневом режиме распаковка без установки: whl-файл сохраняется в shadows/<module>/, используется только для последующей фиксации; во время теневого запуска pip-установка не происходит, предотвращая перезапись уже установленных пакетов и тем самым избегая изменения поведения в проде
promote-без-записи promote_shadow производит только переключение в режиме выполнения, не изменяя пакетный менеджер; после перезапуска возвращается к v1 (в конфигурации по-прежнему указывается на старую версию). Для сохранения v2 после перезапуска используйте «фиксацию и сохранение» или вручную выполните pip install
Зависимости сторонних библиотек = версия в процессе Теневый импорт сторонних библиотек использует уже установленную версию в текущем процессе; новые зависимости, объявленные в whl, не устанавливаются автоматически, при отсутствии зависимостей теневая загрузка завершится ошибкой (ошибка будет брошена без изменений)

Для whl-поглощения, list_shadows и «фиксации и сохранения» (shadow_ingest_whl / shadow_promote_persist / shadow_persist_status) требуется ErisPulse 2.12+; старые версии SDK автоматически понижаются до базового теневого режима (только распаковка и запуск, без сохранения), обнаружение возможностей Dashboard происходит автоматически.

Интерфейс для администрирования: sdk.module.list_shadows() возвращает текущие привязки в виде {имя_модуля: имя_владельца_теневого_режима}, для использования в Dashboard или скриптах.

Реализация whl-поглощения и «фиксации и сохранения» принадлежит SDK: распаковка, сохранение и управление pip-установкой соответствуют эволюции версии SDK, Dashboard является лишь точкой вызова.

Связанные документы