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

# 使用 Python SDK 管理存储卷

> 使用人工智能平台 Python SDK 查询存储配额、购买存储资源、创建 Volume、扩容、共享、删除和配置目录级权限。

Python SDK 可用于自动化管理存储配额和 Volume。使用本文示例前，请先完成 [Python SDK 快速开始](./python-sdk-quickstart)，并确认当前账号具备目标区域、集群和存储资源的使用权限。

## 查询和购买存储资源

查询存储配额：

```python theme={null}
quota = client.volumes.get_quota()
print(quota.data)

detail = client.volumes.get_quota_detail()
for item in detail.data:
    print(item)
```

查询结果可用于判断当前区域和集群是否还有可用存储配额。购买的是存储配额，任务、开发环境或服务使用前还需要创建具体的 Volume。

如果存储配额不足，可以通过订单接口购买存储资源：

```python theme={null}
resp = client.orders.buy_storage(
    orders=[
        {
            "quantity": 1,
            "duration_days": 30,
            "size_in_gi": 500,
            "fs_type": "gpfs",
        }
    ],
    idempotency_key="storage-order-20260916-001",
)

print(resp.data)
```

购买后可查询存储订单。将下例中的 `200` 替换为实际订单 ID：

```python theme={null}
orders = client.orders.list_storage_orders(status="active")
detail = client.orders.get_storage_order(order_id=200)
print(detail.data)
```

确认订单已经生效后，新增存储配额才可用于创建 Volume。需要续费或调整自动续费时，按需调用对应接口：

```python theme={null}
client.orders.renew_storage_order(order_id=200, duration_days=30)
client.orders.set_storage_auto_renew(order_id=200, enabled=True)
```

购买存储资源会产生费用和配额变化。提交前请确认容量、文件系统类型、购买时长和自动续费设置。

## 创建 Volume

```python theme={null}
resp = client.volumes.create(
    name="shared-dataset-v1",
    capacity="500Gi",
    fs_type="gpfs",
)

volume_id = resp.data["id"]
print(volume_id)
```

购买的是存储配额，任务、开发环境或服务使用前还需要创建具体的 Volume。

## 查询 Volume

```python theme={null}
volumes = client.volumes.list(page=1, page_size=20)

for volume in volumes.rows:
    print(volume)

detail = client.volumes.get(volume_id=50)
print(detail.data)
```

查询当前账号可挂载的 Volume：

```python theme={null}
my_volumes = client.volumes.list_my_volumes()
print(my_volumes.data)
```

如果需要构建存储看板，可以查询配额、容量和使用量图表数据：

```python theme={null}
quota_chart = client.volumes.chart_quota_pie()
capacity_chart = client.volumes.chart_capacity_pie()
usage_chart = client.volumes.chart_usage_bar()

print(quota_chart.data)
print(capacity_chart.data)
print(usage_chart.data)
```

## 扩容和删除 Volume

扩容 Volume：

```python theme={null}
client.volumes.resize(volume_id=50, capacity="1Ti")
```

Volume 支持扩容，不建议在自动化脚本中假设支持缩容。

删除 Volume：

```python theme={null}
client.volumes.delete(volume_id=50)
```

需要删除多个 Volume 时，使用批量接口，不要再单独删除同一个 Volume：

```python theme={null}
client.volumes.delete_batch(volume_ids=[50, 51])
```

删除 Volume 会影响依赖该 Volume 的训练任务、开发环境、模型或推理服务。执行前，请确认数据已备份或不再需要。

## 共享 Volume

覆盖设置授权用户：

```python theme={null}
client.volumes.share(
    volume_id=50,
    users=[
        {"user": "alice", "read_only": False},
        {"user": "bob", "read_only": True},
    ],
)
```

增量追加或删除授权用户：

```python theme={null}
client.volumes.share_add_users(
    volume_id=50,
    users=[
        {"user": "carol", "read_only": False},
    ],
)
```

删除指定授权用户：

```python theme={null}
client.volumes.share_delete_users(
    volume_id=50,
    users=["bob"],
)
```

设置管理员：

```python theme={null}
client.volumes.set_admins(
    volume_id=50,
    resource_admins=["admin1", "admin2"],
)
```

共享配置会影响其他用户能否挂载和读写该 Volume。提交前请确认授权用户和读写权限。

## 配置目录级权限

目录级权限用于把同一个 Volume 按公共目录、自定义目录和用户目录拆分授权。相关接口要求 Volume 已开启目录级权限并处于可用状态。

开启目录级权限并设置授权用户范围：

```python theme={null}
client.volumes.update_dir_mode(
    volume_id=230,
    dir_mode=True,
    dir_whitelist=["alice", "bob", "carol"],
)
```

查询目录级权限配置：

```python theme={null}
config = client.volumes.get_dir_config(volume_id=230)
print(config.data)

whitelist = client.volumes.get_dir_whitelist(volume_id=230)
print(whitelist.data)
```

`get_dir_config()` 会返回目录级权限完整配置，包括是否开启目录级权限、用户目录根、授权用户范围，以及公共目录、自定义目录和用户目录的授权信息。`get_dir_whitelist()` 可查询目录授权候选用户；如果已配置授权用户范围，候选用户来自该范围，否则来自当前 Volume 的授权用户。

创建公共目录：

```python theme={null}
client.volumes.create_dir(
    volume_id=230,
    dir_type="public",
    path="/shared-volume/datasets",
    perm="r",
    note="public dataset",
)
```

创建自定义目录并设置授权：

```python theme={null}
resp = client.volumes.create_dir(
    volume_id=230,
    dir_type="custom",
    path="/shared-volume/project-a",
)

entry_id = resp.data["id"]

client.volumes.set_dir_grants(
    volume_id=230,
    entry_id=entry_id,
    grants=[
        {"user": "alice", "perm": "rw"},
        {"user": "bob", "perm": "r"},
    ],
)
```

公共目录对授权用户范围内的用户开放，创建时需要设置 `perm`。自定义目录需要通过 `set_dir_grants()` 显式授权，`grants` 不传或传空列表会清空该目录授权；公共目录不使用 `set_dir_grants()` 配置用户授权。

设置用户目录根路径和目录配额：

```python theme={null}
client.volumes.set_user_dir_base(
    volume_id=230,
    user_dir_base="/shared-volume/users",
)

client.volumes.set_dir_quota(
    volume_id=230,
    entry_id=13,
    limit_quota="100Gi",
)
```

配置目录级权限后，可查询当前账号可挂载的目录：

```python theme={null}
resp = client.volumes.list_my_dir_volumes()
print(resp.data)
```

目录级权限会影响挂载路径和读写能力。创建训练任务、开发环境或推理服务时，请使用有权限的目录，并按目录权限设置只读或读写挂载。

## 场景示例

### 创建 Volume 并分享给用户

```python theme={null}
quota = client.volumes.get_quota()
print(quota.data)

resp = client.volumes.create(
    name="shared-dataset-v1",
    capacity="500Gi",
    fs_type="gpfs",
)
volume_id = resp.data["id"]

client.volumes.share(
    volume_id=volume_id,
    users=[
        {"user": "alice", "read_only": False},
        {"user": "bob", "read_only": True},
    ],
)
```

### 为目录级 Volume 配置项目目录

```python theme={null}
client.volumes.update_dir_mode(
    volume_id=230,
    dir_mode=True,
    dir_whitelist=["alice", "bob"],
)

resp = client.volumes.create_dir(
    volume_id=230,
    dir_type="custom",
    path="/shared-volume/project-a",
)
entry_id = resp.data["id"]

client.volumes.set_dir_grants(
    volume_id=230,
    entry_id=entry_id,
    grants=[
        {"user": "alice", "perm": "rw"},
        {"user": "bob", "perm": "r"},
    ],
)
```

## 相关文档

* [Python SDK 快速开始](./python-sdk-quickstart)
* [创建和使用存储卷](../resources/create-and-use-storage-volumes)
* [配置 Volume 目录级权限](../resources/configure-volume-directory-permissions)