ContextQMD
Back to Fastgpt

Object Storage Configuration

document/content/self-host/config/object-storage.en.mdx

4.15.25.5 KB
Original Source

import { Alert } from '@/components/docs/Alert'; import FastGPTLink from '@/components/docs/linkFastGPT';

Object Storage Configuration

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

Common Required Environment Variables

  • Temporary credential authentication (e.g., STS) is not supported. Ensure service security on your own.
  • Private bucket reuse is not supported. If you set the private and public bucket names to the same value, ensure the bucket policy is at least public read, private write.
  • STORAGE_VENDOR Enum value. Options: minio, aws-s3, oss, cos.
  • STORAGE_REGION Region where the object storage service is located, e.g., us-east-1. Refer to your provider's region list. For self-hosted MinIO, any value works.
  • STORAGE_ACCESS_KEY_ID Access Key ID for the service credentials
  • STORAGE_SECRET_ACCESS_KEY Secret Access Key for the service credentials
  • STORAGE_PUBLIC_BUCKET FastGPT public resource bucket name
  • STORAGE_PRIVATE_BUCKET FastGPT private resource bucket name

Transfer Behavior

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

Self-Hosted MinIO and AWS S3

MinIO has strong AWS S3 protocol support, so MinIO and AWS S3 configurations are nearly identical — differences come from provider-specific or self-hosted requirements. In theory, any object storage with S3 protocol support comparable to MinIO will work, such as SeaweedFS, RustFS, etc.

  • 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

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_DOWNLOAD_URL_MODE=short-redirect
STORAGE_DOWNLOAD_REDIRECT_TTL_SECONDS=300
STORAGE_EXTERNAL_ENDPOINT=https://s3.example.com
STORAGE_S3_CDN_ENDPOINT=https://cdn.example.com
STORAGE_S3_ENDPOINT=http://127.0.0.1:9000
STORAGE_S3_FORCE_PATH_STYLE=true
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

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

  • 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

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=