> ## 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.

# 暂停和恢复

> 了解 PPIO Agent 沙箱暂停和恢复的归档操作流程，查阅该版本保留与恢复运行状态的方式，为维护现有任务提供参考。

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

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

## 暂停沙箱

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

```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()
```

> [!WARNING]
>
> **注意：暂停后的短暂过渡期**
>
> 暂停（pause）是一个异步操作，调用 `beta_pause()` 后沙箱会在后台完成暂停过程。
>
> 在暂停过程尚未完成的这段时间内：
>
> * **查询类操作**（如 `get_info`、`list`）：正常返回，状态显示为 `paused`
> * **执行类操作**（如 `commands.run`、访问沙箱公共 URL）：将返回错误，属于预期行为，建议等待暂停完成后重试（耗时与内存大小相关，参考上方说明）
> * **恢复操作**（`connect`）：会自动等待暂停完成后再恢复沙箱，无需手动轮询或重试

## 恢复沙箱

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

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

> [!WARNING]
>
> 如果尝试恢复（resume）一个已销毁或不存在的 Sandbox：
>
> * JavaScript SDK 会抛出 `NotFoundError`
> * Python SDK 会抛出 `NotFoundException`

```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()
```

## 恢复时指定超时时间

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

```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()
```

## 列出暂停的沙箱

您可以参考如下方式列出所有被暂停的沙箱。详情请参考 [沙箱列表](/docs/sandbox/archive/sandbox-list)。

```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()
```

## 删除暂停的沙箱

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

```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)
```

## 网络连接

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.