Django-Storages 的 Google Cloud Storage 后端使用指南

概述

django-storages 是一个优秀的 Django 存储后端扩展库，它提供了对多种云存储服务的支持。本文将重点介绍其中的 Google Cloud Storage (GCS) 后端实现，帮助开发者将 Django 应用的文件存储无缝迁移到 Google 云平台。

安装与基础配置

安装依赖

首先需要安装包含 GCS 支持的 django-storages 扩展包：

pip install django-storages[google]

Django 版本适配

根据 Django 版本的不同，配置方式有所差异：

Django 4.2+ 配置方式：

STORAGES = {
    "default": {
        "BACKEND": "storages.backends.gcloud.GoogleCloudStorage",
        "OPTIONS": {
            # 配置选项
        },
    },
}

Django 4.2 以下版本配置方式：

DEFAULT_FILE_STORAGE = "storages.backends.gcloud.GoogleCloudStorage"

认证配置

服务账户设置

1. 在 Google Cloud 控制台创建专用服务账户
2. 确保该账户对目标存储桶有读写权限
3. 将服务账户与计算环境关联（GCE、GKE、Cloud Run 等）

认证方式选择

IAM Sign Blob API（推荐）

GS_IAM_SIGN_BLOB = True  # 启用 IAM Sign Blob API
GS_SA_EMAIL = "your-service-account@project.iam.gserviceaccount.com"  # 可选，指定服务账户

优点：

• 无需管理私钥文件
• 适用于云原生环境

注意：有配额限制

私钥文件方式

GS_CREDENTIALS = "path/to/service-account.json"

或通过环境变量：

export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account.json"

核心配置参数

必填参数

GS_BUCKET_NAME = "your-bucket-name"  # 存储桶名称

常用可选参数

GS_PROJECT_ID = "your-project-id"  # GCP 项目ID
GS_DEFAULT_ACL = "publicRead"  # 文件默认访问权限
GS_QUERYSTRING_AUTH = False  # 是否启用URL签名
GS_FILE_OVERWRITE = True  # 是否覆盖同名文件
GS_LOCATION = "subfolder/"  # 存储子目录

性能优化参数

GS_BLOB_CHUNK_SIZE = 5 * 1024 * 1024  # 分块上传大小（必须是256K的倍数）
GS_MAX_MEMORY_SIZE = 10 * 1024 * 1024  # 内存缓存大小（字节）

文件元数据控制

GS_OBJECT_PARAMETERS = {
    "cache_control": "public, max-age=86400",
    "content_type": "application/octet-stream",
    "storage_class": "STANDARD"
}

高级功能

自定义端点

GS_CUSTOM_ENDPOINT = "https://your-cdn.example.com"

URL 签名有效期

from datetime import timedelta
GS_EXPIRATION = timedelta(days=7)  # 最大7天

Gzip 压缩

GS_IS_GZIPPED = True
GZIP_CONTENT_TYPES = (
    "text/css",
    "text/javascript",
    "application/javascript",
    "image/svg+xml"
)

最佳实践建议

1. 生产环境推荐使用 IAM Sign Blob API 方式认证
2. 静态文件设置 publicRead ACL 并禁用 URL 签名
3. 大文件上传时配置适当的分块大小
4. 敏感文件保持默认的签名URL机制
5. 注意 GCS 的存储类别选择以优化成本

常见问题解决

问题1：上传文件返回 HTTP 400 错误
解决方案：检查存储桶的访问控制模式是否为"精细"，或保持 GS_DEFAULT_ACL 为 None

问题2：本地开发无法生成签名URL
解决方案：配置 GS_SA_EMAIL 并确保有有效的服务账户凭据

问题3：URL 签名超过7天有效期
解决方案：将 GS_EXPIRATION 设置为不超过 604800 秒（7天）

通过本文的详细指南，开发者可以轻松地将 Django 应用与 Google Cloud Storage 集成，实现高效、安全的云文件存储解决方案。