Django升级方案

Python2.x到SaaS可以先做一次python版本升级。

1. 安装2to3代码升级工具python3 -m pip install 2to3
2. 使用2to3进行代码升级python3 -m 2to3 -w {项目目录}

python2和python3差异

一、Django1.8升级到Django1.11.12

1.1 settings设置变动

变动:

1.2 路由定义变动

二、Django1.11升级到Django2.2.12

2.1 模型关系字段必须显式写 on_delete

在 Django 1.11 你可以写：

user = models.ForeignKey(User)

在 2.2 这是不合法的，必须指定：

user = models.ForeignKey(User, on_delete=models.CASCADE)

检查所有 ForeignKey、OneToOneField、ManyToManyField（虽然 ManyToMany 不需要 on_delete）并补齐。

升级注意事项

• 如果你原来在 1.11 中某些外键 没有 写 on_delete（默认是 CASCADE），在升级时必须显式指定一个行为（包括 models.PROTECT）；
• 已经写成 on_delete=models.PROTECT 的不需要因为版本换做别的处理。

2.2 MIDDELWARE_CLASSES 变更为MIDDELWARE

2.3 Django TEMPLATES配置变化

2.3.1 前因

• 在 Django 1.11 中，django.contrib.messages.context_processors.messages 和相关的 MessageMiddleware 虽然是推荐配置，但某些情况下，即使没有显式启用，后台也可能勉强运行（依赖旧版本的一些容错机制）。
• 很多老项目在 settings.py 里精简了 TEMPLATES 配置，只保留了自己需要的 context processor，没有把 messages 处理器写进去。
• 因为 Django 1.11 的 admin 对 messages 的强依赖校验不严格，所以这类问题没被暴露出来。

2.3.2 变化点（Django 2.0 ~ 2.2）

• 从 Django 2.0 开始，Django 官方在 admin 应用的系统检查 中加入了严格校验：如果你启用了 django.contrib.admin 但是 在 TEMPLATES 的 context_processors 里没有 django.contrib.messages.context_processors.messages 就会在 runserver 或 check 阶段直接报错 (admin.E404)。
• 这样做是为了保证 admin 的消息提示（保存成功、删除成功等）不会因为配置缺失而失效。

2.3.3 后果

• 升级到 Django 2.2 后，项目启动时就会抛出这个错误：(admin.E404) 'django.contrib.messages.context_processors.messages' must be enabled...
• 解决方法是：在 INSTALLED_APPS 里加入 django.contrib.messages在 MIDDLEWARE 里加入 django.contrib.messages.middleware.MessageMiddleware在 TEMPLATES[0]['OPTIONS']['context_processors'] 中加入 "django.contrib.messages.context_processors.messages"

2.4 自定义错误页面的函数签名变动

django1.11中，这些函数的签名都是一个参数：request， django2.x中“部分”函数签名改为 func(request, exception)。

2.5 模型与 app 相关

app 注册 / app_label

• 确保每个模型都属于一个已经在 INSTALLED_APPS 中注册的 app。
• 避免像你之前遇到的 RuntimeError: model ... doesn't declare an explicit app_label and isn't an application in INSTALLED_APPS：推荐做法：模型定义在 app 包（如 cmdb_collector/models.py）且 app 被加在 INSTALLED_APPS 里（最好用 AppConfig）。备选/边缘：若模型放在非标准位置，显式在 Meta 里写：class Meta: app_label = "cmdb_collector"

2.6 国际化函数变更

国际化函数

• 把 django.utils.translation.ugettext_lazy 替换为 gettext_lazy（ugettext_* 系列在未来已弃用）：from django.utils.translation import ugettext_lazy # 变更为：from django.utils.translation import gettext_lazy as _

2.7 mysqlclient/PyMySQL升级

推荐使用mysqlclient==1.4.6。去掉PyMySQL

2.8 middleware的定义方式发生改变

Django 1.11 到 2.2 Middleware 主要变化

2.8.1 Django 1.11 旧式中间件写法

# settings.pyMIDDLEWARE_CLASSES = [    'django.middleware.security.SecurityMiddleware',    'django.contrib.sessions.middleware.SessionMiddleware',    'myapp.middleware.LoginMiddleware',]​# myapp/middleware.pyclass LoginMiddleware(object):    def process_request(self, request):        print("请求开始")​    def process_view(self, request, view_func, view_args, view_kwargs):        print("请求调用视图之前")​    def process_response(self, request, response):        print("响应返回之前")        return response

• Django 会自动调用这些钩子方法。
• 中间件是老式，继承自 object，没有 __init__ 和 __call__。

2.8.2 Django 2.2 新式中间件写法

# settings.pyMIDDLEWARE = [    'django.middleware.security.SecurityMiddleware',    'django.contrib.sessions.middleware.SessionMiddleware',    'myapp.middleware.LoginMiddleware',]​# myapp/middleware.pyclass LoginMiddleware:    def __init__(self, get_response):        self.get_response = get_response  # 获取调用链的下一个中间件或视图​    def __call__(self, request):        # 请求处理代码（类似 process_request）        print("请求开始")​        response = self.get_response(request)  # 调用下一个中间件或视图​        # 响应处理代码（类似 process_response）        print("响应返回之前")​        return response

• __init__ 接收 get_response，保存调用链下一环。
• __call__ 中处理请求和响应逻辑。
• 旧的钩子 process_request、process_view、process_response 都没有了。

2.8.3 兼容旧式中间件写法：使用 MiddlewareMixin

如果你想用旧式钩子在 Django 2.2：

from django.utils.deprecation import MiddlewareMixin​class LoginMiddleware(MiddlewareMixin):    def process_request(self, request):        print("请求开始")​    def process_view(self, request, view_func, view_args, view_kwargs):        print("请求调用视图之前")​    def process_response(self, request, response):        print("响应返回之前")        return response

• MiddlewareMixin 帮你实现了 __init__ 和 __call__，让旧钩子在新中间件机制里生效。

2.8.4 适配总结：

• 把 MIDDLEWARE_CLASSES 改成 MIDDLEWARE。
• 自定义中间件改写为新式写法（推荐）。
• 如果暂时不能改写，继承 MiddlewareMixin 也能兼容旧式写法。

三、Django2.2升级到Django3.2

🚫 移除的功能（常见）

3.1 完全移除了django.utils.six

from django.utils.six.moves.urllib.parse import urlparse 需要修改为：from urllib.parse import urlparse

3.2 available_attrs 从 Django 3.1 开始被移除了

不要再使用 available_attrs，改用标准库 functools.wraps

如果你的旧代码是这样的：

from django.utils.decorators import available_attrsfrom functools import wraps​def my_decorator(view_func):    @wraps(view_func, assigned=available_attrs(view_func))    def _wrapped_view(request, *args, **kwargs):        # do something        return view_func(request, *args, **kwargs)    return _wrapped_view

请修改为：

from functools import wrapsdef my_decorator(view_func):    @wraps(view_func)    def _wrapped_view(request, *args, **kwargs):        # do something        return view_func(request, *args, **kwargs)    return _wrapped_view

3.3 从 Django 3.2 开始，如果你定义的模型中没有显式指定主键字段（id = models.AutoField(...)），django默认会使用BigAutoField (64-bit 自增主键)

Django 会发出如下提示：

You didn't explicitly set a default `auto_field`, so Django is assuming `BigAutoField`.

3.3.1 解决方法（推荐方式）

方法 1：在 settings.py 中设置全局默认主键类型（推荐）

在你的项目的 settings.py 中添加：

DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'

这样，所有未指定主键字段的模型都将默认使用 BigAutoField，并且不会再显示提示信息。

方法 2：在模型中手动指定主键类型（可选）

from django.db import models​class MyModel(models.Model):    id = models.AutoField(primary_key=True)  # 或 BigAutoField    name = models.CharField(max_length=100)

如果你只想对某些模型使用 AutoField 或 BigAutoField，可以在模型中手动指定。

3.4 django-cors-headers问题

3.4.1 版本问题

推荐：使用3.10.x - 4.2.x

3.4.2 CorsMiddleware中间件问题

CorsMiddleware 必须放在中间件最前面或靠前的位置，否则不生效。

3.4.3 cors配置

CORS_ORIGIN_WHITELIST 需要变更为 CORS_ALLOW_ALL_ORIGINS。

3.5 whitenoise中间变更

版本要使用：5.2 ~ 5.3.0。

四、python3.6升级到python3.11.10

4.1 代码操作指引

4.1.1. 获取推荐版本

我们将所有依赖库主要分为两大类：“语言/框架”和“常规库”。其中，“语言/框架”指 Python、Django 这类组件，它们处于项目的核心位置，对项目功能影响显著，实施升级所需要的工作量也通常比较大。“常规库”指其他的依赖库，如 requests 等，升级所需的工作量较小。

• 语言和框架（2024.11） Python 语言：

• 常规库 :

• 禁用库 Python 语言

注：当前，表格中各依赖库的推荐版本来自文档苏研院平台漏洞扫描组件升级分析。由于该分析报告生成于 2024 年上半年，因此，其中部分版本号可能已过时。针对已过时的条目，等待具体实施升级时，再做针对性调整。

版本更新策略:

• 如果 patch 版本号有更新，总是优先使用新版本，比如总是用 1.2.4 替代 1.2.3。
• 12.2 updated：依赖包如果不在表格里，先确认包是否在项目中是冗余的，如果冗余直接去掉，如果用到了默认先尝试升到最新。

4.2 celery必须升级到celery5.x版本。

• 在 Celery 3.x 和 4.x 版本中，@periodic_task 是常用的周期任务装饰器，用于直接在任务函数上声明执行频率。
• 从 Celery 5.x 开始，官方移除了 @periodic_task 装饰器，不再支持这种写法。
• 现在推荐通过配置 beat_schedule 来管理周期任务。

Celery 5.x 定义周期任务的推荐方式：

1. 定义普通任务from celery import Celeryapp = Celery('proj')@app.taskdef my_periodic_task(): print("This runs periodically")
2. 通过 beat_schedule 配置周期任务from celery.schedules import crontabapp.conf.beat_schedule = { 'run-every-5-minutes': { 'task': 'proj.my_periodic_task', # 任务路径 'schedule': crontab(minute='*/5'), # 相当于3.x中的periodic_task的runevery参数（如：contab示例） # 'args': (), # 如果需要传参数 },}

五、Django3.2升级到Django4.2

5.1 数据库改动

如何兼容 MySQL 5.7

最重要的改动是 4.2 版本不再支持 MySQL 5.7。

如果仍旧存在项目无法升级到 MySQL 8，那么可以考虑引入一个 Patch 来临时解决问题：

from django.db.backends.mysql.features import DatabaseFeaturesfrom django.utils.functional import cached_property​class PatchFeatures:    @cached_property    def minimum_database_version(self):        if self.connection.mysql_is_mariadb:            return (10, 4)        else:            return (5, 7)

目前 Django 仅是对 5.7 做了软性的不兼容改动，在没有使用 8.0 特异的功能时，对 5.7 版本的使用无影响

DatabaseFeatures.minimum_database_version = PatchFeatures.minimum_database_version

5.2 安全相关配置改动

1. CSRF_TRUSTED_ORIGINS

CSRF 现在会参考 Origin Header，如果使用了 CSRF_COOKIE_NAME，就需要在 settings 中额外配置 CSRF_TRUSTED_ORIGINS。例子：

CSRF_TRUSTED_ORIGINS = ["https://*.example.com", "http://*.example.com"]

1. SECURE_PROXY_SSL_HEADER

用于控制 CSRF 模块如何判断请求是否安全，如果在内网调用可以考虑配置修改这个配置，具体的情况可以参考 官方文档。

SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")

1. SECURE_CROSS_ORIGIN_OPENER_POLICY

SecurityMiddleware 现在添加了值为“same-origin”的 Cross-Origin Opener Policy 标头，以防止跨源弹出窗口共享相同的浏览上下文。对我们的登出功能有影响，需要手动修改默认值：

SECURE_CROSS_ORIGIN_OPENER_POLICY = "unsafe-none"

5.4 request.is_ajax()

Django 3.0：仍保留is_ajax()，但未标记为弃用。 ​​Django 3.1​​：正式移除该方法，改为推荐手动检查请求头X-Requested-With。 替换方法：

def is_ajax(request):    return request.headers.get('X-Requested-With') == 'XMLHttpRequest'​# 使用is_ajax(request)

5.5 其他函数变动

如果你的项目里大量使用了需要修改的内容，可以考虑使用 django-upgrade 工具自动进行转换（需要先升级到 Py3.10）。

5.6 新增的内容

5.6.1“更安全”的密码加密算法

用更多的内存防止黑客并行爆破的“更安全”的加密算法 scrypt。（注：用户管理项目可以参考）

5.6.2 官方支持的 RedisCache Backend

相较于社区方案 django-redis，官方提供的功能更为基础，除非是新项目，否则更建议直接升级到原有的 django-redis 库的支持 Django 4 版本。

5.6.3 异步 View 类 和 ORM 接口

算是补全了更多层次的 Django 操作，可以更容易地作异步数据查询：

user = await Creators.object.afirst()

考虑到大部份项目并没有使用上 async 特性，仅需要保持关注即可。