COS 预签名 URL 实战：临时密钥、最小权限与前端直传的安全做法

背景

业务里常见需求：用户从浏览器或小程序直接上传文件到对象存储 COS，或让第三方临时下载私有文件。如果把永久密钥放到前端，一旦泄露整个账号下的资源都有风险。官方文档推荐的做法是：服务端用临时密钥生成预签名 URL，客户端只拿到一个有时效的链接。本文整理这套流程和踩坑点。

原理

COS 默认桶和对象都是私有的。预签名 URL 把签名信息嵌入 URL，持有链接的人在有效期内可以完成指定操作，过期即失效。关键点：

• 签名绑定了 HTTP 方法、桶、对象键和有效期，换一个对象键不能复用
• 可以用永久密钥或临时密钥生成，文档建议使用临时密钥
• 有效期应尽量短，够用即可

第一步：创建最小权限策略

不要给上传用的密钥授予整个桶的读写。以“只允许上传到某前缀”为例，权限范围控制在：

• action：name/cos:PutObject（只下载则用 name/cos:GetObject）
• resource：具体到 uploads/ 前缀，例如 qcs::cos:ap-guangzhou:uid/<appid>:<bucket>/uploads/*

具体 resource 的写法请以 CAM 策略语法文档为准。

第二步：服务端生成预签名 URL（Python SDK）

安装官方 SDK：

pip install -U cos-python-sdk-v5

生成上传和下载链接：

from qcloud_cos import CosConfig, CosS3Client

config = CosConfig(
    Region="ap-guangzhou",
    SecretId=tmp_secret_id,      # 临时密钥，由 STS 获取
    SecretKey=tmp_secret_key,
    Token=tmp_token,
    Scheme="https",
)
client = CosS3Client(config)

# 上传链接，有效 300 秒
put_url = client.get_presigned_url(
    Method="PUT", Bucket="examplebucket-1250000000",
    Key="uploads/2026/avatar.png", Expired=300,
)

# 下载链接
get_url = client.get_presigned_url(
    Method="GET", Bucket="examplebucket-1250000000",
    Key="uploads/2026/avatar.png", Expired=300,
)

使用临时密钥时，生成的 URL 里会带 x-cos-security-token 参数，不要手工去掉。

第三步：客户端上传

curl -X PUT -T avatar.png "<put_url>"

前端用 fetch(put_url, { method: "PUT", body: file }) 即可。注意 Content-Type 等请求头如果参与了签名，上传时必须保持一致，否则会返回签名不匹配。

常见问题排查

• SignatureDoesNotMatch：检查对象键是否和签名时完全一致（含 URL 编码）、请求方法是否一致、服务器时间是否准确
• AccessDenied：临时密钥的策略不包含对应 action 或 resource 前缀
• 链接过期：检查 Expired 设置，以及临时密钥自身的有效期，链接有效期不会超过密钥有效期
• 浏览器无法预览：官方文档提示 2024 年 1 月 1 日后创建的桶不支持用默认域名在浏览器预览文件，建议配置自定义域名
• 跨域报错：在桶的跨域访问 CORS 配置里放行前端域名、PUT/GET 方法和需要的请求头

安全检查清单

• 永久密钥只放在服务端，且不写进代码仓库
• 对象键由服务端生成（带日期和随机串），不要让客户端任意指定，防止覆盖已有文件
• 上传链接有效期按分钟计，下载链接按业务需要设置
• 开启日志或监控，关注异常的大量上传请求
• 需要限制文件大小和类型时，在服务端的策略或回调环节校验，不要只依赖前端

小结

预签名 URL 的核心是“服务端持密钥，客户端持短时链接”。配合临时密钥和最小权限策略，可以在不暴露长期凭证的前提下实现前端直传和临时分享。具体参数与限制以官方文档和控制台为准。