华为云 OBS 对象存储入门:用 Python SDK 完成上传、下载与临时分享链接
> 一个桶、一段代码,把文件存储从服务器磁盘里拆出来。
## 一、为什么要把文件从本地磁盘搬走
刚上线的小项目,通常会把用户上传的图片、附件直接存到服务器磁盘上,路径写死成 `/data/upload/xxx.png`。一开始没问题,但很快会遇到几件事:
- **容量和备份**:磁盘快满了要扩容,扩容要停机;备份还得自己写脚本。
- **多机共享**:服务只要扩到两台机器,文件就分裂在两台机器上,前端访问会 404。
- **迁移成本**:换服务器时,最麻烦的往往不是代码,而是那一堆文件。
- **外链和权限**:想给某个文件生成一个限时下载链接,写起来相当别扭。
对象存储正好解决这一类问题:文件按「桶(Bucket)+ 对象(Object)」组织,天然带多副本、按量计费、可以直接生成带签名的下载链接,还能接 CDN 加速。
下面用华为云 OBS 走一遍完整流程,代码全部是最小可运行版本。
## 二、准备工作
### 2.1 创建桶
进入 OBS 控制台创建桶时,有三个选项值得注意:
1. **区域**:尽量和你的 ECS 放在同一个区域。同区域的 ECS 通过内网 endpoint 访问 OBS,不产生公网流量费,这一点在成本上差别很大。
2. **桶名**:全局唯一,只能用小写字母、数字和短横线,创建后不能改名,建议带上项目前缀。
3. **访问权限**:保持默认的**私有**。后面需要分享文件时用签名链接,而不是把整个桶开放成公共读。
另外存储类别按需求选:经常访问的放标准存储,几个月才看一次的放低频或归档,配合生命周期规则能省不少钱。
### 2.2 获取访问密钥
在「统一身份认证 IAM」里创建访问密钥(AK/SK)。有两点建议:
- **不要用主账号的 AK/SK**。给应用单独建一个 IAM 子用户,只授予 OBS 相关的策略。
- **不要把 AK/SK 硬编码进代码**。用环境变量或配置文件注入,并且确认它没被提交到代码仓库。
如果应用部署在 ECS 上,条件允许的话优先使用临时访问密钥(STS),有效期短、泄露风险更低。
### 2.3 安装 SDK
```bash
pip install esdk-obs-python
```
## 三、初始化客户端
```python
import os
from obs import ObsClient
obs_client = ObsClient(
access_key_id=os.environ["OBS_AK"],
secret_access_key=os.environ["OBS_SK"],
server="https://obs.cn-north-4.myhuaweicloud.com",
)
BUCKET = "demo-static-1250000000"
```
这里 `server` 填的是 endpoint,格式为 `https://obs.<区域>.myhuaweicloud.com`,例如:
- 北京四:`obs.cn-north-4.myhuaweicloud.com`
- 上海一:`obs.cn-east-3.myhuaweicloud.com`
- 贵阳一:`obs.cn-southwest-2.myhuaweicloud.com`
**endpoint 里的区域必须和桶所在区域一致**,写错了会直接报签名或跳转错误,这是最常见的坑之一。
## 四、常用操作
### 4.1 上传文件
```python
def upload_file(local_path: str, object_key: str) -> str:
resp = obs_client.putFile(
bucketName=BUCKET,
objectKey=object_key,
file_path=local_path,
)
if resp.status >= 300:
raise RuntimeError(f"上传失败: {resp.status} {resp.errorMessage}")
return object_key
```
对象名的命名建议:
```text
avatar/2026/11/18/8f3c1a2e-用户ID.png
```
用「业务前缀 / 日期 / UUID」的结构,既方便按目录浏览,也避免了同名覆盖和中文、空格带来的转义问题。
### 4.2 下载文件
```python
resp = obs_client.getObject(
bucketName=BUCKET,
objectKey="avatar/2026/11/18/example.png",
downloadPath="./download.png",
)
print(resp.status)
```
如果只是要把内容读进内存做处理,可以不传 `downloadPath`,直接读 `resp.body`。
### 4.3 分页列举
桶里对象多了以后,一次列举不完,需要按 marker 翻页:
```python
marker = None
while True:
resp = obs_client.listObjects(
bucketName=BUCKET,
prefix="avatar/2026/11/",
marker=marker,
max_keys=1000,
)
for obj in resp.body.contents:
print(obj.key, obj.size)
if not resp.body.is_truncated:
break
marker = resp.body.next_marker
```
很多同学只调一次 `listObjects` 就以为拿到了全部文件,结果超过 1000 个之后「丢数据」。
### 4.4 删除对象
```python
obs_client.deleteObject(BUCKET, "avatar/2026/11/18/example.png")
# 批量删除,一次最多 1000 个
obs_client.deleteObjects(
BUCKET,
deleteObjects=[{"key": "a.png"}, {"key": "b.png"}],
quiet=True,
)
```
### 4.5 生成临时分享链接
这是对象存储最实用的功能之一:桶保持私有,但可以给单个对象签发一个带有效期的 URL。
```python
url = obs_client.createSignedUrl(
method="GET",
bucketName=BUCKET,
objectKey="report/2026-11/summary.pdf",
expires=3600, # 单位秒
)
print(url)
```
前端拿到这个链接就能直接下载,服务端不需要中转文件,也不担心链接被长期传播——过期后自动失效。
## 五、让前端直传文件
文件先传到你的后端、后端再传到 OBS,这条链路在大文件场景下很浪费:占后端带宽、占内存、还容易超时。更常见的做法是**后端只签发凭证,浏览器直接传 OBS**。
基本流程:
1. 前端向后端请求上传凭证。
2. 后端用 `createPostSignature` 生成 policy 和签名,返回给前端。
3. 前端把文件按表单格式 POST 到桶的域名。
4. 上传成功后,后端记录对象名到数据库。
关键点是 policy 要限制死上传条件,例如:
```python
policy = {
"expiration": "2026-11-19T00:00:00Z",
"conditions": [
{"bucket": BUCKET},
["starts-with", "$key", "avatar/2026/11/18/"],
["content-length-range", 0, 10 * 1024 * 1024],
],
}
```
这样即使 policy 泄露,也只能往指定前缀上传、且不超过 10 MB。
另外记得在桶的「跨域设置(CORS)」里放行你的站点域名,方法和来源不匹配时,浏览器会在预检阶段就把请求拦掉,控制台里不会留下任何错误日志,很容易误判成后端问题。
## 六、踩坑记录
1. **endpoint 区域和桶不一致**
报 `301` 或签名错误。先确认桶在哪个区域,再核对 `server` 参数。
2. **服务器时间不准,签名莫名失败**
OBS 的签名带时间戳,机器时间和标准时间偏差过大就会被判定过期。用 `timedatectl` 检查并开启 NTP 同步。
3. **AK/SK 写死在代码里**
一旦推到公开仓库,基本等于把桶送人。用环境变量 + IAM 子用户 + 最小权限策略,出问题时还能随时禁用密钥。
4. **把桶设成公共读图省事**
公共读意味着任何人只要猜到对象名就能访问,还能被批量枚举。除纯静态资源站外,建议一律私有 + 签名链接。
5. **大文件用单次上传**
几十 GB 的文件容易中断重来。SDK 的 `uploadFile` 支持分片和断点续传,比 `putFile` 更适合大文件。
6. **公网和内外网 endpoint 混用**
ECS 访问同区域 OBS 时用内网 endpoint(`obs.<region>.myhuaweicloud.com` 的内网域名),既能省流量费,延迟也更低。
## 七、成本和安全上的几个习惯
- **按存储、请求次数、流出流量计费**,其中外网流出流量通常是大头;同区域 ECS 走内网访问不计流量费。
- 给桶配置**生命周期规则**:30 天没访问的转低频,180 天以上直接删除,避免「存了三年没人看」的费用。
- 开启**服务端加密**和**桶日志**,前者保护静态数据,后者在排查异常访问时很有用。
- 定期检查 IAM 子用户的权限范围,删掉不再使用的 AK/SK。
## 八、小结
对大多数项目来说,接入对象存储的收益是立刻能感受到的:服务器磁盘不再膨胀,扩容和迁移变得简单,文件分享也有了可控的临时链接。
真正需要注意的是细节——区域、endpoint、时间同步、权限边界。这几项配对,后面用起来会非常顺;配错了,报错信息往往指向性很弱,容易绕远路。
下一篇文章打算写写用 OBS 生命周期规则 + 函数工作流做图片自动压缩,有兴趣的话可以关注一下。
- 点赞
- 收藏
- 关注作者
评论(0)