1  # Docker OSSFS 挂载示例
  2  
  3  本示例演示如何使用新版 SDK 的 `ossfs` volume 模型，在 Docker 运行时将阿里云 OSS 挂载到沙箱容器。
  4  
  5  ## 覆盖场景
  6  
  7  1. **基础读写挂载**（OSSFS backend）。
  8  2. **跨沙箱共享数据**（同一 OSSFS backend path）。
  9  3. **通过 `subPath` 挂载不同 OSS prefix**。
 10  
 11  ## 前置条件
 12  
 13  ### 1) 启动 OpenSandbox 服务（Docker runtime）
 14  
 15  请确保服务端主机满足：
 16  
 17  - Linux 主机系统（OpenSandbox Server 运行在 Windows 时不支持 OSSFS backend）
 18  - 已安装 `ossfs`
 19  - 已启用 FUSE
 20  - 已有可写的 OSSFS 本地挂载根目录（默认 `storage.ossfs_mount_root=/mnt/ossfs`）
 21  
 22  `storage.ossfs_mount_root` 是**可选配置**（使用默认值时可不写）。
 23  即使是按需动态挂载，运行时仍需要一个确定的宿主机根目录来放置挂载点：
 24  `<mount_root>/<bucket>/<subPath?>`。
 25  
 26  可选配置示例：
 27  
 28  ```toml
 29  [runtime]
 30  type = "docker"
 31  
 32  [storage]
 33  ossfs_mount_root = "/mnt/ossfs"
 34  ```
 35  
 36  启动服务：
 37  
 38  ```bash
 39  opensandbox-server
 40  ```
 41  
 42  ### 2) 安装 Python SDK
 43  
 44  ```bash
 45  uv pip install opensandbox
 46  ```
 47  
 48  如果当前 PyPI 版本还不包含 OSSFS 相关模型，可从源码安装：
 49  
 50  ```bash
 51  pip install -e sdks/sandbox/python
 52  ```
 53  
 54  ### 3) 配置 OSS 参数
 55  
 56  ```bash
 57  export SANDBOX_DOMAIN=localhost:8080
 58  export SANDBOX_API_KEY=your-api-key
 59  export SANDBOX_IMAGE=ubuntu
 60  
 61  export OSS_BUCKET=your-bucket
 62  export OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
 63  export OSS_ACCESS_KEY_ID=your-ak
 64  export OSS_ACCESS_KEY_SECRET=your-sk
 65  ```
 66  
 67  ## 运行
 68  
 69  ```bash
 70  uv run python examples/docker-ossfs-volume-mount/main.py
 71  ```
 72  
 73  ## SDK 最小示例
 74  
 75  ```python
 76  from opensandbox import Sandbox
 77  from opensandbox.models.sandboxes import OSSFS, Volume
 78  
 79  sandbox = await Sandbox.create(
 80      image="ubuntu",
 81      volumes=[
 82          Volume(
 83              name="oss-data",
 84              ossfs=OSSFS(
 85                  bucket="your-bucket",
 86                  endpoint="oss-cn-hangzhou.aliyuncs.com",
 87                  # version="2.0",   # 可选，默认 "2.0"
 88                  accessKeyId="your-ak",
 89                  accessKeySecret="your-sk",
 90              ),
 91              mountPath="/mnt/data",
 92              subPath="train",      # 可选
 93              readOnly=False,       # 可选
 94          )
 95      ],
 96  )
 97  ```
 98  
 99  ## 说明
100  
101  - 当前实现仅支持**内联凭据**（`accessKeyId` / `accessKeySecret`）。
102  - Docker 运行时采用**按需挂载**（mount-or-reuse），不是预挂载所有 bucket。
103  - API/SDK 中 `ossfs.version` 字段存在，枚举为 `"1.0"` / `"2.0"`，省略时默认 `"2.0"`。
104  - Docker 运行时已按 `version` 区分挂载参数编码：
105    - `1.0`：通过 `ossfs ... -o <option>` 挂载。
106    - `2.0`：通过 `ossfs2 mount ... -c <config-file>` 挂载，`options` 以 `--<option>` 配置项写入配置文件。
107  - `options` 必须是**不带前缀 `-` 的原始参数值**（例如：`allow_other`、`umask=0022`）。
108  
109  ## 参考
110  
111  - [OSEP-0003: Volume 与 VolumeBinding 支持](../../oseps/0003-volume-and-volumebinding-support.md)
112  - [Sandbox Lifecycle API 规范](../../specs/sandbox-lifecycle.yml)