1. 原理与设计
1.1 为什么要使用自定义用户模型
在 Django 的认证体系中，默认的 User 模型提供了基本字段和权限机制，但在实际业务中往往需要更灵活的字段结构与身份识别策略。使用自定义用户模型可以让身份标识从固定的 username 变为可替换的字段（如邮箱、手机号）并进一步扩展字段集，以满足复杂的业务场景。
通过引入 AUTH_USER_MODEL，Django 可以将整个认证与授权体系绑定到你的自定义实现上，这样就不会再依赖默认模型的限制，从而实现更好的扩展性和可维护性。
1.2 AbstractUser 与 AbstractBaseUser 的取舍
Django 提供两种主流的自定义路径：AbstractUser 和 AbstractBaseUser。
使用 AbstractUser 时，你可以在保留原有字段与权限体系的基础上做定制，通常适合小幅度字段扩展；而选择 AbstractBaseUser 则可以从零开始实现身份、字段和权限，适合需要高度定制的场景，但实现成本更高。
无论选择哪条路径，核心原则都是确保模型在 settings.py 中通过 AUTH_USER_MODEL 指向自定义实现，并在迁移后将新结构应用到数据库，以确保后续的认证流程正确工作。
2. 实现自定义用户模型的代码实操
2.1 设计目标与字段选择
常见的设计目标包括：以 邮箱 作为唯一用户名、兼容第三方认证、以及与前端表单的无缝对接等。将字段设计与业务痛点绑定，是实现稳定管理员登录体验的先决条件。
在设计阶段应明确哪些字段需要公开，哪些字段仅管理员使用；同时确保 is_staff、is_active 等权限相关字段在模型中得到正确实现，以便管理员账户能够正常登录和管理系统。
2.2 编写自定义模型代码（示例）
下面给出一个基于 AbstractBaseUser 的自定义用户模型示例，核心点在于以邮箱作为用户名并实现必需的字段与方法：
# models.py
from django.db import models
from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin, BaseUserManagerclass CustomUserManager(BaseUserManager):def create_user(self, email, password=None, **extra_fields):if not email:raise ValueError('Email must be provided')email = self.normalize_email(email)user = self.model(email=email, **extra_fields)user.set_password(password)user.save(using=self._db)return userdef create_superuser(self, email, password=None, **extra_fields):extra_fields.setdefault('is_staff', True)extra_fields.setdefault('is_superuser', True)if extra_fields.get('is_staff') is not True:raise ValueError('Superuser must have is_staff=True.')if extra_fields.get('is_superuser') is not True:raise ValueError('Superuser must have is_superuser=True.')return self.create_user(email, password, **extra_fields)class CustomUser(AbstractBaseUser, PermissionsMixin):email = models.EmailField(unique=True)first_name = models.CharField(max_length=30, blank=True)last_name = models.CharField(max_length=30, blank=True)is_staff = models.BooleanField(default=False)is_active = models.BooleanField(default=True)date_joined = models.DateTimeField(auto_now_add=True)objects = CustomUserManager()USERNAME_FIELD = 'email'REQUIRED_FIELDS = []def __str__(self):return self.email
完成模型定义后，请在 settings.py 中指定 AUTH_USER_MODEL = 'yourapp.CustomUser'，并确保应用已加入 INSTALLED_APPS。这样 Django Admin 及其他认证组件将以你的自定义实现为基础运行。
2.3 自定义管理器与迁移
自定义管理器负责 创建普通用户与超级用户 的流程，并确保密码哈希、字段校验与唯一性等逻辑在创建阶段正确执行。完成设计后执行迁移：makemigrations 与 migrate，确保数据库结构与模型定义保持一致。
# 保留在同一个应用下的管理逻辑（示例）
# 已在上面的 CustomUserManager 中实现 create_user / create_superuser
3. 将自定义用户模型接入管理员后台
3.1 自定义 UserAdmin 的必要性
因为字段结构发生变化，默认的 Django Admin 用户管理界面不再完全适用，需要通过自定义 UserAdmin 来对字段、表单、以及新增用户的表单进行定制。从继承 Django 的 UserAdmin 开始，再覆写 add_form、form、fieldsets、add_fieldsets 等属性，可以实现和现有用户字段的一致性。
3.2 自定义表单与注册
通过自定义创建与修改表单，可以确保管理员账户的校验逻辑与普通用户一致，同时让 Admin 界面显示合适的字段。在 admin.py 中注册自定义 Admin，后台界面将以新结构呈现。
# admin.py
from django.contrib import admin
from django.contrib.auth.admin import UserAdmin
from .models import CustomUser
from .forms import CustomUserCreationForm, CustomUserChangeFormclass CustomUserAdmin(UserAdmin):model = CustomUserform = CustomUserChangeFormadd_form = CustomUserCreationFormlist_display = ('email', 'first_name', 'last_name', 'is_staff', 'is_active')list_filter = ('is_staff', 'is_active')search_fields = ('email', 'first_name', 'last_name')fieldsets = ((None, {'fields': ('email', 'password')}),('Personal info', {'fields': ('first_name', 'last_name')}),('Permissions', {'fields': ('is_active', 'is_staff', 'groups', 'user_permissions')}),('Important dates', {'fields': ('last_login', 'date_joined')}),)add_fieldsets = ((None, {'classes': ('wide',),'fields': ('email', 'password1', 'password2', 'is_staff', 'is_active')}),)ordering = ('email',)
admin.site.register(CustomUser, CustomUserAdmin)
3.3 常见问题及解决办法
如果管理员后台无法登录，需要逐项检查：is_staff 是否为 True、AUTH_USER_MODEL 是否正确、数据库迁移是否已应用、以及是否存在自定义认证后端导致的冲突。进一步确认后台登陆流程中使用的后端与自定义模型的字段映射一致性。
4. 解决管理员登录失败问题的排错流程
4.1 常见场景与排查清单
场景一：管理员无法登录后台。最常见原因是 is_staff 未设置为 True，导致后台入口被阻断。场景二：登录后退出或出现权限错误。需要检查 is_active、last_login 与会话相关配置。场景三：登录界面提示找不到用户字段。请确认 AUTH_USER_MODEL 指向的模型字段与 Admin 界面的字段映射。
在排错时，先对照以下要点进行自检：模型字段对齐、管理员字段分组、以及数据库迁移状态，确保前后端字段一致、且数据库结构正确。
4.2 示例排错流程与快速修复
快速排错的常用流程是通过 Django Shell 验证目标用户的状态与密码校验，然后在 Admin 配置中逐步验证字段映射是否正确。
# 使用 Django shell 演示排错
from django.contrib.auth import get_user_model
User = get_user_model()try:u = User.objects.get(email='admin@example.com')print('is_staff:', u.is_staff)print('is_active:', u.is_active)print('check_password:', u.check_password('你的管理员密码'))
except Exception as e:print('排错异常:', e)
若发现 is_staff 为 False，请在创建超级用户时显式设置 is_staff=True，或在自定义管理器中确保 create_superuser 的默认字段正确覆盖。
若 AUTH_USER_MODEL 不正确，需要在 settings.py 里调整，并重新应用迁移；确保 migrations 之间无冲突，避免字段缺失导致 Admin 登录异常。
4.3 部署与生产环境注意事项
生产环境应确保 HTTPS、CSRF 保护、以及正确的 SESSION、COOKIE 设置，以防止会话攻击影响管理员登录体验。同时，保留详细的日志记录，便于后续故障排查；在发布变更后，务必执行完整的数据库迁移并在测试环境验证管理员登录的稳定性。
本文围绕从原理到实操，全面解决管理员登录失败问题，通过对自定义用户模型、管理员后台接入与排错流程的系统讲解，帮助你在 Django 项目中实现稳定的管理员登录与权限管理。
