本教程详细介绍了将使用php `password_hash()`算法加密的旧用户密码安全迁移至django新站点的策略。由于django与php的哈希机制不兼容，文章提出了一种通过扩展用户模型、存储旧哈希值，并利用自定义认证后端在用户登录时逐步更新密码的方法，确保平滑过渡和用户体验，避免直接导入导致的密码格式错误。
在将现有用户数据从使用PHP password_hash()函数加密密码的旧站点迁移到新的Django应用时，开发者常会遇到密码哈希不兼容的问题。Django拥有自己的密码哈希算法（如PBKDF2），无法直接识别和验证PHP的password_hash()（通常是bcrypt）生成的哈希值，这导致用户无法使用其旧密码登录。本文将提供一个分步指南，通过引入自定义字段和修改认证后端来解决这一挑战，实现用户密码的平滑过渡。
挑战：PHP password_hash()与Django密码哈希不兼容
PHP的password_hash()函数通常使用bcrypt算法（由$2y$前缀标识）生成密码哈希。例如：$2y$10$ZnxKDPbqOfACnGmQeN76o.UtdwWBFBCCLTiGnvCSvl/zqIBeVxhai。直接将这些哈希值导入到Django User模型的password字段会导致“无效密码格式或未知哈希算法”的错误，因为Django期望其内部支持的哈希格式。简单地使用User.objects.create_user()并传入旧哈希值，会导致该哈希值本身被当作明文密码再次哈希，从而无法匹配。
解决方案概述：自定义字段与自定义认证后端
解决此问题的方法是：
- 扩展用户模型：为用户模型添加一个新字段，用于存储旧的PHP密码哈希。
- 导入旧密码：将旧站点中的PHP哈希值导入到这个新字段中。
- 实现自定义认证后端：在用户尝试登录时，首先尝试Django的默认密码验证。如果失败，则使用bcrypt库验证新字段中的旧哈希。如果验证成功，则更新用户的密码为Django支持的格式，并将其保存。
步骤一：扩展Django用户模型
为了存储旧的PHP密码哈希，我们需要在Django的用户模型中添加一个新字段。推荐的做法是创建一个自定义用户模型，或者扩展Django的AbstractUser。
立即学习“PHP免费学习笔记（深入）”；
首先，在你的应用（例如users）的models.py中定义一个自定义用户模型：
# users/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models
class CustomUser(AbstractUser):
# 添加一个字段来存储旧的PHP密码哈希
old_password = models.CharField(max_length=255, blank=True, null=True)
# 可以添加其他自定义字段
# bio = models.TextField(blank=True, null=True)
class Meta:
verbose_name = "用户"
verbose_name_plural = "用户"
def __str__(self):
return self.username
接下来，在settings.py中配置Django使用你的自定义用户模型：
# your_project/settings.py AUTH_USER_MODEL = 'users.CustomUser' # 替换为你的应用名和模型名
完成模型定义后，运行数据库迁移：
python manage.py makemigrations users python manage.py migrate
步骤二：导入旧密码到新字段
现在，你可以将旧PHP站点中的用户数据导入到Django。在导入过程中，将PHP生成的密码哈希值存储到CustomUser模型中的old_password字段，而不是password字段。
以下是一个概念性的导入脚本示例，你需要根据你的具体数据源和导入方式进行调整：
# import_users.py (或在Django shell中执行)
import os
import django
from django.conf import settings
# 确保Django环境已设置
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'your_project.settings')
django.setup()
from users.models import CustomUser # 导入你的自定义用户模型
# 假设你有一个包含旧用户数据的列表或CSV文件
# 示例数据结构：[{'username': 'testguy', 'email': 'test@example.com', 'php_password_hash': '$2y$10$ZnxKDPbqOfACnGmQeN76o.UtdwWBFBCCLTiGnvCSvl/zqIBeVxhai'}]
old_users_data = [
{'username': 'testguy', 'email': 'test@example.com', 'php_password_hash': '$2y$10$ZnxKDPbqOfACnGmQeN76o.UtdwWBFBCCLTiGnvCSvl/zqIBeVxhai'},
# 更多用户数据...
]
for user_data in old_users_data:
try:
user, created = CustomUser.objects.get_or_create(
username=user_data['username'],
defaults={
'email': user_data['email'],
'old_password': user_data['php_password_hash'],
# 注意：不要在此处设置password字段为php_password_hash
# 如果是新用户，可以设置一个临时密码或留空
'password': '', # 留空或设置一个不可用的哈希
}
)
if not created:
# 如果用户已存在，可以选择更新其信息或跳过
user.email = user_data['email']
user.old_password = user_data['php_password_hash']
user.save()
print(f"用户 {user.username} 导入成功。")
except Exception as e:
print(f"导入用户 {user_data['username']} 时发生错误: {e}")
步骤三：实现自定义认证后端
这是实现兼容性检查的关键步骤。我们将创建一个自定义认证后端，在Django默认认证失败时，尝试使用bcrypt库验证old_password字段。
首先，安装bcrypt库：
pip install bcrypt
接下来，在你的应用（例如users）中创建一个backends.py文件：
# users/backends.py
import bcrypt
from django.contrib.auth.backends import ModelBackend
from django.contrib.auth import get_user_model
class PHPHashCheckingBackend(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验证失败，检查是否存在旧的PHP哈希密码
if user.old_password:
try:
# bcrypt.checkpw 期望字节串
# 将明文密码和存储的旧哈希转换为字节串
if bcrypt.checkpw(password.encode('utf-8'), user.old_password.encode('utf-8')):
# 3. 如果旧密码匹配，则更新用户的密码为Django格式
# 这样下次登录时就会使用Django的原生哈希
user.set_password(password)
user.old_password = None # 清除旧密码，标记为已迁移
user.save()
return user
except ValueError:
# bcrypt.checkpw可能会在哈希格式不正确时抛出ValueError
# 例如，如果old_password不是有效的bcrypt哈希
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
最后，在settings.py中注册你的自定义认证后端：
# your_project/settings.py
AUTHENTICATION_BACKENDS = [
'users.backends.PHPHashCheckingBackend', # 你的自定义后端
'django.contrib.auth.backends.ModelBackend', # Django的默认后端
]注意： AUTHENTICATION_BACKENDS的顺序很重要。Django会按顺序尝试每个后端，直到有一个后端成功认证用户。在这个例子中，我们的自定义后端应该放在ModelBackend之前，或者在ModelBackend之后，取决于你希望优先处理哪种验证逻辑。如果你的自定义后端在ModelBackend之前，它会先尝试自定义逻辑。如果放在之后，它会在Django默认验证失败后才被调用。在上述代码中，我们的自定义后端已经包含了对user.check_password(password)的初步检查，所以它可以放在ModelBackend之前。
注意事项与最佳实践
- 安全性：将旧哈希存储在old_password字段中，虽然是临时的解决方案，但仍需确保该字段受到与password字段相同的保护。一旦用户通过旧密码登录并成功迁移到Django哈希，建议将old_password字段清空或设为None。
- 逐步迁移：此方法实现了密码的逐步迁移。只有当用户使用其旧密码成功登录后，其密码才会被更新为Django的哈希格式。这确保了平滑的用户体验，无需强制所有用户立即重置密码。
- 性能：在每次登录时进行两次密码验证（Django默认哈希和bcrypt哈希）可能会略微增加认证时间。但考虑到密码迁移通常是短期需求，这种性能影响通常可以接受。
- 错误处理：bcrypt.checkpw函数要求输入是字节串。确保在调用时使用.encode('utf-8')进行转换。同时，如果old_password不是有效的bcrypt哈希，bcrypt.checkpw可能会抛出ValueError，需要进行适当的错误处理。
- 清除旧字段：在所有用户都迁移完成后，你可以考虑从CustomUser模型中删除old_password字段，并再次运行迁移。
总结
通过上述步骤，你可以成功地将使用PHP password_hash()加密的旧用户密码迁移到Django新站点。这种方法不仅解决了哈希算法不兼容的问题，还提供了一种平滑的用户过渡机制，避免了强制用户重置密码的麻烦。一旦用户登录，其密码将自动更新为Django的原生哈希格式，从而实现了无缝迁移。
