Storage Providers
Relevant source files
The following files were used as context for generating this wiki page:
Storage Providers in Casdoor are specialized entities within the Provider system designed to manage the storage, retrieval, and deletion of binary resources such as user avatars, application logos, and static assets. They abstract the underlying storage infrastructure, allowing the application to interface with local file systems or various cloud-based Object Storage Services (OSS) through a unified interface.
The system utilizes a factory pattern to instantiate specific storage clients based on the provider type. This ensures that core logic for file management—such as safe uploads with retries and path normalization—remains independent of the specific storage backend being used.
Sources: object/storage.go:27-41, storage/storage.go:19-45
Architecture and Components
Storage Provider Factory
The backend implements a factory function GetStorageProvider which initializes the appropriate storage implementation based on the providerType string. It maps configuration data (credentials, endpoints, buckets) into an object satisfying the oss.StorageInterface.
The logic ensures that if a provider requires a certificate (specifically for the "Casdoor" provider type), it is retrieved and passed during initialization.
Sources: storage/storage.go:19-45, deployment/deploy.go:31-50
Supported Provider Types
Casdoor supports a wide range of storage backends, categorized as either local or cloud-based.
| Provider Type | Backend Description |
|---|---|
| Local File System | Stores files directly on the server's disk in a files directory. |
| AWS S3 | Amazon Web Services Simple Storage Service. |
| MinIO | S3-compatible open-source object storage. |
| Aliyun OSS | Alibaba Cloud Object Storage Service. |
| Tencent Cloud COS | Tencent Cloud Cloud Object Storage. |
| Azure Blob | Microsoft Azure Blob Storage. |
| Google Cloud Storage | Google Cloud Platform object storage. |
| Casdoor | Internal storage mechanism often used for recursive or proxied storage. |
Sources: object/storage.go:31-37, storage/storage.go:21-43
Core Storage Logic
Safe File Uploads
The system implements a robust upload wrapper UploadFileSafe. This function includes:
- Security Checks: Validates the path to prevent directory traversal attacks (checks for
..). - Retry Mechanism: Attempts the upload up to 5 times in case of transient network or provider errors.
- Key Refinement: Adjusts the object key based on specific provider requirements (e.g., stripping leading slashes for Google Cloud Storage or handling prefixes for MinIO).
Sources: object/storage.go:146-156, object/storage.go:158-175, object/storage.go:189-202
URL and Path Management
Casdoor manages two distinct identifiers for stored resources:
- File URL: The publicly accessible URL used by browsers to fetch the resource.
- Object Key: The internal path used by the storage provider to identify the object.
For the Local File System, the URL is constructed by joining the provider domain with the /files prefix. For cloud providers, the URL is typically constructed using the host and bucket name.
Sources: object/storage.go:81-110
Configuration and Management
Provider Fields
Storage providers require specific configuration fields depending on their type. These are managed via the frontend and stored in the Provider object.
| Configuration Field | Relevance |
|---|---|
| Endpoint | The internet-facing API URL of the storage service. |
| Intranet Endpoint | A private endpoint used if isCloudIntranet is enabled in configuration. |
| Bucket | The specific container/bucket name in the storage service. |
| Path Prefix | An optional folder path prepended to all uploaded object keys. |
| Domain | The custom domain or CDN URL used to serve the files. |
| Region ID | The geographic region where the bucket is located (e.g., us-east-1). |
Sources: web/src/provider/StorageProviderFields.js:23-110, object/storage.go:47-53
Resource Management API
The system provides a RESTful API for managing resources stored via these providers.
| Endpoint | Method | Description |
|---|---|---|
/api/upload-resource | POST | Uploads a file to the configured provider. |
/api/get-resources | GET | Lists resources with support for pagination and filtering. |
/api/delete-resource | POST | Deletes a resource from the storage backend. |
Sources: swagger/swagger.yml:1483-1540, web/src/ResourceListPage.js:46-60
Integration Use Cases
Avatar Management
Casdoor can automatically manage user avatars. When a permanent avatar is requested, the system downloads the image from a source URL and re-uploads it to the defaultStorageProvider under the /avatar/{organization}/{username} path.
Sources: object/avatar.go:43-61
Static File Deployment
The deployment module utilizes storage providers to distribute static assets. It can upload the built JavaScript and CSS folders from the web directory directly to a configured storage provider and then update the HTML templates to point to the provider's domain.
Sources: deployment/deploy.go:23-53
Conclusion
The Storage Provider system is a critical infrastructure component that enables Casdoor to remain vendor-neutral while providing robust file management capabilities. By abstracting storage via an interface and providing high-level wrappers for safety and retries, the system ensures reliable asset management across diverse environments, from local development to multi-cloud deployments.