@nibuil/provider-upload-aliyun-oss

A custom Strapi Upload Provider for storing files in Alibaba Cloud OSS.

This package integrates with Strapi's Upload plugin and supports:

• Uploading files to OSS (stream upload path)
• Deleting files from OSS
• Private-bucket mode with signed download URLs
• Basic health check and file stream retrieval

Features

• OSS client via ali-oss
• Object path prefixing through appPath
• Private bucket support (isPrivate() returns true)
• Signed URL generation for secure file access
• Extensible OSS client options using extraParams

Requirements

• Node.js environment compatible with your Strapi project
• Strapi project with Upload plugin enabled
• Alibaba Cloud OSS bucket and credentials:
  • accessKeyId
  • accessKeySecret
  • bucket
  • region (recommended)
  • endpoint (used to build public URL string in upload result)

Installation

Install this provider in your Strapi project:

npm install @nibuil/provider-upload-aliyun-oss

or

yarn add @nibuil/provider-upload-aliyun-oss

or

pnpm add @nibuil/provider-upload-aliyun-oss

Strapi Configuration

Configure the Upload plugin in config/plugins.js (Strapi v4 style):

module.exports = ({ env }) => ({
  upload: {
    config: {
      provider: "@nibuil/provider-upload-aliyun-oss",
      providerOptions: {
        endpoint: env("OSS_ENDPOINT"), // e.g. oss-cn-hangzhou.aliyuncs.com
        region: env("OSS_REGION", "oss-cn-hangzhou"),
        bucket: env("OSS_BUCKET"),
        accessKeyId: env("OSS_ACCESS_KEY_ID"),
        accessKeySecret: env("OSS_ACCESS_KEY_SECRET"),
        appPath: env("OSS_APP_PATH", "uploads"),
        secure: true,
        extraParams: {
          // Any additional ali-oss Client options
          // cname: true,
          // timeout: "60s",
        },
      },
    },
  },
});

Then add your environment variables:

OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
OSS_REGION=oss-cn-hangzhou
OSS_BUCKET=your-bucket-name
OSS_ACCESS_KEY_ID=your-access-key-id
OSS_ACCESS_KEY_SECRET=your-access-key-secret
OSS_APP_PATH=uploads

Provider Options

The provider accepts the following options:

| Option | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | accessKeyId | string | Yes | - | OSS Access Key ID | | accessKeySecret | string | Yes | - | OSS Access Key Secret | | secure | boolean | Recommended | true | Mapped to authorizationV4; enables V4 signing behavior | | region | string | No | oss-cn-hangzhou | OSS region | | bucket | string | Recommended | - | OSS bucket name | | endpoint | string | Recommended | - | OSS endpoint domain used for URL construction | | appPath | string | No | example | Prefix folder used in object key path | | extraParams | object | No | {} | Spread into OSS client constructor |

How It Stores Files

Uploaded objects are stored using this key format:

{appPath}/{file.hash}{file.ext}

For example:

uploads/ab12cd34ef56.png

Runtime Behavior

uploadStream(file)

• Reads from file.stream
• Uploads to OSS using client.putStream(objectKey, stream)
• Returns:
  • url: https://{bucket}.{endpoint}/{objectKey} (empty string if endpoint is missing)
  • key: object key in OSS

upload(file, options)

The current implementation returns a resolved placeholder and does not perform OSS upload logic. In Strapi deployments that use stream uploads, uploadStream is the effective path.

delete(file)

• Deletes object by reconstructed name:
  • {appPath}/{file.hash}{file.ext}
• Returns error object with failObjectName attached on failure

getSignedUrl(file)

Used for private bucket access. It tries to determine object key in this order:

1. file.hash + file.ext
2. Extract from file.url
3. file.path
4. file.name fallback with appPath

Signed URL details:

• Method: GET
• Expiration: 86400 seconds (1 day)
• Response hint: content-disposition=inline

isPrivate()

Always returns true.

This tells Strapi to use signed URL behavior for asset access.

health()

Returns "healthy" when client is initialized.

getStream(filePath)

Fetches object stream from OSS using client.getStream(filePath).

Local Development

Build:

npm run build

Test command placeholder:

npm test

Troubleshooting

Empty URL in upload response

uploadStream returns an empty URL if endpoint is not configured. Set providerOptions.endpoint.

Signature URL generation fails

Check that:

• Credentials are valid
• Bucket/region/endpoint match
• The stored file metadata includes enough info to reconstruct object key

Access denied from OSS

Verify RAM policy permissions for:

• oss:PutObject
• oss:GetObject
• oss:DeleteObject

for your target bucket and prefix.

Security Notes

• Never commit real OSS credentials
• Prefer environment variables for sensitive values
• Use RAM users with least privilege required

License

MIT