Complete Custom S3 Setup (Mainland China)
Custom S3 is used for wide-area file transfer. The web app uploads files directly from the browser to presigned URLs issued by the backend, so in addition to Endpoint, credentials, and bucket permissions, the bucket CORS configuration must be correct.
When to use S3
- Two devices are not on the same LAN.
- Files are large and need stable wide-area relay.
- You want file contents stored in your own object storage service.
- LAN direct transfer, WebRTC, or HTTP direct transfer is unavailable.
Settings fields
| Field | Description |
|---|---|
| Endpoint | S3 API root URL including scheme, for example https://cos.ap-guangzhou.myqcloud.com. |
| Region | Bucket region. Provider naming differs, so keep it consistent with the provider console. |
| Bucket | Bucket used for relay and temporary file storage. |
| Access Key ID | Prefer a sub-account key scoped to this bucket only. |
| Secret Access Key | Submitted only when saving or testing; leave blank when editing later to keep the existing key. |
Bucket permission recommendations
Create a dedicated sub-account or access key for ShrimpSend and grant only the permissions required for the target Bucket:
- Upload objects.
- Download objects.
- Delete temporary objects.
- Multipart upload permissions, including initiate multipart upload, upload parts, list parts, complete multipart upload, and abort multipart upload.
Do not use root account credentials, and do not grant management permissions for unrelated buckets.
CORS is required
The browser sends cross-origin requests to the object storage domain. Bucket CORS must allow the Origin where users open the ShrimpSend web app.
Origin means the following part of the browser address:
Examples:
https://xiachuan.net
Do not include a path, and do not add a trailing /. If users access the web app through multiple domains, add each Origin separately.
CORS rule reference
| Item | Recommended value |
|---|---|
| AllowedOrigins | The actual ShrimpSend web Origin. |
| AllowedMethods | Include at least GET, PUT, POST, DELETE, HEAD. |
| AllowedHeaders | Prefer *, or include at least content-type, content-md5, x-amz-*, x-amz-date, authorization. |
| ExposeHeaders | Include at least ETag. |
| MaxAgeSeconds | 86400 is reasonable to reduce preflight requests. |
Common providers
Tencent Cloud COS
Add a rule under the bucket's Security Management or Cross-Origin Resource Sharing (CORS) settings. Endpoint usually looks like:
https://cos.{region}.myqcloud.com
Alibaba Cloud OSS
Add a rule under the bucket's Permission Management or CORS settings. Use the public or internal Endpoint shown in the provider console.
AWS S3
Configure Cross-origin resource sharing under Bucket Permissions. Endpoint usually uses the regional virtual-hosted style URL.
Cloudflare R2
Configure CORS policy in R2 Bucket Settings. Use the S3 API Endpoint shown in the console.
MinIO
Configure CORS for the bucket in MinIO Console. For intranet deployments, AllowedOrigins must include the exact address and port used by the browser to access the frontend.
Test connection
After saving the configuration, click "Test connection" immediately. If the test fails, check in order:
- Whether Endpoint includes the scheme.
- Whether Region and Bucket match the object storage console.
- Whether the key has permissions for the target bucket.
- Whether CORS includes the current web Origin.
- Whether the object storage service allows access from the public internet or the current network.
Data boundary
When you use custom S3, file contents are uploaded to the object storage service you configure. ShrimpSend's server mainly issues upload/download URLs, records necessary task metadata, and synchronizes transfer state.