Django：如何将复合键设为AbstractUser的USERNAME_FIELD？

你的核心矛盾是：Django 要求 USERNAME_FIELD 对应的字段必须全局唯一，但你的业务需求是邮箱+角色组合唯一。下面提供两种适配不同场景的解决思路：

场景1：仅特定角色用户（如管理员）登录后台 #

如果只有特定角色（比如 ADMIN）的用户需要登录 Django Admin，且可以接受这类角色的邮箱全局唯一，可采用以下方案：

1. 调整用户模型 #

修改字段约束，重写 clean 和 save 方法，确保管理员角色的邮箱全局唯一：

from django.core.exceptions import ValidationError
from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    name = "user"

    ROLE_CHOICES = [
        ('CONSUMER', '消费者'),
        ('ADMIN', '管理员'),
        # 其他角色选项
    ]

    email = models.EmailField()  # 不设置全局unique=True
    username = None
    role = models.CharField(choices=ROLE_CHOICES, default="CONSUMER", max_length=255)
    profile_picture = models.URLField(blank=True, null=True)
    dob = models.DateField(null=True, blank=True)
    country = models.CharField(blank=True, max_length=255)

    EMAIL_FIELD = "email"
    USERNAME_FIELD = "email"  # 直接用邮箱作为登录标识
    REQUIRED_FIELDS = ['role']

    def clean(self):
        super().clean()
        # 管理员角色邮箱必须全局唯一
        if self.role == 'ADMIN':
            exists = User.objects.filter(email=self.email, role='ADMIN').exclude(pk=self.pk).exists()
            if exists:
                raise ValidationError("该邮箱已被管理员账号占用")

    def save(self, *args, **kwargs):
        # 管理员自动拥有后台访问权限
        if self.role == 'ADMIN':
            self.is_staff = True
        super().save(*args, **kwargs)

    class Meta:
        verbose_name = "user"
        verbose_name_plural = "users"
        constraints = [
            models.UniqueConstraint(fields=['email', 'role'], name='unique_email_per_role')
        ]

2. 验证逻辑说明 #

• 普通角色（如消费者）的邮箱可以重复，只要角色不同即可，满足你的业务约束。
• 管理员角色的邮箱通过 clean 方法强制全局唯一，符合 Django 对 USERNAME_FIELD 的唯一要求，登录后台时不会出现冲突。

场景2：支持同一邮箱不同角色用户登录（含后台） #

如果需要同一邮箱对应多个角色的用户都能登录（比如同一邮箱既是消费者又是管理员），需通过自定义认证后端绕开 USERNAME_FIELD 的全局唯一限制：

1. 修改用户模型 #

新增 UUID 字段作为全局唯一的 USERNAME_FIELD，保留邮箱+角色的复合约束：

import uuid
from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    name = "user"
    uuid = models.UUIDField(default=uuid.uuid4, unique=True, editable=False)

    ROLE_CHOICES = [
        ('CONSUMER', '消费者'),
        ('ADMIN', '管理员'),
        # 其他角色选项
    ]

    email = models.EmailField()
    username = None
    role = models.CharField(choices=ROLE_CHOICES, default="CONSUMER", max_length=255)
    profile_picture = models.URLField(blank=True, null=True)
    dob = models.DateField(null=True, blank=True)
    country = models.CharField(blank=True, max_length=255)

    EMAIL_FIELD = "email"
    USERNAME_FIELD = "uuid"  # 用UUID作为全局唯一标识
    REQUIRED_FIELDS = ['email', 'role']

    class Meta:
        verbose_name = "user"
        verbose_name_plural = "users"
        constraints = [
            models.UniqueConstraint(fields=['email', 'role'], name='unique_email_per_role')
        ]

2. 自定义认证后端 #

创建 backends.py 文件，实现基于邮箱+角色的认证逻辑：

from django.contrib.auth.backends import ModelBackend
from .models import User

class EmailRoleBackend(ModelBackend):
    def authenticate(self, request, email=None, password=None, **kwargs):
        try:
            # 后台登录仅允许管理员角色
            if request.path.startswith('/admin/'):
                user = User.objects.get(email=email, role='ADMIN')
            else:
                # 前端登录可根据传入的role参数匹配用户，若无参数默认匹配消费者
                user = User.objects.get(email=email, role=kwargs.get('role', 'CONSUMER'))
        except User.DoesNotExist:
            return None
        
        if user.check_password(password):
            return user

    def get_user(self, user_id):
        try:
            return User.objects.get(pk=user_id)
        except User.DoesNotExist:
            return None

3. 配置认证后端 #

在 settings.py 中替换默认认证后端：

AUTHENTICATION_BACKENDS = [
    'your_app.backends.EmailRoleBackend',
]

4. 自定义后台登录表单 #

让后台登录时使用邮箱而非 UUID 作为输入：

# 在admin.py中
from django.contrib.admin.forms import AdminAuthenticationForm
from django.contrib.auth import authenticate
from django import forms
from django.contrib import admin

class CustomAdminLoginForm(AdminAuthenticationForm):
    username = forms.EmailField(label="邮箱")

    def clean(self):
        email = self.cleaned_data.get('username')
        password = self.cleaned_data.get('password')

        if email and password:
            self.user_cache = authenticate(self.request, email=email, password=password)
            if self.user_cache is None:
                raise forms.ValidationError("邮箱或密码错误")
            else:
                self.confirm_login_allowed(self.user_cache)
        return self.cleaned_data

# 替换后台登录表单
admin.site.login_form = CustomAdminLoginForm

内容的提问来源于stack exchange，提问作者suvodipMondal