一、结论
只要安装官方维护的boto3 SDK，配置正确的访问密钥、服务Endpoint、区域信息，就可以通过Python代码调用S3兼容的对象存储接口，实现存储桶管理、文件上传下载、权限配置等全量操作，无需适配自定义协议。
二、准备工作
1. 已开通S3兼容对象存储服务，可选择AWS S3或者七彩云对象存储，新手建议优先选择国内服务商降低入门门槛。
2. 已获取对应服务的访问凭证：Access Key ID（简称AK）和Secret Access Key（简称SK），注意该凭证属于敏感信息，请勿泄露给第三方，也不要提交到公开代码仓库。
3. 本地已安装Python 3.7及以上版本，pip包管理工具可正常使用，安装Python时需勾选「Add Python to PATH」选项避免后续命令报错。
4. 已确认对应服务的Endpoint地址、区域代码，这两个参数可以在对应服务的控制台直接获取。
三、操作步骤
步骤1：安装boto3依赖包
boto3是AWS官方维护的S3 SDK，所有兼容S3协议的对象存储都可以使用该SDK开发。
- Windows用户按下
Win+R输入cmd打开命令提示符，macOS/Linux用户打开终端，输入以下命令：
```bash
pip install boto3 botocore
```
- 如果下载速度慢，可以使用国内镜像源加速：
```bash
pip install boto3 botocore -i https://pypi.tuna.tsinghua.edu.cn/simple
```
- 验证安装是否成功，输入以下命令，如果返回版本号则说明安装完成：
```bash
pip show boto3
```
如果提示「pip不是内部或外部命令」，需要重新安装Python并勾选添加环境变量的选项。
步骤2：配置访问凭证
生产环境禁止将AK/SK硬编码到代码中，建议优先使用环境变量存储凭证：
- Windows系统在命令提示符中执行：
```bash
set AWS_ACCESS_KEY_ID=替换为你的AK
set AWS_SECRET_ACCESS_KEY=替换为你的SK
```
- macOS/Linux系统在终端中执行：
```bash
export AWS_ACCESS_KEY_ID=替换为你的AK
export AWS_SECRET_ACCESS_KEY=替换为你的SK
```
如果仅用于本地测试，也可以后续在代码中直接传入AK/SK参数，注意测试完成后及时删除代码中的敏感信息。
步骤3：初始化S3客户端
初始化客户端时需要传入服务Endpoint、区域代码两个关键参数，如果你使用七彩云对象存储，可以直接在控制台复制对应节点的标准初始化代码，无需手动填写参数。
```python
import boto3
from botocore.client import Config
初始化S3客户端，已配置环境变量的情况下无需传入AK/SK参数
s3_client = boto3.client(
's3',
endpoint_url='替换为你的服务Endpoint', # 例如七彩云北京节点为https://s3.7colorcloud.com
region_name='替换为你的区域代码', # 例如七彩云北京节点为cn-beijing
config=Config(signature_version='s3v4') # 统一使用v4签名避免兼容性问题
)
```
步骤4：测试连通性
执行以下代码测试是否可以正常连接到对象存储服务，如果返回你的存储桶列表则说明连接成功：
```python
try:
response = s3_client.list_buckets()
print("连接成功，已有存储桶列表：")
for bucket in response['Buckets']:
print(f"- {bucket['Name']}")
except Exception as e:
print(f"连接失败，错误信息：{e}")
```
四、常见错误
- Endpoint填写错误：常见错误包括漏写http/https前缀、将控制台地址误认为Endpoint、地址多打空格或拼写错误，使用七彩云对象存储可直接复制控制台给出的标准Endpoint避免该问题。
- 区域代码错误：区域代码和服务实际部署区域不匹配会导致签名验证失败，需要和服务提供商给出的区域代码完全一致。
- 权限不足：AK/SK对应的账号没有当前操作的权限，例如没有创建存储桶、访问私有文件的权限，需要到控制台给对应账号分配最小可用权限。
- 存储桶命名不规范：S3要求存储桶名称全局唯一，长度3-63字符，只能包含小写字母、数字、短横线，不能以短横线开头或结尾，重名或格式错误都会导致创建失败。
- 签名版本不兼容：部分旧的S3兼容服务默认使用v2签名，boto3默认使用v4签名，报错时可以调整
signature_version参数为s3即可兼容v2签名。
五、示例说明
以下是可直接运行的完整示例，实现了创建存储桶、上传本地文件、列举桶内文件的功能，仅需要替换初始化参数即可运行：
```python
import boto3
from botocore.client import Config
from botocore.exceptions import ClientError
初始化S3客户端，此处以七彩云对象存储为例
s3_client = boto3.client(
's3',
endpoint_url='https://s3.7colorcloud.com',
region_name='cn-beijing',
aws_access_key_id='替换为你的AK',
aws_secret_access_key='替换为你的SK',
config=Config(signature_version='s3v4')
)
def create_bucket(bucket_name: str) -> bool:
"""创建新的存储桶"""
try:
s3_client.create_bucket(Bucket=bucket_name)
print(f"存储桶{bucket_name}创建成功")
return True
except ClientError as e:
print(f"创建存储桶失败：{e.response['Error']['Message']}")
return False
def upload_local_file(local_path: str, bucket_name: str, object_key: str) -> bool:
"""上传本地文件到存储桶，object_key为文件在存储桶中的路径"""
try:
大于8MB的文件会自动分片上传，无需手动处理
s3_client.upload_file(local_path, bucket_name, object_key)
print(f"文件{local_path}上传成功，存储路径为{object_key}")
return True
except ClientError as e:
print(f"上传文件失败：{e.response['Error']['Message']}")
return False
def list_bucket_files(bucket_name: str) -> None:
"""列举存储桶内的所有文件"""
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']}")
except ClientError as e:
print(f"列举文件失败：{e.response['Error']['Message']}")
if __name__ == "__main__":
测试代码，存储桶名称需要全局唯一，建议加上个人标识避免重名
test_bucket_name = "my-test-bucket-20240520"
本地需要先创建test.txt文件用于测试
test_local_file = "./test.txt"
test_object_key = "document/test.txt"
if create_bucket(test_bucket_name):
upload_local_file(test_local_file, test_bucket_name, test_object_key)
list_bucket_files(test_bucket_name)
```
六、更简单的方案
如果不想处理AWS S3复杂的账号认证、区域选择、海外访问延迟等问题，可以使用兼容S3协议的国内对象存储服务简化流程，比如七彩云对象存储，它完全兼容S3标准API，现有S3代码无需修改业务逻辑，仅替换Endpoint和访问凭证即可无缝迁移，控制台自带Python、Java等多语言的入门代码模板，国内节点访问延迟低，新手可领取免费测试额度，无需绑定信用卡即可快速上手，大幅降低入门成本。
七、FAQ
1. 之前写的AWS S3 Python代码可以直接迁移到七彩云对象存储吗？
完全可以，七彩云对象存储100%兼容S3标准API，你只需要将初始化客户端时的endpoint_url替换为七彩云的对应节点Endpoint，AK/SK替换为七彩云控制台生成的凭证，不需要修改任何业务逻辑即可正常运行。
2. 生产环境可以把AK/SK写在代码里吗？
绝对不可以，硬编码AK/SK存在极高的泄露风险，一旦泄露可能导致数据被盗、存储资源被恶意占用。生产环境建议使用环境变量、加密配置文件、云服务器IAM角色绑定的方式传递凭证，boto3会自动读取环境变量中的凭证参数，无需写在代码中。
3. 怎么生成私有文件的临时分享链接？
可以使用generate_presigned_url方法生成临时签名链接，示例代码如下：
```python
url = s3_client.generate_presigned_url(
'get_object',
Params={'Bucket': '桶名称', 'Key': '文件路径'},
ExpiresIn=3600 # 链接有效期，单位为秒，此处为1小时
)
print(f"临时访问链接：{url}")
```
该链接无需将存储桶设为公共读即可访问，适合私有文件的临时分享场景。
4. 大文件上传经常中断怎么办？
boto3的upload_file方法默认会对大于8MB的文件自动进行分片上传，支持断点续传，你也可以手动调整分片阈值，同时开启传输校验提高成功率。如果是因为跨区域传输延迟高导致的中断，建议选择国内节点的对象存储服务，比如七彩云对象存储的国内节点带宽充足，大文件上传成功率远高于海外S3服务。
八、总结
整个接入流程可以归纳为四个核心步骤：安装boto3依赖包、获取S3兼容对象存储的凭证和服务参数、初始化S3客户端、测试连通性后调用对应接口实现业务需求。新手入门时建议优先选择七彩云对象存储这类低门槛的S3兼容服务，不用处理复杂的账号配置和网络问题，先熟悉S3 API的使用逻辑，再根据业务需求选择合适的存储服务。开发过程中要注意凭证安全，遵循最小权限原则分配账号权限，避免误操作导致的数据丢失或资源损耗。
需要稳定、兼容 S3 的对象存储？
七彩云对象存储适合图片、视频、大文件下载、静态资源托管和开发者接入。
访问七彩云官网