Frame.io 的 Storage Connect：注册资产

Storage Connect 功能允许 Frame.io 企业客户使用自有的云存储端点作为 Frame.io 的备份存储。如今，当用户将资产上传到 Frame.io 时，该资产会流经应用程序堆栈并存储在 Frame.io 的 Amazon S3 存储桶中。类似地，资源的播放和传递也是通过 Frame.io 管理的 Amazon S3 存储桶提供服务的。

使用您自己的 AWS S3 作为数据源，同时将 Frame.io 作为浏览、搜索、共享和审阅的统一界面。您现在可以连接：

一个主 S3 存储桶（读/写）——用于存储来自 Frame.io 的新上传文件。
任意数量的附加 S3 存储桶（只读‑权限）——使 S3 中的现有媒体可在 Frame.io 中查看和播放，无需复制或重复原始文件。

Frame.io 会生成轻量级代理文件（缩略图、预览文件、播放文件），而原始文件始终保留在您的 S3 中。要注册已存在于连接存储桶中的文件，请使用 V4 公共 API：导入文件端点。

注：此服务适用于使用 Storage Connect 的 Frame.io 新客户和现有客户。为了支持现有客户，Frame.io 提供一次性迁移功能，可将过去存储在 Frame.io 管理的 Amazon S3 存储桶中的现有客户数据迁移到客户管理的 Amazon S3 存储桶中，以便广泛使用。

以下信息旨在为净新增和现有的 Frame.io 客户提供分步指南，帮助配置他们的 S3 存储桶以与 Storage Connect 兼容。

先决条件

需持有 Frame.io 企业版帐户，并已为您的组织启用 Storage Connect 功能。
需具备创建/更新 AWS IAM 角色/策略以及配置 S3 存储桶权限的权限。
需拥有 Frame.io V4 公共 API 访问权限（用于调用导入文件端点，该端点用于从只读‑存储桶注册现有对象）。

注意：关于具体的 IAM 信任配置与帐户映射，您的 Frame.io 联系人（CSM/实施专家）将提供最新的 OIDC/角色设置，并在上架过程中验证权限。

关键概念

主（读/写）存储桶：当用户向 Frame.io 上传文件时，用于接收原始文件的 S3 存储桶。Frame.io 在此处需要读取+写入权限。
仅读取‑存储桶：一个或多个 S3 存储桶，Frame 可以读取，但不能写入。通过调用导入文件 API 使资产在 Frame.io 中可见（无需复制原始文件）。
代理文件：Frame.io 会生成衍生文件（缩略图、预览文件和流媒体代理文件），即使原始文件保留在您的 S3 中，资产仍可在 Frame.io 中播放。

第一部分——配置主读写 S3 存储桶

选择或创建将用作主要存储的 S3 存储桶。

为 Frame.io 创建 IAM 角色（由 Frame.io 身份提供商信任），并附加授予存储桶/前缀读写权限的 IAM 策略。

策略示例框架（请替换 ARN 并尽可能限制为必要的前缀）：

{ 
  "Version": "2012-10-17", 
  "Statement": [ 
    { 
      "Sid": "ListPrimaryBucket", 
      "Effect": "Allow", 
      "Action": ["s3:ListBucket"], 
      "Resource": "arn:aws:s3:::YOUR_PRIMARY_BUCKET" 
    }, 
    { 
      "Sid": "RWPrimaryObjects", 
      "Effect": "Allow", 
      "Action": [ 
        "s3:GetObject", 
        "s3:PutObject", 
        "s3:DeleteObject", 
        "s3:AbortMultipartUpload", 
        "s3:ListMultipartUploadParts" 
      ], 
      "Resource": "arn:aws:s3:::YOUR_PRIMARY_BUCKET/*" 
    } 
  ] 
}

向 Frame.io 提供详细信息：IAM 角色 ARN、存储桶名称以及任何首选对象前缀。Frame.io 将完成映射配置，使您的用户在 Frame 中的上传文件指向该存储桶。
通过在 Frame 中执行测试上传来验证，以确认原始文件已上传到您的 S3 并且代理文件出现在 Frame 中。

第二部分——添加一个或多个‑只读 S3 存储桶

您可以将其他 S3 存储桶关联为只读‑源。Frame.io 将读取对象以生成代理文件并支持播放，但不会向这些存储桶写入新对象。

选择要在 Frame 中公开的其他 S3 存储桶（以及可选的文件夹前缀）。
创建（或更新）供 Frame.io 使用的 IAM 角色，授予对每个存储桶/前缀的只读‑访问权限。

每个存储桶的策略示例框架（请调整 ARN/前缀并为每个存储桶添加）：

{  
  "Version": "2012-10-17",  
  "Statement": [  
    {  
      "Sid": "ListReadOnlyBucket",  
      "Effect": "Allow",  
      "Action": ["s3:ListBucket"],  
      "Resource": "arn:aws:s3:::YOUR_RO_BUCKET"  
    },  
    {  
      "Sid": "ReadObjects",  
      "Effect": "Allow",  
      "Action": ["s3:GetObject", "s3:GetObjectVersion"],  
      "Resource": "arn:aws:s3:::YOUR_RO_BUCKET/*"  
    }  
  ]  
}

向 Frame.io 提供详细信息：相同的角色 ARN（或每个存储桶使用不同 ARN）、每个存储桶名称及应作为只读‑内容暴露的可选前缀。
请继续使用导入文件 API（如下所述）从这些只读‑存储桶中注册现有文件。

第三部分——在 Frame 中注册现有 S3 对象（导入 API）

添加只‑读存储桶时，您的媒体文件已经存在于 S3 中。使用导入文件端点将这些 S3 对象注册到您的 Frame 项目/文件夹中，无需复制原始文件。

导入功能的作用

在 Frame 中创建一个指向您 S3 对象的文件资产。
触发 Frame 生成用于浏览/播放的代理文件。
将原始文件保留在您的 S3 中。

在调用 API 之前

确保存储连接映射已完成（Frame.io 已获取您的角色 ARN、存储桶和前缀信息）。
获取具有所需文件范围的 OAuth 令牌。
确定 Frame 中的目标容器（项目根目录或文件夹资产 ID），导入的文件将出现在此位置。
确定要导入的 S3 存储桶和对象键。

示例（cURL 伪代码）

请参考官方 API 文档获取确切的路径和字段信息。以下结构展示了核心流程。

# 伪代码——具体 URL 和架构请查阅“导入文件”端点文档

curl -X POST "https://api.frame.io/v4/files.import_file" \ 
  -H "Authorization: Bearer $TOKEN" \ 
  -H "Content-Type: application/json" \ 
  -d '{ 
    "container_id": "<FRAME_FOLDER_OR_PROJECT_ASSET_ID>", 
    "external": { 
      "provider": "s3", 
      "bucket": "my-readonly-bucket", 
      "key": "Marketing/2025/hero.mov" 
    }, 
    "display_name": "hero.mov" 
  }'

在 Frame 内进行验证

打开目标项目/文件夹——导入的文件将像其他资产一样显示。
一旦代理文件生成完成，即可立即进行播放。
检查资产详情以确认存储位置是否为您的 S3。

行为与注意事项

上传至任意 Frame 客户端（web、iOS 端、传输应用等）的文件，将存入主读写存储桶。
从只读‑存储桶导入的资产将保留在原位；在 Frame 中删除资产不会删除只读‑存储桶中的原始文件。（请遵循贵组织对读写存储桶的删除策略。）
生命周期/归档：若对象转移至 Glacier 或暂时不可用，已生成的代理文件可能仍支持浏览；原始文件的可访问性将取决于 S3 存储层级与可用性状态。

故障排除

导入/播放时出现 403/访问被拒绝→请确认 IAM 策略包含该对象 ARN 的 s3:GetObject 权限。
未发现对象→请确认存储桶/前缀映射与您要导入的对象键匹配。
代理文件未生成→请确认文件类型受支持且 IAM 允许读取权限；检查是否存在临时性 S3 错误。
批量导入时触发速率限制→请采用指数退避重试机制；控制并发频率。

常见问题解答

问：我可以添加多少个只‑读存储桶？

答：数量无限制。您可以为每个存储桶（及可选前缀）配置只读‑权限映射。

问：我需要将现有媒体库移动或复制到 Frame 中吗？

答：不需要。使用导入文件 API 即可直接注册现有文件。

问：我之后可以移除存储桶吗？

答：可以。移除只读‑存储桶会使这些资产在 Frame 中取消发布（您的原始文件仍保留在 S3 中）。

问：Frame 会向我的只‑读存储桶写入数据吗？

答：不会。Frame 仅读取对象以生成代理文件并在需要时流式传输原始文件；写入操作仅发生在主读/写存储桶中。