云存储Pro（CFS）接口

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

使用前须知

• 当前创建、扩容、删除和询价能力面向 *容器可用区，普通云主机可用区不支持这套 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. 选择容器可用区，调用 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。

创建新容器实例时，还可以在 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)