# Object Storage Configuration

> How to configure and connect to various object storage providers via environment variables, and common configuration issues

Source: https://doc.fastgpt.io/self-host/config/object-storage
Last Updated: 2026-11-12

## Object Storage Configuration

FastGPT supports self-hosted MinIO / RustFS as well as AWS S3, Alibaba Cloud OSS, Tencent Cloud COS, and Cloudflare R2. When using any vendor other than `minio`, you must create both `STORAGE_PUBLIC_BUCKET` and `STORAGE_PRIVATE_BUCKET` in advance (non-MinIO adapters only check that the buckets exist at startup and fail if either bucket is missing) and grant the access key read/write permissions on both buckets.

## Access Modes

* Uploads always go through the FastGPT backend proxy.
* FastGPT provides authenticated short links for file downloads to manage file access and protect object storage credentials.
* `STORAGE_DOWNLOAD_URL_MODE` supports two modes and defaults to `short-proxy`:
  * `short-proxy`: FastGPT validates the short link and proxies the file stream. Downloads through short links do not require a public object storage endpoint.
  * `short-redirect`: FastGPT validates the short link, then redirects to a short-lived object storage or CDN URL. File traffic bypasses FastGPT.
* The plugin logo endpoint always redirects to the public bucket URL. Storage-backed images under `/api/system/img/` are proxied by FastGPT in `short-proxy` mode and redirected to the public bucket only in `short-redirect` mode.
* Self-hosted MinIO requires `STORAGE_EXTERNAL_ENDPOINT` in `short-redirect` mode. Plugin logos also need it when browsers cannot reach `STORAGE_S3_ENDPOINT`.

## Provider Configuration

### MinIO

> MinIO has strong AWS S3 protocol support and is suitable for local development and self-hosted deployments. In theory, any object storage with S3 protocol support comparable to MinIO will work, such as SeaweedFS or RustFS.

* `STORAGE_S3_ENDPOINT` Internal connection address. Use the Compose service name or container name, e.g., `http://fastgpt-rustfs:9000` for the RustFS service bundled with the official template
* `STORAGE_EXTERNAL_ENDPOINT` An address accessible by both **server** and **client** to reach the bucket. Use a fixed host IP or domain name — don't use `127.0.0.1` or `localhost` (containers can't access loopback addresses). This variable does not change the download mode automatically.
* `STORAGE_S3_CDN_ENDPOINT` \[Optional] CDN endpoint used for temporary `short-redirect` download URLs. This variable does not change the default download mode and requires `STORAGE_EXTERNAL_ENDPOINT`. Uploads still go through the FastGPT backend proxy and do not use the CDN.
* `STORAGE_S3_FORCE_PATH_STYLE` \[Optional] Virtual-hosted-style or path-style routing. Default: `false` (virtual-hosted style). Self-hosted MinIO / RustFS usually requires setting it to `true` explicitly; the official template already does.
* `STORAGE_S3_MAX_RETRIES` \[Optional] Maximum request retry attempts. Default: 3

When exposing MinIO in Kubernetes or Docker, configure `STORAGE_EXTERNAL_ENDPOINT` to a static host IP or domain reachable by both browsers and FastGPT to ensure public bucket assets such as plugin logos load correctly.

**Complete Example**

> When using Sealos Object Storage: set `STORAGE_VENDOR` to `aws-s3` if the two buckets are already created in the console, or set it to `minio` if you need FastGPT to create the buckets automatically.

```dotenv
STORAGE_VENDOR=minio
STORAGE_REGION=us-east-1
STORAGE_ACCESS_KEY_ID=your_access_key
STORAGE_SECRET_ACCESS_KEY=your_secret_key
STORAGE_PUBLIC_BUCKET=fastgpt-public
STORAGE_PRIVATE_BUCKET=fastgpt-private
STORAGE_S3_ENDPOINT=http://fastgpt-rustfs:9000
STORAGE_S3_FORCE_PATH_STYLE=true
STORAGE_S3_MAX_RETRIES=3
```

### AWS S3

AWS S3 uses the same S3-compatible variables as MinIO. When `STORAGE_VENDOR=aws-s3`, you must create separate public and private buckets in advance and configure public-read or CloudFront/custom-domain access for the public bucket.

```dotenv
STORAGE_VENDOR=aws-s3
STORAGE_REGION=ap-southeast-1
STORAGE_ACCESS_KEY_ID=your_access_key
STORAGE_SECRET_ACCESS_KEY=your_secret_key
STORAGE_PUBLIC_BUCKET=fastgpt-public
STORAGE_PRIVATE_BUCKET=fastgpt-private
STORAGE_S3_ENDPOINT=https://s3.ap-southeast-1.amazonaws.com
STORAGE_S3_FORCE_PATH_STYLE=false
STORAGE_S3_MAX_RETRIES=3
```

### Alibaba Cloud OSS

> * [CORS Configuration](https://help.aliyun.com/zh/oss/user-guide/configure-cross-origin-resource-sharing/?spm=5176.8466032.console-base_help.dexternal.1bcd1450Wau6J6#b58400ec36rqf)

* `STORAGE_OSS_ENDPOINT` Alibaba Cloud OSS hostname. Default is usually `{region}.aliyuncs.com`, e.g., `oss-cn-hangzhou.aliyuncs.com`. If using a custom domain, enter it here, e.g., `your-domain.com`
* `STORAGE_OSS_CNAME` Whether custom domain is enabled
* `STORAGE_OSS_SECURE` Whether TLS is enabled. Disable if your domain doesn't have a certificate.
* `STORAGE_OSS_INTERNAL` \[Optional] Whether to use internal network access. Enable if your service is also on Alibaba Cloud to save bandwidth. Default: disabled

Set the OSS public bucket to public-read and keep the private bucket private. The same Access Key can be used for both buckets, but the bucket names must remain distinct.

**Complete Example**

```dotenv
STORAGE_VENDOR=oss
STORAGE_REGION=oss-cn-hangzhou
STORAGE_ACCESS_KEY_ID=your_access_key
STORAGE_SECRET_ACCESS_KEY=your_secret_key
STORAGE_PUBLIC_BUCKET=fastgpt-public
STORAGE_PRIVATE_BUCKET=fastgpt-private
STORAGE_OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
STORAGE_OSS_CNAME=false
STORAGE_OSS_SECURE=false
STORAGE_OSS_INTERNAL=false
```

### Tencent Cloud COS

> * [CORS Configuration](https://cloud.tencent.com/document/product/436/13318)

* `STORAGE_COS_PROTOCOL` Options: `https:`, `http:` — don't forget the `:`. If your custom domain doesn't have a certificate, don't use `https:`
* `STORAGE_COS_USE_ACCELERATE` \[Optional] Enable global acceleration domain. Default: false. If true, the bucket must have global acceleration enabled.
* `STORAGE_COS_CNAME_DOMAIN` \[Optional] Custom domain, e.g., `your-domain.com`
* `STORAGE_COS_PROXY` \[Optional] Proxy server, e.g., `http://localhost:7897`

COS bucket names must include the account App ID suffix, for example `fastgpt-public-1250000000`. Configure anonymous read only for the public bucket and keep the private bucket private.

**Complete Example**

```dotenv
STORAGE_VENDOR=cos
STORAGE_REGION=ap-shanghai
STORAGE_ACCESS_KEY_ID=your_access_key
STORAGE_SECRET_ACCESS_KEY=your_secret_key
STORAGE_PUBLIC_BUCKET=fastgpt-public
STORAGE_PRIVATE_BUCKET=fastgpt-private
STORAGE_COS_PROTOCOL=http:
STORAGE_COS_USE_ACCELERATE=false
STORAGE_COS_CNAME_DOMAIN=
STORAGE_COS_PROXY=
```

### Cloudflare R2

R2 uses the S3-compatible API. Set `STORAGE_REGION` to `auto` and use the account-level S3 endpoint from Cloudflare as `STORAGE_S3_ENDPOINT`. FastGPT does not rewrite R2 presigned URLs through `STORAGE_S3_CDN_ENDPOINT`; private objects should normally use the default `short-proxy` download mode.

`STORAGE_R2_PUBLIC_ENDPOINT` is required for public objects. Set it to the custom domain bound to the bucket for public HTTPS access without query parameters.

For production, configure a custom domain bound to the R2 bucket for reliable access. Create both R2 buckets in advance; FastGPT verifies production buckets at startup.

```dotenv
STORAGE_VENDOR=r2
STORAGE_REGION=auto
STORAGE_S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
STORAGE_R2_PUBLIC_ENDPOINT=https://assets.example.com
STORAGE_ACCESS_KEY_ID=<r2-access-key-id>
STORAGE_SECRET_ACCESS_KEY=<r2-secret-access-key>
STORAGE_PUBLIC_BUCKET=<r2-public-bucket>
STORAGE_PRIVATE_BUCKET=<r2-private-bucket>
STORAGE_S3_FORCE_PATH_STYLE=false
```
