华为云 OBS 对象存储入门:用 Python SDK 完成上传、下载与临时分享链接

举报
yd_275282631 发表于 2026/11/18 00:18:09 2026/11/18
【摘要】 把文件从服务器本地磁盘搬到对象存储,是很多项目上云的第一步。本文用华为云 OBS 的 Python SDK,从建桶、配权限讲到上传下载、分页列举和临时签名链接,并整理区域不匹配、时间不同步、AK/SK 泄露等常见问题。

> 一个桶、一段代码,把文件存储从服务器磁盘里拆出来。

## 一、为什么要把文件从本地磁盘搬走

刚上线的小项目,通常会把用户上传的图片、附件直接存到服务器磁盘上,路径写死成 `/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 生命周期规则 + 函数工作流做图片自动压缩,有兴趣的话可以关注一下。

【版权声明】本文为华为云社区用户原创内容,未经允许不得转载,如需转载请自行联系原作者进行授权。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。