Storage Backends

PicFast supports 6 storage backends. Each is configured via the admin panel under Storage Strategies. You can create multiple strategies and assign them to different user groups.

Local

Store files on the local filesystem. Simplest option — good for single-server deployments and development.

{
  "type": "local",
  "root": "/data/uploads",
  "url": "https://picfast.example.com/uploads"
}

S3-compatible

AWS S3, MinIO, Cloudflare R2, and any S3-compatible service.

{
  "type": "s3",
  "endpoint": "https://s3.us-east-1.amazonaws.com",
  "region": "us-east-1",
  "bucket": "my-picfast",
  "access_key": "your-access-key",
  "secret_key": "your-secret-key",
  "url": "https://my-picfast.s3.us-east-1.amazonaws.com"
}

Alibaba OSS

{
  "type": "oss",
  "endpoint": "oss-cn-hangzhou.aliyuncs.com",
  "bucket": "my-picfast",
  "access_key": "your-access-key",
  "secret_key": "your-secret-key",
  "url": "https://my-picfast.oss-cn-hangzhou.aliyuncs.com"
}

Tencent COS

{
  "type": "cos",
  "bucket_url": "https://my-picfast.cos.ap-guangzhou.myqcloud.com",
  "secret_id": "your-secret-id",
  "secret_key": "your-secret-key",
  "url": "https://my-picfast.cos.ap-guangzhou.myqcloud.com"
}

Qiniu Kodo

{
  "type": "kodo",
  "access_key": "your-access-key",
  "secret_key": "your-secret-key",
  "bucket": "my-picfast",
  "domain": "https://picfast.example.com",
  "zone": "z0"
}

WebDAV

Connect to any WebDAV-compatible storage (Nextcloud, ownCloud, etc.).

{
  "type": "webdav",
  "endpoint": "https://dav.example.com",
  "username": "user",
  "password": "password",
  "url": "https://dav.example.com/pics"
}

Link mode

By default, cloud backends (S3, OSS, COS, Kodo) return direct CDN URLs for uploaded images. Local and WebDAV backends always serve through PicFast's proxy route (/i/{key}.{ext}).

You can change this behavior with the link_mode field:

{
  "type": "s3",
  "endpoint": "https://s3.us-east-1.amazonaws.com",
  "bucket": "my-picfast",
  "access_key": "...",
  "secret_key": "...",
  "url": "https://cdn.example.com",
  "link_mode": "proxy"
}

Proxy mode is useful when you need unified access control (private images) or want to use PicFast's on-the-fly image processing for cloud-stored images. Switching modes takes effect immediately — no re-upload or migration needed.

Switching backends

Images already stored in one backend stay there. When you change the default strategy for a group, new uploads go to the new backend. Existing images continue to be served from their original locations — no migration needed.