屿声

简体中文

English

简体中文

English

阿里云 OSS 云同步配置 ​

屿声支持通过 S3 协议把加密后的数据同步到你自己的对象存储。本指南介绍如何创建阿里云 OSS Bucket、配置访问权限，并在屿声中完成连接。

本页以华北 2（北京）地域为例。请根据你的 Bucket 所在地域替换 Endpoint 和 Region。

妥善保管 AccessKey

请为屿声单独创建 RAM 用户和 AccessKey，不要使用阿里云账号（主账号）的 AccessKey。AccessKey Secret 只在创建时显示一次，请勿通过截图、公开文档或聊天记录分享。

准备工作 ​

开始前，你需要：

  • 注册并登录阿里云
  • 完成实名认证并开通对象存储 OSS
  • 准备一个用于屿声同步的 Bucket；如果已有合适的私有 Bucket，可以直接使用

第一步：创建 Bucket ​

进入对象存储 OSS 控制台，在「Bucket 列表」中点击「创建 Bucket」。

建议使用以下设置：

项目建议设置
Bucket 名称使用独立且容易识别的名称，例如 my-islet-backup
地域选择距离你较近的地域；创建后不能更改
存储类型标准存储
读写权限私有
阻止公共访问开启

创建后，记下 Bucket 名称和地域代码。地域代码会用于填写屿声中的 Region，例如华北 2（北京）对应 oss-cn-beijing。

中国大陆地域的公网 Endpoint 限制

阿里云说明，自 2025 年 3 月 20 日起，新开通 OSS 的用户通过默认公网 Endpoint 访问中国大陆地域 Bucket 的数据接口时可能受到限制。如果你的账号受该政策影响，可以改用中国大陆以外的地域，例如新加坡；详情请查看阿里云的 OSS 控制台快速入门文档。

第二步：配置跨域规则 ​

屿声需要从浏览器或 Chrome 扩展直接访问 OSS，因此必须为 Bucket 配置跨域资源共享（CORS）。

  1. 进入刚创建的 Bucket。
  2. 在菜单中选择「数据安全」→「跨域设置」。
  3. 点击「创建规则」。
  4. 按下表填写并保存。
项目填写内容
来源*
允许 MethodsGET、POST、PUT、DELETE、HEAD
允许 Headers*
暴露 HeadersETag、x-oss-request-id，每行一个
缓存时间（秒）0
返回 Vary: Origin开启

「允许 Headers」需要填写 *。屿声使用 S3 协议，请求中会包含 authorization、x-amz-* 和 amz-sdk-* 等请求头；只允许 x-oss-* 会导致连接测试失败。

「暴露 Headers」决定屿声可以读取哪些 OSS 响应头。ETag 用于识别上传结果，x-oss-request-id 可用于排查请求错误。它不会改变 Bucket 的读写权限。

CORS 不会公开 Bucket

来源设为 * 只允许不同来源的客户端发起跨域请求。Bucket 仍然保持私有，请求必须通过 AccessKey 签名才能读取或写入数据。

这里使用 * 是为了兼容浏览器、Chrome 扩展和不同设备。如果只从固定网页访问 OSS，可以把来源改为该网页的完整 Origin。

跨域规则可能需要最多 15 分钟生效。保存后如果列表没有立即更新，请稍后刷新页面。

第三步：创建 RAM 用户和权限 ​

不要给屿声使用主账号 AccessKey。建议创建一个独立的 RAM 用户，并且只允许它读写指定 Bucket 中的同步目录。

  1. 进入访问控制 RAM 控制台。
  2. 选择「身份管理」→「用户」，创建一个用于屿声同步的 RAM 用户。
  3. 创建一条自定义权限策略，把下面的 YOUR_BUCKET 和 YOUR_PREFIX 替换为实际值。
json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject",
        "oss:PutObject"
      ],
      "Resource": "acs:oss:*:*:YOUR_BUCKET/YOUR_PREFIX/*"
    }
  ]
}

例如，Bucket 是 my-islet-backup，屿声中的 Prefix 使用 chat-diary，Resource 应填写：

text
acs:oss:*:*:my-islet-backup/chat-diary/*
  1. 把这条权限策略授权给刚创建的 RAM 用户。
  2. 打开该用户的「认证管理」页面，创建 AccessKey。
  3. 保存 AccessKey ID 和 AccessKey Secret。AccessKey Secret 关闭创建窗口后无法再次查看。

如果不需要限制同步目录，也可以把 Resource 写成 acs:oss:*:*:YOUR_BUCKET/*，允许该 RAM 用户读写整个 Bucket。

第四步：在屿声中填写配置 ​

在屿声的云同步设置中选择「S3」，填写以下内容：

屿声字段填写方式华北 2（北京）示例
EndpointBucket 所在地域的公网 Endpoint，不要包含 Bucket 名称https://oss-cn-beijing.aliyuncs.com
RegionBucket 的地域代码oss-cn-beijing
Bucket第一步创建的 Bucket 名称my-islet-backup
Access Key IDRAM 用户的 AccessKey ID—
Secret Access KeyRAM 用户的 AccessKey Secret—
Prefix同步文件在 Bucket 中的目录前缀chat-diary
强制路径样式关闭—

阿里云 OSS 的 S3 兼容接口使用虚拟主机样式，请务必关闭「强制路径样式」。填写完成后点击「下一步」，屿声会写入并读取一个健康检查文件，以确认配置可用。

常见问题 ​

提示 CORS 或 Failed to fetch ​

确认跨域规则已经生效，并重点检查：

  • 来源和允许 Headers 都是 *
  • 允许 Methods 包含 GET、PUT 和 HEAD
  • 没有其他冲突的跨域规则

修改规则后，等待几分钟，重新打开屿声再测试。

提示 AccessDenied ​

AccessKey 对应的 RAM 用户没有足够权限，或者权限策略中的 Bucket、Prefix 与屿声配置不一致。检查自定义策略中的 Resource，并确认策略已经授权给正确的 RAM 用户。

提示 SignatureDoesNotMatch ​

检查以下内容：

  • Endpoint 和 Region 是否属于同一个地域
  • AccessKey ID 和 AccessKey Secret 是否完整，前后是否包含空格
  • 「强制路径样式」是否已经关闭

修改跨域规则后仍然失败 ​

阿里云提示跨域规则可能需要最多 15 分钟生效。等待后重新测试；如果仍然失败，可以在浏览器开发者工具的「网络」面板中查看 OPTIONS 和 PUT 请求的状态码。

相关文档 ​