文件存储在兼容 S3的第三方应用中配置 TurboS3

本文面向需要在兼容 S3的第三方应用中配置 TurboS3的用户，介绍配置所需的前置条件、基本与高级配置项、三种连通性验证方式及常见问题解决方案。
前置条件
在开始配置前，请确认以下条件已满足：
1. 已创建 Turbo 文件系统，创建流程请参见 在 Linux 客户端上使用 CFS Turbo 文件系统，且 Turbo 文件系统状态为可使用。
2. 参考 在控制台配置 TurboS3 为 Turbo 文件系统配置 TurboS3，并获取并保存了鉴权策略的 Secret ID 和 Secret Key。
3. 应用所在环境已与 Turbo 实例网络互通：应用运行所在的 CVM / 容器必须在 TurboS3关联的 VPC 下。
4. 目标第三方应用或 SDK 支持 S3兼容协议。
注意：
TurboS3目前需开白使用，若需要使用可 提交工单 与我们联系。TurboS3仅支持腾讯云内网访问，不支持从公网直接访问，无法通过公网 IP 或 NAT 网关连接。
基本配置项
兼容 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）
无需开放额外端口
连通性验证
完成配置后，建议通过以下方式快速验证 TurboS3是否连通以及文件上传下载等操作是否正常。以下示例中：
<your-secret-id> / <your-secret-key>：鉴权策略中配置的 Secret ID / Secret Key
<your-filesystem-id>：替换为 Turbo 文件系统的实例 ID（形如 cfs-xxxxxxx）
方式一：Python 连通性检测
前置准备
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__)"
创建脚本
将以下内容保存为 test_turbos3.py 。
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": "path"},
        signature_version="s3v4",
    ),
    verify=False,
)
﻿
try:
    response = s3.list_objects_v2(Bucket=fs_id, MaxKeys=1)
    print(f"[OK] Turbo S3 连接成功！文件系统: {fs_id}")
    contents = response.get("Contents", [])
    if contents:
        print(f"  示例文件: {contents[0]['Key']} ({contents[0]['Size']} bytes)")
    else:
        print(f"  存储桶为空，没有对象。")
except Exception as e:
    print(f"[FAIL] 连接失败: {e}")
执行脚本
# Linux
python3 test_turbos3.py
﻿
# Windows（PowerShell）
python test_turbos3.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
方式三：Python 完整文件流程测试
前置准备
确保已安装 Python 3 和 boto3：
# Linux
pip3 install boto3 botocore
﻿
# Windows
pip install boto3 botocore
创建脚本
将以下内容保存为 test_turbos3_full.py：
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": "path"}, 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
预期输出
﻿
常见问题
连接报 SSL 证书错误，应如何处理？
请将 Turbo S3的自签 CA 证书导入至您应用的信任证书库中。
提示“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。

配置项	推荐值	说明
协议	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的第三方应用中配置 TurboS3

本页目录：

前置条件

基本配置项

高级配置项

连通性验证

方式一：Python 连通性检测

前置准备

创建脚本

执行脚本

预期输出

方式二：AWS CLI 命令行批量管理

前置准备

配置凭据（选择其一）

执行连通性测试

预期输出

常用 AWS CLI 命令速查

方式三：Python 完整文件流程测试

前置准备

创建脚本

执行脚本

预期输出

常见问题

连接报 SSL 证书错误，应如何处理？

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

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

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