Перейти до основного вмісту
Версія: 2.0

Зовнішнє сховище даних

Зовнішнє сховище даних переносить великі дані workflow до підключуваного об’єктного сховища (S3, GCS, Azure Blob або локальної файлової системи) й замінює вбудовані байти в історії workflow невеликим перевірюваним конвертом посилання. Використовуйте його, коли аргументи activity чи дочірніх workflow, результати, signal або дані update завеликі для безпосереднього зберігання в записі бази даних, що містить історію workflow.

Runtime зберігає дані вбудовано, доки їхній закодований розмір менший за поріг namespace. Лише дані, що досягли порога, записуються через налаштований драйвер і потрапляють до історії як конверт durable-workflow.v2.external-payload-reference.v1. Replay та експорт історії відмовляють, якщо об’єкт за посиланням відсутній, змінений або перебуває поза налаштованим префіксом. Система ніколи непомітно не підставляє порожнє значення замість відсутнього об’єкта.

Коли використовувати​

Обирайте зовнішнє сховище даних, коли застосунок справді має передавати через workflow дані розміром понад кілька сотень кілобайт:

  • Обробка документів і медіа, яка передає PDF, зображення або аудіооб’єкти від однієї activity до наступної.
  • Звіти, експорти або архіви, кінцевий результат яких є великим серіалізованим файлом.
  • Дані потоків повідомлень із зовнішніх систем, які не надають стабільний URL об’єкта для прямого посилання з workflow.
  • Будь-які дані, які інакше перевищили б структурне обмеження payload_size_bytes.

Малі дані, як-от поля площини керування, ID, прапорці стану й типовий JSON, залишаються вбудованими без додаткових витрат. Політика діє лише після досягнення порога, тому ввімкнення зовнішнього сховища для namespace не переносить малі дані.

Як працює винесення даних​

Кожен namespace має незалежну політику зовнішнього сховища даних. Коли runtime кодує дані для стійкого зберігання, він порівнює кількість закодованих байтів із налаштованим threshold_bytes:

  • Закодований розмір менший за поріг. Дані зберігаються вбудовано, як і раніше. Історія не змінюється.
  • Закодований розмір дорівнює порогу або перевищує його. Runtime передає закодовані байти налаштованому драйверу, отримує URI, яким керує драйвер, і записує посилання на зовнішні дані в історію. Посилання містить URI, хеш SHA-256, точну довжину в байтах, кодек даних і необов’язкову підказку expires_at.

Під час replay worker отримують байти за посиланням через той самий драйвер, перевіряють очікувані розмір і SHA-256 об’єкта й лише тоді передають дані декодеру. Невідповідність розміру або хешу спричиняє ExternalPayloadIntegrityException (PHP) або ExternalPayloadIntegrityError (Python) і відображається як помилка replay, а не непомітні порожні дані.

Конверт посилання є стабільним форматом передавання. Він однаковий незалежно від того, хто створив дані: PHP workflow, worker Python SDK чи прямий клієнт HTTP API. Повний контракт полів наведено в розділі Конверт посилання на зовнішні дані.

Межа довіри декодування​

Зберігання й декодування даних мають окремі межі довіри. Об’єктне сховище може містити закодовані байти або посилання, а сервер кодеків, власний декодер, процес worker або засіб експорту історії, що декодує ці байти, може бачити дані застосунку у відкритому тексті.

Вважайте кожен сервер кодеків межею довіри, якою керує клієнт. Визначте, де він працює, яка мережа має доступ, які ключі йому доступні, які журнали аудиту він створює та як приховуються чутливі дані в декодованих переглядах перед показом оператору. Durable Workflow записує назви кодеків, URI посилань, хеші, розміри, відбитки схем і обмежені перегляди, але це не еквівалент наскрізного шифрування.

Вибір драйвера​

ДрайверСхема URIТипове використання
localfile://Локальна розробка, CI та однохостові розгортання, де сервер і worker використовують спільну файлову систему. Не підходить, якщо worker працюють на інших хостах.
s3s3://Amazon S3 та сумісні сховища, наприклад MinIO і Cloudflare R2, через диск файлової системи на сервері.
gcsgs://Google Cloud Storage через диск файлової системи на сервері.
azureazure://Azure Blob Storage через диск файлової системи на сервері.

Драйвери об’єктних сховищ налаштовують облікові дані bucket/container через іменований диск файлової системи на сервері. Тому секрети перебувають у конфігурації сервера, а не в записі політики namespace.

Налаштування namespace​

Налаштуйте політику через CLI або HTTP API сервера. Обидва записують той самий конверт external_payload_storage у запис namespace.

Через CLI​

# Production namespace using Amazon S3 through the 'external-payload-objects' disk.
dw namespace:set-storage-driver billing s3 \
  --disk=external-payload-objects \
  --bucket=dw-payloads \
  --prefix=billing/ \
  --threshold-bytes=2097152

# Development namespace using the local filesystem.
dw namespace:set-storage-driver dev local \
  --uri=file:///var/lib/durable-workflow/payloads

# Disable offload while keeping the policy record (all payloads stay inline).
dw namespace:set-storage-driver billing s3 \
  --disk=external-payload-objects \
  --bucket=dw-payloads \
  --disable

Через API сервера​

curl -sS -X PUT "$DURABLE_WORKFLOW_SERVER_URL/api/namespaces/billing/external-storage" \
  -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \
  -H "X-Durable-Workflow-Control-Plane-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "driver": "s3",
    "threshold_bytes": 2097152,
    "config": {
      "disk": "external-payload-objects",
      "bucket": "dw-payloads",
      "prefix": "billing/"
    }
  }'

Опис namespace, повернений GET /api/namespaces/{name} або dw namespace:describe, містить визначений конверт external_payload_storage, щоб оператори й автоматизація могли перевірити активну політику без повторного запису.

Перевірка політики​

Перед допуском трафіку workflow використовуйте діагностику повного циклу, щоб довести, що налаштована політика справді може записувати й читати байти з обліковими даними namespace:

dw storage:test --namespace=billing --large-bytes=2097152 --json

Діагностика записує малі вбудовані дані й одні дані, що досягли порога, повторно отримує обидва набори, перевіряє розмір і SHA-256 та повертає машиночитані об’єкти результатів small_payload і large_payload. Успішний результат великих даних доводить, що драйвер може створити чинний конверт durable-workflow.v2.external-payload-reference.v1 у повному циклі. Помилка діагностики означає проблему політики сховища. Не допускайте трафік workflow через namespace, політика якого не проходить перевірку запису й читання.

Вибір порога​

Типово дані залишаються вбудованими до досягнення threshold_bytes. Орієнтири для початкового налаштування:

  • Обирайте поріг, за якого вбудовані дані починають створювати операційне навантаження: зазвичай від 256 KiB до 2 MiB закодованих байтів.
  • Залишайте достатній запас до структурного обмеження namespace payload_size_bytes, щоб ліміт застосовувався до конверта посилання, а не до самих зовнішніх байтів.
  • Задавайте один поріг для namespace. Обирайте його за activity або workflow, що створює найбільше байтів на запуск, а не за медіанними даними.

Надто низький поріг не дає переваги: малі дані швидше проходять цикл через базу даних, ніж через зовнішнє сховище, а сам конверт посилання також займає невелику частину історії.

Replay, зберігання й очищення​

  • Цілісність replay. Кожне отримання перевіряє збережений об’єкт за size_bytes та sha256 посилання. Змінений або відсутній об’єкт спричиняє виняток цілісності замість непомітного підставлення іншого значення.
  • Кеш перевірених даних. Worker кешують перевірені байти за (uri, sha256, size, codec) з обмеженнями кількості записів і розміру. Повторне читання історії того самого запуску не завантажує об’єкт знову, зберігаючи перевірку цілісності під час першого завантаження.
  • Зберігання. Коли серверний прохід retention видаляє запуск workflow, він також видаляє зовнішні об’єкти даних, на які посилається його історія. За працюючого retention об’єкти без посилань не накопичуються.
  • Експорт історії. Експортована історія зберігає конверт посилання. Downstream-споживачі, яким потрібні зовнішні байти, мають отримати їх через той самий драйвер і перевірити за конвертом перед декодуванням. Формат експорту не вбудовує зовнішні байти.

Використання з коду​

Більшість застосунків не викликають API сховища безпосередньо: runtime прозоро виносить дані за політикою namespace, а SDK декодує посилання під час replay. Застосунки, які мають створювати або споживати конверти поза runtime, наприклад мовно-незалежний обробник мосту або тест із синтезованими великими даними, використовують допоміжні функції SDK.

  • PHP (пакет workflow). Допоміжний клас Workflow\V2\Support\ExternalPayloadStorage зберігає й отримує байти через будь-який драйвер, що реалізує Workflow\V2\Contracts\ExternalPayloadStorageDriver. LocalFilesystemExternalPayloadStorage обробляє URI file://. Окремий сервер постачається з драйвером диска файлової системи, який підтримує драйвери політики s3, gcs та azure через іменований диск Laravel.
  • Python SDK. Розділ Зовнішнє сховище даних описує ExternalPayloadReference, ExternalPayloadCache, store_external_payload(), fetch_external_payload() та адаптери LocalFilesystemExternalStorage, S3ExternalStorage, GCSExternalStorage і AzureBlobExternalStorage. Клієнтами хмарних SDK керує застосунок. SDK не додає boto3, google-cloud-storage або azure-storage-blob як залежності runtime.
  • Прямий HTTP. HTTP-клієнти, які кодують дані вручну, можуть зберегти байти через драйвер, а потім передати конверт посилання в полі даних запиту. Конверт даних протоколу worker ({codec, blob}) також містить посилання для аргументів activity, результатів, даних signal та update.

Дивіться також​