跳到主要内容

存储方案

一、基本信息​

存储方案用于配置系统上传图片、视频、附件时使用的对象存储服务。生产环境推荐使用阿里云 OSS、腾讯云 COS 或自建 MinIO，本地存储仅建议本地测试使用。

存储方案

二、操作路径​

通过【平台】-【设置】-【系统参数】-【存储方案】进行配置。

三、开通和配置​

三方存储配置​

按下面顺序完成阿里云控制台配置。标记为【重点】的内容，后面都需要填写到我们系统中。

系统字段参考位置
Bucket名称参考【重点 1】。
EndPoint（地域节点）参考【重点 2】。
密钥id参考【重点 3】。
密钥参考【重点 3】。
Ram角色Arn参考【重点 4】。
StsEndPoint（地域节点）参考【重点 5】。

1. 创建 Bucket​

登录阿里云 OSS 控制台，在【Bucket 列表】中点击【创建 Bucket】。

阿里云 OSS 创建 Bucket

必要参数说明：

参数建议
Bucket 名称后续要填写到系统【Bucket名称】。创建后不可修改，建议使用小写字母、数字和中划线。
地域创建后不可修改，建议选择离 API 服务器或主要用户最近的地域。
存储类型普通图片、附件上传选择【标准存储】。
存储冗余类型按预算选择【本地冗余】或【同城冗余】。
版本控制默认关闭即可，需要防误删时再开启。

配置完成后点击【完成创建】。

阿里云 OSS 完成创建 Bucket

重点 1：Bucket 名称

这里创建的 Bucket 名称需要复制到我们系统【Bucket名称】。如果系统显示为【储存空间】，也填写这个 Bucket 名称。

示例：阿里云创建的 Bucket 名称为 shoptnt，系统【Bucket名称】填写 shoptnt。

2. 获取 Endpoint​

进入刚创建的 Bucket，在【概览】页面下方查看【访问端口】。

阿里云 OSS Bucket Endpoint

Endpoint 选择说明：

场景填写方式
API 服务不在阿里云，或不确定网络环境使用【外网访问】Endpoint。
API 服务部署在阿里云 ECS，且 ECS 与 Bucket 在同一地域可以使用对应的内网 Endpoint。
小程序、App、HTTPS 站点系统中填写 https:// 开头的 Endpoint。

重点 2：EndPoint（地域节点）

Bucket 页面中的 Endpoint 需要复制到我们系统【EndPoint（地域节点）】。

示例：如果选择外网 Endpoint oss-cn-guangzhou.aliyuncs.com，系统【EndPoint（地域节点）】填写 https://oss-cn-guangzhou.aliyuncs.com。

内网 Endpoint 只能给服务器访问使用，不要把内网域名返回给浏览器作为图片访问地址。

3. 配置 Bucket 访问权限​

进入 Bucket 左侧【权限控制】。

阿里云 OSS 权限控制入口

先进入【阻止公共访问】，关闭【阻止公共访问】。

阿里云 OSS 关闭阻止公共访问

再进入【读写权限】，Bucket ACL 选择【公共读】。

阿里云 OSS Bucket ACL 公共读

安全提示

只选择【公共读】，不要选择【公共读写】。公共读用于前端访问图片，公共写会带来安全风险。

4. 配置跨域 CORS​

前端直传 OSS 前，需要给 Bucket 配置跨域规则。进入 Bucket 左侧【数据安全】-【跨域设置】，点击【创建规则】。

阿里云 OSS 跨域设置入口

跨域规则建议按下表配置：

参数测试环境生产环境
来源可先填写 * 快速验证填写商城前端域名，例如 https://www.example.com。
允许 Methods勾选 GET、POST、PUT、DELETE、HEAD至少需要 POST、PUT，建议保留 GET、HEAD。
允许 Headers填写 *可填写 *，稳定后再按实际请求头收紧。
暴露 Headers填写 ETag、x-oss-request-id填写 ETag、x-oss-request-id。
缓存时间（秒）排查问题时可填 0建议填 600 或更长。

阿里云 OSS 编辑跨域规则

5. 配置 RAM 用户和 STS 角色​

推荐使用 STS Token 临时凭证访问 OSS。系统先使用 RAM 用户的 AccessKey 调用 STS AssumeRole，再用返回的临时凭证上传文件。

在 Bucket 的【权限控制】-【访问控制 RAM】中点击【前往 RAM 控制台】。

阿里云 OSS 访问控制 RAM

进入【用户】页面，点击【创建用户】。

阿里云 RAM 创建用户入口

RAM 用户建议这样创建：

  1. 登录名称填写 oss-image、shop-oss 这类能看出用途的名称。
  2. 不勾选【使用控制台访问】。
  3. 如需生成 AccessKey，只用于系统服务调用 STS，不直接访问 OSS。

阿里云 RAM 创建用户 AccessKey

创建完成后立即复制并保存【AccessKey ID】和【AccessKey Secret】。

阿里云 RAM 用户 AccessKey 创建结果

重点 3：密钥id / 密钥

【AccessKey ID】需要填写到我们系统【密钥id】。

【AccessKey Secret】需要填写到我们系统【密钥】。AccessKey Secret 页面关闭后无法再次查看。

注意：还需要给这个 RAM 用户授权系统策略【AliyunSTSAssumeRoleAccess】，否则系统获取 STS Token 会报 403 You are not authorized to do this action。

创建 RAM 角色时，信任主体按部署方式选择：

阿里云 RAM 创建角色信任主体

场景选择
系统服务通过 RAM 用户调用 AssumeRole 获取 STS Token选择【云账号】，信任主体名称选择【当前云账号】。
系统部署在阿里云 ECS，并使用 ECS 实例 RAM 角色获取临时凭证选择【云服务】，再选择对应云服务。
企业 SSO 或外部身份提供商接入选择【身份提供商】，普通商城部署一般不用。

创建成功后进入角色详情页，复制并保存角色 ARN。

阿里云 RAM 角色详情新增授权

重点 4：Ram角色Arn

角色详情页中的 ARN 需要填写到我们系统【Ram角色Arn】。

示例：acs:ram::1672608113458803:role/oss-images。

在角色【权限管理】中点击【新增授权】，资源范围选择【账号级别】，授权主体保持当前 RAM 角色，权限策略搜索 oss。

阿里云 RAM 角色新增 OSS 授权

权限说明

快速验证可以选择【AliyunOSSFullAccess】。如果已选择【AliyunOSSFullAccess】，不需要再选择【AliyunOSSReadOnlyAccess】。

生产环境建议创建自定义权限策略，只授权当前 Bucket 的读写权限。

重点 5：StsEndPoint（地域节点）

STS 服务接入点需要填写到我们系统【StsEndPoint（地域节点）】。

Bucket 创建在哪个地域，就使用该地域对应的 STS Endpoint。填写时把示例中的 cn-guangzhou 替换为 Bucket 所在地域的 RegionId。

示例：Bucket 在华南 3（广州），RegionId 为 cn-guangzhou，填写 https://sts.cn-guangzhou.aliyuncs.com。

示例：Bucket 在华东 1（杭州），RegionId 为 cn-hangzhou，填写 https://sts.cn-hangzhou.aliyuncs.com。

6. 配置 OSS 缩略图​

进入 Bucket 左侧【数据处理】-【图片处理】，在【样式管理】中点击【导入样式】。

阿里云 OSS 导入缩略图样式

下载并导入缩略图规则文件：

点击下载 aliyun-oss-thumbnail-rules.txt。

规则文件包含 100x100、300x300、400x400、800x800 四个样式。

导入完成后点击【访问设置】，开启自定义分隔符，选择 _。

阿里云 OSS 图片处理访问设置

缩略图说明

自定义分隔符必须选择 _，系统生成缩略图地址时会使用 原图地址_样式名称。

例如原图地址为 https://shoptnt.oss-cn-guangzhou.aliyuncs.com/shop/demo.png，300x300 缩略图地址为 https://shoptnt.oss-cn-guangzhou.aliyuncs.com/shop/demo.png_300x300。

7. 域名管理（推荐使用，可选）​

如果图片需要在浏览器中直接预览，生产环境建议绑定自定义 HTTPS 域名或 CDN 域名。这样图片地址可以使用自己的域名，避免直接暴露 OSS 默认域名，也便于后续接入 CDN、证书和缓存策略。

进入 Bucket 左侧【Bucket 配置】-【域名管理】，点击【绑定域名】。

阿里云 OSS 域名管理

配置步骤：

  1. 准备一个图片访问域名，例如 img.example.com 或 static.example.com。
  2. 在 OSS【域名管理】中绑定该域名。
  3. 到域名 DNS 控制台添加 CNAME 解析，把图片域名指向 OSS 提示的 CNAME 地址。
  4. 等待域名状态变为已绑定或已生效。
  5. 在【HTTPS 证书】中上传或申请该域名的 HTTPS 证书，并开启 HTTPS 访问。
  6. 如果使用阿里云 CDN，先在 CDN 中添加加速域名，源站选择当前 OSS Bucket，再按 CDN 提示配置 CNAME。

域名说明

系统【EndPoint（地域节点）】仍填写 OSS Endpoint，用于系统上传文件和调用 OSS。

自定义域名或 CDN 域名用于浏览器访问图片。如果系统有单独的【访问域名】、【图片域名】或【文件域名】字段，填写自定义 HTTPS 域名，例如 https://img.example.com。

如果系统没有单独的访问域名字段，上传后的图片地址通常仍会使用系统【EndPoint】生成；这种情况下要使用自定义域名，需要确认系统是否支持单独配置文件访问域名。

如果后期才把 http 改成 https，历史图片地址不会自动变化，需要重新上传或批量替换历史地址。

平台存储配置​

进入【平台】-【设置】-【系统参数】-【存储方案】，找到【阿里云 OSS】并点击【修改】。

系统字段填写说明
Bucket名称（或储存空间）参考【重点 1】，填写上面创建的 Bucket 名称，例如 shoptnt。
EndPoint（地域节点）参考【重点 2】，填写 OSS Endpoint，例如 https://oss-cn-guangzhou.aliyuncs.com。
二级路径文件目录前缀，例如 shop/、goods/，不需要时可留空。
密钥id参考【重点 3】，填写 RAM 用户的 AccessKey ID，用于调用 STS。
密钥参考【重点 3】，填写 RAM 用户的 AccessKey Secret，用于调用 STS。
Ram角色Arn参考【重点 4】，填写 RAM 角色详情页中的 ARN，例如 acs:ram::1672608113458803:role/oss-images。
StsEndPoint（地域节点）参考【重点 5】，按 Bucket 所在地域替换 RegionId，例如广州填写 https://sts.cn-guangzhou.aliyuncs.com。

保存后点击【开启】，上传一张图片测试。

验证与常见问题​

现象优先检查
获取 STS Token 报 AssumeRole 403RAM 用户是否授权【AliyunSTSAssumeRoleAccess】，RAM 角色 ARN 是否填写正确。
上传时报 XHR error (req "error")Bucket 跨域 CORS 是否允许当前域名、POST、PUT 和请求头。
上传成功但图片打不开Bucket 是否公共读，图片 URL 是否使用公网或自定义 HTTPS 域名。
缩略图打不开OSS 图片样式是否导入成功，自定义分隔符是否选择 _。

四、常见注意事项​

  1. 同一时间只开启一个存储方案。
  2. 修改存储方案只影响新上传的文件，历史文件地址不会自动迁移。
  3. 小程序只支持 HTTPS 文件地址，存储访问地址必须配置 HTTPS。
  4. 视频文件较大时，建议确认网关、Nginx 和对象存储的上传大小限制均不小于系统允许值。
  5. 上传后复制图片地址到浏览器打开，是最快的连通性验证方式。