# 自动恢复
<subtitle>让已暂停的沙箱在收到访问或 SDK 操作时自动恢复运行。</subtitle>

很多工作负载并不需要沙箱一直保持运行，但一旦有请求或操作到来，沙箱应该可以直接继续工作。自动恢复用于处理这个场景：当已暂停的沙箱收到活动时，系统会自动唤醒沙箱，业务代码不需要提前检查或手动管理沙箱状态。

自动恢复基于 [沙箱持久化](/docs/agent-sandbox/sdk/sandbox/persistence.md) 的生命周期能力。启用后，沙箱可以在超时后自动暂停，并在后续活动到来时自动恢复。

> 自动恢复依赖暂停的沙箱。暂停的沙箱会占用持久化存储，并按持久化存储规则计费。详细计费方式请参考 [计费说明](/docs/agent-sandbox/product/fee.md)。

## 配置自动恢复

创建沙箱时设置 `lifecycle`，即可控制沙箱超时后的动作，以及已暂停沙箱是否在收到活动时自动恢复。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    timeout=10 * 60,
    lifecycle={
        "on_timeout": "pause",
        "auto_resume": True,  # 收到活动时自动恢复
    },
)
```

### 生命周期选项

`lifecycle` 支持以下常用配置：

| 配置项 | 取值 | 说明 |
| --- | --- | --- |
| `on_timeout` | `"kill"` | 默认行为。沙箱达到超时时间后被销毁 |
| `on_timeout` | `"pause"` | 沙箱达到超时时间后自动暂停，并保留文件系统与内存状态 |
| `auto_resume` | `False` | 默认行为。已暂停沙箱不会自动恢复，需要手动连接 |
| `auto_resume` | `True` | 已暂停沙箱收到活动时自动恢复。通常与 `on_timeout: "pause"` 搭配使用 |

如果未启用 `auto_resume`，仍然可以通过 `Sandbox.connect()` 手动恢复已暂停的沙箱。

```python
from ucloud_sandbox import Sandbox

same_sandbox = Sandbox.connect("your-sandbox-id")
```

## 自动恢复后的超时时间

沙箱自动恢复后，会重新开始计算超时时间。恢复后的超时时间至少为 **5 分钟**；如果创建沙箱时设置了更长的 `timeout`，则会沿用更长的值。

例如，创建沙箱时设置 2 分钟超时：

1. 沙箱运行 2 分钟后自动暂停。
2. 后续活动到来，沙箱自动恢复。
3. 恢复后使用 5 分钟超时，因为 5 分钟是自动恢复后的最小超时时间。
4. 如果没有新的活动刷新超时，沙箱会在 5 分钟后再次暂停。

如果创建沙箱时设置 1 小时超时，自动恢复后的超时时间也是 1 小时，因为它超过了 5 分钟最小值。

这个循环会在每次自动恢复后重复。生命周期配置会跨暂停和恢复持续生效。

> 您可以在沙箱恢复后调用 `set_timeout()` 修改超时时间。更多说明请参考 [沙箱生命周期](/docs/agent-sandbox/sdk/sandbox/lifecycle.md)。

## 哪些活动会触发自动恢复

自动恢复由沙箱活动触发，包括 HTTP 流量和 SDK 操作。

常见触发方式包括：

- `sandbox.commands.run(...)`
- `sandbox.files.read(...)`
- `sandbox.files.write(...)`
- 打开沙箱内服务的公共 URL，或向沙箱内运行的服务发送请求

如果沙箱处于已暂停状态，并且创建时启用了 `lifecycle.auto_resume`，下一次受支持的操作会自动恢复沙箱。此时不需要先调用 `Sandbox.connect()`。

## 示例：暂停后读取文件

下面的示例会写入一个文件，暂停沙箱，然后读取该文件。读取操作会触发自动恢复。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    timeout=10 * 60,
    lifecycle={
        "on_timeout": "pause",
        "auto_resume": True,
    },
)

sandbox.files.write("/home/user/hello.txt", "来自已暂停沙箱的问候")
sandbox.pause()

content = sandbox.files.read("/home/user/hello.txt")
print(content)
print(f"读取后的状态：{sandbox.get_info().state}")
```

## 示例：自动恢复 Web 服务

自动恢复很适合 Web 服务和预览环境。沙箱暂停后，如果有 HTTP 请求访问沙箱内服务，沙箱会自动恢复并处理请求。

下面的示例启动一个简单的 HTTP 服务，并获取它的公共 URL。可以通过 `get_host()` 获取指定端口对应的公网访问域名。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    timeout=5 * 60,
    lifecycle={
        "on_timeout": "pause",
        "auto_resume": True,
    },
)

sandbox.commands.run("python3 -m http.server 3000", background=True)

host = sandbox.get_host(3000)

# 沙箱超时并暂停后，访问这个 URL 会自动恢复沙箱
print(f"预览地址：https://{host}")
```

## 清理沙箱

自动恢复配置会持续生效：沙箱恢复后，如果再次超时，仍会再次自动暂停。只要后续还有活动到来，沙箱就会在 Running 和 Paused 之间循环切换。

如果不再需要该沙箱，请调用 `.kill()`。销毁后的沙箱无法再次恢复。

```python
sandbox.kill()
```