云存储Pro（CFS）接口

云存储Pro（CFS）为 Pod 实例提供独立的文件存储。同一账号、同一可用区的多个 Pod 实例可以挂载同一份 CFS；卸载只是解除实例与存储的挂载关系，不会删除 CFS。

使用前须知

• 当前创建、扩容、删除和询价能力面向 Pod 可用区，普通云主机可用区不支持这套 CFS 操作。可通过 DescribeCompShareSupportZone 查询可用区并查看 IsPod。
• 每个账号在同一可用区最多有 1 份未删除的 CFS，这个限制不会因为切换项目而增加。挂载时使用实例实际所在可用区的 CFS，不支持跨可用区挂载。
• 容量为 50～2048 GiB（最大 2 TiB），支持扩容，不支持缩容。
• 创建和购买询价支持 Month、Year、Day、Dynamic，默认 Month，不支持新购 Postpay。
• 给运行中的实例挂载或卸载 CFS 会自动停止并启动实例，请先保存任务并安排业务中断窗口。
• 创建、扩容及首次自动开通存储会产生费用；删除前请备份数据。

接口一览

挂载 CFS 复用 AttachUS3，不是 AttachCFS。AttachUS3 对 cpod- 实例执行 CFS 挂载，对普通 uhost- 实例则执行 US3 对象存储挂载。两种场景的使用限制不同。

推荐调用流程

首次创建并挂载

1. 选择 Pod 可用区，调用 DescribeCFS 检查当前项目下是否已有 CFS。同一账号在其他项目中已有 CFS 时，也不能在该可用区重复创建。
2. 如需新建，调用 GetCompShareCFSPrice 确认价格，再用相同的 Size、ChargeType、Quantity 调用 CreateCFS。
3. 调用 AttachUS3，只需传目标实例的 UHostId 和地域、可用区，不需要指定 CfsId。
4. 调用 DescribeCFS 检查 MountStatus 和 MountedUHostIds，并通过 DescribeCompShareInstance 确认实例恢复运行。

也可以直接调用 AttachUS3： 如果账号在实例所在可用区尚无 CFS，接口会自动创建 50 GiB、按月计费、购买周期为 1 的 CFS，再进行挂载。这不是免费的挂载动作；如果需要自选容量、计费方式或代金券，请先调用 CreateCFS。

创建新 Pod 实例时，还可以在 CreateCompShareInstance 中设置 EnableCfs=true，挂载账号在同一可用区已有的 CFS。该参数默认 false；找不到已有 CFS 时实例仍会正常创建，但不会自动创建 CFS，和直接调用 AttachUS3 的行为不同。

扩容

先查询当前容量，再用同一目标 Size 依次调用 GetCompShareCFSUpgradePrice 和 ResizeCFS。例如从 100 GiB 扩到 200 GiB，传 Size=200，不是 100。完成后重新查询 DescribeCFS 确认容量。

卸载与删除

先备份数据，通过 DescribeCFS 查看挂载实例；调用 DetachCFS 解除所有挂载后，再调用 DeleteCFS。如果仍有挂载，默认删除会被拒绝，实例关机不等于已卸载。

也可以在确认相关实例均已停止后，使用 DeleteCFS 的 Recycle=true 先卸载再删除。它不是回收站或强制删除开关：检测到运行中的挂载实例时会拒绝删除，并返回 RunningUHostIds。退费可提前通过 GetCompShareCFSRefundPrice 预览，最终以删除时的结算为准。

请求格式与鉴权

这些接口使用 GPU OpenAPI 的公钥、私钥签名，不使用模型 API Key。配置方式见 API 接口范例。各接口页的 JSON 是请求参数示例，正式调用时由 SDK 完成签名；也可以使用页面上的「试一试」。

Region、Zone 使用地域和可用区名称，ProjectId 可用于指定项目。账号标识和内部数字可用区 ID 由网关处理，不需要自行填写 top_organization_id、organization_id、zone_id。

以下示例只查询存储，不会创建或变更资源。其他 Action 可以使用同样的 SDK 通用调用方式，参数以对应接口页为准。

import os
from ucloud.client import Client
from ucloud.core import exc
 
client = Client({
    "region": "cn-bj2",
    "public_key": os.environ["UCLOUD_PUBLIC_KEY"],
    "private_key": os.environ["UCLOUD_PRIVATE_KEY"],
    "base_url": "https://api.compshare.cn",
})
 
try:
    response = client.ucompshare().invoke("DescribeCFS", {
        "Region": "cn-bj2",
        "Zone": "cn-bj2-03",
    })
    for item in response.get("CFSSet", []):
        print(item["CfsId"], item.get("Size"), item.get("MountStatus"))
except exc.UCloudException as error:
    print("请求失败：", error)