首页 > 文章 > python教程

Django多租户架构实现教程

时间：2026-05-23 23:18:29 355浏览收藏

本文深入解析了 Django 生态中最成熟稳定的多租户方案 django-tenants，聚焦 PostgreSQL schema 模式下的实战落地要点：从强制替换数据库后端、租户模型继承 TenantMixin 并启用 auto_create_schema，到子域名/路径/请求头三种租户识别方式的取舍与自定义中间件编写，再到关键的迁移命令区分（--shared 与 --tenant）及易踩坑细节（如原生 SQL 的 search_path 手动管理、psycopg3 兼容性、schema 命名规范等），手把手带你避开常见陷阱，真正实现“一个租户一个隔离 schema”的高可靠 SaaS 架构。

Python Django怎么实现多租户SaaS架构_使用django-tenants隔离模式

django-tenants 是当前 Django 生态中基于 PostgreSQL schema 实现多租户最稳定、文档最全的方案。它不依赖额外服务或复杂中间件链，核心就是「一个租户一个 schema」，所有隔离逻辑由数据库层和 ORM 层协同完成——只要你的数据库是 PostgreSQL，且项目结构允许按 schema 切分，就能快速落地。

怎么配置 `django-tenants` 的数据库后端？

必须替换默认 PostgreSQL 后端，否则 schema 切换不会生效。

ENGINE 必须设为 django_tenants.postgresql_backend，不是 django.db.backends.postgresql
公共 schema（public）必须存在，且只放共享表（如 Tenant 模型、用户认证表等）
租户 schema 名称不能含大写字母、特殊符号或以数字开头；推荐用小写 ASCII 字符 + 下划线
如果用 psycopg3（2026 年主流），需确认 django-tenants 版本 ≥ 4.0.0，否则会报 AttributeError: module 'psycopg' has no attribute 'extensions'

示例 settings.py 片段：

DATABASES = {
    'default': {
        'ENGINE': 'django_tenants.postgresql_backend',
        'NAME': 'saas_db',
        'USER': 'postgres',
        'PASSWORD': 'xxx',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

租户模型怎么定义？为什么 `auto_create_schema=True` 很关键？

租户模型必须继承 TenantMixin，且字段名必须含 schema_name（字符串类型）。

schema_name 是数据库层面的唯一标识，也是 URL 路由/域名匹配的依据
auto_create_schema=True 表示调用 .save() 时自动执行 CREATE SCHEMA，否则得手动运行 ./manage.py migrate_schemas --shared 和 ./manage.py migrate_schemas --tenant
若租户注册流程需要异步创建 schema（比如防爆破），可设为 False，再在后台任务中显式调用 tenant.create_schema()
domain_url 字段不是必须的，但如果你用子域名路由（如 acme.example.com），就必须有且唯一

最小可行模型：

from django_tenants.models import TenantMixin
<p>class Client(TenantMixin):
name = models.CharField(max_length=100)
paid_until = models.DateField(null=True)
on_trial = models.BooleanField(default=True)
created_on = models.DateField(auto_now_add=True)</p><pre class="brush:python;toolbar:false;">auto_create_schema = True  # ⚠️ 不加这行，租户数据进不了自己的 schema

中间件怎么识别租户？域名 vs 路径路由的区别在哪？

默认中间件 django_tenants.middleware.main.TenantMainMiddleware 只支持子域名识别（tenant.example.com）。如果用路径（example.com/tenant1/）或 header 识别，必须自定义中间件并重写 get_tenant 方法。

子域名方式：简单、符合 SaaS 直觉，但需 DNS 配置支持通配符（*.example.com）
路径方式：前端无需改 DNS，但所有 URL 前缀要统一，且静态文件、管理后台路径容易冲突
header 方式（如 X-Tenant-ID）：适合内部 API 或微前端场景，但无法用于浏览器直连
无论哪种方式，都必须确保 request.tenant 在进入视图前已赋值，否则 ORM 查询会落到 public schema

路径路由示例（需替换中间件）：

class PathTenantMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response
<pre class="brush:python;toolbar:false;">def __call__(self, request):
    path_parts = request.path.strip('/').split('/')
    if len(path_parts) > 0:
        schema_name = path_parts[0]
        try:
            request.tenant = Client.objects.get(schema_name=schema_name)
        except Client.DoesNotExist:
            pass
    return self.get_response(request)