本教程旨在解决将使用php `password_hash()`函数加密的用户密码迁移到django项目中的挑战。由于两种框架的密码哈希算法不兼容，直接导入会导致认证失败。文章将详细介绍一种实用的解决方案：通过在django用户模型中添加一个额外的字段来存储旧密码，并定制认证后端，实现在用户首次登录时使用`bcrypt`验证旧密码，并将其自动更新为django兼容格式，从而确保用户体验的平滑过渡。
引言：PHP password_hash()与Django密码兼容性问题
在将现有PHP网站的用户数据迁移到新的Django应用时，一个常见且棘手的问题是如何处理用户的密码。PHP的password_hash()函数通常生成以$2y$或$2a$开头的哈希值，这些哈希值是基于bcrypt算法的。然而，Django有其自己的默认密码哈希机制（如PBKDF2），并且其User模型在处理密码时，期望接收明文密码并自行进行哈希处理，或者接收符合其特定格式（通常包含哈希算法前缀）的已哈希密码。
当尝试将PHP生成的$2y$10$ZnxKDPbqOfACnGmQeN76o.UtdwWBFBCCLTiGnvCSvl/zqIBeVxhai这类哈希值直接赋给Django User对象的password字段，或通过User.objects.create_user()方法传入时，Django会将其误认为是明文密码，并尝试对其进行二次哈希，或者由于格式不识别而拒绝存储，导致用户无法正常登录。为了解决这一问题，我们需要一种策略来识别并验证这些旧的PHP密码，同时逐步将其迁移到Django的哈希格式。
解决方案概述：分步迁移策略
本教程将介绍一种“分步迁移”的策略。这种方法的核心思想是：
- 添加辅助字段： 在Django的用户模型中新增一个字段，专门用于存储来自PHP的原始哈希密码。
- 定制认证后端： 修改Django的认证后端，使其在默认密码验证失败时，尝试使用bcrypt算法验证辅助字段中的旧密码。
- 自动更新： 如果旧密码验证成功，则在用户首次登录时，将其密码更新为Django原生哈希格式，并存储到标准的password字段中，从而实现平滑迁移。
实施步骤
步骤一：扩展用户模型，添加 old_password 字段
首先，我们需要在Django的用户模型中添加一个字段来存储从PHP导入的旧密码。如果您的项目使用了自定义用户模型（推荐做法），可以直接在其models.py中添加。如果使用的是Django内置的User模型，则需要通过创建OneToOneField关联的方式进行扩展，或者更推荐的方法是使用AbstractUser或AbstractBaseUser来自定义用户模型。
立即学习“PHP免费学习笔记（深入）”；
以下是使用AbstractUser扩展用户模型的示例：
# myapp/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models
class CustomUser(AbstractUser):
# 现有字段...
old_password = models.CharField(max_length=255, blank=True, null=True, help_text="用于存储从旧PHP系统导入的密码哈希值")
# 可以添加其他自定义字段
# 例如：phone_number = models.CharField(max_length=15, blank=True, null=True)
class Meta:
verbose_name = '用户'
verbose_name_plural = '用户'
# 确保在settings.py中配置AUTH_USER_MODEL = 'myapp.CustomUser'完成模型定义后，运行数据库迁移命令：
python manage.py makemigrations myapp python manage.py migrate
步骤二：导入旧密码数据
在数据导入过程中，您需要将从PHP数据库中导出的用户密码哈希值，填充到新创建的old_password字段中。请确保您只将PHP的哈希值导入到old_password字段，而不要尝试填充到Django的password字段。
假设您有一个包含用户数据的CSV文件或通过ORM查询获取的数据，导入脚本可能类似于：
# import_users.py (示例脚本)
import csv
from django.contrib.auth import get_user_model
from django.db import transaction
# 确保已安装bcrypt: pip install bcrypt
import bcrypt
User = get_user_model()
def import_php_users(csv_file_path):
with open(csv_file_path, 'r', encoding='utf-8') as file:
reader = csv.DictReader(file)
users_to_create = []
for row in reader:
username = row['username']
email = row['email']
php_hashed_password = row['php_password_hash'] # 假设CSV中包含PHP哈希密码
# 创建用户，将PHP哈希密码存储到old_password字段
# 注意：这里不设置Django的password字段，或者可以设置一个临时密码
# 也可以先不设置password字段，让其在首次登录时由Django生成
user = User(
username=username,
email=email,
old_password=php_hashed_password
)
users_to_create.append(user)
with transaction.atomic():
User.objects.bulk_create(users_to_create, ignore_conflicts=True) # 忽略重复用户
print(f"成功导入 {len(users_to_create)} 位用户。")
if __name__ == '__main__':
# 假设您的CSV文件路径
import_php_users('path/to/your/php_users.csv')注意事项：
- 在导入时，old_password字段可以直接存储PHP生成的哈希字符串，无需任何额外处理。
- password字段可以留空，或者在用户首次登录时由Django自动设置。
步骤三：创建自定义认证后端
接下来，我们需要创建一个自定义的认证后端，它将处理用户登录请求。这个后端会在Django默认的密码验证失败时，检查old_password字段。
首先，确保您的环境中安装了bcrypt库：
pip install bcrypt
然后，在您的应用目录（例如myapp/）中创建一个backends.py文件，并添加以下代码：
# myapp/backends.py
from django.contrib.auth.backends import ModelBackend
from django.contrib.auth import get_user_model
import bcrypt # 导入bcrypt库
class PHPMigrationBackend(ModelBackend):
def authenticate(self, request, username=None, password=None, **kwargs):
User = get_user_model()
try:
user = User.objects.get(username=username)
except User.DoesNotExist:
return None
# 1. 尝试使用Django的默认密码验证机制
if user.check_password(password):
return user
else:
# 2. 如果Django默认验证失败，检查old_password字段
if user.old_password and user.old_password != "":
try:
# bcrypt.checkpw 期望字节串
# 将明文密码和存储的哈希密码转换为字节串进行比较
if bcrypt.checkpw(password.encode('utf-8'), user.old_password.encode('utf-8')):
# 3. 如果旧密码验证成功，更新用户密码为Django格式
user.set_password(password) # 这将使用Django当前的哈希算法重新哈希密码
user.old_password = "" # 清空旧密码字段
user.save()
return user
except ValueError:
# 如果old_password格式不正确，bcrypt可能会抛出ValueError
# 此时不进行处理，让认证失败
pass
return None # 密码不匹配
def get_user(self, user_id):
User = get_user_model()
try:
return User.objects.get(pk=user_id)
except User.DoesNotExist:
return None代码解释：
- authenticate方法是认证逻辑的核心。
- 它首先尝试通过username获取用户对象。
- user.check_password(password)会使用Django内置的哈希器验证密码。
- 如果内置验证失败，代码会检查user.old_password是否存在且不为空。
- bcrypt.checkpw()用于比较用户输入的明文密码和存储在old_password中的PHP哈希密码。注意，bcrypt.checkpw需要字节串作为输入，因此需要对密码进行编码。
- 如果bcrypt验证成功，说明用户使用了旧密码登录。此时，我们调用user.set_password(password)将用户的密码更新为Django的哈希格式，并清空old_password字段，然后保存用户对象。
- 这确保了用户在下次登录时将直接使用Django的哈希密码，不再需要通过old_password字段进行验证。
步骤四：注册自定义认证后端
最后一步是在Django项目的settings.py文件中注册您的自定义认证后端。确保将其放在默认的ModelBackend之前，以便它能优先处理认证逻辑。
# your_project/settings.py
AUTHENTICATION_BACKENDS = [
'myapp.backends.PHPMigrationBackend', # 您的自定义后端
'django.contrib.auth.backends.ModelBackend', # Django的默认后端
]
# 如果您使用了自定义用户模型，请确保也配置了它
AUTH_USER_MODEL = 'myapp.CustomUser' # 替换为您的应用名和模型名总结与注意事项
通过上述步骤，您已经成功建立了一个机制，允许Django应用识别并验证来自旧PHP网站的password_hash()密码，并在用户首次登录时将其平滑迁移到Django的哈希格式。
关键点回顾：
- 非破坏性迁移： 用户无需感知密码迁移过程，只需使用原有密码登录即可。
- 逐步迁移： 只有当用户登录时，其密码才会被更新。这对于拥有大量用户的系统来说，是一个资源友好的策略。
- 安全性： 在old_password字段中存储旧哈希值是临时的。一旦用户登录并密码更新，该字段就会被清空。
- 依赖： 确保安装了bcrypt库。
潜在优化与考虑：
- 性能： 对于每次登录尝试，如果Django默认验证失败，会额外执行一次bcrypt验证。对于高并发系统，这可能会带来轻微的性能开销，但在大多数迁移场景中是可以接受的。
- 强制迁移： 如果您希望在特定时间点强制所有用户迁移密码，可以考虑在后台任务中遍历所有带有old_password的用户，并提示他们重置密码。
- 自定义哈希器： 另一种更“Django化”的解决方案是编写一个自定义的密码哈希器，使其能够识别并验证PHP的bcrypt哈希。这种方法可以将PHP哈希直接存储在Django的password字段中，但实现起来更为复杂，需要深入理解Django的密码哈希器接口。本教程提供的方案是一个更直接、更易于实现的实用工作流程。
通过遵循本教程，您将能够为您的用户提供一个无缝的迁移体验，同时确保您新Django应用中的密码安全和兼容性。
