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

# 概述

Volume 是一种独立于沙箱生命周期的持久化存储卷。挂载到沙箱后，它会以目录形式出现在文件系统中，代码可以像读写本地目录一样访问其中的数据。

<Note>
  此功能仅支持 v2 [区域](/docs/sandbox/overview#区域)。当前 Volume 为内测阶段。
</Note>

当你需要在沙箱销毁后保留数据，或在多个沙箱之间共享同一份数据时，使用 Volume；如果你只是保存一个已经初始化好的运行环境，优先考虑 Snapshot。

沙箱自带的文件系统随沙箱的生命周期走——沙箱被 kill 后数据随之释放。Volume 的作用就是把「需要长期保留、需要跨沙箱使用的数据」从单个沙箱的生命周期中解耦出来:

* **数据持久化**:沙箱销毁后 Volume 中的数据仍然保留,新沙箱挂载同一个 Volume 即可继续使用
* **跨沙箱共享**:同团队的多个沙箱可以挂载同一个 Volume,复用数据集、模型缓存、构建产物等
* **容量可控**:创建时指定容量配额(GiB),可随时查询实际用量并动态调整配额

|      | 沙箱文件系统   | Snapshot           | Volume       |
| ---- | -------- | ------------------ | ------------ |
| 生命周期 | 随沙箱创建和销毁 | 独立保存的状态快照          | 独立存在,可读写     |
| 典型用途 | 运行时的临时数据 | 保存配置好的环境,新沙箱免重复初始化 | 持久数据、跨沙箱共享目录 |

典型工作流:创建 Volume → 挂载到沙箱内路径 → 沙箱内正常读写 → 卸载或销毁沙箱,数据保留在 Volume 中。

```python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()

vol = ppio.volume.create("shared-data", quota_size_gib=10)

sbx = ppio.sandbox.create(template)
sbx.mount_volume(vol.name, "/mnt/data")

sbx.commands.run('echo "hello volume" > /mnt/data/hello.txt')

sbx.kill()  # 沙箱销毁,/mnt/data 中写入的数据仍保留在 Volume 里
```

挂载有两种方式:创建沙箱时通过 `volume_mounts` 参数声明,或对运行中的沙箱调用 `mount_volume` 动态挂载,详见 [挂载与卸载](/docs/sandbox/volume-mount)。