> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 暂停和恢复

export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>在运行本文档中的示例代码前，请确保您已正确配置环境变量，详情请参考 <a href="/sandbox/get-start#配置环境变量">配置环境变量</a>。</Note>;
  }
};

您现在可以**暂停**沙箱并且在后续需要时**恢复**该沙箱，恢复后，沙箱的文件系统和内存状态，包括正在运行的进程、已加载的变量、数据等都将被恢复。<u>在沙箱暂停期间，我们不会对沙箱的运行时间计费。</u>

<SandboxConfigHint />

<Warning>
  请注意：

  * 暂停沙箱所需的时间和沙箱的 RAM（内存）大小有关，每 1 GB RAM 需要约 4 秒；
  * 恢复沙箱需要约 1 秒；
  * 暂停状态的沙箱数据将永久保留，直到您主动调用 `kill` 方法销毁沙箱。
</Warning>

## 暂停沙箱

当您暂停沙箱时，沙箱的<Link href="/sandbox/filesystem">文件系统</Link>和内存状态都将被保存。包括沙箱文件系统中的所有文件以及所有正在运行的进程、已加载的变量、数据等。

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox } from 'ppio-sandbox/code-interpreter'
  // or import { Sandbox } from 'ppio-sandbox'
  // or import { Sandbox } from 'ppio-sandbox/desktop'

  const sandbox = await Sandbox.create()
  console.log('Sandbox created', sandbox.sandboxId)

  // 暂停沙箱
  // 建议您将沙箱 ID 保存到数据库中，以便稍后恢复沙箱。
  const result = await sandbox.betaPause()
  console.log('Sandbox paused', sandbox.sandboxId, result)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox
  # or from ppio_sandbox.core import Sandbox
  # or from ppio_sandbox.desktop import Sandbox

  sandbox = Sandbox.create()
  print('Sandbox created', sandbox.sandbox_id)

  # 暂停沙箱
  # 建议您将沙箱 ID 保存到数据库中，以便稍后恢复沙箱。
  sandbox.beta_pause()
  print('Sandbox paused', sandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

<Warning>
  **注意：暂停后的短暂过渡期**

  暂停（pause）是一个异步操作，调用 `beta_pause()` 后沙箱会在后台完成暂停过程。

  在暂停过程尚未完成的这段时间内：

  * **查询类操作**（如 `get_info`、`list`）：正常返回，状态显示为 `paused`
  * **执行类操作**（如 `commands.run`、访问沙箱公共 URL）：将返回错误，属于预期行为，建议等待暂停完成后重试（耗时与内存大小相关，参考上方说明）
  * **恢复操作**（`connect`）：会自动等待暂停完成后再恢复沙箱，无需手动轮询或重试
</Warning>

## 恢复沙箱

当您恢复沙箱时，沙箱在暂停前文件系统中的所有文件、所有正在运行的进程、已加载的变量、数据等将被恢复。

<Tip>
  如果在调用 `beta_pause()` 之后立即调用 `connect()` 恢复沙箱，`connect()` 会自动等待暂停过程完成后再执行恢复。无需手动轮询沙箱状态，整个过程对调用方是透明的。
</Tip>

<Warning>
  如果尝试恢复（resume）一个已销毁或不存在的 Sandbox：

  * JavaScript SDK 会抛出 `NotFoundError`
  * Python SDK 会抛出 `NotFoundException`
</Warning>

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox } from 'ppio-sandbox/code-interpreter'
  // or import { Sandbox } from 'ppio-sandbox'
  // or import { Sandbox } from 'ppio-sandbox/desktop'

  const sandbox = await Sandbox.create()
  console.log('Sandbox created', sandbox.sandboxId)

  // 暂停沙箱
  // 建议您将沙箱 ID 保存到数据库中，以便稍后恢复沙箱。
  const result = await sandbox.betaPause()
  console.log('Sandbox paused', sandbox.sandboxId, result)

  // 恢复沙箱
  // 即使在暂停完成前调用 connect()，也会自动等待暂停结束后再恢复。
  const resumedSandbox = await sandbox.connect()
  console.log('Sandbox resumed', resumedSandbox.sandboxId)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox
  # or from ppio_sandbox.core import Sandbox
  # or from ppio_sandbox.desktop import Sandbox

  sandbox = Sandbox.create()
  print('Sandbox created', sandbox.sandbox_id)

  # 暂停沙箱
  # 建议您将沙箱 ID 保存到数据库中，以便稍后恢复沙箱。
  sandbox.beta_pause()
  print('Sandbox paused', sandbox.sandbox_id)

  # 恢复沙箱
  # 即使在暂停完成前调用 connect()，也会自动等待暂停结束后再恢复。
  connectedSandbox = sandbox.connect()
  print('Sandbox resumed', connectedSandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

## 恢复时指定超时时间

当您恢复沙箱时，沙箱的 timeout 会重置为默认的 5 分钟。您可以参考如下方法来自定义 timeout 值。

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox } from 'ppio-sandbox/code-interpreter'
  // or import { Sandbox } from 'ppio-sandbox'
  // or import { Sandbox } from 'ppio-sandbox/desktop'

  const sandbox = await Sandbox.create()

  const connectedSandbox = await Sandbox.connect(sandbox.sandboxId, { timeoutMs: 60 * 1000 }) // 60 秒
  console.log('Sandbox connected', connectedSandbox.sandboxId)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox
  # or from ppio_sandbox.core import Sandbox
  # or from ppio_sandbox.desktop import Sandbox

  sandbox = Sandbox.create()

  connectedSandbox = Sandbox.connect(sandbox.sandbox_id, timeout=60) # 60 秒
  print('Sandbox connected', connectedSandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

## 列出暂停的沙箱

您可以参考如下方式列出所有被暂停的沙箱。详情请参考 <Link href="/sandbox/sandbox-list">沙箱列表</Link>。

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox, SandboxInfo } from 'ppio-sandbox/code-interpreter'
  // or import { Sandbox, SandboxInfo } from 'ppio-sandbox'
  // or import { Sandbox, SandboxInfo } from 'ppio-sandbox/desktop'

  const sandbox = await Sandbox.create()

  // 过滤出所有被暂停的沙箱
  const paginator = Sandbox.list({ query: { state: ['paused'] } })

  // 分页获取所有被暂停的沙箱
  const sandboxes: SandboxInfo[] = []
  while (paginator.hasNext) {
    const items = await paginator.nextItems()
    sandboxes.push(...items)
  }

  console.log('all paused sandboxes', sandboxes)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox, SandboxInfo, SandboxQuery, SandboxState
  # or from ppio_sandbox.core import Sandbox, SandboxInfo, SandboxQuery
  # or from ppio_sandbox.desktop import Sandbox, SandboxInfo, SandboxQuery

  sandbox = Sandbox.create()

  sandbox.beta_pause()
  print('Sandbox paused', sandbox.sandbox_id)

  # 过滤出所有被暂停的沙箱
  paginator = Sandbox.list(query=SandboxQuery(state=[SandboxState.PAUSED]))

  # 分页获取所有被暂停的沙箱
  sandboxes: list[SandboxInfo] = []
  while paginator.has_next:
    items = paginator.next_items()
    sandboxes.extend(items)

  print('all paused sandboxes', sandboxes)

  sandbox.kill()
  ```
</CodeGroup>

## 删除暂停的沙箱

您可以通过在沙箱实例上调用 `kill` 方法来删除暂停的沙箱。

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={null}
  import { Sandbox } from 'ppio-sandbox/code-interpreter'
  // or import { Sandbox } from 'ppio-sandbox'
  // or import { Sandbox } from 'ppio-sandbox/desktop'

  const sandbox = await Sandbox.create()
  console.log('Sandbox created', sandbox.sandboxId)

  // 暂停沙箱
  await sandbox.betaPause()

  // 删除被暂停的沙箱
  await sandbox.kill()

  // 或者通过指定沙箱 ID 来删除被暂停的沙箱
  // await Sandbox.kill(sandboxId)
  ```

  ```python Python icon="python" theme={null}
  from ppio_sandbox.code_interpreter import Sandbox
  # or from ppio_sandbox.core import Sandbox
  # or from ppio_sandbox.desktop import Sandbox

  sandbox = Sandbox.create()

  # 暂停沙箱
  sandbox.beta_pause()

  # 删除被暂停的沙箱
  sandbox.kill()

  # 或者通过指定沙箱 ID 来删除被暂停的沙箱
  # Sandbox.kill(sandbox_id)
  ```
</CodeGroup>

## 网络连接

当您在沙箱内运行了服务并且暂停沙箱后，该服务将无法再从外部访问，所有客户端都将断开连接。在您恢复沙箱后，该服务可被再次访问，但您需要重新连接客户端。