文件存储操作指南

本文面向初次使用 CFS Turbo 的 S3接入点的用户，介绍接入点的新建、策略配置、监控查看、修改和删除等完整操作流程。
注意：
此功能目前需开白使用，若需要使用可 提交工单 与我们联系。
前置条件
已创建 Turbo 文件系统，创建流程请参见 在 Linux 客户端上使用 CFS Turbo 文件系统。
已在 Turbo 文件系统所在可用区创建 VPC 及子网，并保证与 Turbo 文件系统网络互通，且指定的子网下可用 IP 数量 大于等于10。创建 VPC 及子网操作详见 快速搭建 IPv4 私有网络。
说明：
首次使用时，单击新建接入点，系统会自动检查当前账号是否授权（预设）权限策略，包括 QcloudDNSPubReadOnlyAccess（公共解析(DNSPub)只读访问权限）和 QcloudVPCReadOnlyAccess（私有网络(VPC)只读访问权限）。若未授权，会弹出授权确认框，单击同意授权后方可继续创建。
新建接入点
1. 登录 文件存储控制台，单击目标 Turbo 文件系统的实例 ID，进入文件系统详情页，选择侧边栏中的 S3接入点。
﻿
2. 在 TurboS3接入点配置界面，单击新建接入点。在新建接入点弹窗中配置以下内容：
﻿
配置项
介绍
基本设置（必选）
选择网络
选择与 Turbo 文件系统相同可用区的 VPC 及子网。如需其他 VPC 网络下客户端能够通过 S3协议访问 Turbo 文件系统，请在高级设置中进行配置。
注意：
配置成功后，所选 VPC 不允许被绑定到其他 Turbo 文件系统 S3接入点。
﻿
鉴权策略
仅私有读写（推荐）：所有操作均需 Secret ID/Secret Key 身份验证
公有读私有写（高风险）：读操作无需验证，写操作需身份验证
公有读写（高风险）：读写均无需身份验证
注意：
公有读私有写、公有读写策略会导致数据在无需认证的情况下被访问，存在安全风险，非必要请勿使用。
高级设置（可选）
关联其他 VPC
希望其他 VPC 下客户端能够通过 S3协议访问 Turbo 文件系统，可以配置。
注意：
所选 VPC 需与 S3接入点 VPC 互通网络，否则即便关联上，也无法通过 S3协议访问 Turbo 文件系统。您可以通过云联网关联不同的 VPC，详情请参见 云联网快速入门。
配置成功后，所选 VPC 不允许关联到其他 Turbo 文件系统 S3接入点。
﻿
3. 确认无误后单击确定，等待接入点状态从配置中转变为可用。在可用状态下，您可以继续配置权限策略。
接入点状态说明
状态
说明
配置中
接入点正在初始化，请等待。
可用
接入点正常运行，可进行所有操作。
失败
接入点创建或操作失败，可尝试编辑或删除后重建。
删除中
接入点正在被删除，请勿重复操作。
配置权限策略
接入点创建成功后，可配置细粒度的访问策略。
创建策略
1. 在接入点列表中，单击目标接入点左侧的展开箭头，查看该接入点的策略列表。
﻿
2. 单击创建策略，在权限策略配置弹窗中，填写以下信息。在授权策略部分，
账号信息：
分类
参数
介绍
账号信息
Secret ID
被授权账号的腾讯云 Secret ID。Secret ID/Secret Key 需由管理员账号登录腾讯云 访问管理 CAM > API 密钥 控制台生成，创建方式详见 子账号管理。
﻿
Secret Key
与 Secret ID 对应的 Secret Key。
注意：
Secret Key 仅用于服务端签名验证，查询不会回显。请自行维护好 Secret ID 和 Secret Key，防止被他人盗用。一旦泄露，请及时删除 S3 接入点绑定的策略。
授权策略：您可以使用可视化策略生成器或者 JSON 创建策略。
可视化策略生成器
JSON
﻿
分类
参数
介绍
授权策略
效果（Effect）
选择允许(Allow)或拒绝(Deny)
﻿
操作（Action）
可从预设选择（读写操作、读操作、写操作），也可精细选取单个操作。其中：
读操作预设包含：HeadBucket、GetObject、HeadObject、ListObjects、ListObjectsV2、ListMultipartUploads、ListParts
写操作预设包含：PutObject、DeleteObject、DeleteObjects、CreateMultipartUpload、UploadPart、CompleteMultipartUpload、AbortMultipartUpload、CopyObject、UploadPartCopy
读写操作预设包含上述两类操作
说明：
TurboS3提供了 AWS S3兼容的 API，操作详情请参见 AWS S3 API 介绍。
﻿
资源（Resource）
设置策略覆盖的资源范围：
全部资源：值为*。（默认）策略覆盖文件系统根目录下所有文件和目录。
指定资源路径：值为文件系统内目录路径/*，策略覆盖文件系统路径下指定文件或目录。您可添加多个资源路径。
﻿
策略 JSON 和 AWS S3接入点策略语法基本兼容，以下是简要的语法说明和示例，您也可以通过可视化策略生成器转换的 JSON 内容进行学习和模仿：
顶层结构：
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow", // 或者 "Deny"
      "Action": [...],
      "Resource": [...]
    }
  ]
}
示例1：全量访问策略（允许该 SecretId 操作所有资源）：
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:*"
      ],
      "Resource": [
        "arn:aws:s3:::cfs-xxxxxx",
        "arn:aws:s3:::cfs-xxxxxx/*"
      ]
    }
  ]
}
示例2：读写策略（允许该 SecretId 对指定目录读写，但拒绝删除）：
﻿
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:HeadBucket",
        "s3:GetObject",
        "s3:HeadObject",
        "s3:ListObjects",
        "s3:ListObjectsV2",
        "s3:ListMultipartUploads",
        "s3:ListParts",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:DeleteObjects",
        "s3:CreateMultipartUpload",
        "s3:UploadPart",
        "s3:CompleteMultipartUpload",
        "s3:AbortMultipartUpload",
        "s3:CopyObject",
        "s3:UploadPartCopy"
      ],
      "Resource": [
        "arn:aws:s3:::cfs-xxxxxx",
        "arn:aws:s3:::cfs-xxxxxx/aaa/bbb/*"
      ]
    },
    {
      "Effect": "Deny",
      "Action": [
        "s3:DeleteObject",
        "s3:DeleteObjects"
      ],
      "Resource": [
        "arn:aws:s3:::cfs-xxxxxx",
        "arn:aws:s3:::cfs-xxxxxx/*"
      ]
    }
  ]
}
示例3：只读策略（只允许该 SecretId 读取特定目录）：
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:HeadBucket",
        "s3:GetObject",
        "s3:HeadObject",
        "s3:ListObjects",
        "s3:ListObjectsV2",
        "s3:ListMultipartUploads",
        "s3:ListParts"
      ],
      "Resource": [
        "arn:aws:s3:::cfs-xxxxxx",
        "arn:aws:s3:::cfs-xxxxxx/aaa/bbb/*"
      ]
    }
  ]
}
3. 单击确定完成策略创建，等待策略状态从配置中转变为可用。
编辑策略
1. 登录 文件存储控制台，单击目标 Turbo 文件系统的实例 ID，进入文件系统详情页，点击侧边栏中的 S3接入点 。
2. 单击 S3接入点左侧展开箭头，在策略列表找到目标策略，仅策略状态为可用或已失效时支持操作。
3. 单击操作列编辑。
4. 修改目标字段后单击确定，等待策略状态从配置中转变为可用。
注意：
修改策略须再次填写 Secret Key，否则无法保存。
下载策略 JSON
1. 登录 文件存储控制台，单击目标 Turbo 文件系统的实例 ID，进入文件系统详情页，点击侧边栏中的 S3接入点 。
2. 单击 S3接入点左侧展开箭头，查看该接入点的策略列表，操作栏单击下载 JSON，可将授权策略导出为本地 JSON 文件，便于备份或审查。
删除策略
1. 登录 文件存储控制台，单击目标 Turbo 文件系统的实例 ID，进入文件系统详情页，点击侧边栏中的 S3接入点 。
2. 单击 S3接入点左侧展开箭头，在策略列表找到目标策略。单击操作列删除，确认后策略进入删除流程。
注意：
删除策略后对应账号的访问权限立即失效，请确认业务侧已做好切换准备。
查看监控
1. 在接入点列表，单击目标接入点的监控图标或操作列的监控。
﻿
2. 在监控面板中查看该接入点的读写带宽统计，您可自行调整时间范围和时间粒度进行对比分析。
修改接入点
注意：
修改接入点仅支持高级设置中绑定 VPC 的增减。
1. 登录 文件存储控制台，单击目标 Turbo 文件系统的实例 ID，进入文件系统详情页，点击侧边栏中的 S3接入点 。
2. 在接入点列表，找到目标接入点，仅可用或已失效的接入点支持修改。
3. 单击操作列的编辑。
4. 在弹出框中，通过高级设置的穿梭框添加或移除绑定 VPC：
左侧选择地域和 VPC，单击添加到右侧。
右侧已绑定列表中，单击移除按钮可解绑对应 VPC。
5. 确认无误后单击确定保存。
删除接入点
注意：
删除操作不可恢复，且必须先删除接入点下的所有权限策略，才能删除接入点本身。
1. 登录 文件存储控制台，单击目标 Turbo 文件系统的实例 ID，进入文件系统详情页，选择侧边栏中的 S3接入点 。
2. 在接入点列表，找到目标接入点，单击操作列的删除。
说明：
仅可用（且无策略）和失败状态的接入点可删除；配置中和删除中状态不可操作。
3. 在确认弹窗中单击确定，接入点进入删除中状态，删除完成后将从 S3接入点列表中消失。
S3相关配置项说明
兼容 S3尤其是支持 Amazon S3的第三方应用或 SDK，核心配置均涉及以下6个字段。不同应用对这些字段的命名可能不同，请对照下表填写：
基础配置项
配置项常见名称
说明
TurboS3 填写内容参考
Endpoint / 服务端点
S3兼容服务地址
填入 https://turbos3.internal.tencentcfs.com
Access Key
访问密钥 ID
鉴权策略中配置的 Secret ID
Secret Key
访问密钥 Key
鉴权策略中配置的 Secret Key
Bucket / 存储桶
目标文件系统
填入 Turbo 文件系统的实例 ID（形如 cfs-xxxxxxx）
注意：
Turbo S3无需拼入 APPID，直接填写文件系统 ID 即可。
Region（如需填写）
地域
留空，如应用强制要求填写，请选择文件系统所在可用区对应的地域简称（如 ap-guangzhou）
Provider / 服务提供商（如需填写）
选择存储后端类型
如需填写，可选择 S3 Compatible 。
注意：
部分应用直接通过自定义 Endpoint 识别 S3兼容存储，无需单独选择 Provider。
高级配置项
配置项
推荐值
说明
协议
HTTPS
Turbo S3使用自签证书，如应用报 SSL 证书错误，可导入自签 CA ，不支持 HTTP 协议
签名版本
AWS Signature V4
与标准 S3 SDK 兼容
URL 风格 / Addressing Style
Virtual-Hosted-Style
Turbo S3仅支持 Virtual-Hosted-Style，不支持 Path-Style。如应用提供选项，务必选择 Virtual-Hosted-Style。
端口
443（HTTPS）
无需开放额外端口
S3 SDK&CLI 使用示例
前置条件
在开始配置前，请确认以下条件已满足：
参考 新建接入点 为 Turbo 文件系统配置 TurboS3，同时获取并保存了鉴权策略的 Secret ID 和 Secret Key。
应用所在环境已与 Turbo 实例网络互通：应用运行所在的 CVM / 容器必须在 TurboS3关联的 VPC 下。
Python S3 SDK 使用指南
前置准备
Linux
Windows（PowerShell）
1. 安装 Python 3 及 pip（如已安装可跳过）。
TencentOS / CentOS：
sudo yum install -y python3 python3-pip
Ubuntu / Debian
sudo apt update && sudo apt install -y python3 python3-pip
2. 安装 boto3。
pip3 install boto3 botocore
3. 验证安装。
python3 -c "import boto3; print(boto3.__version__)"
1. 下载安装 Python 3（如已安装可跳过）。前往 Python 官网 下载安装包，勾选 Add Python to PATH。
2. 安装 boto3。
  pip install boto3 botocore
3. 验证安装。
python -c "import boto3; print(boto3.__version__)"
SDK 使用示例
import boto3
from botocore.client import Config
﻿
﻿
endpoint_url = "https://turbos3.internal.tencentcfs.com"
# ===== 修改以下 3 个变量 =====
fs_id       = "<your-filesystem-id>"     # 形如 cfs-xxxxxxx
access_key  = "<your-secret-id>"
secret_key  = "<your-secret-key>"
# ============================
﻿
s3 = boto3.client(
    "s3",
    endpoint_url=endpoint_url,
    aws_access_key_id=access_key,
    aws_secret_access_key=secret_key,
    config=Config(s3={"addressing_style": "virtual"}, signature_version="s3v4"),
    verify=False,
)
﻿
test_key = "s3-connectivity-test.txt"
﻿
try:
    # 1. 上传测试文件
    s3.put_object(Bucket=fs_id, Key=test_key, Body=b"Turbo S3 connected!")
    print(f"[OK] 测试文件 {test_key} 上传成功")
﻿
    # 2. 读取验证
    obj = s3.get_object(Bucket=fs_id, Key=test_key)
    content = obj["Body"].read().decode()
    print(f"[OK] 读取验证成功，内容: {content}")
﻿
    # 3. 清理
    s3.delete_object(Bucket=fs_id, Key=test_key)
    print(f"[OK] 测试文件已清理")
﻿
    print("\\n=== Turbo S3 连通性验证全部通过 ===")
﻿
except Exception as e:
    print(f"[FAIL] 操作失败: {e}")
    # 尝试清理残留文件
    try:
        s3.delete_object(Bucket=fs_id, Key=test_key)
    except:
        pass
执行脚本
# Linux
python3 test_turbos3_full.py
﻿
# Windows（PowerShell）
python test_turbos3_full.py
预期输出
﻿
AWS CLI 命令行工具使用指南
前置准备
Linux
Windows（PowerShell）
1. 安装 AWS CLI。
 通过包管理器安装。
# TencentOS / CentOS 
sudo yum install -y awscli
# Ubuntu / Debian
sudo apt update && sudo apt install -y awscli
通过 pip 安装（推荐，版本更新）。
pip3 install awscli --upgrade
官方安装脚本（适用于任何 Linux）。
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
2. 验证安装。
aws --version
1. 安装 AWS CLI。
通过 pip 安装（推荐）。
pip install awscli
下载官方 MSI 安装包。前往 AWS CLI 官网 下载对应架构的 .msi 文件，双击进行安装。
2. 验证安装。
aws --version
配置凭据（选择其一）
方式一：临时修改环境配置
Linux：
export AWS_ACCESS_KEY_ID="<your-secret-id>"
export AWS_SECRET_ACCESS_KEY="<your-secret-key>"
Windows（PowerShell）：
$env:AWS_ACCESS_KEY_ID="<your-secret-id>"
$env:AWS_SECRET_ACCESS_KEY="<your-secret-key>"
方式二：持久化配置环境变量。凭据保存至 ~/.aws/credentials（Linux）或 %USERPROFILE%\\.aws\\credentials（Windows），后续命令无需重复指定。
# Linux & Windows 通用
aws configure set aws_access_key_id <your-secret-id>
aws configure set aws_secret_access_key <your-secret-key>
执行连通性测试
aws s3 ls s3://<your-filesystem-id>/ \\
    --endpoint-url https://turbos3.internal.tencentcfs.com \\
    --no-verify-ssl
预期输出
成功连上 Turbo S3并列出文件系统内容，例如 stress-test/ 是测试文件系统里的一个目录。
﻿
常用 AWS CLI 命令：
# 上传文件
aws s3 cp /path/to/local/file s3://<fs-id>/remote/path \\ 
    --endpoint-url https://turbos3.internal.tencentcfs.com --no-verify-ssl
﻿
# 下载文件
aws s3 cp s3://<fs-id>/remote/file /path/to/local/ \\ 
    --endpoint-url https://turbos3.internal.tencentcfs.com --no-verify-ssl
﻿
# 同步目录（递归）
aws s3 sync /local/dir/ s3://<fs-id>/remote/dir/ \\ 
    --endpoint-url https://turbos3.internal.tencentcfs.com --no-verify-ssl
﻿
# 删除对象
aws s3 rm s3://<fs-id>/remote/file \\ 
    --endpoint-url https://turbos3.internal.tencentcfs.com --no-verify-ssl
常见问题
子网可用 IP 不足怎么办？
在创建接入点时，页面会显示所选子网的可用 IP 数量。如不足10个，请前往 VPC 控制台 扩容子网 CIDR 或新建子网。
创建接入点时提示授权失败怎么办？
请检查当前账号是否有操作服务角色的权限（CAM:CreateRole、CAM:AttachRolePolicies 等），或联系主账号在 CAM 控制台 完成服务授权。
接入点状态一直显示配置中怎么处理？
如创建超过10分钟仍未变为可用，请尝试刷新页面或 提交工单 与我们联系。
绑定了新 VPC 后客户端仍无法访问怎么排查？
请确认客户端所在子网路由表已配置访问 turbos3.internal.tencentcfs.com 域名的正确路由，并检查安全组规则是否放行对应端口。
提示“NoSuchBucket”错误，是什么原因？
此错误通常由 Bucket 名称格式填写错误导致。请您核对配置信息，确保填写的是文件系统 ID（格式示例：cfs-xxxxxxx），无需在末尾拼接 -APPID 后缀。
出现连接超时，如何排查？
连接超时通常与网络连通性有关。请您首先检查运行应用的云服务器（CVM）或容器实例，是否部署在与 Turbo S3关联的私有网络（VPC）之下。
TurboS3和基于 Turbo 客户端正常挂载能否同时使用？
可以。TurboS3与基于 Turbo 客户端正常挂载的 CFS Turbo 文件系统共享同一个命名空间。这意味着，通过任一协议写入的数据，另一协议（ POSIX 协议）均可立即读取访问，实现了数据的无缝互通。

配置项常见名称	说明	TurboS3 填写内容参考
Endpoint / 服务端点	S3兼容服务地址	填入 `https://turbos3.internal.tencentcfs.com`
Access Key	访问密钥 ID	鉴权策略中配置的 Secret ID
Secret Key	访问密钥 Key	鉴权策略中配置的 Secret Key
Bucket / 存储桶	目标文件系统	填入 Turbo 文件系统的实例 ID（形如 `cfs-xxxxxxx`）注意： Turbo S3无需拼入 APPID，直接填写文件系统 ID 即可。
Region（如需填写）	地域	留空，如应用强制要求填写，请选择文件系统所在可用区对应的地域简称（如 `ap-guangzhou`）
Provider / 服务提供商（如需填写）	选择存储后端类型	如需填写，可选择 S3 Compatible 。注意：部分应用直接通过自定义 Endpoint 识别 S3兼容存储，无需单独选择 Provider。

	配置项	介绍
基本设置（必选）	选择网络	选择与 Turbo 文件系统相同可用区的 VPC 及子网。如需其他 VPC 网络下客户端能够通过 S3协议访问 Turbo 文件系统，请在高级设置中进行配置。注意：配置成功后，所选 VPC 不允许被绑定到其他 Turbo 文件系统 S3接入点。
基本设置（必选）		鉴权策略	仅私有读写（推荐）：所有操作均需 Secret ID/Secret Key 身份验证公有读私有写（高风险）：读操作无需验证，写操作需身份验证公有读写（高风险）：读写均无需身份验证注意：公有读私有写、公有读写策略会导致数据在无需认证的情况下被访问，存在安全风险，非必要请勿使用。
高级设置（可选）	关联其他 VPC	希望其他 VPC 下客户端能够通过 S3协议访问 Turbo 文件系统，可以配置。注意：所选 VPC 需与 S3接入点 VPC 互通网络，否则即便关联上，也无法通过 S3协议访问 Turbo 文件系统。您可以通过云联网关联不同的 VPC，详情请参见云联网快速入门。配置成功后，所选 VPC 不允许关联到其他 Turbo 文件系统 S3接入点。

状态	说明
配置中	接入点正在初始化，请等待。
可用	接入点正常运行，可进行所有操作。
失败	接入点创建或操作失败，可尝试编辑或删除后重建。
删除中	接入点正在被删除，请勿重复操作。

分类	参数	介绍
账号信息	Secret ID	被授权账号的腾讯云 Secret ID。Secret ID/Secret Key 需由管理员账号登录腾讯云访问管理 CAM > API 密钥控制台生成，创建方式详见子账号管理。
账号信息		Secret Key	与 Secret ID 对应的 Secret Key。注意： Secret Key 仅用于服务端签名验证，查询不会回显。请自行维护好 Secret ID 和 Secret Key，防止被他人盗用。一旦泄露，请及时删除 S3 接入点绑定的策略。

配置项	推荐值	说明
协议	HTTPS	Turbo S3使用自签证书，如应用报 SSL 证书错误，可导入自签 CA ，不支持 HTTP 协议
签名版本	AWS Signature V4	与标准 S3 SDK 兼容
URL 风格 / Addressing Style	Virtual-Hosted-Style	Turbo S3仅支持 Virtual-Hosted-Style，不支持 Path-Style。如应用提供选项，务必选择 Virtual-Hosted-Style。
端口	443（HTTPS）	无需开放额外端口

操作指南

本页目录：

前置条件

新建接入点

接入点状态说明

配置权限策略

创建策略

编辑策略

下载策略 JSON

删除策略

查看监控

修改接入点

删除接入点

S3相关配置项说明

基础配置项

高级配置项

S3 SDK&CLI 使用示例

前置条件

Python S3 SDK 使用指南

前置准备

SDK 使用示例

执行脚本

预期输出

AWS CLI 命令行工具使用指南

前置准备

配置凭据（选择其一）

执行连通性测试

预期输出

常用 AWS CLI 命令：

常见问题

子网可用 IP 不足怎么办？

创建接入点时提示授权失败怎么办？

接入点状态一直显示配置中怎么处理？

绑定了新 VPC 后客户端仍无法访问怎么排查？

提示“NoSuchBucket”错误，是什么原因？

出现连接超时，如何排查？

TurboS3和基于 Turbo 客户端正常挂载能否同时使用？