← Sandbox SDK / sandbox / 1-0-preview

Миграция

Прежде чем начать

Работайте в ветке или в staging-развёртывании. Завершите шаги миграции кода из этого руководства, а затем переключите продакшен одним деплоем.
Учитывайте, что переключение занимает короткое время простоя. Работающие процессы, терминалы и другие задачи в контейнере останавливаются, когда новый образ заменяет старый.
Составьте список мест вызова в Worker:
- Команды: exec, execStream, startProcess, строковые сигналы завершения, stdin процесса
- Сессии и транспорт: createSession, enableDefaultSession, SANDBOX_TRANSPORT, setTransport
- Терминалы: sandbox.terminal, сессия terminal(), xterm sessionId
- Interpreter: createCodeContext / runCode на чистом Sandbox
- Git: gitCheckout

Если вам всё ещё нужна предварительная очистка stable-line (RPC-транспорт, exposePort, вспомогательные функции для потоков), завершите Миграция в связи с прекращением поддержки в 2026 году, затем вернитесь сюда.

Что вы измените

Стабильная поверхность	Действие предпросмотра
`SANDBOX_TRANSPORT`, `transport` на `getSandbox()`, `setTransport()`	Удалено. Preview использует RPC автоматически, настройка транспорта не требуется.
`await sandbox.exec(string)` → буферизованный результат	`await sandbox.exec(argv)` затем `await process.output(...)`.
`execStream`, `startProcess`, вспомогательные функции для логов процессов	Дескриптор процесса: `logs`, `kill`, `waitFor*`.
Сессия по умолчанию / `enableDefaultSession`	Удалено. Каждый `exec` работает независимо.
`createSession` / `ExecutionSession`	Удалено из основного публичного API. Передайте `cwd`/`env` на `exec`, либо один shell-скрипт в формате argv.
Методы Interpreter в `Sandbox`	Те же имена методов у `sandbox.interpreter` после `withInterpreter`. `runCode` возвращает обычные `ExecutionResult`. См. Code interpreter.
Сигналы завершения в виде строк	Числовые сигналы на `process.kill`.
`waitForPort` режим по умолчанию	Значение по умолчанию для предпросмотра: `tcp`. Передайте `mode: "http"` для HTTP-проверок.
Процесс / поток stdin	У дескриптора нет stdin процесса. Неинтерактивный режим: argv/`cwd`/`env`. Интерактивный PTY: терминалы.
`sandbox.terminal(request)` / сессия `terminal()`	`createTerminal`, затем `terminal.connect(request)`.
xterm `sessionId`	`terminalId` (и необязательный `cursor`).
`sandbox.gitCheckout(...)`	Удалено. Выполните `git` с argv `exec`, например `['git', 'clone', '--', url, dir]`, затем `output()` / waits по мере необходимости.

Файлы, точки монтирования, резервные копии, порты, туннели, proxyToSandbox, и большинство параметров жизненного цикла остаются доступны. За их сигнатурами обращайтесь к основной документации Sandbox. Там, где стабильная страница всё ещё описывает сессии, выбор транспорта, строковые exec helpers, или sandbox.terminal, в этом случае обратитесь вместо этого к разделу про preview.

Установите пакет и образ превью

npm i @cloudflare/sandbox@next

Убедитесь, что lockfile разрешает @cloudflare/sandbox на preview-сборку. Укажите в Dockerfile соответствующий preview-образ, например cloudflare/sandbox:next (или -python / другой вариант, который вы используете).

Не смешивайте preview-пакет Worker со stable-образом контейнера и наоборот. Обе стороны должны использовать один и тот же @next строка.

Удаление выбора транспорта

Удалить SANDBOX_TRANSPORT, transport опцию для getSandbox(), SandboxTransport типов и sandbox.setTransport(). Заменяющая настройка не требуется.

Миграция выполнения команд

Буферизованные команды

Стабильно:

const result = await sandbox.exec("npm test");
console.log(result.stdout, result.exitCode);

Предпросмотр:

const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"]);
const result = await process.output({ encoding: "utf8" });
console.log(result.stdout, result.exitCode);

const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"]);
const result = await process.output({ encoding: "utf8" });
console.log(result.stdout, result.exitCode);

Правила:

await sandbox.exec(...) означает запуск выполнен успешно, а не команда завершена.
При запуске отдельного бинарного файла предпочитайте argv без shell: ['npm', 'test'] с cwd задан.
output() по умолчанию равно байт передаёт потоком (Uint8Array). Передайте { encoding: "utf8" } для строк.
Не существует sandbox.run() вспомогательную функцию совместимости на текущем preview tip.

Фоновые процессы и потоковая передача

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

// Default readiness mode is TCP. Use mode: "http" when you need an HTTP check.
await server.waitForPort(3000, { timeout: 60_000 });
// await server.waitForPort(3000, { mode: "http", path: "/health", timeout: 60_000 });

const stream = await server.logs({ follow: true, replay: true });
// consume stream...

await server.kill(); // numeric signal; default 15

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

// Default readiness mode is TCP. Use mode: "http" when you need an HTTP check.
await server.waitForPort(3000, { timeout: 60_000 });
// await server.waitForPort(3000, { mode: "http", path: "/health", timeout: 60_000 });

const stream = await server.logs({ follow: true, replay: true });
// consume stream...

await server.kill(); // numeric signal; default 15

Подробности о дескрипторе процесса (ожидания, события логов, kill, без stdin): API процессов.

Между запросами Worker сохраняйте server.id и возобновите работу с getProcess(id) только пока этот процесс может ещё выполняться в текущем контейнере. Если контейнер остановлен, getProcess может возвращать null. Если у вас остался handle от предыдущего контейнера, ожидайте ошибку stale-handle. В обоих случаях запустите новый exec от работы, которую всё ещё нужно выполнить. См. Сколько живёт процесс.

Рабочий каталог и окружение

Стабильная	Предпросмотр
`exec("cd /app"); exec("npm test");`	`exec(['/bin/bash', '-lc', 'cd /app && npm test'])` или `exec(['npm', 'test'], { cwd: '/app' })`
Экспортированные переменные в сессии по умолчанию	`setEnvVars` и/или `env` на каждый `exec`
`createSession({ env })`	`setEnvVars` и/или `env` на каждый `exec` / `createTerminal`

Подробности: Переменные окружения.

Не помещайте боевые API-ключи или долгоживущие учётные данные провайдера в setEnvVars или запустите env. Храните секреты в Worker и внедряйте их с помощью исходящий трафик обработчики, когда процессу нужно вызвать внешний API.

Тайм-ауты и отмена

Цель	API
Ограничение времени жизни процесса	`exec(argv, { timeout })` : может завершиться с `timedOut: true`
Ограничьте время ожидания	Параметры или `AbortSignal` на `output` / waits / `logs` : выполняет не завершить процесс

API сброса сессии

Удалить createSession, getSession, deleteSession, а также sessionId опции для базовых вызовов.

Изоляция пользователей остаётся одна песочница на пользователя (или в рамках границы доверия), а не сессии внутри одной песочницы.

Подключите интерпретатор

См. Code interpreter. Минимум:

import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";

export class Sandbox extends BaseSandbox {
	interpreter = withInterpreter(this);
}

import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";

export class Sandbox extends BaseSandbox<Env> {
	interpreter = withInterpreter(this);
}

Используйте -python вариант образа при запуске Python. Следите, чтобы пакет Worker и образ контейнера использовали одну и ту же @next строка.

Git

sandbox.gitCheckout удален. Выполните клонирование или fetch с argv exec, например:

const clone = await sandbox.exec(
	["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
	{ cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });

const clone = await sandbox.exec(
	["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
	{ cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });

Терминалы

Замените stable sandbox.terminal(request) (а также сессионных terminal()) с помощью API ресурса preview-терминала:

const terminal = await sandbox.createTerminal({ command: ['bash'], ... })
Сохраните terminal.id с идентификатором песочницы.
При обновлении до WebSocket: getTerminal(id) затем terminal.connect(request, { cursor?, cols?, rows? }).
В браузере @cloudflare/sandbox/xterm использует terminalId.

Подробности: Терминалы, Terminals API.

Самостоятельно развёрнутый мост

Это руководство посвящено приложениям Worker SDK на @next.

Самостоятельно развёрнутый Мост песочницы остается на стабильной ветке релизов. Держите его пакет Worker, образ контейнера и HTTP-клиенты на соответствующих стабильных версиях. Не сочетайте bridge-развертывание с @cloudflare/sandbox@next.

Управление жизненным циклом в стиле preview-версии

На @next, ID песочницы остается стабильным, а контейнер за ним можно заменить. Processes и terminals существуют только в рамках текущего контейнера. После замены старые handle перестают работать, и вам нужно начинать работу заново.

Это нормально после простоя, перезапусков и переключения при этой миграции. Полная модель: Жизненный цикл песочницы и Сколько живёт процесс. Шаблоны восстановления: Ошибки и восстановление. Каталог: API ошибок.

При миграции долго выполняющихся задач:

Не считайте сохранённый process.id или terminal.id как достаточное условие для возобновления работы после произвольной задержки или после деплоя.
Сохраните команду, cwd, env, и любую контрольную точку приложения, необходимую для перезапуска.
При последующем запросе вызовите getProcess(id) / getTerminal(id) только если этот ресурс может всё ещё выполняться в текущем контейнере. Если вы получаете null или ошибку устаревшего дескриптора, начните заново с сохранённой работы.

Обрабатывайте как минимум следующие ошибки:

Ошибка	Что делать
`ContainerUnavailableError`	Контейнер не приступил к выполнению задачи, повторите попытку позже (`retryAfterMs` если она установлена), затем повторите операцию
`StaleProcessHandleError` / `StaleTerminalHandleError`	Предыдущий контейнер: возобновление работы с сохранённого состояния
`OperationInterruptedError`	Работа могла уже начаться: подробнее см. `reason` / `retryable`; проверьте состояние перед повтором
`RPCTransportError`	Потеря связи во время вызова: последующий вызов может сработать, но этот вызов, возможно, уже был выполнен
`ProcessWaitTimeoutError` / `ProcessAbortedError`	Ожидание просто завершилось: процесс может всё ещё работать
`RuntimeControlProtocolError` или неработоспособный образ после развёртывания	Пакет Worker и образ контейнера должны совпадать по `@next` строка; не воспринимайте это как медленный запуск

getProcess / getTerminal / list* не запускают контейнер. Они возвращают null или [] когда ни один не запущен (это не исключение).

Разверните переключение

Сначала выполните шаги миграции кода из этого руководства в отдельной ветке. Переключение в продакшен сводится к одному деплою preview-пакета Worker и соответствующего образа контейнера.

Стабильный Sandbox и @next используют разные протоколы управления. Смешанная пара не работает ни в одном направлении: новый код Worker с устаревшим образом контейнера завершается ошибкой, как и устаревший код Worker с новым образом контейнера.

При обычном wrangler deploy, код Worker становится активным немедленно, тогда как экземпляры контейнеров могут обновляться постепенно. Из-за этого возникает окно, в котором новый код Worker может обращаться к старым контейнерам. Для этой миграции разверните контейнеры одним шагом:

npx wrangler deploy --containers-rollout=immediate

--containers-rollout=immediate не переопределяет rollout_active_grace_period. Оставьте этот параметр со значением по умолчанию 0 для переключения (или установите значение 0 если вы указали его раньше). Ненулевой grace period дольше сохраняет старые контейнеры активными, пока новый Worker уже работает.

Перед продакшеном:

Завершите или остановите работу, которую нужно сохранить на момент переключения.
Разверните с помощью команды немедленного развёртывания контейнера из предыдущего раздела.
Дождитесь, пока новый образ контейнера начнёт обслуживать трафик.
Считайте идентификаторы процессов и терминалов, существовавшие до развёртывания, недействительными. Начните эту работу заново и используйте новые идентификаторы.
Выполняет проверки в Проверить.

Для обычных деплоев после миграции см. Разверните приложение Sandbox. О параметрах rollout см. Развёртывания.

Проверить

Убедитесь, что lockfile и Dockerfile используют одну и ту же @next строку, а затем разверните с помощью --containers-rollout=immediate.
Запускает один argv exec и output({ encoding: "utf8" }).
Запускает один долгоживущий процесс с waitForPort или logs.
Если приложение использует терминал в браузере: создание, подключение и возобновление с помощью getTerminal пока он ещё есть у контейнера.
Задействуйте интерпретатор, только если ваше приложение использует это расширение (для Python требуется -python).
Убедитесь, что обработка ошибок различает недоступность, прерывание/RPC, устаревший handle и локальные тайм-ауты ожидания, Ошибки и восстановление.
Убедитесь, что секреты не хранятся в окружении песочницы. При необходимости используйте обработчики исходящих запросов.
Ещё раз выполните grep для поиска удалённых API (transport, sessions, execStream, startProcess, sandbox.terminal, gitCheckout, xterm sessionId).

Агенты для написания кода

Установка Cloudflare Skills ↗ для вашего агента (Настройка агента). sandbox-migrate-to-next skill выполняет эту миграцию. Для новых приложений на @next, используйте sandbox-next. Для повседневной работы с текущим стабильным пакетом используйте sandbox-stable. Очистка устаревших API при сохранении стабильной версии находится в Руководство по прекращению поддержки в 2026 году (и sandbox-stable) перед этим руководством или вместо него.