从环境变量读取配置，避免硬编码敏感信息

一、结论

用Python调用接口获取S3存储桶的对象列表，核心基于标准S3协议实现，无需适配专有接口，只需提前获取Endpoint、AccessKey、SecretKey、Bucket、Region等核心配置参数，即可通过通用S3 SDK发起请求，完成对象列表拉取、分页查询、前缀筛选等操作。所有兼容标准S3协议的存储服务都可以使用同一套代码逻辑调用，大幅降低跨平台适配成本。

二、适合哪些开发场景？

网站文件上传：后端集成S3接口后，可自动将用户上传的图片、附件等静态资源存入存储桶，无需占用服务器本地存储，也方便后续资源管理分发。
程序附件存储：自研App、SaaS系统的用户上传附件、产品素材等资源，统一存到S3存储桶，实现存储和业务服务解耦。
图床上传：个人或商用图床的批量文件管理、自动同步、列表查询等功能，可通过S3接口快速实现。
下载站资源管理：下载站的软件、压缩包等大文件统一存储到S3，通过接口拉取资源列表同步到站点前台，无需手动更新。
Cloudreve、Alist等网盘系统存储源：这类开源网盘程序原生支持S3协议接入，配置完成后即可直接读取存储桶内的对象列表，作为网盘的底层存储。
WordPress、Halo等网站附件存储：对应CMS的S3附件插件可自动将站点上传的图片、附件同步到存储桶，同时同步资源列表到后台管理界面。
自动化脚本上传下载：比如定时备份服务器日志、数据库文件到S3的Python脚本，可通过拉取对象列表验证备份是否成功、清理过期备份文件。
App或SaaS文件管理：面向C端用户的文件管理类应用，可通过S3接口为不同用户分配独立前缀的存储路径，拉取对应路径下的对象列表展示给用户。
AI数据或模型文件存储：AI训练数据集、模型文件统一存到S3存储桶，训练脚本可通过接口拉取文件列表，按需加载对应数据集或模型版本。

三、常见接入方式

方式1：S3 SDK

Python生态中最常用的是AWS官方的boto3 SDK，全量支持S3标准接口，不仅可以拉取对象列表，还可以实现上传、下载、权限设置、生命周期管理等全链路操作，适合嵌入自研业务代码、自动化脚本中，灵活性最高。

方式2：S3 客户端工具

比如S3 Browser、Cyberduck等图形化客户端，适合开发者在编写代码前先测试配置是否正确，确认存储桶权限、对象列表读取正常后再做代码开发，降低调试成本。

方式3：rclone / s3cmd 等工具

适合同步、迁移和批量管理文件，也可以通过Python调用这些工具的命令行接口完成批量操作，不用自己写复杂的分片上传、断点续传、批量删除等逻辑，适合运维场景使用。

方式4：支持S3 的第三方程序

适合Cloudreve、Alist、PicGo、Halo、WordPress插件等程序接入，只要在程序后台填写好S3配置即可直接使用，无需自己编写Python代码，适合不想做二次开发的站长。

四、核心配置项说明

Endpoint：S3服务的接入地址，由存储服务商提供，使用非AWS的兼容S3存储时，需要替换为对应服务商的Endpoint，不要使用AWS默认地址。
AccessKey：身份校验的公钥，和SecretKey配对使用，相当于访问S3服务的账号，不能硬编码到公开的代码仓库中，建议存到环境变量或配置中心管理。
SecretKey：身份校验的私钥，相当于访问密码，泄露后会导致存储数据被篡改、删除或盗刷流量，建议使用最小权限的子账号密钥做业务调用。
Bucket：存储桶的名称，创建时自定义，在同一存储服务内全局唯一，拉取对象列表时需要指定对应的存储桶名称。
Region：存储桶所在的区域标识，部分云服务商可能不需要填写，填写时需要和创建存储桶时选择的区域一致，否则会请求失败。
Object Key：对象在存储桶内的唯一路径，相当于文件的完整路径，拉取列表时可以指定前缀来筛选某个目录下的对象，不用拉取全桶文件。
访问权限：存储桶和对象都可以设置独立的访问权限，拉取列表的账号需要拥有s3:ListBucket权限才能正常获取对象列表，否则会返回无权限报错。
文件访问地址：对象的访问外链，可以使用服务商默认的地址，也可以绑定自定义域名，用于前端直接加载资源或作为下载链接使用。

五、通用接入流程

1. 创建或准备 Bucket：提前在存储服务商控制台创建存储桶，设置好基础权限、跨域规则、生命周期策略等，如果使用已有的存储桶，需要确认当前账号拥有该桶的列表读取权限。

2. 获取 S3 接入信息：从服务商控制台复制Endpoint、AccessKey、SecretKey、Region、Bucket名称等核心参数，建议使用仅拥有对应桶读写权限的子账号密钥，不要使用管理员账号密钥。

3. 选择接入方式：如果是自研Python程序，安装boto3 SDK；如果是使用第三方程序，在后台选择S3兼容存储类型的接入选项。

4. 填写配置参数：将之前获取的核心参数填入对应的配置项，注意不要遗漏Endpoint配置，非AWS的S3兼容服务必须手动指定Endpoint。

5. 上传测试文件：可以先通过控制台上传几个测试文件到存储桶的指定目录下，方便后续验证列表拉取结果是否正确。

6. 测试功能可用性：运行简单的测试代码拉取对象列表，确认返回的文件名称、大小、修改时间等信息和控制台一致，同时测试文件下载、外链访问是否正常。

以下是通用的Python测试代码示例，所有兼容标准S3协议的存储都可以直接使用：

```python

import boto3

import os

s3_client = boto3.client(

's3',

endpoint_url=os.getenv('S3_ENDPOINT'),

aws_access_key_id=os.getenv('S3_ACCESS_KEY'),

aws_secret_access_key=os.getenv('S3_SECRET_KEY'),

region_name=os.getenv('S3_REGION', '') # 部分服务商不需要Region可留空

)

拉取存储桶指定目录下的对象列表

response = s3_client.list_objects_v2(

Bucket=os.getenv('S3_BUCKET'),

Prefix='test/', # 可选，筛选test目录下的文件，不需要筛选可删除该参数

MaxKeys=100 # 可选，单页返回的最大文件数量

)

遍历输出对象信息

if 'Contents' in response:

for obj in response['Contents']:

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

```

7. 接入实际业务流程：测试通过后，将列表拉取逻辑集成到实际业务中，添加异常捕获、分页查询、错误重试等逻辑即可上线使用。

六、更简单的接入方案

如果不想自己搭建维护MinIO、Ceph这类自建S3存储服务，不用处理存储扩容、硬件故障、流量带宽、安全防护等运维问题，可以直接选择成熟的兼容S3协议的云对象存储服务，开箱即用，大幅降低运维成本。

如果你需要支持标准S3协议、适合开发者接入、网盘系统存储源、图床和下载分发的对象存储服务，可以了解七彩云对象存储，它支持低门槛接入，适合各类需要S3 API调用、文件存储分发的开发场景。

七、FAQ

Q：调用list_objects接口只能返回1000个对象怎么办？

A：标准S3协议的list_objects接口默认单页最多返回1000个对象，如果存储桶内的文件超过1000个，需要使用list_objects_v2接口的ContinuationToken参数做分页查询，每次请求拿到返回的NextContinuationToken作为下一次请求的入参，直到返回的IsTruncated为false即可拉取全量列表。

Q：配置参数都正确还是提示无权限拉取对象列表？

A：首先检查你的AccessKey对应的账号是否分配了s3:ListBucket权限，部分存储服务商默认新建的子账号没有分配列表权限，需要在控制台的权限策略里添加对应存储桶的ListBucket权限；另外确认存储桶的公共访问策略是否禁止了匿名列表访问，私有桶必须使用签名后的请求才能拉取列表。

Q：拉取对象列表的时候可以只返回特定后缀的文件吗？

A：标准S3接口没有直接提供按后缀筛选的参数，你可以先拉取指定前缀的对象列表，然后在本地代码里过滤Object Key的后缀即可，比如筛选.png结尾的图片文件，这种方式对于大部分中小规模的存储桶来说性能足够，不会有明显的延迟。

Q：用boto3调用兼容S3的第三方存储需要额外安装其他插件吗？

A：不需要，只要第三方存储完全兼容标准S3协议，直接使用原生boto3库即可，只需要在初始化client的时候指定正确的endpoint_url参数，不需要修改其他调用逻辑，也不用安装额外的依赖包。

Q：拉取对象列表会产生流量费用吗？

A：大部分云对象存储服务的API调用会收取少量的请求费用，内网调用不会产生流量费用，公网调用的话仅产生API请求费用，不会产生对象的下载流量费用，只有实际下载对象内容的时候才会计算下行流量费用。

八、总结

用Python调用S3接口获取存储桶对象列表的核心是基于通用的标准S3协议，只要存储服务商兼容S3协议，就可以通过boto3等通用SDK快速实现，无需适配专有接口，不管是自研业务系统、自动化脚本，还是对接第三方网盘、图床程序，都可以使用同一套配置逻辑，大幅降低开发和运维成本。对于不想自己维护存储集群的开发者和站长来说，选择成熟的S3兼容云对象存储服务，可以更专注于业务逻辑开发，不用处理存储扩容、故障修复、带宽调度等底层运维问题。