User Guide
Storage Service Configuration
Configure file storage service
TinyShip supports multiple object storage services for file upload and management.
Related Pages
| Page | Path | Description |
|---|---|---|
| Upload Demo | /upload | File upload demo page |
Supported Storage Services
| Service | Advantage | Recommended Use |
|---|---|---|
| Aliyun OSS | Fast in China, Alibaba ecosystem | Apps targeting Chinese users |
| AWS S3 | Global coverage, mature ecosystem | Apps targeting international users |
| Cloudflare R2 | No egress fees, cost-effective | Cost-sensitive applications |
| Tencent COS | China cloud storage, solid ecosystem | Apps targeting Chinese users |
All providers support:
- ✅ Upload/download
- ✅ Signed URL generation
- ✅ File deletion
- ✅ File existence check
- ✅ Metadata retrieval
- ✅ Directory listing
Configure in config/storage.ts
// config/storage.ts
export const storageConfig = {
defaultProvider: 'oss' as const, // 'oss' | 's3' | 'r2' | 'cos'
oss: {
region: 'oss-cn-shanghai',
accessKeyId: '...',
accessKeySecret: '...',
bucket: 'your-bucket',
endpoint: '',
defaultExpiration: 60
},
s3: {
region: 'us-east-1',
accessKeyId: '...',
accessKeySecret: '...',
bucket: 'your-bucket',
endpoint: '',
forcePathStyle: false,
defaultExpiration: 3600
},
r2: {
accountId: '...',
accessKeyId: '...',
accessKeySecret: '...',
bucket: 'your-bucket',
defaultExpiration: 3600
},
cos: {
region: 'ap-guangzhou',
secretId: '...',
secretKey: '...',
bucket: 'your-bucket-appid',
defaultExpiration: 3600
}
}Option Notes:
defaultProvider: Default storage providerdefaultExpiration: Default signed URL expiration (seconds)forcePathStyle: Some S3-compatible services requiretrue
Environment Variables
Add provider configurations in .env:
# Default storage provider
STORAGE_PROVIDER=oss # options: oss, s3, r2, cos
# Aliyun OSS
OSS_REGION=oss-cn-shanghai
OSS_ACCESS_KEY_ID=your_access_key_id
OSS_ACCESS_KEY_SECRET=your_access_key_secret
OSS_BUCKET=your-bucket-name
# AWS S3
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your_access_key_id
S3_ACCESS_KEY_SECRET=your_secret_access_key
S3_BUCKET=your-bucket-name
# Cloudflare R2
R2_ACCOUNT_ID=your_cloudflare_account_id
R2_ACCESS_KEY_ID=your_r2_access_key_id
R2_ACCESS_KEY_SECRET=your_r2_access_key_secret
R2_BUCKET=your-bucket-name
# Tencent COS
COS_REGION=ap-guangzhou
COS_SECRET_ID=your_secret_id
COS_SECRET_KEY=your_secret_key
COS_BUCKET=your-bucket-name-appidNote: OSS can reuse ALIYUN_ACCESS_KEY_ID and ALIYUN_ACCESS_KEY_SECRET. If OSS-specific keys are not set, it will fall back to the Aliyun generic keys.
Usage
Basic Usage
import { storage } from '@libs/storage';
const result = await storage.uploadFile({
file: fileBuffer,
fileName: 'document.pdf',
contentType: 'application/pdf',
folder: 'uploads/2024'
});
const { url } = await storage.generateSignedUrl({
key: result.key,
expiresIn: 3600
});Specify Provider
import { createStorageProvider } from '@libs/storage';
const s3Storage = createStorageProvider('s3');
const ossStorage = createStorageProvider('oss');
const r2Storage = createStorageProvider('r2');
const cosStorage = createStorageProvider('cos');
await s3Storage.uploadFile({
file: buffer,
fileName: 'file.zip'
});For more API details and examples, see: libs/storage/README.md