华为云 OBS 用 Python SDK 上传下载文件实践

一、背景

对象存储服务 OBS 是华为云上最常用的存储产品之一，适合存放图片、日志、备份和静态资源。日常开发中，我们经常需要用脚本批量上传文件或下载结果，本文记录使用官方 Python SDK（包名 esdk-obs-python）完成上传、下载、列举和删除的完整过程，以及我踩过的几个坑。

二、准备工作

1. 在 OBS 控制台创建一个桶，记下桶名和所在区域（例如 cn-north-4），对应的终端节点形如 obs.cn-north-4.myhuaweicloud.com。

2. 使用 IAM 子账号并仅授予 OBS 相关权限，不要用主账号的访问密钥。已有的 AK/SK 通过环境变量传入，千万不要写进代码或提交到仓库。

3. 安装 SDK：pip install esdk-obs-python，建议 Python 3.7 以上版本。

三、初始化客户端

先在终端设置环境变量 OBS_AK、OBS_SK，然后在代码中读取。核心代码如下：from obs import ObsClient；import os；client = ObsClient(access_key_id=os.environ["OBS_AK"], secret_access_key=os.environ["OBS_SK"], server="https://obs.cn-north-4.myhuaweicloud.com")。注意 server 必须与桶所在区域一致，否则会返回 301 或 403 之类的错误。

四、上传文件

最常用的是 putFile：resp = client.putFile("my-bucket", "docs/report.txt", "/tmp/report.txt")。判断是否成功要看 resp.status，小于 300 表示成功，否则打印 resp.errorCode 和 resp.errorMessage 排查。

对于超过 100MB 的大文件，建议使用分段上传接口 uploadFile，例如：client.uploadFile("my-bucket", "backup/big.zip", "/data/big.zip", partSize=10*1024*1024, taskNum=5, enableCheckpoint=True)。开启 enableCheckpoint 后，网络中断时可以断点续传，重新执行同一段代码即可从上次进度继续，非常实用。

五、下载文件

下载使用 getObject，把 downloadPath 指定为本地路径即可：resp = client.getObject("my-bucket", "docs/report.txt", downloadPath="/tmp/report_copy.txt")。大文件同样可以用 downloadFile 做断点续传下载：client.downloadFile("my-bucket", "backup/big.zip", downloadFile="/data/big_copy.zip", partSize=10*1024*1024, taskNum=5, enableCheckpoint=True)。

六、列举与删除

列举某个前缀下的对象用 listObjects，传入 prefix="docs/" 和 max_keys=100，返回结果在 resp.body.contents 中，每个元素有 key 和 size 属性。需要分页时读取 resp.body.next_marker 作为下一次请求的 marker 参数。删除使用 deleteObject，批量删除用 deleteObjects。

七、踩坑总结

1. 区域与终端节点不一致会导致请求失败，第一步先核对区域。

2. 使用完客户端务必调用 client.close() 释放连接，脚本中可以放在 finally 里。

3. 对象键不要以斜杠开头，用斜杠分隔即可模拟目录结构。

4. 上传后如果要给外部访问，请优先使用临时授权访问（createSignedUrl，设置较短有效期），而不是把桶设为公共读。

5. 生产环境建议开启服务端加密与版本控制，防止误删覆盖。

八、小结

通过 esdk-obs-python，只需十几行代码就能完成 OBS 的上传、下载、列举和删除，再配合断点续传和临时授权，基本可以满足日常脚本和备份需求。后续我打算继续研究生命周期规则，把过期日志自动转冷存储以节省费用，有进展再和大家分享。如有疑问欢迎在评论区交流。