Теневые модули и постепенный переход
Tip
Когда читать эту статью: при необходимости постепенного развертывания — одновременная пробная работа новой версии, сравнение поведения и принятие решения о переходе или откате. Если вам это не нужно, можете пропустить эту статью — это не повлияет на использование других функций.
Что вы узнаете: пять уровней изоляции теневых модулей, способ сопоставления поведения (
diff), процесс одобренного перехода (promote) и автоматического отката при сбое, а также границы, которые не могут быть пересечены фреймворком.В этой статье не рассматриваются: общие механизмы горячей перезагрузки и управления принадлежностью модулей (см. систему владельцев (owner)).
Теневой модуль = новая версия того же модуля, которая параллельно работает с текущей версией под отдельным владельцем (например, roll_shadow), получая копии реальных событий и перехватывая исходящие действия для учета, а не отправляя их наружу. Сравнение поведения двух версий происходит в shadow_diff. После подтверждения, что новая версия безопасна, можно выполнить promote, чтобы сразу принять её как основную, или dismiss, чтобы отказаться от неё в любой момент. Код модуля не изменяется, вся работа осуществляется с помощью API во время выполнения: такие же операции, как load / unload / reload, можно вызывать через Dashboard или пользовательские модули управления, без необходимости писать какие-либо конфигурационные параметры.
{!--< tips >!--}
- Запуск:
await sdk.module.shadow_start("roll", source="путь/к/v2")— новая версия кода работает параллельно со старой под отдельным владельцем (по умолчанию имя владельца берется из пути) - Теневой модуль не участвует в реальной маршрутизации и графе зависимостей: команды с одинаковыми именами выполняются в директории теневого модуля, маршрутизация регистрируется, но не привязывается, тихая трансляция жизненного цикла,
module.callи разрешение зависимостей по-прежнему указывают на v1 - Принятие решения о переходе всегда осуществляется человеком:
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 является лишь точкой вызова.
Связанные документы
- Система собственности (owner) — основа механизма изоляции теней с независимым собственником
- Взаимодействие сессии —
trace_idи ящик для входящих сообщений (источник данных с выравниванием по разнице) - Область видимости (scope) — контрольный интерфейс для входа и выхода событий