对象存储 VOS
S3 接入与第三方工具配置
连接参数、AWS CLI / rclone / SDK 示例、自动跨域配置和私有下载排障。
连接参数
进入「对象存储 VOS → S3 接入」,复制当前 Endpoint,创建授权到目标桶的访问密钥。Secret 仅创建时显示,请在可信的服务端或工具凭据配置中保存。
下面的 example-bucket 表示控制台提供的桶连接标识。也可使用密钥授权范围内唯一的桶名称;不要使用展示域名代替 Bucket。
| 参数 | 填写内容 | 说明 |
|---|---|---|
| Endpoint | 从控制台复制完整 HTTPS 地址 | 不要追加桶名、文件路径或 ? 参数 |
| Region | us-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 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。凭据填写到工具的私有配置中,以下占位符不能直接作为密钥使用。
[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 指定。
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 访问,请替换为自己的前端来源。
{
"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 与下载域名的连通性、证书和回源状态;这类错误不等同于密钥错误 |