안정적 → Sandbox SDK 1.0 프리뷰(@next)로 마이그레이션
포트를 수행합니다. 순서대로 단계를 따르세요. 세부 내용은 문서에 있습니다. 단계에 세부 정보가 필요한 경우 연결된 페이지를 가져오세요.
새 프로젝트는 이 스킬이 아닌 @next(sandbox-next)에서 시작해야 합니다. 일상적인 안정적 작업 → sandbox-stable. @next로 이동 없이 사용 중단된 API 정리 → 먼저 2026 사용 중단 가이드가 필요하면 사용하세요.
기존 앱은 가능할 때 마이그레이션하여 1.0이 안정 릴리즈가 될 때 준비가 되어 있어야 합니다. 사용자 동의 없이 프로덕션을 강제로 전환하지 마십시오.
설치된 @next 타입과 마이그레이션 문서를 메모리보다 선호합니다.
워크플로우
- 검토 엄격한 규칙 및 교체 맵
- 감사 코드베이스; 일치 항목 및 대상 형태 나열
- 명확화 사용자와 함께 (컷오버, 브리지, Python 이미지, 불명확한 사이트)
- 업그레이드 패키지, 이미지 및 코드
- 검증
사용자 결정이 필요한 단계 이후에는 중지합니다.
엄격한 규칙
- Worker 패키지와 컨테이너 이미지는 동일한
@next라인이어야 합니다. - 프로덕션 컷오버는 즉시 컨테이너 롤아웃을 사용합니다. 안정적 및
@next제어 프로토콜은 양방향으로 호환되지 않습니다. 점진적 롤아웃은 깨진 혼합 윈도우를 남깁니다. 진행 중인 컨테이너 작업이 중단될 수 있습니다. - 컷오버 후
await sandbox.exec(...)는 프로세스 시작을 의미하며 명령 완료를 의미하지 않습니다. - Argv는 그대로입니다(암시적 셸 없음). 셸 구문에는 명시적 셸 바이너리가 필요합니다.
- 프로세스 핸들에는 stdin이 없음 → 대화형 입력을 위한 터미널.
- 관찰
timeout/AbortSignal은 대기만 취소하며 프로세스는 취소하지 않습니다. - 모든 오류에 대한 단일 재시도 루프는 없습니다.
- API를 발명하지 마십시오(코어의
gitCheckout, 프로세스 stdin, 문자열 실행 완료 헬퍼). - 자체 배포 브리지는 안정적으로 유지(아직 프리뷰 라인의 일부가 아님).
교체 맵
| 안정적 | @next |
|---|---|
SANDBOX_TRANSPORT / transport / setTransport | 제거 — RPC 전용 |
await sandbox.exec("cmd") → 버퍼링된 결과 | await sandbox.exec(argv) → 핸들, 그 다음 output / 대기 |
execStream / startProcess | 동일한 핸들: logs, waitFor*, kill |
| 기본 / 명명된 세션 | 사라짐 — cwd/env는 실행마다, 또는 하나의 셸 스크립트 |
sandbox.terminal(request) / 세션 터미널 | createTerminal + terminal.connect(request) |
xterm sessionId | terminalId |
Sandbox의 인터프리터 메서드 | withInterpreter → sandbox.interpreter.* |
gitCheckout | exec를 통한 argv git |
| 문자열 kill 신호 | 숫자만 |
파일, 마운트, 백업, 포트, 터널, proxyToSandbox | 대부분 변경되지 않음(안정적 페이지의 세션/전송 비트 무시) |
세부 정보: 마이그레이션 · 포트 이후, 일상 작업 → sandbox-next
감사
rg 'SANDBOX_TRANSPORT|transport:|setTransport|enableDefaultSession|createSession|getSession|deleteSession|execStream\(|startProcess\(|killProcess\(|sandbox\.terminal\(|sessionId|gitCheckout\(|SandboxTransport|ExecutionSession'
또한: 문자열 exec(, cd 후 exec, Sandbox의 createCodeContext / runCode.
명확화 (필요할 때 질문)
--containers-rollout=immediate로 프로덕션을 전환해도 괜찮습니까? (실행 중인 프로세스/터미널/스트림이 중지될 수 있음)?- 자체 배포 브리지? 안정적에 유지.
- Python 인터프리터 →
-python이미지 변형? - 맵으로 다루지 않는 호출 사이트?
업그레이드
패키지 및 이미지
npm install @cloudflare/sandbox@next
FROM cloudflare/sandbox:next
# Python: cloudflare/sandbox:next-python
부동 next가 아닌 경우 Worker와 이미지에서 동일한 프리릴리즈 태그입니다.
영역별 코드
맵에서 교체를 적용합니다. 각 영역에 대해 안정적 습관이 아닌 문서에서 구현합니다.
| 영역 | 문서 |
|---|---|
| 명령 / 핸들 / 대기 | 프로세스 · 프로세스 API |
cwd / env / 비밀 | 환경 · 아웃바운드 트래픽 |
| 세션 제거 | 마이그레이션 · 수명 주기 |
| 터미널 | 터미널 |
| 인터프리터 | 인터프리터 |
| 오류 | 오류 |
| 요청 간 지속 작업 | 프로세스 실행 — 수명/내구성 |
명령 (형태):
// 이전 (안정적)
const result = await sandbox.exec("npm test");
// 이후 (@next)
const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"]);
const result = await process.output({ encoding: "utf8" });
const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
cwd: "/workspace/app",
});
await server.waitForPort(3000, { timeout: 60_000 });
await server.kill(); // 숫자; 기본 15
터미널 (형태):
const terminal = await sandbox.createTerminal({ command: ["bash"], cwd: "/workspace" });
const t = await sandbox.getTerminal(terminal.id);
if (!t) return new Response("terminal gone", { status: 410 });
return t.connect(request, { cursor, cols, rows });
인터프리터 (형태):
import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";
export class Sandbox extends BaseSandbox<Env> {
interpreter = withInterpreter(this);
}
Git (형태):
const clone = await sandbox.exec(
["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
{ cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });
전송 설정을 완전히 삭제합니다. 세션 API를 제거합니다. 별도의 샌드박스 ID로 사용자를 격리합니다.
배포 컷오버
먼저 스테이징/브랜치. 프로덕션은 일치하는 Worker + 이미지의 하나의 배포입니다.
npx wrangler deploy --containers-rollout=immediate
rollout_active_grace_period를 기본 0으로 유지(또는 올린 경우 0으로 설정). 컷오버 후, 배포 전 프로세스/터미널 ID는 유효하지 않습니다. 세부 정보: 마이그레이션 · 컨테이너 롤아웃
검증
- Lockfile + Dockerfile이 동일한
@next라인에 있는지 @next에 대한 타입 체크- argv
exec+output({ encoding: "utf8" })스모크 테스트 - 장기 프로세스 / 터미널 / 인터프리터가 사용된 경우 스모크 테스트
- 오류 구분: 사용 불가 / 중단된 RPC / 오래됨 / 로컬 대기
- sandbox 환경에 라이브 비밀 없음
- 제거된 API 다시 grep
- 프로덕션에서
--containers-rollout=immediate사용
그 후 일상 작업은 **sandbox-next**를 사용합니다.
위험 신호 — 중지하고 수정
@nextWorker와 안정적 이미지 혼합(또는 그 반대)- 이 컷오버를 위한 점진적 컨테이너 롤아웃
await exec를 명령 완료로 취급cd/ export가exec호출 간에 유지된다고 가정- 모든 오류에 대한 하나의 재시도 래퍼
gitCheckout, 프로세스 stdin 또는 문서화되지 않은 API 발명- 배포 후 컷오버 전 프로세스/터미널 ID 유지
- 사용자 동의 없이 프로덕션 컷오버 강제
setEnvVars/ 실행env에 라이브 비밀 저장