FastGPTFastGPT

Object Storage Configuration

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

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.

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.

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

  • 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

  • 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 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.

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
Edit on GitHub

Last updated

On this page

Put your business knowledge to work with AI

Import company documents and build accurate, reliable, traceable AI answers.