本教程旨在解决将使用PHP `password_hash()`算法加密的旧网站用户密码迁移到Django新站点的挑战。由于Django默认不识别PHP的密码格式，直接导入会导致认证失败。文章将介绍一种分步迁移策略：通过扩展用户模型添加一个字段来存储旧密码，并定制Django的认证后端，在用户首次登录时透明地验证旧密码并将其更新为Django兼容的格式，实现用户体验无缝过渡。
在将现有用户数据从一个使用PHP password_hash()进行密码加密的系统迁移到Django时，开发者常面临一个核心挑战：Django的认证系统默认无法识别PHP生成的密码哈希（例如 $2y$10$ZnxKDPbqOfACnGmQeN76o.UtdwWBFBCCLTiGnvCSvl/zqIBeVxhai 这种格式）。直接将这些哈希值导入到Django User 模型的 password 字段会导致“无效密码格式或未知哈希算法”的错误，用户将无法登录。本文将提供一个实用的解决方案，通过定制Django的认证流程，实现旧密码的平滑过渡。
理解问题根源
Django的 User 模型使用内置的密码哈希器来存储密码，这些哈希器通常是 PBKDF2、Bcrypt（Django自己的实现）或 Argon2 等，并且其存储格式与PHP的 password_hash() 函数生成的哈希格式不同。因此，即使将PHP的哈希值直接赋给 user.password 字段，Django也无法正确验证。
例如，以下尝试直接导入PHP哈希值的方式是无效的：
立即学习“PHP免费学习笔记（深入）”；
from django.contrib.auth.models import User # 方式一：直接赋值 # usertest = User(username='testguy', email='test@example.com', password='$2y$10$ZnxKDPbqOfACnGmQeN76o.UtdwWBFBCCLTiGnvCSvl/zqIBeVxhai') # usertest.save() # 这会导致密码字段为空或格式错误 # 方式二：使用 create_user # User.objects.create_user(username='testguy', email='test@example.com', password='$2y$10$ZnxKDPbqOfACnGmQeN76o.UtdwWBFBCCLTiGnvCSvl/zqIBeVxhai') # 这种方式会将整个哈希字符串作为明文密码再次哈希，导致实际存储的密码并非预期的PHP哈希，用户也无法登录。
为了解决这个问题，我们需要一种机制，既能存储旧的PHP哈希，又能让Django在用户尝试登录时识别并验证它们，最终将密码更新为Django兼容的格式。
解决方案：增量式密码迁移策略
本策略的核心思想是：不在Django的默认 password 字段中存储PHP哈希，而是为旧密码创建一个单独的字段，并在用户首次登录时，通过自定义认证后端来验证旧密码，然后将其转换为Django兼容的格式。
步骤一：扩展Django用户模型，添加 old_password 字段
首先，你需要一个地方来存储从PHP网站导入的原始密码哈希。最佳实践是创建一个自定义用户模型（如果尚未创建），并添加一个 old_password 字段。
1. 创建自定义用户模型 (如果尚未创建)
在你的应用（例如 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)
# 可以添加其他自定义字段
# 例如：some_other_field = models.CharField(max_length=100)
def __str__(self):
return self.username2. 配置 settings.py 使用自定义用户模型
在你的 settings.py 中指定 AUTH_USER_MODEL：
# settings.py AUTH_USER_MODEL = 'users.CustomUser'
3. 运行数据库迁移
python manage.py makemigrations users python manage.py migrate
如果你的项目已经在使用 AbstractUser 或 AbstractBaseUser 的自定义用户模型，只需在现有模型中添加 old_password 字段并运行迁移即可。
步骤二：导入旧密码到 old_password 字段
在数据导入过程中，将从PHP网站获取的原始密码哈希（例如 $2y$10$...）存储到 CustomUser 模型的 old_password 字段中。务必不要将这些哈希值放入默认的 password 字段。
# 假设你有一个从PHP数据库导出的用户列表
import_data = [
{'username': 'testguy', 'email': 'test@example.com', 'php_password_hash': '$2y$10$ZnxKDPbqOfACnGmQeN76o.UtdwWBFBCCLTiGnvCSvl/zqIBeVxhai'},
# ... 更多用户数据
]
from users.models import CustomUser
for user_data in import_data:
user, created = CustomUser.objects.get_or_create(
username=user_data['username'],
defaults={
'email': user_data['email'],
# 将PHP哈希存储到 old_password 字段
'old_password': user_data['php_password_hash'],
# 默认的 password 字段可以留空，或者设置为一个无法使用的值
# Django 会在用户首次登录时自动设置新的 password
}
)
if not created:
# 如果用户已存在，更新 old_password 和 email
user.email = user_data['email']
user.old_password = user_data['php_password_hash']
user.save()
print("用户数据导入完成，旧密码已存储到 old_password 字段。")步骤三：创建自定义认证后端
这是实现兼容性的关键步骤。我们将创建一个自定义认证后端，它将首先尝试使用Django的默认机制验证密码。如果失败，并且用户存在 old_password，它将使用 bcrypt 库来验证PHP哈希。如果验证成功，用户的 password 字段将被更新为Django兼容的格式，以便将来的登录可以直接使用Django的默认认证。
1. 安装 bcrypt 库
PHP的 password_hash() 函数默认使用 bcrypt 算法。因此，我们需要在Python环境中安装 bcrypt 库来验证这些哈希。
pip install bcrypt
2. 创建 backends.py 文件
在你的应用（例如 users）中创建 backends.py：
# users/backends.py
from django.contrib.auth.backends import ModelBackend
from django.contrib.auth import get_user_model
import bcrypt
class PHPPasswordAuthBackend(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
# 尝试使用Django内置的密码检查机制
# 如果用户之前已经登录并更新了密码，这里会成功
if user.check_password(password):
return user
else:
# 如果Django密码检查失败，检查是否存在旧的PHP密码
if user.old_password and user.old_password.startswith('$2y$'):
try:
# bcrypt.checkpw 期望字节串
# 将明文密码和存储的旧哈希转换为字节串进行比较
if bcrypt.checkpw(password.encode('utf-8'), user.old_password.encode('utf-8')):
# 旧密码验证成功！
# 更新用户的密码为Django兼容的格式，并清除 old_password 字段
user.set_password(password) # 使用Django的哈希器重新哈希新密码
user.old_password = None # 清除旧密码字段
user.save()
return user
except ValueError:
# bcrypt.checkpw 可能因为哈希格式问题抛出 ValueError
# 记录错误或忽略，继续返回 None
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 None3. 配置 settings.py 使用自定义认证后端
在 settings.py 中，将你的自定义后端添加到 AUTHENTICATION_BACKENDS 列表中。确保你的自定义后端在 ModelBackend 之前，这样它有机会首先处理认证逻辑。
# settings.py
AUTHENTICATION_BACKENDS = [
'users.backends.PHPPasswordAuthBackend', # 你的自定义后端
'django.contrib.auth.backends.ModelBackend', # Django的默认后端
]工作原理总结
- 当用户尝试登录时，Django的认证系统会按 AUTHENTICATION_BACKENDS 列表的顺序调用后端。
- PHPPasswordAuthBackend 首先被调用。它会尝试查找用户。
- 如果找到用户，它会先调用 user.check_password(password)，这是Django内置的密码验证方法。
- 如果用户之前已经登录过（并且其密码已通过本机制更新为Django格式），则此检查会成功，用户登录。
- 如果 user.check_password(password) 失败，PHPPasswordAuthBackend 会检查 user.old_password 字段。
- 如果 old_password 存在且是PHP的 $2y$... 格式，它会使用 bcrypt.checkpw() 来验证用户输入的明文密码和存储的旧哈希。
- 如果 bcrypt 验证成功，这意味着用户使用了正确的旧密码。此时，系统会立即使用 user.set_password(password) 将用户输入的明文密码重新哈希并存储到 user.password 字段中（使用Django的默认哈希算法），并清除 user.old_password 字段。这样，用户下次登录时就可以直接通过Django的默认认证机制。
- 如果 PHPPasswordAuthBackend 无法认证用户，它会返回 None，Django会继续尝试列表中的下一个后端（即 ModelBackend）。
注意事项与最佳实践
- 安全性： 这种方法是安全的，因为旧的PHP哈希从未被直接转换或暴露，而是通过验证后生成新的Django哈希。
- 性能： 对于仍存储在 old_password 字段中的用户，每次登录尝试都会额外进行一次 bcrypt 验证。一旦用户登录并更新了密码，这个额外的开销就会消失。
- 字段清理： 随着时间的推移，所有用户都将登录并将其密码更新为Django兼容的格式，old_password 字段将逐渐变空。当确认所有（或绝大多数）用户都已迁移后，你可以考虑从 CustomUser 模型中移除 old_password 字段，并删除自定义认证后端。
- 错误处理： 在实际生产环境中，你可能希望在 bcrypt.checkpw 失败时添加更详细的日志记录，以便追踪潜在问题。
- 兼容性： 确保你的PHP password_hash() 使用的是 PASSWORD_BCRYPT 算法，因为这是 bcrypt 库支持的。
- 初始密码为空或无效： 如果在导入时 password 字段留空，用户首次登录必须通过 old_password 验证。如果 password 字段被设置为一个Django能识别但无效的哈希（例如 !），则 user.check_password() 会失败，然后会尝试 old_password。
通过上述步骤，你可以实现从PHP password_hash() 到Django的平滑用户密码迁移，为用户提供无缝的登录体验，同时确保密码存储的安全性。
