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_MODEsupports two modes and defaults toshort-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 inshort-proxymode and redirected to the public bucket only inshort-redirectmode. - Self-hosted MinIO requires
STORAGE_EXTERNAL_ENDPOINTinshort-redirectmode. Plugin logos also need it when browsers cannot reachSTORAGE_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_ENDPOINTInternal connection address. Use the Compose service name or container name, e.g.,http://fastgpt-rustfs:9000for the RustFS service bundled with the official templateSTORAGE_EXTERNAL_ENDPOINTAn address accessible by both server and client to reach the bucket. Use a fixed host IP or domain name — don't use127.0.0.1orlocalhost(containers can't access loopback addresses). This variable does not change the download mode automatically.STORAGE_S3_CDN_ENDPOINT[Optional] CDN endpoint used for temporaryshort-redirectdownload URLs. This variable does not change the default download mode and requiresSTORAGE_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 totrueexplicitly; 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_VENDORtoaws-s3if the two buckets are already created in the console, or set it tominioif 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=3AWS 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=3Alibaba Cloud OSS
STORAGE_OSS_ENDPOINTAlibaba 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.comSTORAGE_OSS_CNAMEWhether custom domain is enabledSTORAGE_OSS_SECUREWhether 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=falseTencent Cloud COS
STORAGE_COS_PROTOCOLOptions:https:,http:— don't forget the:. If your custom domain doesn't have a certificate, don't usehttps: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.comSTORAGE_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=falseLast updated