从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.s*e() # 这会导致密码字段为空或格式错误

# 方式二：使用 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. 运行数据库迁移

灵思AI

专业的智能写作辅助平台

163 查看详情

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.s*e()

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.s*e()
                        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的默认后端
]

工作原理总结

1. 当用户尝试登录时，Django的认证系统会按 AUTHENTICATION_BACKENDS 列表的顺序调用后端。
2. PHPPasswordAuthBackend 首先被调用。它会尝试查找用户。
3. 如果找到用户，它会先调用 user.check_password(password)，这是Django内置的密码验证方法。
   • 如果用户之前已经登录过（并且其密码已通过本机制更新为Django格式），则此检查会成功，用户登录。
4. 如果 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的默认认证机制。
5. 如果 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 password_hash()迁移到Django：旧密码的平滑过渡策略的详细内容，更多请关注php中文网其它相关文章！

# 创建一个  # 河南营销全网推广大概价格多少  # 佛山seo短视频优化策略  # 宜宾优化网站咨询  # 梅林网站建设  # 抚顺网站推广软件  # 台州新站seo优化  # 抖音搜索SEO八星  # 马鞍山怎么做网站优化  # 营销推广策划的意义  # seo内容收集整理  # 设置为  # 怎么看  # 可以直接  # 你可以  # php  # 它会  # 这是  # 首次  # 自定义  # php网站  # django  # ai  # csv  # 后端  # 字节  # go  # python  # word 

相关栏目： 【 Google疑问12 】 【 Facebook疑问10 】 【 优化推广96088 】 【 技术知识133117 】 【 IDC资讯59369 】 【 网络运营7196 】 【 IT资讯61894 】

相关推荐： C++如何使用CMake构建项目_C++ CMakeLists.txt编写入门教程  毒蘑菇VOLUMESHADER_BM官网首页登录入口 毒蘑菇VOLUMESHADER_BM官网首页登录入口说明  J*aScript桌面应用_Electron多进程架构实战  一加 Ace 6V 快充无法启用_一加 Ace 6V 充电优化  智云Q3和Q2有什么升级_智云Q3与Q2手持云台功能与性能对比分析  Win11怎么开启HDR_Windows 11显示器画质增强设置  《sketchbook》选中部分图案移动方法  苹果如何下载nanobanana  狙击外星人小游戏在线链接_狙击外星人小游戏网页链接  什么是Satis，如何用它搭建一个私有的composer仓库？  三角洲行动2025年9月10日摩斯密码分享  胃动力不足？试试这5个调理方法  C#解析并修改XML后保存 如何确保格式与编码的正确性  火狐浏览器无法自动更新怎么办 手动更新火狐浏览器到最新版本【解决】  QQ邮箱注册地址 免费获取QQ邮箱账号  《饿了么》拼好饭点外卖教程2025  PySimpleGUI中实现键盘按键与按钮事件绑定教程  解决VS Code中Python版本冲突与输出异常的指南  虫虫漫画绿色安全入口_虫虫漫画绿色安全入口安全看漫画  php如何实现多域名共享session_php存储session到redis与跨域读取配置  三星A55应用闪退排查步骤_Samsung A55稳定性优化技巧  苹果17 Pro如何启用分屏浏览_iPhone 17 Pro分屏浏览设置步骤  《撕歌》会员开通方法  《新三国志曹操传》游历事件袁尚突围攻略  J*aScript模块加载器_RequireJS原理分析  B站怎么开|直播| B站|直播|申请需要什么条件【新手必看】  被称为海蜈蚣的海洋动物是  小米civi如何设置锁屏时间  《虎扑》取消评分记录方法  知乎APP怎么查看自己被邀请的问题_知乎APP邀请回答记录查看与参与方法  126邮箱申请入口官网_126邮箱注册免费登录2025  Python测试中模块导入路径解析的最佳实践  PHP安全加载非公开目录图片与动态内容类型处理指南  4399正版网页版入口高清直达链接  《地下城堡4：骑士与破碎编年史》墓穴挑战125攻略  windows10怎么更改下载路径_windows10默认存储位置修改教程  电脑从睡眠中被自动唤醒怎么办_Windows唤醒源事件查看与禁用【解决】  J*aScript对象中深度嵌套URL键的查找与更新策略  FullCalendar自定义按钮样式定制指南  126邮箱网页在线登录2025_126邮箱网页版入口官方地址  抖音手机分身两个账号怎么切换？分身两个系统是一样的吗？  rabbitmq 持久化有什么缺点？  京东快递物流信息不更新怎么办_物流停滞原因与处理方法  《豆瓣》私信用户方法  Highcharts雷达图径向轴数值标签实现教程  如何在mysql中比较InnoDB和MyISAM区别  顺丰快递收费标准查询_如何查看顺丰最新收费价格  抖音作品被限流怎么办 抖音内容优化与流量恢复方法  vivo云服务一直提示空间不足怎么办 怎么办vivo云服务老是提示空间不足  晨报|开发商暗示《空洞骑士：丝之歌》DLC开发中 《合金装备4》有望重制 

 2025-12-03