S3 access and third-party tools

Connection settings

Go to Object storage VOS → S3 access. Copy the current Endpoint and create a key authorized for the target bucket. The Secret is shown only at creation; store it in trusted server or tool credentials.

example-bucket below represents the bucket connection identifier from the console. A unique bucket name within the key's scope also works. Do not use a display domain as Bucket.

AWS CLI: upload and download a file

Use AWS CLI v2. Configure credentials in your terminal first and replace the example Endpoint and Bucket with real values. The high-level s3 cp command uses multipart upload according to its configuration.

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

Example domains and paths are illustrative. Replace them with real resources you are authorized to use.

Create hello.txt locally before uploading. Compare both files after downloading; upload progress alone does not prove successful integration.

rclone: use S3-compatible storage

Create a remote with rclone config, choose s3 and set provider to Other. Store credentials in the tool's private configuration. The placeholders below are not usable keys.

[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

Example domains and paths are illustrative. Replace them with real resources you are authorized to use.

List files using rclone lsf vos:example-bucket. Create the bucket in the console first; no_check_bucket prevents the tool from trying to create an unauthorized bucket.

JavaScript: generate a temporary download URL on the server

Install @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner. Supply credentials through server environment variables; never bundle the Secret into browser code. This example generates a GET URL valid for 15 minutes, as set by 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 返回给需要下载的访问者，保持完整地址。

Example domains and paths are illustrative. Replace them with real resources you are authorized to use.

Automatic CORS setup by third-party apps

GetBucketCors, PutBucketCors and DeleteBucketCors are supported. Apps such as Cloudreve call these standard APIs for automatic CORS setup. The key needs the corresponding write access to the bucket, and its policy must allow the operation.

After setup, view the rules in the bucket's CORS settings. CORS controls browser cross-origin requests; it does not make private files public or replace signature authorization. The example allows https://app.example.com; replace it with your own frontend origin.

{
  "CORSRules": [{
    "AllowedOrigins": ["https://app.example.com"],
    "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag", "Content-Length", "Content-Range"],
    "MaxAgeSeconds": 3600
  }]
}

Example domains and paths are illustrative. Replace them with real resources you are authorized to use.

Write and read CORS rules manually

Save the JSON above as cors.json, then run the commands below. PutBucketCors replaces all CORS rules for the bucket, so read and merge existing rules first.

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

Example domains and paths are illustrative. Replace them with real resources you are authorized to use.

Private downloads and acceleration domains

Private-bucket downloads require valid credentials or a presigned URL. Preserve all X-Amz-* and response-content-* parameters. Do not decode and rebuild filenames or append parameters to signed URLs.

Host is part of Signature V4. Third-party apps must generate download links using a VOS-supported acceleration-domain configuration. Do not assume replacing any presigned URL's host will work. Test the S3 Endpoint download first, then the configured acceleration entry.

Uploads use PUT and downloads use GET. Do not test a GET-signed URL with HEAD. Generate a new URL after expiry; changing time parameters cannot extend it.

Common operations and upload limits

These are current API hard limits; administrators may configure lower limits. Use the values shown in the console. 1 MiB = 1,048,576 bytes; 1 GiB = 1,073,741,824 bytes.

This describes common VOS compatibility, not full support for every advanced AWS S3 feature. Storage capacity and access costs follow their respective services' billing rules.

Troubleshoot by error code