尧图网页设计 
阿里云 OSS 私有存储这个题目几乎每个做前端开发或者全栈的人都绕不开。我自己最早踩过一个特别典型的坑为了保证数据安全Bucket 设成了私有结果页面上的图片直接全部 403后来为了图省事把 Bucket 改成公共读好了图片能开了结果月底账单出来直接被流量费吓一跳。更别提有人图方便直接把 AccessKey 写在代码里一个项目提交到公开仓库服务器资源被人拿去刷流量一晚上能给你烧掉几千块。这篇博文把我这几年在 OSS 私有存储 前端项目访问上攒下来的一套完整方案整理出来包括权限模型、STS 临时凭证直传、签名 URL、CDN 鉴权以及各种报错的实际排查经验。内容偏实战但原理部分我会尽量讲透适合刚接手前端项目、第一次接触 OSS 私有 Bucket 的开发者也适合已经部署上线但想优化安全性和访问速度的团队参考。1. 私有存储的权限模型与访问方案选型先搞清楚一个核心问题OSS 的“私有”到底是怎么定义出来的。OSS 的权限体系里Bucket 和 Object 都有访问权限公共读意味着所有人拿到 URL 就能直接读私有则意味着默认情况下只允许经过签名或授权的方式访问。私有 Bucket 的安全性天然更高但麻烦也随之而来前端项目怎么在不让用户看到密钥的前提下安全地读写这些私有资源。1.1 OSS 权限体系里最常用的三个概念很多人一上手就被 AccessKey、RAM 用户、STS、Bucket Policy 这几个概念搞晕。我用一个生活化的类比来解释。AccessKey ID 和 AccessKey Secret相当于你家的门钥匙。有了这串东西等同于拥有调用 OSS API 的完整权限具体权限看 AccessKey 对应的是主账号还是子账号。RAM 用户相当于你给家里请的保洁阿姨专门配了一把钥匙这把钥匙只能开某几个房间不能动其他区域。在阿里云控制台创建一个 RAM 子用户给它只授权 OSS 的读取权限那它就是一把受限钥匙。STS 临时凭证相当于去酒店入住时前台给你的房卡有效期到次日中午过期自动失效。就算别人捡到了房卡也只能在规定时间内刷指定的楼层。Bucket Policy 和 RAM Policy本质都是权限策略只是作用范围不同。前者是针对某个 Bucket 设规则后者是给某个用户或角色设规则。日常开发里优先用 RAM Policy STS 组合而不是在控制台上把 Bucket 改成公共读。我在实际项目里见过不少人把主账号 AccessKey 直接放到前端 JavaScript 代码里然后配一个公共读 Bucket。这种做法表面上跑得通实际等于把家门钥匙挂在门口。只要有人打开控制台看一眼网络请求就能拿到你的密钥。所以私有 Bucket 的第一条铁律就是任何密钥都不能出现在前端代码里。1.2 私有 Bucket 为什么不能直接暴露给前端读如果 Bucket 是私有前端拿一个不带签名的 URL 去请求 ObjectOSS 会直接返回 403。此时很多人的第一反应是把 Bucket 改成公共读。这种方案有两个非常大的隐患。第一是成本不可控。公共读意味着任何人都能拿到 Object 的真实地址如果被人恶意分享、下载OSS 的流量费会快速上涨。我见过一个案例对方只是把图片 URL 贴到了某个访问量很大的站一天的流量费就远超预期。第二是数据安全边界完全失效。虽然 Object 本身可能只是图片、附件但一旦所有资源都公开可读任何未授权用户都能遍历甚至批量下载你的敏感资料比如订单附件、用户证件照片。你没法保证某个业务数据未来不会从私有变成敏感数据所以从一开始就守住“默认私有”的边界比事后补救成本低得多。1.3 三种主流访问方案的对比与选型解决“私有 Bucket 前端访问”这个矛盾业界主流方案基本上可以归纳为三种形态。方案安全级别实现复杂度适用场景后端中转下载高低低频访问、小文件短期使用STS 临时凭证直传 OSS高中前端直接上传文件如头像、附件签名 URL / CDN URL 鉴权高中前端展示、下载私有文件如网页图片后端中转下载最保守前端把文件 ID 传给后端后端用服务端 SDK 从 OSS 拉取数据再返回给前端。这种方式适合文件不大、请求量不高的场景问题在于 OSS 流量会先经过你的应用服务器占用应用带宽和内存并发一高就扛不住。STS 临时凭证直传是如今前端上传到 OSS 的标准答案。服务端通过 AssumeRole 接口换取一个带时效和权限限制的临时凭证前端拿到凭证后直接调用 OSS SDK 上传。整个过程密钥不落地权限还能精确控制到某个 Bucket 的某个目录。签名 URL 是私有文件读取的标准姿势。服务端生成一个带过期时间的 URL格式类似https://bucket.oss-cn-hangzhou.aliyuncs.com/private-file.pdf?OSSAccessKeyIdxxxExpiresxxxSignaturexxx。前端拿到这个 URL 后就像访问普通链接一样加载资源。如果访问量特别大再在前面加一层 CDN开启 URL 鉴权把回源压力拦在边缘节点。方案选型没有绝对的最佳关键看你的业务是“读多写少”还是“写多读少”。上传频率高建议上 STS读取频率高建议上签名 URL 或 CDN 鉴权。混合场景就两套一起上我后面会分别展开讲。2. 方案一STS 临时凭证实现前端安全直传前端上传文件到 OSS看起来只是put一下的事但安全设计的关键不在上传本身而在于“凭证怎么发放”。最安全的做法是后端负责验身份OSS 只认临时凭证前端永远接触不到持久密钥。2.1 原理为什么是“后端签名前端直传”这里要解释一个很常见的问题为什么不能让前端直接把文件传给你的后端服务器再由后端转存到 OSS原因不复杂首先是性能瓶颈上传文件如果都走应用服务器应用服务器的带宽和连接数会成为瓶颈一个小项目可能没问题但多人同时上传大文件时应用服务器很容易被打满接口延迟飙升其次是成本问题同样的流量OSS 内网传输和公网传输价格不同但经由应用服务器中转相当于多付了一份带宽的钱再次是稳定性文件上传是长连接应用服务器还要处理业务请求混在一起容易产生互相拖累的情况。STS 方案解决问题的思路是把“验证身份”和“写入文件”这两件事拆开。前端先调用你自己的后端接口后端拿着配置好的 RAM 用户密钥到阿里云 STS 服务申请一个临时凭证。这个临时凭证有四个关键属性有效期默认 3600 秒可以自己设置权限范围Policy 指定的 OSS 操作资源范围例如只能操作某个 Bucket 的某个目录临时身份标识RoleSessionName前端拿到临时凭证后再用它去初始化 OSS SDK直接上传文件。整个过程后端只需要处理一个轻量级的凭证申请接口不承担文件字节流的传输所以哪怕同时来几千个上传请求后端压力也不大。2.2 后端签发 STS 凭证的标准姿势先要做前置准备。在阿里云 RAM 控制台创建一个子用户比如叫oss-sts-prod给它分配一个自定义策略这个策略只允许 AssumeRole 操作。然后再创建一个 RAM 角色比如叫oss-frontend-uploader角色的信任策略允许刚才那个子用户去 AssumeRole同时给角色关联一个面向 OSS 写入的权限策略。很多初学者容易在这里绕晕简单理解就是子用户是一把钥匙角色是一份授权说明书STS 是把两者结合生成一张临时房卡。以下是 Java 后端的 STS 签发代码示例这是我在 Spring Boot 项目里实际用过的简化版本。先引入阿里云 SDK 依赖然后写一个 Service。// pom.xml 里要引入的依赖 // com.aliyun:aliyun-java-sdk-sts // com.aliyun:aliyun-java-sdk-core import com.aliyuncs.DefaultAcsClient; import com.aliyuncs.auth.sts.AssumeRoleRequest; import com.aliyuncs.auth.sts.AssumeRoleResponse; import com.aliyuncs.profile.DefaultProfile; public class StsService { // 这些配置建议放到环境变量或配置中心不要硬编码 private static final String ACCESS_KEY_ID your-ram-user-access-key-id; private static final String ACCESS_KEY_SECRET your-ram-user-access-key-secret; private static final String ROLE_ARN acs:ram::1234567890123456:role/oss-frontend-uploader; private static final String REGION_ID cn-hangzhou; public AssumeRoleResponse.Credentials getStsCredential() { DefaultProfile profile DefaultProfile.getProfile(REGION_ID, ACCESS_KEY_ID, ACCESS_KEY_SECRET); DefaultAcsClient client new DefaultAcsClient(profile); AssumeRoleRequest request new AssumeRoleRequest(); request.setRoleArn(ROLE_ARN); request.setRoleSessionName(web-upload-session); // 有效期设置单位是秒 request.setDurationSeconds(3600L); // 这里可以临时收紧权限策略内容会覆盖角色本身的策略吗不会二者取交集 request.setPolicy({\Version\:\1\,\Statement\:[{\Effect\:\Allow\,\Action\:[\oss:PutObject\],\Resource\:[\acs:oss:*:*:my-bucket/uploads/*\]}]}); AssumeRoleResponse response client.getAcsResponse(request); return response.getCredentials(); } }这里有几个要点值得多说几句。setPolicy是可选的但它非常有用。角色本身可能配置了比较大的权限范围而你在签发临时凭证时可以通过 Policy 再收紧一层。比如角色允许访问my-bucket全部资源但你只想让某个前端页面只上传到uploads/目录就可以在签发的 Policy 里限制。最终临时凭证的有效权限是“角色权限”和“STS Policy 权限”的交集利用这个特性可以做多租户隔离。DurationSeconds不建议设置得太长。临时凭证的意义就在于短期有效过长的有效期会放大泄露风险。我一般按业务场景设置普通 Web 端 900 到 1800 秒足够用。有些团队为了省事设置成 12 小时等于把临时凭证变成了准持久凭证风险暴露面大大增加。前端拿到 STS 响应后数据结构大概是这样的{ accessKeyId: STS.xxx, accessKeySecret: yyy, securityToken: zzz, expiration: 2025-01-01T12:00:00Z }前端再把这三个字段传给 OSS SDK。2.3 前端直传 OSS 的完整实现前端部分我以 aliyun-oss 官方 SDK 为例。安装依赖后核心代码如下。import OSS from ali-oss; async function uploadFile(file) { // 1. 请求后端接口获取临时凭证 const tokenRes await fetch(/api/oss/sts, { credentials: include }); const sts await tokenRes.json(); // 2. 用临时凭证初始化 OSS Client const client new OSS({ region: oss-cn-hangzhou, bucket: my-bucket, accessKeyId: sts.accessKeyId, accessKeySecret: sts.accessKeySecret, stsToken: sts.securityToken, refreshSTSToken: async () { // 可选SDK 会在凭证过期前自动刷新 const res await fetch(/api/oss/sts, { credentials: include }); return await res.json(); }, refreshSTSTokenInterval: 900000 // 默认15分钟刷新一次单位毫秒 }); // 3. 执行分片上传适合大文件 const result await client.multipartUpload(uploads/${Date.now()}-${file.name}, file, { progress: (p, cpt, res) { console.log(上传进度${Math.floor(p * 100)}%); }, partSize: 1024 * 1024 * 10, // 分片大小 10MB timeout: 120000 }); return result.name; }这段代码有两个值得注意的点。第一个是refreshSTSToken回调。OSS 官方 SDK 支持在临时凭证过期前自动重新申请新凭证这对长传大文件特别重要。如果你传一个 2GB 的压缩包上传时长可能超过凭证有效期没有自动刷新机制就会出现传了一半突然 403 的情况。第二个是文件名处理。直接拿用户上传的文件名拼在路径里可能带来路径覆盖和非法字符问题。我习惯在服务端做一层文件名映射或者在前端统一改写成时间戳 随机串 原始扩展名一方面避免中文名乱码另一方面防止用户传入../../xxx这类危险路径。上传完成后如果 Bucket 是私有那么前端拿到的result.name只是一个对象 key并不能直接作为公开访问地址。要怎么展示我会在下一章讲。2.4 CORS 配置与常见问题前端直传 OSS 天然是跨域请求因为前端页面运行在自己的域名上而 OSS 请求发往*.aliyuncs.com。如果 OSS 控制台没配置 CORS浏览器会把响应拦截掉表现就是控制台报错Access to XMLHttpRequest at https://xxx.oss-cn-hangzhou.aliyuncs.com/... from origin https://yourdomain.com has been blocked by CORS policy。OSS 控制台的 CORS 配置路径是Bucket 列表 - 数据安全 - 跨域设置。新增规则时建议按下表填写。配置项推荐值说明来源https://yourdomain.com多个域名用换行分隔生产环境不要填星号允许 MethodsGET, PUT, POST, DELETE, HEAD上传需要 PUT / POST允许 Headers*上传时会带 Authorization、x-oss-* 等头暴露 HeadersETag分片上传的校验需要读这个响应头CORS 是所有直传方案里最先要确认的配置很多时候上传报错不是代码逻辑有问题而是来源域名没匹配上。比如你本地开发用的localhost:8080CORS 里只配了线上域名本地一调就报错。3. 方案二私有文件的前端访问签名 URL CDN 鉴权上传搞定了下一件事就是“怎么把私有文件展示给用户”。私有 Bucket 的 Object 不能直接通过 URL 访问必须带上签名参数。签名 URL 是后端生成的前端拿过来直接使用。这里我再展开讲两种落地方式一种是最小可用的签名 URL另一种是生产环境下更适合的 CDN URL 鉴权。3.1 最小方案后端生成签名 URL后端调用 OSS SDK 生成签名 URL 的代码很简单。// Java 示例 import com.aliyun.oss.OSS; import com.aliyun.oss.OSSClientBuilder; import java.util.Date; public class OssService { private OSS client; public String generateSignedUrl(String objectKey, int expiresSeconds) { // 初始化 client 时用 RAM 用户的 AccessKey而不是主账号 String endpoint https://oss-cn-hangzhou.aliyuncs.com; this.client new OSSClientBuilder().build(endpoint, ACCESS_KEY_ID, ACCESS_KEY_SECRET); Date expiration new Date(System.currentTimeMillis() expiresSeconds * 1000); // 生成签名 URL只对指定 Object 生效 return client.generatePresignedUrl(my-bucket, objectKey, expiration).toString(); } }前端拿到这个 URL 后可以直接塞给img src、video或者window.open()不需要再做任何额外的鉴权处理。浏览器请求该 URL 时OSS 会检查签名参数的合法性以及过期时间校验通过就返回文件内容。过期时间的设计在这一步非常关键。我见过两种极端一种是把过期时间设成 10 年那跟公共读没有任何区别签名 URL 泄露出去了就一直是公开的另一种是设成 60 秒结果用户页面加载稍微慢一点图片就裂了。我的建议是分场景处理页面内嵌图片、音视频建议 600 到 1800 秒。一轮页面访问通常远小于这个时间但你又不能设太短因为用户可能把页面挂在后台一段时间再切回来这时候图片会重新加载。用户主动点击下载、预览附件建议 60 到 300 秒。下载场景通常是即时动作过期时间设短一点更安全。如果是邮件、IM 消息里发出去的链接建议 7 天或 30 天但要配合访问次数限制或专门的凭证系统这种一般超出了 OSS 签名 URL 的能力范围需要业务层做控制。另外有个细节签名 URL 是按次生成的如果同一张图片在一个页面上出现多次后端最好做一层缓存否则每加载一次页面就生成一次签名 URL尤其是列表页有几十张图片时会对后端产生没必要的计算压力。可以在服务端做一个短时间的内存缓存比如 5 分钟内相同 key 的签名 URL 直接复用。3.2 生产环境升级CDN URL 鉴权签名 URL 方案功能上没问题但生产环境还要考虑性能和体验。所有私有文件的访问都直接打到 OSS 源站一方面公网回源带宽成本高另一方面同一热点文件会被重复拉取延迟也降不下来。常规解法就是在前面加一层 CDN并把 CDN 的 URL 鉴权打开。CDN URL 鉴权的原理可以一句话讲清CDN 节点拿到请求后先校验 URL 里的auth_key签名是否合法、是否过期合法就回源或直接返回缓存内容不合法就拒绝。这个签名一般由后端生成和 OSS 签名 URL 的流程类似但作用对象从 OSS 变成了 CDN 节点。登录阿里云 CDN 控制台添加加速域名源站类型填 OSS 域名。如果 OSS Bucket 是私有CDN 回源时需要配置阿里云回源签名也就是让 CDN 节点在回源时自动携带 OSS 需要的签名信息这样源站才能识别来自 CDN 的合法请求。具体路径是CDN 域名管理 - 回源配置 - 阿里云 OSS 回源授权开启后 CDN 回源拿到的就是合法请求。然后在 CDN 的访问控制里开启 URL 鉴权。阿里云 CDN 提供 Type A、Type B、Type C、Type D 四种鉴权方式区别主要在 URL 参数组织格式和加密算法细节。Type A 最常用URL 格式如下http://cdn.example.com/path/file.jpg?auth_keytimestamp-rand-uid-md5hashmd5hash的计算规则一般是md5(URI-Timestamp-rand-uid-PrivateKey)具体算法在阿里云文档里有现成示例Java 代码类似这样public static String generateAuthKey(String uri, long timestamp, String rand, String uid, String privateKey) { String source String.format(%s-%s-%s-%s-%s, uri, timestamp, rand, uid, privateKey); String md5Hash DigestUtils.md5Hex(source); return String.format(%s-%s-%s-%s, timestamp, rand, uid, md5Hash); }这里要注意CDN 鉴权的auth_key是基于“前端最终访问的 URL”生成的生成规则里包含 URI 部分所以每次生成时要带上完整的路径。加 CDN 之后前端访问链接不再是 而是https://cdn.example.com/xxx。我特别想提醒一个坑不要在用了 CDN URL 鉴权之后还把 OSS 源站的签名 URL 暴露给前端。这样等于绕过了 CDN直接回源既导致流量费失控也起不到缓存加速的作用。前端只能访问 CDN 域名源站 URL 只能存在于 CDN 回源配置里。3.3 前端如何优雅地使用签名链接签名链接虽然好用但如果前端处理不当还是会踩坑。我在这里分享几个实际项目里沉淀下来的经验。第一不要在接口返回的数据里一次性生成大量长期有效的签名 URL然后一股脑塞给前端。更好的做法是接口只返回文件 key 或者文件 ID前端渲染图片时再通过一个轻量接口换取签名 URL。这样做的好处是权限回收及时你在后端可以随时取消某个用户的访问资格。缺点是会增加一次请求但是可以通过懒加载来优化。第二利用浏览器的onerror事件做兜底。长列表页面里用户往下滑动看内容有些图片的签名 URL 可能在页面停留很久之后过期。我遇到过一次比较头疼的情况用户停在某个页面 30 分钟切回来看图片浏览器重新发起请求签名已过期图片裂了。后来的解决办法是给img加一个onerror处理检测到加载失败后重新请求签名 URL替换src最多重试两次避免死循环。function loadWithSignedUrl(imgElement, fileKey, retryCount 0) { fetch(/api/files/${fileKey}/signed-url) .then(res res.json()) .then(data { imgElement.onerror () { if (retryCount 2) { loadWithSignedUrl(imgElement, fileKey, retryCount 1); } }; imgElement.src data.url; }); }第三能用 CDN 域名就用 CDN 域名。CDN 节点缓存了静态资源之后就算签名 URL 过期只要请求参数仍然满足鉴权要求CDN 节点可以直接返回缓存内容不用回源。这不仅能降低源站压力也在一定程度上缓解了过期问题。不过要注意如果 CDN 的边缘缓存配置了较长的 TTL刷新 CDN 缓存也是一个必须考虑的操作点否则会出现更新文件后用户还是看到旧文件的尴尬情况。4. 实操中常见的坑与排查思路OSS 相关报错有一个特点大多数错误信息里都藏着真实原因但很多人看了报错就慌反而忽略了错误码和响应头里的信息。这一章我把这几年遇到的高频问题整理出来每个都给排查思路和解决办法。4.1 AccessDenied: Put public object acl is not allowed这个报错特别经典完整错误大概是oss 上传失败: accessdenied: put public object acl is not allowed我见过好几个人一看到这个就以为是权限不够然后把 RAM 用户权限开到最大结果还是报错。真实原因是你上传时设置或者继承的 Object ACL 是public-read而 Bucket 的权限策略不允许写入公共读对象。阿里云默认策略里有些 Bucket 可能配置了“禁止公共访问”的防护规则或者你用的子用户权限没有oss:PutObjectAcl这个操作。上传请求里如果带了x-oss-object-acl: public-read而当前账户不支持设置公共读 ACL就会返回这个错误。解决办法分两层前端或服务端构造上传请求时去掉acl: public-read这个参数。私有 Bucket 的默认 ACL 就是继承 Bucket 的访问权限大多数情况下不需要显式设置。如果业务确实需要某些文件公开读不要用“上传时设置 ACL”的方式而是用“上传后单独操作 ACL”的流程并且在 RAM 策略里只授权oss:PutObjectAcl给专门的内部服务账号前端直传账号不给这个权限。我用表格把排查动作列一下排查动作说明检查上传代码里是否有 acl 参数去掉 public-read / public-read-write检查 RAM 用户是否具备 PutObjectAcl 权限一般不需要给前端直传账号检查 Bucket 是否开启禁止公共访问安全设置里确认检查 STS Policy 里是否限制了 Object ACL 操作STS 的 Policy 也需要同步调整4.2 签名 URL 过期导致资源加载失败表现是页面刚打开时一切正常过了一段时间图片、视频或者下载链接点击后直接 403。原因通常很简单签名 URL 的过期时间到了。这类问题排查有两个方向。第一个是看业务场景和过期时间是否匹配。如果是一个后台管理页面用户可能挂机一上午那签名 URL 只给 5 分钟肯定不够前端应该设计成“资源即将过期时重新获取”。第二个是检查服务器时间和阿里云标准时间的偏差。签名 URL 的校验依赖时间戳如果服务器时间不准生成的签名 URL 可能直接是无效的。尤其是自己搭的 NAS、虚拟机时间久了会有偏差建议部署时配置好 NTP 时间同步。这里也顺便说明为什么我推荐前端不要直接缓存签名 URL而是缓存文件 key。文件 key 是稳定不变的签名 URL 随时可以重新生成。把两者混在一起缓存等于把临时的东西当成永久的用迟早出问题。4.3 CORS 报错排查前端直传 OSS 时最容易犯的错就是先把代码写完再回来配 CORS结果浏览器一直报跨域错误。排查思路如下第一步确认 OSS 控制台的 CORS 规则里是否允许当前来源域名。注意端口也要算在内http://localhost:8080和http://localhost:3000是不同的来源。第二步确认允许 Methods 里是否包含上传用的方法。multipartUpload会先发一个 OPTIONS 预检请求如果 OPTIONS 没被允许会直接失败。第三步确认允许 Headers 是否包含了签名所需的Authorization、x-oss-*等自定义头。如果填得太窄请求发出去了但预检不通过报错信息里会提示缺少哪个 header。一个比较隐蔽的问题有些人在 OSS 控制台配了 CORS但是用的是自定义域名CORS 配置写的是 Bucket 的默认域名结果浏览器请求的是自定义域名跨域规则没匹配上。如果你给 OSS 绑定了自定义域名要确认 CDN 或 OSS 域名对应的 CORS 规则都配置正确。4.4 STS 权限过大或过小STS 临时凭证的权限范围看起来很简单实际配置时经常出现两个极端。极端一权限过小。比如 STS Policy 里写了Resource: [acs:oss:*:*:my-bucket/uploads/*]但前端上传时用的 key 是images/avatar.jpg不在uploads/下就会报AccessDenied。这种问题排查起来比较容易看报错里返回的 Object key再对照 Policy 里的资源范围即可。极端二权限过大。有些团队图省事直接把AliyunOSSFullAccess授权给 STS 角色。这意味着只要拿到临时凭证就能列举你账号下所有 Bucket删除任何 Object。临时凭证有效期哪怕只有 15 分钟被攻击者拿到也足够造成巨大损失。我常用的最小权限模板类似这样{ Version: 1, Statement: [ { Effect: Allow, Action: [ oss:PutObject, oss:GetObject, oss:ListObjects ], Resource: [ acs:oss:*:*:my-bucket, acs:oss:*:*:my-bucket/* ] } ] }原则就是给什么操作给什么路径按最小够用来。上传、下载、列举分开授权方便以后单独回收。4.5 常见错误码速查表错误码或报错片段可能原因解决方案AccessDenied: The bucket you visit is not belong to youRAM 用户或 STS 凭证没有该 Bucket 权限检查策略中的 Bucket 名称和 RegionAccessDenied: Request has expired签名 URL 或 STS 凭证过期调整过期时间检查服务端时间同步InvalidAccessKeyIdAccessKey ID 不存在或已禁用去 RAM 控制台检查密钥状态SignatureDoesNotMatchAccessKey Secret 错误或客户端时间偏差过大检查签名密钥校准服务器时间Put public object acl is not allowed上传时设置了 public-read ACL但账号无该权限去掉 ACL 参数或单独授权NoSuchKey访问的 Object 不存在检查文件 key 是否正确是否传错路径CORS 跨域报错CORS 规则未配置或来源不匹配按 4.3 排查通过 CDN 访问返回 403CDN 鉴权配置错误或时间戳校验失败检查 CDN 鉴权算法、密钥、URL 格式5. 生产环境落地权限管控、日志与成本优化方案跑通只是第一步真正上线前我建议再做一轮“安全加固”和“成本体检”。很多项目在开发和测试阶段都能跑得好好的一上生产就出问题多半是只关注了功能路径忽略了权限边界和运行细节。5.1 最小权限 RAM 策略模板生产环境的 RAM 策略建议分三类角色配置后端服务账号负责 STS 签发的 RAM 用户只需要sts:AssumeRole权限。运维管理账号负责 Bucket 生命周期配置、日志查看、CDN 配置权限不开通数据面读写权限。业务临时角色角色策略按 4.4 中的最小权限模板只开放特定 Bucket 和目录。这样即使某一个凭证泄露攻击者也不能横向移动因为你没有在同一个密钥上叠加太多权限。5.2 生命周期管理与上传行为约束OSS 的存储费用和流量费用是两条线。很多人只看存储费忽略了碎片和临时文件积累的问题。前端直传大文件如果中途失败OSS 可能残留部分分片数据。时间一长这些分片会占不少存储空间。建议在 Bucket 的“生命周期管理”里配置规则针对/uploads/下的碎片文件设置 7 天自动删除针对临时目录比如/temp/设置 30 天转低频访问或直接清理。这属于典型的“小成本大收益”配置一次后面不用再管。另一个容易被忽视的点是上传文件大小限制。前端直传如果不对文件大小做限制用户传个 100GB 的临时文件进来存储费用立刻上升。建议在后端 STS 接口里做文件类型和大小限制前端也做一层校验两边都卡住防止绕过前端。5.3 访问日志与安全审计建议在 Bucket 的“日志管理”里开启访问日志。日志会记录谁在什么时间请求了哪个 Object、返回状态码是多少、用了什么签名方式。这个功能平时没感觉一旦发生安全事件它就是定位的第一手证据。我遇到过一种情况某个私有文件被分享出去了对方把链接贴到了公开群里。开启日志之后才发现原来问题出在一个后端接口把签名 URL 写进接口返回值而接口本身又没有做访问控制。日志里的 User-Agent、Referer 和访问时间线帮我们定位到了是哪个业务路径泄露的。此外可以在 RAM 控制台开启操作审计记录谁在什么时间修改了 Bucket 策略、谁调用了 AssumeRole。合规审计也好排查问题也罢这些都属于“事后能保命”的配置。5.4 时间同步与签名校验的关联这是一个冷门但很实用的小知识点。OSS 签名 URL 和 STS 凭证都包含时间戳校验时依赖客户端发送的时间和 OSS 服务器时间的偏差。偏差超过一定范围一般默认 15 分钟请求会被判定为无效。云服务器本身一般会自动同步时间但自建的物理机、容器集群里的某些节点可能因为防火墙策略没法访问 NTP 服务器时间越偏越远。表现为今天生成的签名 URL 能用过几天同样的代码生成的签名 URL 直接报Request has expired而你检查过期时间明明是够的。排查方法很简单在应用服务器上执行date和date -u对比标准时间。如果偏差超过几秒赶紧配置 NTP 同步。我见过最夸张的一次服务器时间慢了 8 个小时所有签名 URL 一到前端就报过期排查了半天最后发现是时间问题。6. 写在最后的实战心得这套方案我在多个项目里落地过从最初的前后端不分离的老项目到现在的纯前端 SPA 加微服务后端核心思路一直没有变化密钥永远留在服务端前端只拿短期凭证访问权限精确到文件和目录。真正让我觉得这套方案值得推荐的原因是它的“可演进性”。刚开始可以先用最简单的后端生成签名 URL后期流量上来之后加 CDN 和 URL 鉴权再往后要支持多用户上传就上 STS 和 RAM 角色分离。每一步都不需要推翻重来只需要在现有架构上加一层。这种渐进式的演进方式对一个业务快速变化的团队来说非常友好。最后再分享一个排查技巧遇到任何 OSS 相关的 403、400 报错先别急着改代码先看响应头里的x-oss-error-code和x-oss-request-id。前者直接告诉你错误类型后者可以作为唯一标识去 OSS 控制台或者提工单时给技术支持查日志。这个习惯能帮你省下大量排查时间尤其是在线上环境看到请求 ID 定位问题比瞎猜快得多。 阿里云 OSS 私有存储前端访问方案：STS 临时凭证与签名 URL 实战
阿里云 OSS 私有存储这个题目几乎每个做前端开发或者全栈的人都绕不开。我自己最早踩过一个特别典型的坑为了保证数据安全Bucket 设成了私有结果页面上的图片直接全部 403后来为了图省事把 Bucket 改成公共读好了图片能开了结果月底账单出来直接被流量费吓一跳。更别提有人图方便直接把 AccessKey 写在代码里一个项目提交到公开仓库服务器资源被人拿去刷流量一晚上能给你烧掉几千块。这篇博文把我这几年在 OSS 私有存储 前端项目访问上攒下来的一套完整方案整理出来包括权限模型、STS 临时凭证直传、签名 URL、CDN 鉴权以及各种报错的实际排查经验。内容偏实战但原理部分我会尽量讲透适合刚接手前端项目、第一次接触 OSS 私有 Bucket 的开发者也适合已经部署上线但想优化安全性和访问速度的团队参考。1. 私有存储的权限模型与访问方案选型先搞清楚一个核心问题OSS 的“私有”到底是怎么定义出来的。OSS 的权限体系里Bucket 和 Object 都有访问权限公共读意味着所有人拿到 URL 就能直接读私有则意味着默认情况下只允许经过签名或授权的方式访问。私有 Bucket 的安全性天然更高但麻烦也随之而来前端项目怎么在不让用户看到密钥的前提下安全地读写这些私有资源。1.1 OSS 权限体系里最常用的三个概念很多人一上手就被 AccessKey、RAM 用户、STS、Bucket Policy 这几个概念搞晕。我用一个生活化的类比来解释。AccessKey ID 和 AccessKey Secret相当于你家的门钥匙。有了这串东西等同于拥有调用 OSS API 的完整权限具体权限看 AccessKey 对应的是主账号还是子账号。RAM 用户相当于你给家里请的保洁阿姨专门配了一把钥匙这把钥匙只能开某几个房间不能动其他区域。在阿里云控制台创建一个 RAM 子用户给它只授权 OSS 的读取权限那它就是一把受限钥匙。STS 临时凭证相当于去酒店入住时前台给你的房卡有效期到次日中午过期自动失效。就算别人捡到了房卡也只能在规定时间内刷指定的楼层。Bucket Policy 和 RAM Policy本质都是权限策略只是作用范围不同。前者是针对某个 Bucket 设规则后者是给某个用户或角色设规则。日常开发里优先用 RAM Policy STS 组合而不是在控制台上把 Bucket 改成公共读。我在实际项目里见过不少人把主账号 AccessKey 直接放到前端 JavaScript 代码里然后配一个公共读 Bucket。这种做法表面上跑得通实际等于把家门钥匙挂在门口。只要有人打开控制台看一眼网络请求就能拿到你的密钥。所以私有 Bucket 的第一条铁律就是任何密钥都不能出现在前端代码里。1.2 私有 Bucket 为什么不能直接暴露给前端读如果 Bucket 是私有前端拿一个不带签名的 URL 去请求 ObjectOSS 会直接返回 403。此时很多人的第一反应是把 Bucket 改成公共读。这种方案有两个非常大的隐患。第一是成本不可控。公共读意味着任何人都能拿到 Object 的真实地址如果被人恶意分享、下载OSS 的流量费会快速上涨。我见过一个案例对方只是把图片 URL 贴到了某个访问量很大的站一天的流量费就远超预期。第二是数据安全边界完全失效。虽然 Object 本身可能只是图片、附件但一旦所有资源都公开可读任何未授权用户都能遍历甚至批量下载你的敏感资料比如订单附件、用户证件照片。你没法保证某个业务数据未来不会从私有变成敏感数据所以从一开始就守住“默认私有”的边界比事后补救成本低得多。1.3 三种主流访问方案的对比与选型解决“私有 Bucket 前端访问”这个矛盾业界主流方案基本上可以归纳为三种形态。方案安全级别实现复杂度适用场景后端中转下载高低低频访问、小文件短期使用STS 临时凭证直传 OSS高中前端直接上传文件如头像、附件签名 URL / CDN URL 鉴权高中前端展示、下载私有文件如网页图片后端中转下载最保守前端把文件 ID 传给后端后端用服务端 SDK 从 OSS 拉取数据再返回给前端。这种方式适合文件不大、请求量不高的场景问题在于 OSS 流量会先经过你的应用服务器占用应用带宽和内存并发一高就扛不住。STS 临时凭证直传是如今前端上传到 OSS 的标准答案。服务端通过 AssumeRole 接口换取一个带时效和权限限制的临时凭证前端拿到凭证后直接调用 OSS SDK 上传。整个过程密钥不落地权限还能精确控制到某个 Bucket 的某个目录。签名 URL 是私有文件读取的标准姿势。服务端生成一个带过期时间的 URL格式类似https://bucket.oss-cn-hangzhou.aliyuncs.com/private-file.pdf?OSSAccessKeyIdxxxExpiresxxxSignaturexxx。前端拿到这个 URL 后就像访问普通链接一样加载资源。如果访问量特别大再在前面加一层 CDN开启 URL 鉴权把回源压力拦在边缘节点。方案选型没有绝对的最佳关键看你的业务是“读多写少”还是“写多读少”。上传频率高建议上 STS读取频率高建议上签名 URL 或 CDN 鉴权。混合场景就两套一起上我后面会分别展开讲。2. 方案一STS 临时凭证实现前端安全直传前端上传文件到 OSS看起来只是put一下的事但安全设计的关键不在上传本身而在于“凭证怎么发放”。最安全的做法是后端负责验身份OSS 只认临时凭证前端永远接触不到持久密钥。2.1 原理为什么是“后端签名前端直传”这里要解释一个很常见的问题为什么不能让前端直接把文件传给你的后端服务器再由后端转存到 OSS原因不复杂首先是性能瓶颈上传文件如果都走应用服务器应用服务器的带宽和连接数会成为瓶颈一个小项目可能没问题但多人同时上传大文件时应用服务器很容易被打满接口延迟飙升其次是成本问题同样的流量OSS 内网传输和公网传输价格不同但经由应用服务器中转相当于多付了一份带宽的钱再次是稳定性文件上传是长连接应用服务器还要处理业务请求混在一起容易产生互相拖累的情况。STS 方案解决问题的思路是把“验证身份”和“写入文件”这两件事拆开。前端先调用你自己的后端接口后端拿着配置好的 RAM 用户密钥到阿里云 STS 服务申请一个临时凭证。这个临时凭证有四个关键属性有效期默认 3600 秒可以自己设置权限范围Policy 指定的 OSS 操作资源范围例如只能操作某个 Bucket 的某个目录临时身份标识RoleSessionName前端拿到临时凭证后再用它去初始化 OSS SDK直接上传文件。整个过程后端只需要处理一个轻量级的凭证申请接口不承担文件字节流的传输所以哪怕同时来几千个上传请求后端压力也不大。2.2 后端签发 STS 凭证的标准姿势先要做前置准备。在阿里云 RAM 控制台创建一个子用户比如叫oss-sts-prod给它分配一个自定义策略这个策略只允许 AssumeRole 操作。然后再创建一个 RAM 角色比如叫oss-frontend-uploader角色的信任策略允许刚才那个子用户去 AssumeRole同时给角色关联一个面向 OSS 写入的权限策略。很多初学者容易在这里绕晕简单理解就是子用户是一把钥匙角色是一份授权说明书STS 是把两者结合生成一张临时房卡。以下是 Java 后端的 STS 签发代码示例这是我在 Spring Boot 项目里实际用过的简化版本。先引入阿里云 SDK 依赖然后写一个 Service。// pom.xml 里要引入的依赖 // com.aliyun:aliyun-java-sdk-sts // com.aliyun:aliyun-java-sdk-core import com.aliyuncs.DefaultAcsClient; import com.aliyuncs.auth.sts.AssumeRoleRequest; import com.aliyuncs.auth.sts.AssumeRoleResponse; import com.aliyuncs.profile.DefaultProfile; public class StsService { // 这些配置建议放到环境变量或配置中心不要硬编码 private static final String ACCESS_KEY_ID your-ram-user-access-key-id; private static final String ACCESS_KEY_SECRET your-ram-user-access-key-secret; private static final String ROLE_ARN acs:ram::1234567890123456:role/oss-frontend-uploader; private static final String REGION_ID cn-hangzhou; public AssumeRoleResponse.Credentials getStsCredential() { DefaultProfile profile DefaultProfile.getProfile(REGION_ID, ACCESS_KEY_ID, ACCESS_KEY_SECRET); DefaultAcsClient client new DefaultAcsClient(profile); AssumeRoleRequest request new AssumeRoleRequest(); request.setRoleArn(ROLE_ARN); request.setRoleSessionName(web-upload-session); // 有效期设置单位是秒 request.setDurationSeconds(3600L); // 这里可以临时收紧权限策略内容会覆盖角色本身的策略吗不会二者取交集 request.setPolicy({\Version\:\1\,\Statement\:[{\Effect\:\Allow\,\Action\:[\oss:PutObject\],\Resource\:[\acs:oss:*:*:my-bucket/uploads/*\]}]}); AssumeRoleResponse response client.getAcsResponse(request); return response.getCredentials(); } }这里有几个要点值得多说几句。setPolicy是可选的但它非常有用。角色本身可能配置了比较大的权限范围而你在签发临时凭证时可以通过 Policy 再收紧一层。比如角色允许访问my-bucket全部资源但你只想让某个前端页面只上传到uploads/目录就可以在签发的 Policy 里限制。最终临时凭证的有效权限是“角色权限”和“STS Policy 权限”的交集利用这个特性可以做多租户隔离。DurationSeconds不建议设置得太长。临时凭证的意义就在于短期有效过长的有效期会放大泄露风险。我一般按业务场景设置普通 Web 端 900 到 1800 秒足够用。有些团队为了省事设置成 12 小时等于把临时凭证变成了准持久凭证风险暴露面大大增加。前端拿到 STS 响应后数据结构大概是这样的{ accessKeyId: STS.xxx, accessKeySecret: yyy, securityToken: zzz, expiration: 2025-01-01T12:00:00Z }前端再把这三个字段传给 OSS SDK。2.3 前端直传 OSS 的完整实现前端部分我以 aliyun-oss 官方 SDK 为例。安装依赖后核心代码如下。import OSS from ali-oss; async function uploadFile(file) { // 1. 请求后端接口获取临时凭证 const tokenRes await fetch(/api/oss/sts, { credentials: include }); const sts await tokenRes.json(); // 2. 用临时凭证初始化 OSS Client const client new OSS({ region: oss-cn-hangzhou, bucket: my-bucket, accessKeyId: sts.accessKeyId, accessKeySecret: sts.accessKeySecret, stsToken: sts.securityToken, refreshSTSToken: async () { // 可选SDK 会在凭证过期前自动刷新 const res await fetch(/api/oss/sts, { credentials: include }); return await res.json(); }, refreshSTSTokenInterval: 900000 // 默认15分钟刷新一次单位毫秒 }); // 3. 执行分片上传适合大文件 const result await client.multipartUpload(uploads/${Date.now()}-${file.name}, file, { progress: (p, cpt, res) { console.log(上传进度${Math.floor(p * 100)}%); }, partSize: 1024 * 1024 * 10, // 分片大小 10MB timeout: 120000 }); return result.name; }这段代码有两个值得注意的点。第一个是refreshSTSToken回调。OSS 官方 SDK 支持在临时凭证过期前自动重新申请新凭证这对长传大文件特别重要。如果你传一个 2GB 的压缩包上传时长可能超过凭证有效期没有自动刷新机制就会出现传了一半突然 403 的情况。第二个是文件名处理。直接拿用户上传的文件名拼在路径里可能带来路径覆盖和非法字符问题。我习惯在服务端做一层文件名映射或者在前端统一改写成时间戳 随机串 原始扩展名一方面避免中文名乱码另一方面防止用户传入../../xxx这类危险路径。上传完成后如果 Bucket 是私有那么前端拿到的result.name只是一个对象 key并不能直接作为公开访问地址。要怎么展示我会在下一章讲。2.4 CORS 配置与常见问题前端直传 OSS 天然是跨域请求因为前端页面运行在自己的域名上而 OSS 请求发往*.aliyuncs.com。如果 OSS 控制台没配置 CORS浏览器会把响应拦截掉表现就是控制台报错Access to XMLHttpRequest at https://xxx.oss-cn-hangzhou.aliyuncs.com/... from origin https://yourdomain.com has been blocked by CORS policy。OSS 控制台的 CORS 配置路径是Bucket 列表 - 数据安全 - 跨域设置。新增规则时建议按下表填写。配置项推荐值说明来源https://yourdomain.com多个域名用换行分隔生产环境不要填星号允许 MethodsGET, PUT, POST, DELETE, HEAD上传需要 PUT / POST允许 Headers*上传时会带 Authorization、x-oss-* 等头暴露 HeadersETag分片上传的校验需要读这个响应头CORS 是所有直传方案里最先要确认的配置很多时候上传报错不是代码逻辑有问题而是来源域名没匹配上。比如你本地开发用的localhost:8080CORS 里只配了线上域名本地一调就报错。3. 方案二私有文件的前端访问签名 URL CDN 鉴权上传搞定了下一件事就是“怎么把私有文件展示给用户”。私有 Bucket 的 Object 不能直接通过 URL 访问必须带上签名参数。签名 URL 是后端生成的前端拿过来直接使用。这里我再展开讲两种落地方式一种是最小可用的签名 URL另一种是生产环境下更适合的 CDN URL 鉴权。3.1 最小方案后端生成签名 URL后端调用 OSS SDK 生成签名 URL 的代码很简单。// Java 示例 import com.aliyun.oss.OSS; import com.aliyun.oss.OSSClientBuilder; import java.util.Date; public class OssService { private OSS client; public String generateSignedUrl(String objectKey, int expiresSeconds) { // 初始化 client 时用 RAM 用户的 AccessKey而不是主账号 String endpoint https://oss-cn-hangzhou.aliyuncs.com; this.client new OSSClientBuilder().build(endpoint, ACCESS_KEY_ID, ACCESS_KEY_SECRET); Date expiration new Date(System.currentTimeMillis() expiresSeconds * 1000); // 生成签名 URL只对指定 Object 生效 return client.generatePresignedUrl(my-bucket, objectKey, expiration).toString(); } }前端拿到这个 URL 后可以直接塞给img src、video或者window.open()不需要再做任何额外的鉴权处理。浏览器请求该 URL 时OSS 会检查签名参数的合法性以及过期时间校验通过就返回文件内容。过期时间的设计在这一步非常关键。我见过两种极端一种是把过期时间设成 10 年那跟公共读没有任何区别签名 URL 泄露出去了就一直是公开的另一种是设成 60 秒结果用户页面加载稍微慢一点图片就裂了。我的建议是分场景处理页面内嵌图片、音视频建议 600 到 1800 秒。一轮页面访问通常远小于这个时间但你又不能设太短因为用户可能把页面挂在后台一段时间再切回来这时候图片会重新加载。用户主动点击下载、预览附件建议 60 到 300 秒。下载场景通常是即时动作过期时间设短一点更安全。如果是邮件、IM 消息里发出去的链接建议 7 天或 30 天但要配合访问次数限制或专门的凭证系统这种一般超出了 OSS 签名 URL 的能力范围需要业务层做控制。另外有个细节签名 URL 是按次生成的如果同一张图片在一个页面上出现多次后端最好做一层缓存否则每加载一次页面就生成一次签名 URL尤其是列表页有几十张图片时会对后端产生没必要的计算压力。可以在服务端做一个短时间的内存缓存比如 5 分钟内相同 key 的签名 URL 直接复用。3.2 生产环境升级CDN URL 鉴权签名 URL 方案功能上没问题但生产环境还要考虑性能和体验。所有私有文件的访问都直接打到 OSS 源站一方面公网回源带宽成本高另一方面同一热点文件会被重复拉取延迟也降不下来。常规解法就是在前面加一层 CDN并把 CDN 的 URL 鉴权打开。CDN URL 鉴权的原理可以一句话讲清CDN 节点拿到请求后先校验 URL 里的auth_key签名是否合法、是否过期合法就回源或直接返回缓存内容不合法就拒绝。这个签名一般由后端生成和 OSS 签名 URL 的流程类似但作用对象从 OSS 变成了 CDN 节点。登录阿里云 CDN 控制台添加加速域名源站类型填 OSS 域名。如果 OSS Bucket 是私有CDN 回源时需要配置阿里云回源签名也就是让 CDN 节点在回源时自动携带 OSS 需要的签名信息这样源站才能识别来自 CDN 的合法请求。具体路径是CDN 域名管理 - 回源配置 - 阿里云 OSS 回源授权开启后 CDN 回源拿到的就是合法请求。然后在 CDN 的访问控制里开启 URL 鉴权。阿里云 CDN 提供 Type A、Type B、Type C、Type D 四种鉴权方式区别主要在 URL 参数组织格式和加密算法细节。Type A 最常用URL 格式如下http://cdn.example.com/path/file.jpg?auth_keytimestamp-rand-uid-md5hashmd5hash的计算规则一般是md5(URI-Timestamp-rand-uid-PrivateKey)具体算法在阿里云文档里有现成示例Java 代码类似这样public static String generateAuthKey(String uri, long timestamp, String rand, String uid, String privateKey) { String source String.format(%s-%s-%s-%s-%s, uri, timestamp, rand, uid, privateKey); String md5Hash DigestUtils.md5Hex(source); return String.format(%s-%s-%s-%s, timestamp, rand, uid, md5Hash); }这里要注意CDN 鉴权的auth_key是基于“前端最终访问的 URL”生成的生成规则里包含 URI 部分所以每次生成时要带上完整的路径。加 CDN 之后前端访问链接不再是 而是https://cdn.example.com/xxx。我特别想提醒一个坑不要在用了 CDN URL 鉴权之后还把 OSS 源站的签名 URL 暴露给前端。这样等于绕过了 CDN直接回源既导致流量费失控也起不到缓存加速的作用。前端只能访问 CDN 域名源站 URL 只能存在于 CDN 回源配置里。3.3 前端如何优雅地使用签名链接签名链接虽然好用但如果前端处理不当还是会踩坑。我在这里分享几个实际项目里沉淀下来的经验。第一不要在接口返回的数据里一次性生成大量长期有效的签名 URL然后一股脑塞给前端。更好的做法是接口只返回文件 key 或者文件 ID前端渲染图片时再通过一个轻量接口换取签名 URL。这样做的好处是权限回收及时你在后端可以随时取消某个用户的访问资格。缺点是会增加一次请求但是可以通过懒加载来优化。第二利用浏览器的onerror事件做兜底。长列表页面里用户往下滑动看内容有些图片的签名 URL 可能在页面停留很久之后过期。我遇到过一次比较头疼的情况用户停在某个页面 30 分钟切回来看图片浏览器重新发起请求签名已过期图片裂了。后来的解决办法是给img加一个onerror处理检测到加载失败后重新请求签名 URL替换src最多重试两次避免死循环。function loadWithSignedUrl(imgElement, fileKey, retryCount 0) { fetch(/api/files/${fileKey}/signed-url) .then(res res.json()) .then(data { imgElement.onerror () { if (retryCount 2) { loadWithSignedUrl(imgElement, fileKey, retryCount 1); } }; imgElement.src data.url; }); }第三能用 CDN 域名就用 CDN 域名。CDN 节点缓存了静态资源之后就算签名 URL 过期只要请求参数仍然满足鉴权要求CDN 节点可以直接返回缓存内容不用回源。这不仅能降低源站压力也在一定程度上缓解了过期问题。不过要注意如果 CDN 的边缘缓存配置了较长的 TTL刷新 CDN 缓存也是一个必须考虑的操作点否则会出现更新文件后用户还是看到旧文件的尴尬情况。4. 实操中常见的坑与排查思路OSS 相关报错有一个特点大多数错误信息里都藏着真实原因但很多人看了报错就慌反而忽略了错误码和响应头里的信息。这一章我把这几年遇到的高频问题整理出来每个都给排查思路和解决办法。4.1 AccessDenied: Put public object acl is not allowed这个报错特别经典完整错误大概是oss 上传失败: accessdenied: put public object acl is not allowed我见过好几个人一看到这个就以为是权限不够然后把 RAM 用户权限开到最大结果还是报错。真实原因是你上传时设置或者继承的 Object ACL 是public-read而 Bucket 的权限策略不允许写入公共读对象。阿里云默认策略里有些 Bucket 可能配置了“禁止公共访问”的防护规则或者你用的子用户权限没有oss:PutObjectAcl这个操作。上传请求里如果带了x-oss-object-acl: public-read而当前账户不支持设置公共读 ACL就会返回这个错误。解决办法分两层前端或服务端构造上传请求时去掉acl: public-read这个参数。私有 Bucket 的默认 ACL 就是继承 Bucket 的访问权限大多数情况下不需要显式设置。如果业务确实需要某些文件公开读不要用“上传时设置 ACL”的方式而是用“上传后单独操作 ACL”的流程并且在 RAM 策略里只授权oss:PutObjectAcl给专门的内部服务账号前端直传账号不给这个权限。我用表格把排查动作列一下排查动作说明检查上传代码里是否有 acl 参数去掉 public-read / public-read-write检查 RAM 用户是否具备 PutObjectAcl 权限一般不需要给前端直传账号检查 Bucket 是否开启禁止公共访问安全设置里确认检查 STS Policy 里是否限制了 Object ACL 操作STS 的 Policy 也需要同步调整4.2 签名 URL 过期导致资源加载失败表现是页面刚打开时一切正常过了一段时间图片、视频或者下载链接点击后直接 403。原因通常很简单签名 URL 的过期时间到了。这类问题排查有两个方向。第一个是看业务场景和过期时间是否匹配。如果是一个后台管理页面用户可能挂机一上午那签名 URL 只给 5 分钟肯定不够前端应该设计成“资源即将过期时重新获取”。第二个是检查服务器时间和阿里云标准时间的偏差。签名 URL 的校验依赖时间戳如果服务器时间不准生成的签名 URL 可能直接是无效的。尤其是自己搭的 NAS、虚拟机时间久了会有偏差建议部署时配置好 NTP 时间同步。这里也顺便说明为什么我推荐前端不要直接缓存签名 URL而是缓存文件 key。文件 key 是稳定不变的签名 URL 随时可以重新生成。把两者混在一起缓存等于把临时的东西当成永久的用迟早出问题。4.3 CORS 报错排查前端直传 OSS 时最容易犯的错就是先把代码写完再回来配 CORS结果浏览器一直报跨域错误。排查思路如下第一步确认 OSS 控制台的 CORS 规则里是否允许当前来源域名。注意端口也要算在内http://localhost:8080和http://localhost:3000是不同的来源。第二步确认允许 Methods 里是否包含上传用的方法。multipartUpload会先发一个 OPTIONS 预检请求如果 OPTIONS 没被允许会直接失败。第三步确认允许 Headers 是否包含了签名所需的Authorization、x-oss-*等自定义头。如果填得太窄请求发出去了但预检不通过报错信息里会提示缺少哪个 header。一个比较隐蔽的问题有些人在 OSS 控制台配了 CORS但是用的是自定义域名CORS 配置写的是 Bucket 的默认域名结果浏览器请求的是自定义域名跨域规则没匹配上。如果你给 OSS 绑定了自定义域名要确认 CDN 或 OSS 域名对应的 CORS 规则都配置正确。4.4 STS 权限过大或过小STS 临时凭证的权限范围看起来很简单实际配置时经常出现两个极端。极端一权限过小。比如 STS Policy 里写了Resource: [acs:oss:*:*:my-bucket/uploads/*]但前端上传时用的 key 是images/avatar.jpg不在uploads/下就会报AccessDenied。这种问题排查起来比较容易看报错里返回的 Object key再对照 Policy 里的资源范围即可。极端二权限过大。有些团队图省事直接把AliyunOSSFullAccess授权给 STS 角色。这意味着只要拿到临时凭证就能列举你账号下所有 Bucket删除任何 Object。临时凭证有效期哪怕只有 15 分钟被攻击者拿到也足够造成巨大损失。我常用的最小权限模板类似这样{ Version: 1, Statement: [ { Effect: Allow, Action: [ oss:PutObject, oss:GetObject, oss:ListObjects ], Resource: [ acs:oss:*:*:my-bucket, acs:oss:*:*:my-bucket/* ] } ] }原则就是给什么操作给什么路径按最小够用来。上传、下载、列举分开授权方便以后单独回收。4.5 常见错误码速查表错误码或报错片段可能原因解决方案AccessDenied: The bucket you visit is not belong to youRAM 用户或 STS 凭证没有该 Bucket 权限检查策略中的 Bucket 名称和 RegionAccessDenied: Request has expired签名 URL 或 STS 凭证过期调整过期时间检查服务端时间同步InvalidAccessKeyIdAccessKey ID 不存在或已禁用去 RAM 控制台检查密钥状态SignatureDoesNotMatchAccessKey Secret 错误或客户端时间偏差过大检查签名密钥校准服务器时间Put public object acl is not allowed上传时设置了 public-read ACL但账号无该权限去掉 ACL 参数或单独授权NoSuchKey访问的 Object 不存在检查文件 key 是否正确是否传错路径CORS 跨域报错CORS 规则未配置或来源不匹配按 4.3 排查通过 CDN 访问返回 403CDN 鉴权配置错误或时间戳校验失败检查 CDN 鉴权算法、密钥、URL 格式5. 生产环境落地权限管控、日志与成本优化方案跑通只是第一步真正上线前我建议再做一轮“安全加固”和“成本体检”。很多项目在开发和测试阶段都能跑得好好的一上生产就出问题多半是只关注了功能路径忽略了权限边界和运行细节。5.1 最小权限 RAM 策略模板生产环境的 RAM 策略建议分三类角色配置后端服务账号负责 STS 签发的 RAM 用户只需要sts:AssumeRole权限。运维管理账号负责 Bucket 生命周期配置、日志查看、CDN 配置权限不开通数据面读写权限。业务临时角色角色策略按 4.4 中的最小权限模板只开放特定 Bucket 和目录。这样即使某一个凭证泄露攻击者也不能横向移动因为你没有在同一个密钥上叠加太多权限。5.2 生命周期管理与上传行为约束OSS 的存储费用和流量费用是两条线。很多人只看存储费忽略了碎片和临时文件积累的问题。前端直传大文件如果中途失败OSS 可能残留部分分片数据。时间一长这些分片会占不少存储空间。建议在 Bucket 的“生命周期管理”里配置规则针对/uploads/下的碎片文件设置 7 天自动删除针对临时目录比如/temp/设置 30 天转低频访问或直接清理。这属于典型的“小成本大收益”配置一次后面不用再管。另一个容易被忽视的点是上传文件大小限制。前端直传如果不对文件大小做限制用户传个 100GB 的临时文件进来存储费用立刻上升。建议在后端 STS 接口里做文件类型和大小限制前端也做一层校验两边都卡住防止绕过前端。5.3 访问日志与安全审计建议在 Bucket 的“日志管理”里开启访问日志。日志会记录谁在什么时间请求了哪个 Object、返回状态码是多少、用了什么签名方式。这个功能平时没感觉一旦发生安全事件它就是定位的第一手证据。我遇到过一种情况某个私有文件被分享出去了对方把链接贴到了公开群里。开启日志之后才发现原来问题出在一个后端接口把签名 URL 写进接口返回值而接口本身又没有做访问控制。日志里的 User-Agent、Referer 和访问时间线帮我们定位到了是哪个业务路径泄露的。此外可以在 RAM 控制台开启操作审计记录谁在什么时间修改了 Bucket 策略、谁调用了 AssumeRole。合规审计也好排查问题也罢这些都属于“事后能保命”的配置。5.4 时间同步与签名校验的关联这是一个冷门但很实用的小知识点。OSS 签名 URL 和 STS 凭证都包含时间戳校验时依赖客户端发送的时间和 OSS 服务器时间的偏差。偏差超过一定范围一般默认 15 分钟请求会被判定为无效。云服务器本身一般会自动同步时间但自建的物理机、容器集群里的某些节点可能因为防火墙策略没法访问 NTP 服务器时间越偏越远。表现为今天生成的签名 URL 能用过几天同样的代码生成的签名 URL 直接报Request has expired而你检查过期时间明明是够的。排查方法很简单在应用服务器上执行date和date -u对比标准时间。如果偏差超过几秒赶紧配置 NTP 同步。我见过最夸张的一次服务器时间慢了 8 个小时所有签名 URL 一到前端就报过期排查了半天最后发现是时间问题。6. 写在最后的实战心得这套方案我在多个项目里落地过从最初的前后端不分离的老项目到现在的纯前端 SPA 加微服务后端核心思路一直没有变化密钥永远留在服务端前端只拿短期凭证访问权限精确到文件和目录。真正让我觉得这套方案值得推荐的原因是它的“可演进性”。刚开始可以先用最简单的后端生成签名 URL后期流量上来之后加 CDN 和 URL 鉴权再往后要支持多用户上传就上 STS 和 RAM 角色分离。每一步都不需要推翻重来只需要在现有架构上加一层。这种渐进式的演进方式对一个业务快速变化的团队来说非常友好。最后再分享一个排查技巧遇到任何 OSS 相关的 403、400 报错先别急着改代码先看响应头里的x-oss-error-code和x-oss-request-id。前者直接告诉你错误类型后者可以作为唯一标识去 OSS 控制台或者提工单时给技术支持查日志。这个习惯能帮你省下大量排查时间尤其是在线上环境看到请求 ID 定位问题比瞎猜快得多。