Django Storages 的 Azure 存储后端使用指南

概述

在 Django 项目中，当我们需要将媒体文件和静态文件存储在 Microsoft Azure 云存储服务中时，可以使用 django-storages 提供的 Azure 存储后端。这个后端封装了 Azure Blob 存储服务的功能，使其能够无缝集成到 Django 的文件存储系统中。

安装配置

安装依赖

首先需要安装必要的 Python 包：

pip install django-storages[azure]

如果需要使用 Azure 托管身份认证，还需要额外安装：

pip install azure-identity

Django 配置

Django 4.2 版本对存储后端配置方式进行了重大改进。新版本推荐使用 STORAGES 字典进行配置：

STORAGES = {
    "default": {
        "BACKEND": "storages.backends.azure_storage.AzureStorage",
        "OPTIONS": {
            # 配置选项
        },
    },
    "staticfiles": {
        "BACKEND": "storages.backends.azure_storage.AzureStorage",
        "OPTIONS": {
            # 静态文件配置选项
        },
    },
}

对于 Django 4.2 之前的版本，则需要分别配置：

DEFAULT_FILE_STORAGE = "storages.backends.azure_storage.AzureStorage"
STATICFILES_STORAGE = "storages.backends.azure_storage.AzureStorage"

认证方式

Azure 存储后端支持多种认证方式，按优先级顺序如下：

1. 连接字符串（connection_string）
2. 账户密钥（account_key）和账户名称（account_name）
3. 令牌凭证（token_credential）和账户名称
4. SAS 令牌（sas_token）

使用托管身份认证

Azure 托管身份（Managed Identity）是一种无需在代码中存储凭据的认证方式，特别适合运行在 Azure 服务（如 App Services、Functions 等）中的应用。

配置示例：

from azure.identity import DefaultAzureCredential

STORAGES = {
    "default": {
        "BACKEND": "storages.backends.azure_storage.AzureStorage",
        "OPTIONS": {
            "token_credential": DefaultAzureCredential(),
            "account_name": "yourstorageaccount",
            "azure_container": "media",
        },
    }
}

核心配置参数

必需参数

• azure_container：指定存储文件的容器名称，容器必须预先创建

常用可选参数

• azure_ssl：是否使用 HTTPS 连接（默认为 True）
• upload_max_conn：上传单个文件时的最大连接数（默认 2）
• timeout：全局连接超时时间（秒，默认 20）
• max_memory_size：下载文件时的最大内存使用量（默认 2MB）
• expiration_secs：URL 过期时间（秒，None 表示永不过期）
• overwrite_files：是否覆盖同名文件（默认 False）
• location：文件存储的基础路径
• endpoint_suffix：端点后缀（默认为 core.windows.net）
• custom_domain：自定义域名用于生成文件 URL

高级配置

• cache_control：设置 Cache-Control HTTP 响应头
• object_parameters：设置所有对象的元数据
• client_options：传递给 BlobServiceClient 的额外选项

使用 Azurite 本地模拟器

Azurite 是 Azure 存储服务的本地模拟器，适合开发和测试环境使用。配置示例：

STORAGES = {
    "default": {
        "BACKEND": "storages.backends.azure_storage.AzureStorage",
        "OPTIONS": {
            "connection_string": "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;...",
            "azure_container": "media",
        },
    }
}

注意事项

文件名限制

Azure 存储对文件名有以下限制：

• 不能以点(.)或斜杠(/)结尾
• 不能包含超过 256 个斜杠
• 长度不能超过 1024 个字符

公共与私有 URL

私有 URL 包含 SAS 令牌，可以通过查询参数覆盖某些 blob 属性，如 cache-control、content-type 等。

生成带参数的 URL 示例：

az_storage = AzureStorage()
az_url = az_storage.url(blob_name, parameters={'content_type': 'text/html;'})

最佳实践

1. 生产环境推荐使用托管身份认证，提高安全性
2. 为不同环境（开发、测试、生产）配置不同的容器
3. 合理设置缓存控制头，优化性能
4. 考虑文件命名规范，避免 Azure 存储的限制
5. 监控存储使用情况和性能指标

通过合理配置 django-storages 的 Azure 后端，可以轻松实现 Django 应用与 Azure 云存储的无缝集成，既保证了文件存储的可靠性，又能充分利用云服务的扩展性和性能优势。