Django自定义用户模型在Admin面板操作时触发FOREIGN KEY约束失败

遇到这种外键约束失败的问题，大概率是自定义用户模型和Django自带的关联表（比如权限、组）的关系没配置对，或者Admin/表单的配置有遗漏。我来给你梳理几个最常见的排查方向：

Django默认用户模型关联了auth.Group和auth.Permission，如果你的自定义模型没处理好这些关联，Admin操作时就会触发外键约束：

• 如果你继承的是AbstractUser：它已经自带groups和user_permissions字段，别手动覆盖这些字段，或者覆盖时必须用正确的外键关联逻辑。
• 如果你用的是AbstractBaseUser：必须手动添加这两个关联字段，而且要指定唯一的related_name避免和默认用户模型冲突，示例代码如下：

  from django.contrib.auth.models import Group, Permission
  
  class CustomUser(AbstractBaseUser, PermissionsMixin):
      # 你的其他自定义字段...
      groups = models.ManyToManyField(
          Group,
          verbose_name='用户组',
          blank=True,
          related_name="custom_user_set",
          related_query_name="user",
      )
      user_permissions = models.ManyToManyField(
          Permission,
          verbose_name='用户权限',
          blank=True,
          related_name="custom_user_set",
          related_query_name="user",
      )
  

自定义UserAdmin时，别遗漏关联字段的管理：

• 如果你继承了django.contrib.auth.admin.UserAdmin，要确保fieldsets和add_fieldsets包含groups、user_permissions（如果需要这些功能）；如果不需要，也要确保数据库里没有依赖这些字段的约束。
• 示例正确的Admin配置片段：

  from django.contrib.auth.admin import UserAdmin
  from .models import CustomUser
  
  class CustomUserAdmin(UserAdmin):
      model = CustomUser
      # 继承默认字段集，添加自定义字段
      fieldsets = UserAdmin.fieldsets + (
          ('自定义信息', {'fields': ('nickname',)}),
      )
      add_fieldsets = UserAdmin.add_fieldsets + (
          ('自定义信息', {'fields': ('nickname',)}),
      )
  
  admin.site.register(CustomUser, CustomUserAdmin)
  

• 先确认所有迁移都已执行：运行python manage.py makemigrations和python manage.py migrate，有时候未完成的迁移会导致数据库结构和模型不一致。
• 如果你是中途从默认用户模型切换到自定义模型：Django不支持已有数据时直接切换，数据库里的auth_permission、auth_group等表可能还关联着旧用户模型的ID，导致约束失败。开发环境可以尝试清空数据库、重新迁移、创建新超级用户再测试。

如果你的UserCreationForm或UserChangeForm没正确关联自定义模型，也会导致保存失败：

• 确保表单继承自正确的基类，并且Meta类指定了你的自定义用户模型，示例：

  from django.contrib.auth.forms import UserCreationForm, UserChangeForm
  from .models import CustomUser
  
  class CustomUserCreationForm(UserCreationForm):
      class Meta(UserCreationForm.Meta):
          model = CustomUser
          fields = UserCreationForm.Meta.fields + ('nickname',)
  
  class CustomUserChangeForm(UserChangeForm):
      class Meta(UserChangeForm.Meta):
          model = CustomUser
  

DEBUG模式下，Django的错误页面会显示具体的约束失败信息——比如是哪个表、哪个字段的约束出了问题。找到错误堆栈里的DatabaseError详情，能帮你精准定位问题（比如如果是auth_user_groups表报错，那就是用户和组的关联有问题）。

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