Object Storage Configuration

Object Storage Configuration

This guide covers environment variable configuration for object storage providers supported by FastGPT, including self-hosted MinIO, AWS S3, Cloudflare R2, Alibaba Cloud OSS, and Tencent Cloud COS.

FastGPT supports MinIO, AWS S3, Alibaba Cloud OSS, Tencent Cloud COS, and Cloudflare R2. Except for local MinIO development, create STORAGE_PUBLIC_BUCKET and STORAGE_PRIVATE_BUCKET ahead of time and grant the FastGPT access key read/write permission on both buckets.

Access Modes

• Uploads always go through the FastGPT backend proxy.
• External download URLs are always FastGPT short links. FastGPT no longer returns object storage presigned URLs directly.
• STORAGE_DOWNLOAD_URL_MODE supports two modes and defaults to short-proxy:
  • short-proxy: FastGPT validates the short link and proxies the file stream. No public object storage endpoint is required.
  • short-redirect: FastGPT validates the short link, then redirects to a short-lived object storage or CDN URL. File traffic bypasses FastGPT.
• Self-hosted MinIO requires STORAGE_EXTERNAL_ENDPOINT when using short-redirect.

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. Can be a container ID, e.g., http://fastgpt-minio:9000
• 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. If vendor is minio, this is fixed to true.
• STORAGE_S3_MAX_RETRIES [Optional] Maximum request retry attempts. Default: 3

Complete Example

If using Sealos object storage, set STORAGE_VENDOR to minio

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://127.0.0.1:9000
STORAGE_S3_FORCE_PATH_STYLE=true
STORAGE_S3_MAX_RETRIES=3

AWS S3

AWS S3 uses the same S3-compatible variables as MinIO. For production, create separate public and private buckets in advance and configure public-read or CloudFront/custom-domain access only for the public bucket.

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

• 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

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

• 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

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 HTTPS custom domain (or another public HTTPS domain bound to the bucket). This is separate from the R2 S3 API endpoint and must not contain query parameters.

For production, use a custom domain instead of the rate-limited r2.dev development URL. Create both R2 buckets in advance; FastGPT checks that production buckets exist at startup and does not create them automatically.

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