---
title: Aliyun OSS
description: Configure Aliyun Object Storage Service (OSS) for China-mainland friendly deployments.
createdAt: 2025-11-24T10:05:00+08:00
lastModified: 2025-11-24T22:26:48+08:00
order: 37
---

# Aliyun OSS Storage

Aliyun OSS is ideal when you need data residency in mainland China or want to leverage Alibaba Cloud's backbone network. The new `provider: 'oss'` option in Afilmory automatically sets sane defaults for endpoints and SigV4 signing so you only fill in the essentials.

## Configuration

```typescript
import { defineBuilderConfig } from '@afilmory/builder'

export default defineBuilderConfig(() => ({
  storage: {
    provider: 'oss',
    bucket: process.env.OSS_BUCKET!,
    region: process.env.OSS_REGION || 'oss-cn-hangzhou',
    accessKeyId: process.env.OSS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.OSS_ACCESS_KEY_SECRET!,
    endpoint: process.env.OSS_ENDPOINT, // optional, defaults to bucket.region.aliyuncs.com
    prefix: process.env.OSS_PREFIX || 'photos/',
    customDomain: process.env.OSS_CUSTOM_DOMAIN, // optional CDN or acceleration domain
  },
}))
```

## Environment Variables

```bash
# Required
OSS_BUCKET=my-gallery-assets
OSS_REGION=oss-cn-hangzhou
OSS_ACCESS_KEY_ID=xxxxxxxx
OSS_ACCESS_KEY_SECRET=yyyyyyyy

# Optional
OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
OSS_PREFIX=photos/
OSS_CUSTOM_DOMAIN=https://img.example.cn
```

## Notes on Endpoints

- If you omit `endpoint`, the provider emits `https://<bucket>.<region>.aliyuncs.com`.
- You can point `endpoint` to an internal VPC domain or acceleration endpoint; public URLs still honor `customDomain` when provided.
- The SigV4 service defaults to `oss`. Override `sigV4Service` only when using custom gateways that expect a different service name.

## Best Practices

- **Use ICP-ready domains**: set `customDomain` to an OSS-bound domain that has completed ICP filing for production in mainland China.
- **Prefix per tenant**: combine `prefix` with tenant IDs or years to simplify lifecycle policies.
- **Network paths**: pair `endpoint` with the closest region (e.g., `oss-cn-shanghai-internal.aliyuncs.com`) when running builder inside Alibaba Cloud to avoid public egress.

## Troubleshooting

- _Signature mismatch_: verify your AccessKey pair and ensure system clock drift is under 5 minutes.
- _403 Forbidden after upload_: confirm the RAM policy allows `oss:PutObject` / `oss:GetObject` for the bucket prefix.
- _Slow downloads outside China_: front OSS with a CDN and set `customDomain` so generated URLs route through the CDN.
