← Sandbox SDK / sandbox / 1-0-preview
Жизненный цикл песочницы
Ваше приложение обращается к sandbox с помощью ID песочницы. Среда Linux, в которой выполняются команды и хранятся локальные файлы, представляет собой контейнер. Идентификатор может существовать дольше, чем любой отдельный контейнер.
Это различие важно для процессов, терминалов, файлов и восстановления после остановки из-за простоя или замены.
ID песочницы и контейнер
Большинство приложений используют одну песочницу на пользователя или задачу:
const sandbox = getSandbox(env.Sandbox, "user-123");const sandbox = getSandbox(env.Sandbox, "user-123");| Значение | |
|---|---|
| ID песочницы | Строка, которую вы передаёте в getSandbox (например, "user-123"). Используйте тот же ID, чтобы позже снова обратиться к той же песочнице. |
| Durable Object | Координатор, стоящий за этим ID. Один и тот же ID всегда соответствует одному и тому же экземпляру Durable Object. |
| Контейнер | Текущий Containers экземпляр, который выполняет работу Linux для песочницы. |
| Процесс или терминал | Программа или интерактивный PTY внутри текущий контейнер. |
| Локальные файлы | Файлы на диске этого контейнера (например, в /workspace). |
Одинаковый ID песочницы не означает тот же контейнер. После остановки или замены контейнера следующая задача с этим ID может выполняться уже в новом контейнере.
Когда контейнер запускается
getSandbox() возвращает управление немедленно. Сам по себе он не запускает контейнер.
Контейнер запускается, когда операция требует его использования, например exec(), createTerminal(), или записи файла. Первый запуск после развёртывания или простоя может занять больше времени, чем обращение к уже прогретому контейнеру. Если контейнер ещё не готов, SDK может выбросить ContainerUnavailableError. Эта ошибка означает, что операция не запустилась внутри контейнера. См. Ошибки и восстановление.
Пока контейнер работает
Пока контейнер активен для данного sandbox ID:
- Процессы и терминалы продолжают работать, пока не завершатся сами или пока вы их не остановите.
- Локальные файлы остаются доступными в этом контейнере.
- Последующие запросы Worker могут вызывать
getProcessилиgetTerminalи продолжить, если который контейнер всё ещё содержит этот ресурс.
Детали процесса: Сколько живёт процесс. Терминалы: Терминалы.
Когда контейнер останавливается или заменяется
Контейнер не является постоянным. Cloudflare может остановить его после периода бездействия. Он также может остановиться из-за сбоев или когда платформа заменяет его в ходе штатных операций (например, после некоторых развёртываний).
Когда это происходит:
- Ваше приложение по-прежнему использует тот же sandbox ID.
- Процессы и терминалы из старого контейнера исчезают вместе со своими ID и текущими буферами логов.
- Локальные файлы из старого контейнера теряются, если только приложение не восстановило их (например, с помощью резервная копия или смонтированный bucket).
- Следующая реальная задача может запустить новое контейнер для того же ID песочницы.
- Дескрипторы от предыдущего контейнера перестают работать по принципу fail closed.
getProcessиgetTerminalвозвращатьnullкогда ресурс отсутствует в текущем контейнере. Эти запросы не запускают контейнер только для того, чтобы ответить на вопрос.
Чтобы продолжить работу позже, сохраните задача (что запускать, cwd, env, и любую контрольную точку приложения), а не только ID процесса или терминала.
Остановка при простое, замена и удаление
| Событие | Что остаётся | Что удалено |
|---|---|---|
| Остановка при простое | ID песочницы и идентичность Durable Object | Процессы, терминалы и локальные файлы из остановленного контейнера |
| Замена (сбой, развёртывание или другая замена) | ID песочницы и идентичность Durable Object | Аналогично остановке по простою для предыдущего контейнера |
destroy() |
Строку ID песочницы можно использовать повторно позже | Считайте предыдущую работу для этого поколения завершённой |
После остановки из-за простоя или замены следующая реальная задача может запустить новое контейнер для того же ID песочницы. Старые хендлы процессов и терминалов становятся недействительными. Процедуры восстановления: Ошибки и восстановление.
keepAlive и sleepAfter изменяют поведение простоя. Они не сохраняют один и тот же экземпляр контейнера навсегда. См. раздел о стабильном API жизненного цикла и Параметры песочницы (игнорировать параметры transport и default-session в @next).
Состояние, которое переживает контейнер
Только то, что ваше приложение сохраняет (или восстанавливает) то, что переживает новый контейнер:
| Требуется | Что должно находиться вне контейнера |
|---|---|
| Найдите песочницу снова | ID песочницы |
| Продолжение работы при следующем запросе | ID ресурса пока текущий контейнер всё ещё содержит его, а также достаточно контекста задачи, чтобы запустить её заново, если это не так |
| Устойчивость к остановке или замене | задача: настройка команды или терминала, cwd, env, контрольная точка |
| Сохраняйте файлы после создания нового контейнера | Метаданные резервных копий, конфигурация монтирования или другое постоянное хранилище |