素材库自定义阿里云OSS教程

素材库默认使用平台对象存储，每个用户有 100 MB 配额。当配额不够用、或希望素材落在自己的云账号下时，可以配置自有阿里云 OSS：配置生效后，你在素材库上传的所有素材都会直接存进你的 OSS，不占用平台配额。

当前仅支持阿里云 OSS，暂不支持其他对象存储。

配置分两步：先在阿里云侧把 OSS 准备好（约 5 分钟），再到魔芋AI 素材库页面填写参数。

一、在阿里云侧准备 OSS

1.1 开通 OSS 服务

登录阿里云控制台。

搜索并进入 对象存储 OSS 控制台。

首次使用需按提示开通服务（开通本身免费，按实际存储量和流量计费）。

1.2 创建 Bucket

在 OSS 控制台点击 Bucket 列表 → 创建 Bucket，关键项：

配置项	建议值
Bucket 名称	全局唯一，例如 `my-moyu-material`。请记下这个名字，稍后要填
地域	选择离你用户最近的地域，例如 `华东1（杭州）`
读写权限	公共读（详见下方说明）
存储类型	标准存储
版本控制	关闭

设置Bucket权限为公共读，如下图所示：

⚠️ 读写权限必须设为「公共读」。平台上传素材后返回的是 https://{bucket}.{endpoint}/{路径} 这样的直链，不带签名。如果 Bucket 是私有读写，素材列表里的图片/视频预览会全部 403 无法显示。

1.3 创建 RAM 子账号并授权

进入 访问控制 RAM 控制台 → 身份管理 → 用户 → 创建用户。

登录名称随意，例如 moyu-material-uploader。

访问方式勾选「OpenAPI 调用访问」（不要勾选控制台登录），创建后会得到一对密钥：

AccessKey ID

AccessKey Secret

⚠️ AccessKey Secret 只在创建成功时显示一次，请立即复制保存，关闭页面后无法再次查看。

回到用户列表，点击刚创建的用户 → 权限管理 → 新增授权，授予 OSS 权限。

1.4 确定 Endpoint

在 OSS 控制台点击进入 Bucket → 概览，页面下方的「访问端口」区域可以看到 Endpoint，形如：

oss-cn-hangzhou.aliyuncs.com

注意：填不带 Bucket 名的公网 Endpoint。平台会自动拼成 {Bucket}.{Endpoint}，如果这里多写了 Bucket 名会导致访问地址错误。

1.5 确认参数清单

准备工作完成后，你手上应该有以下 5 个值：

参数	示例	从哪来
AccessKeyId	`LTAI5tXXXXXXXXXXXXXX`	1.3 创建 RAM 用户时获得
AccessKeySecret	`XXXXXXXXXXXXXXXXXXXXXX`	1.3 创建 RAM 用户时获得
Bucket	`my-moyu-material`	1.2 创建 Bucket 时设定
Endpoint	`oss-cn-hangzhou.aliyuncs.com`	1.4 从 Bucket 概览页获取
路径前缀	`material`	自定义，见下方说明

二、在魔芋AI 配置

2.1 打开配置弹窗

登录魔芋AI，进入左侧菜单的 素材管理 页面。

在页面右上角，点击 「自定义对象存储」 按钮，弹出「自定义对象存储（阿里云 OSS）」配置窗口。

2.2 填写配置项

依次填写：

表单项	填写内容	必填
启用自有 OSS	打开开关	是
AccessKeyId	1.5 中的 AccessKeyId	是
AccessKeySecret	1.5 中的 AccessKeySecret	是
Bucket	1.5 中的 Bucket 名（只填 Bucket 名，不要带域名）	是
Endpoint	1.5 中的 Endpoint，如 `oss-cn-hangzhou.aliyuncs.com`	是
路径前缀	素材在 Bucket 中的目录前缀，默认 `material`	否

填完后点击确定保存。

2.3 验证配置是否生效

回到素材库页面，新建一个分组后上传一个文件：

上传成功后，打开该素材的详情，URL 应该是一个形如 https://{你的Bucket}.{你的Endpoint}/material/... 的地址；

到阿里云 OSS 控制台，进入对应 Bucket → 文件管理，在 {路径前缀}/{用户ID}/ 目录下能看到刚上传的文件；

素材库页面上方的配额用量不再增长（自有 OSS 的素材不计入平台配额）。

以上三点都符合，说明配置已生效。

素材在 OSS 中的存放路径

{Bucket}/{路径前缀}/{用户ID}/{随机ID}{扩展名}

例如路径前缀为 material、用户 ID 为 10 时，上传的图片会落在：

my-moyu-material/material/10/3f2b1c9e-....jpg

同目录下不会混入其他用户或平台的素材，便于你按目录统计用量或单独设置生命周期规则。

四、注意事项

计费

配置自有 OSS 后，素材的存储费用和公网访问流量费用由你的阿里云账号承担，不再由平台承担。平台侧也不再把这部分素材计入 100 MB 配额。

如果素材量较大，建议在 Bucket 上配置生命周期规则（例如转低频访问存储、自动清理过期对象），以控制成本。

删除素材时的行为

在素材库中删除素材或分组时，平台会同步删除你 OSS 上对应的对象。

五、常见问题

配置保存了，但上传的素材还是走平台 OSS

排查顺序：

开关是否打开：「启用自有 OSS」必须处于打开状态。

必填项是否齐全：AccessKeyId / AccessKeySecret / Bucket / Endpoint 四项任何一个为空，平台都会静默回落到平台 OSS，不会给出任何错误提示。请逐个确认，尤其是 AccessKeySecret 是否保存成功。

重新打开配置弹窗，确认各字段值已经正确回填。

上传时报错，提示 OSS 相关失败

报错现象	可能原因
提示创建 OSS client / bucket 失败	Endpoint 填写有误（多填了 Bucket 名、写了内网 Endpoint、或地域不匹配）
提示上传到用户 OSS 失败	RAM 权限不足（缺少 `oss:PutObject`）、Bucket 名写错，或 Key 已失效/被禁用
提示用户 OSS 配置不完整	启用开关打开了但必填字段有缺失
HTTP 403 / SignatureDoesNotMatch	AccessKeyId 与 AccessKeySecret 不匹配，或复制时带了多余空格

素材列表里的图片显示不出来 / 返回 403

Bucket 的读写权限不是「公共读」。到 OSS 控制台把 Bucket 读写权限改为公共读即可。

关闭「启用自有 OSS」后，之前存在自己 OSS 上的素材怎么办

已经上传的素材不受影响：数据库里仍然记录着它们的 OSS 地址，素材列表可以正常查看和使用。

但如上文「删除素材时的行为」所述，关闭开关后平台无法再删除这些历史对象，需要你自行到 OSS 控制台清理。因此更推荐的做法是：保留配置、只把开关关掉（配置项留存在账号里），这样后续需要手动清理时还能重新打开开关借助平台能力处理。

附：配置项与接口字段对应关系

如果你想通过接口批量配置，或需要排查数据问题，可参考下表。配置保存在用户设置的 setting 字段中。

界面表单项	接口字段	存储字段名
启用自有 OSS	`enabled`	`material_oss_enabled`
AccessKeyId	`access_id`	`material_oss_access_id`
AccessKeySecret	`access_key`	`material_oss_access_key`
Bucket	`bucket`	`material_oss_bucket`
Endpoint	`endpoint`	`material_oss_endpoint`
路径前缀	`path_prefix`	`material_oss_path_prefix`

注意：该配置接口需要登录态（浏览器会话），无法用 sk-xxxx API 令牌直接调用。

素材库自定义阿里云OSS教程

一、在阿里云侧准备 OSS#

1.1 开通 OSS 服务#

1.2 创建 Bucket#

1.3 创建 RAM 子账号并授权#

1.4 确定 Endpoint#

1.5 确认参数清单#

二、在魔芋AI 配置#

2.1 打开配置弹窗#

2.2 填写配置项#

2.3 验证配置是否生效#

素材在 OSS 中的存放路径#

四、注意事项#

计费#

删除素材时的行为#

五、常见问题#

配置保存了，但上传的素材还是走平台 OSS#

上传时报错，提示 OSS 相关失败#

素材列表里的图片显示不出来 / 返回 403#

关闭「启用自有 OSS」后，之前存在自己 OSS 上的素材怎么办#

附：配置项与接口字段对应关系#