从PHP password_hash()迁移到Django：旧密码的平滑过渡策略

本教程旨在解决将使用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哈希值的方式是无效的：

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.username

2. 配置 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 None

3. 配置 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的平滑用户密码迁移，为用户提供无缝的登录体验，同时确保密码存储的安全性。

# php # word # python # go # 字节 # 后端 # csv # ai # django # php网站

返回目录在线咨询

上一篇：采用Webflow进行视觉开发时，响应式设计需要注意什么？
下一篇：浅谈PHP错误类型及屏蔽方法

您的项目需求

*请认真填写需求信息，我们会在24小时内与您取得联系。

全网整合营销服务商