跳到正文

对象存储 VOS

S3 接入与第三方工具配置

更新于 阅读约 13 分钟

连接参数、AWS CLI / rclone / SDK 示例、自动跨域配置和私有下载排障。

连接参数

进入「对象存储 VOS → S3 接入」,复制当前 Endpoint,创建授权到目标桶的访问密钥。Secret 仅创建时显示,请在可信的服务端或工具凭据配置中保存。

下面的 example-bucket 表示控制台提供的桶连接标识。也可使用密钥授权范围内唯一的桶名称;不要使用展示域名代替 Bucket。

连接参数
参数填写内容说明
Endpoint从控制台复制完整 HTTPS 地址不要追加桶名、文件路径或 ? 参数
Regionus-east-1即使工具允许留空,也建议明确填写
寻址方式Path style / 强制路径格式请求形式为 Endpoint / Bucket / Object Key
签名版本AWS Signature Version 4使用 Access Key ID 与 Secret Access Key
Bucket桶连接标识或授权范围内唯一桶名先在控制台创建桶,再为密钥选择授权桶
权限读取,或读写上传、删除与自动配置跨域需要相应写权限

AWS CLI:上传并下载一个文件

使用 AWS CLI v2。先在终端配置凭据,示例中的 Endpoint 与 Bucket 要替换为你的实际值。高层 s3 cp 命令会按配置自动进行分片上传。

终端 · AWS CLI v2
aws configure --profile signhub
aws configure set s3.addressing_style path --profile signhub
aws configure set s3.multipart_chunksize 8MB --profile signhub
aws configure set s3.max_concurrent_requests 2 --profile signhub
aws configure set request_checksum_calculation when_required --profile signhub
aws configure set response_checksum_validation when_required --profile signhub

aws --profile signhub --region us-east-1 --endpoint-url https://s3.example.com s3 ls s3://example-bucket/
aws --profile signhub --region us-east-1 --endpoint-url https://s3.example.com s3 cp ./hello.txt s3://example-bucket/hello.txt
aws --profile signhub --region us-east-1 --endpoint-url https://s3.example.com s3 cp s3://example-bucket/hello.txt ./hello-downloaded.txt

示例中的域名与路径仅用于说明,使用时替换为你有权操作的实际资源。

上传前在本地创建 hello.txt。下载完成后对比两份文件内容;不要仅根据上传进度判断接入成功。

rclone:使用 S3 兼容存储

使用 rclone config 创建 remote,选择 s3,provider 选择 Other。凭据填写到工具的私有配置中,以下占位符不能直接作为密钥使用。

rclone.conf · 配置示例
[vos]
type = s3
provider = Other
access_key_id = YOUR_ACCESS_KEY_ID
secret_access_key = YOUR_SECRET_ACCESS_KEY
region = us-east-1
endpoint = https://s3.example.com
force_path_style = true
upload_concurrency = 2
chunk_size = 8Mi
no_check_bucket = true
disable_checksum = true

示例中的域名与路径仅用于说明,使用时替换为你有权操作的实际资源。

使用 rclone lsf vos:example-bucket 列出文件。桶应预先在控制台创建,no_check_bucket 避免工具尝试创建未授权桶。

JavaScript:服务端生成临时下载地址

安装 @aws-sdk/client-s3 与 @aws-sdk/s3-request-presigner,在服务端通过环境变量注入凭据。不要将 Secret 打包进浏览器代码。此示例生成 15 分钟有效的 GET 地址;有效期由本次 expiresIn 指定。

JavaScript · AWS SDK v3
import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3'
import { getSignedUrl } from '@aws-sdk/s3-request-presigner'

const client = new S3Client({
  endpoint: process.env.VOS_ENDPOINT,
  region: 'us-east-1',
  forcePathStyle: true,
  credentials: {
    accessKeyId: process.env.VOS_ACCESS_KEY_ID,
    secretAccessKey: process.env.VOS_SECRET_ACCESS_KEY,
  },
  requestChecksumCalculation: 'WHEN_REQUIRED',
  responseChecksumValidation: 'WHEN_REQUIRED',
})

const url = await getSignedUrl(client, new GetObjectCommand({
  Bucket: 'example-bucket',
  Key: 'hello.txt',
}), { expiresIn: 900 })
// 将 url 返回给需要下载的访问者,保持完整地址。

示例中的域名与路径仅用于说明,使用时替换为你有权操作的实际资源。

第三方程序自动配置跨域

支持 GetBucketCors、PutBucketCors 与 DeleteBucketCors。Cloudreve 等程序的「自动配置跨域」会调用这些标准接口;需要对目标桶具备相应写权限的密钥,密钥策略也必须允许该操作。

配置成功后,可在控制台目标桶的跨域设置中查看规则。CORS 决定浏览器是否允许跨站请求,不会把私有文件变成公开文件,也不会替代签名鉴权。以下示例允许 https://app.example.com 访问,请替换为自己的前端来源。

cors.json · 跨域规则示例
{
  "CORSRules": [{
    "AllowedOrigins": ["https://app.example.com"],
    "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag", "Content-Length", "Content-Range"],
    "MaxAgeSeconds": 3600
  }]
}

示例中的域名与路径仅用于说明,使用时替换为你有权操作的实际资源。

手动写入和读取跨域规则

将上一段 JSON 保存为本地 cors.json,然后执行以下命令。PutBucketCors 会替换整个桶的跨域规则,已有规则应先读取并合并。

终端 · 跨域配置
aws --profile signhub --region us-east-1 --endpoint-url https://s3.example.com s3api get-bucket-cors --bucket example-bucket
aws --profile signhub --region us-east-1 --endpoint-url https://s3.example.com s3api put-bucket-cors --bucket example-bucket --cors-configuration file://cors.json
aws --profile signhub --region us-east-1 --endpoint-url https://s3.example.com s3api get-bucket-cors --bucket example-bucket

示例中的域名与路径仅用于说明,使用时替换为你有权操作的实际资源。

私有下载与加速域名

私有桶下载必须使用有效凭据或预签名 URL。原样保留 X-Amz-* 和 response-content-* 参数,不要解码后重新拼接文件名,也不要给签名地址追加参数。

Host 参与 Signature V4 计算。第三方程序应使用 VOS 支持的加速域名配置方式生成下载链接,不能默认把任意预签名 URL 的域名替换后仍可用。先验证 S3 Endpoint 下载,再验证所配置的加速下载入口。

上传使用 PUT,下载使用 GET;针对 GET 生成的签名链接不要用 HEAD 请求判断是否有效。链接过期后重新生成,不通过改时间参数延长。

常用操作与上传限制

以下为当前接口硬上限,后台可以设置更低的允许值,接入时以控制台显示值为准。1 MiB = 1,048,576 字节,1 GiB = 1,073,741,824 字节。

常用操作与上传限制
项目当前范围
单个 S3 对象最大 10 GiB;大文件使用 Multipart Upload
单次 PutObject最大 256 MiB
UploadPart 分片单片最大 64 MiB;工具建议配置为 8 MiB
浏览器控制台上传最大 20 GiB,采用分片上传;实际以控制台显示的允许值为准,与 S3 上传上限分别管理
常用文件操作列出桶/对象、读取元数据、上传、下载、删除、分片及预签名访问
桶配置支持跨域读取、写入和删除;其他高级配置以控制台对应功能为准
创建桶先在控制台创建;S3 CreateBucket 不用于创建任意未授权桶

这是 VOS 的常用兼容范围,不代表支持 AWS S3 的全部高级功能。容量占用与访问费用分别按相应服务计费。

按错误码排查

按错误码排查
现象检查顺序
SignatureDoesNotMatch核对 Region、Path style、设备时间;确认 URL 的域名、路径、查询参数和签名后保持一致
AccessDenied / 403核对密钥启用状态、目标桶、读写权限与密钥策略;私有文件还需有效签名
自动配置跨域失败查看 PutBucketCors 的具体错误;只读密钥不能写入 CORS,连接失败与权限拒绝要分别处理
NoSuchBucket / NoSuchKey核对桶连接标识、目录层级、文件名大小写和实际上传位置
EntityTooLarge / 413核对单次 PUT 与单片限制;大文件启用分片,单对象仍受总大小限制
请求过期同步设备时间并重新生成链接;使用工具生成的有效期,不自行改签名时间
TLS 重置 / 5xx分别检查 Endpoint 与下载域名的连通性、证书和回源状态;这类错误不等同于密钥错误