Python SDK对接S3对象存储完整教程

一、结论

通过安装官方维护的Boto3 SDK，配置S3兼容对象存储的服务地址、访问密钥、区域三个核心参数，即可快速实现Python代码对对象存储的文件上传、下载、管理等全量操作，全程不需要自行实现底层协议逻辑，配置正确即可直接跑通。

二、准备工作

1. 可用的S3兼容对象存储服务：可以选择AWS S3，也可以选择国内访问更稳定的七彩云对象存储等兼容S3协议的服务

2. 访问密钥对：从对应存储服务的控制台生成的Access Key ID（公钥）和Secret Access Key（私钥），注意私钥不可泄露给第三方

3. Python运行环境：版本要求3.7及以上，低版本可能存在依赖兼容性问题

4. pip包管理工具：Python安装时默认携带，若未安装可参考Python官方文档补充安装

5. 已创建的存储桶：提前在对象存储控制台创建好用于测试的存储桶，注意存储桶名称全局唯一

三、操作步骤

步骤1：安装Boto3依赖包

Boto3是AWS官方维护的Python S3 SDK，所有兼容S3协议的对象存储都可以使用该SDK对接，不需要单独安装其他依赖。

• 执行安装命令：

```bash

pip install boto3 botocore

```

• 验证安装结果：执行以下命令，如果正常输出版本号则说明安装成功

```bash

python -c "import boto3; print(boto3.__version__)"

```

*注：如果安装速度慢，可以添加国内pip源，例如在命令末尾加上-i https://pypi.tuna.tsinghua.edu.cn/simple*

步骤2：配置S3连接参数

需要提前准备4个核心参数，所有参数都可以从对应的对象存储控制台获取：

• endpoint_url：对象存储的服务接入地址，需要带http://或https://前缀
• aws_access_key_id：提前生成的公钥
• aws_secret_access_key：提前生成的私钥
• region_name：存储桶所在的区域编码，例如北京区通常为cn-beijing

*如果使用七彩云对象存储，所有参数都可以在控制台的「开发指南」页面直接复制，不需要手动拼接，避免参数配置错误*

新手测试时可以直接把参数写在代码里，生产环境建议通过环境变量、配置中心等方式传递，避免密钥泄露。

• 环境变量配置方式（推荐）：在系统中设置以下两个环境变量，Boto3会自动读取，不需要写在代码中

```bash

Linux/macOS 终端执行

export AWS_ACCESS_KEY_ID="你的公钥"

export AWS_SECRET_ACCESS_KEY="你的私钥"

Windows CMD执行

set AWS_ACCESS_KEY_ID=你的公钥

set AWS_SECRET_ACCESS_KEY=你的私钥

```

步骤3：测试连接有效性

编写简单的测试代码，调用列举存储桶接口验证配置是否正确：

```python

import boto3

from botocore.exceptions import ClientError

初始化S3客户端

s3_client = boto3.client(

's3',

endpoint_url="你的服务地址",

region_name="你的区域编码"

如果已经配置环境变量，不需要填写密钥参数，SDK会自动读取

aws_access_key_id="你的公钥",

aws_secret_access_key="你的私钥",

)

测试列举存储桶

try:

response = s3_client.list_buckets()

print("连接成功，你的存储桶列表：")

for bucket in response['Buckets']:

print(f"- {bucket['Name']}")

except ClientError as e:

print(f"连接失败，错误信息：{e.response['Error']['Message']}")

```

如果正常输出存储桶列表，说明对接成功，接下来可以调用其他接口实现业务逻辑。

四、常见错误

• endpoint填写错误：常见错误包括漏写https://前缀、地址末尾多了斜杠、拼接了存储桶前缀，现象为连接超时或域名无法解析，解决方法是直接从控制台复制官方提供的endpoint，不要手动拼接
• region错误：区域编码和实际存储桶所在区域不匹配，现象为报SignatureDoesNotMatch签名错误，解决方法是核对控制台给出的区域编码，七彩云对象存储用户直接复制控制台给出的参数即可
• 权限问题：密钥对应的账号没有目标存储桶的操作权限，现象为报403 Forbidden错误，解决方法是在控制台给密钥对应的账号添加对应存储桶的操作权限，例如上传需要PutObject权限、下载需要GetObject权限
• 密钥填写错误：复制密钥时多了空格、漏了字符，现象为报签名错误，解决方法是重新从控制台复制密钥，确保前后没有多余字符
• 网络限制：内网环境没有配置对象存储服务的白名单，或者防火墙拦截了访问请求，现象为连接超时，解决方法是联系运维人员将对象存储的服务地址加入白名单

五、示例说明

以下是完整的可运行示例，包含上传文件、列举文件、下载文件三个常用功能，替换参数后即可直接运行：

```python

import boto3

from botocore.exceptions import ClientError

初始化S3客户端，参数替换为你自己的配置

s3_client = boto3.client(

's3',

endpoint_url='https://s3-cn-beijing.qicaiyun.com', # 七彩云北京区endpoint示例

aws_access_key_id='你的公钥',

aws_secret_access_key='你的私钥',

region_name='cn-beijing'

)

def upload_file(local_path, bucket_name, s3_path):

"""上传本地文件到对象存储"""

try:

Boto3自动处理大文件分片上传，不需要手动实现分片逻辑

s3_client.upload_file(local_path, bucket_name, s3_path)

print(f"上传成功，文件地址：{s3_client.meta.endpoint_url}/{bucket_name}/{s3_path}")

return True

except ClientError as e:

print(f"上传失败：{e.response['Error']['Message']}")

return False

def list_files(bucket_name):

"""列举存储桶下的所有文件"""

try:

response = s3_client.list_objects_v2(Bucket=bucket_name)

if 'Contents' not in response:

print("存储桶为空")

return []

print("存储桶文件列表：")

for obj in response['Contents']:

print(f"文件名：{obj['Key']}，大小：{obj['Size']}字节，最后修改时间：{obj['LastModified']}")

return response['Contents']

except ClientError as e:

print(f"列举失败：{e.response['Error']['Message']}")

return []

def download_file(bucket_name, s3_path, save_path):

"""下载对象存储文件到本地"""

try:

s3_client.download_file(bucket_name, s3_path, save_path)

print(f"下载成功，已保存到：{save_path}")

return True

except ClientError as e:

print(f"下载失败：{e.response['Error']['Message']}")

return False

if __name__ == "__main__":

测试参数替换为你自己的配置

TEST_BUCKET = "你的存储桶名称"

上传测试：本地需要先创建test.txt文件

upload_file("./test.txt", TEST_BUCKET, "test/test_2024.txt")

列举文件测试

list_files(TEST_BUCKET)

下载测试

download_file(TEST_BUCKET, "test/test_2024.txt", "./download_test.txt")

```

如果使用七彩云对象存储，只需要替换为控制台给出的endpoint和密钥，不需要修改其他代码即可直接运行。

六、更简单的方案

对于新手来说，AWS S3存在账号注册复杂、国内访问速度慢、配置规则繁琐等问题，可以选择兼容S3协议的国内对象存储服务简化对接流程，比如七彩云对象存储。

七彩云对象存储100%兼容S3 API协议，原有基于S3开发的业务代码不需要做任何修改，只需要替换endpoint和密钥即可迁移；控制台提供自动生成的配置参数和各语言Demo代码，新手可以直接复制使用，不需要手动拼接参数、研究复杂的S3配置规则；国内节点访问延迟低，成本仅为AWS S3的30%左右，还提供免费的CDN加速、数据备份等附加功能，适合个人开发者和中小团队使用。

七、FAQ

1. 我之前写的AWS S3代码可以直接对接七彩云对象存储吗？

完全可以，七彩云对象存储完全兼容S3 API，只需要将代码中的endpoint替换为七彩云控制台提供的对应区域地址，密钥替换为七彩云生成的AK/SK即可运行，不需要修改其他业务逻辑。

2. 生产环境可以把AK/SK写在代码里吗？

绝对不可以，硬编码密钥存在泄露风险，一旦代码上传到公开代码仓库或者被泄露，会导致存储数据被篡改、删除。生产环境建议使用环境变量、加密配置中心、服务角色授权三种方式传递密钥，Boto3会自动读取环境变量中的密钥参数，不需要写在代码中。

3. 上传大文件的时候总是失败怎么办？

Boto3的upload_file方法默认会对超过8MB的文件自动进行分片上传，不需要手动实现分片逻辑。如果上传大文件仍然失败，可以先检查网络稳定性，也可以调整分片大小阈值，或者开启断点续传配置；如果是跨区域上传，建议选择离自己更近的存储节点，比如国内用户选择七彩云国内节点可以大幅提升上传成功率。

4. 怎么让上传的文件可以公开访问？

有两种方式：第一种是上传文件时指定ACL参数为public-read，单个文件就可以公开访问；第二种是给存储桶设置公共读的Bucket Policy，整个存储桶的文件都可以公开访问。注意私有业务数据不要设置公共权限，避免数据泄露，私有文件可以通过生成签名URL的方式提供限时访问。

八、总结

对接流程整体分为三步：首先安装Boto3依赖包，然后准备S3兼容对象存储的服务地址、密钥、区域三个核心参数，最后初始化S3客户端调用对应接口即可。

新手入门建议优先选择国内的S3兼容对象存储服务，比如七彩云对象存储，不需要处理AWS的账号注册、网络加速等额外问题，控制台提供的现成Demo和参数可以帮助你在10分钟内跑通全流程。生产环境使用时要注意做好密钥安全管理，添加异常捕获和重试机制，不要自行实现底层S3协议逻辑，直接使用成熟的Boto3 SDK即可覆盖99%的业务场景。