企业官网建设流程全解析

• 后端
• 电商

本指南面向正在升级 django-oscar 的开发者，系统讲解 Oscar 升级过程中最容易出问题的环节——数据库迁移（migrations）的处理。Oscar 允许你 fork（分叉/覆盖）其任意 app 并扩展模型，因此升级时迁移策略取决于你对哪些 app 做过定制：本文按「未自定义」「自定义但模型未变」「自定义且模型已变」三种场景分别给出可落地的操作步骤与底层原理，并结合仓库中shippingapp 的真实迁移链与oscar_fork_app命令源码进行佐证。读完本文，你将能独立判断升级时的迁移风险，并熟练运用makemigrations、迁移拷贝、空迁移占位等手段平滑完成升级。

升级问题的根源：Oscar 的可定制架构

django-oscar 的领域模型分布在oscar.apps下的多个子应用中（如catalogue、basket、checkout、order、shipping等），每个应用都随发布版本附带自己的迁移文件。Oscar 的架构设计允许你用同名模块覆盖任意 app——这种机制称为 fork（分叉），具体操作流程参见 Forking an app 与 class loading 机制详解。

正是这种「可定制性」让升级时的迁移处理变得棘手：

• 如果某个新版本 Oscar 修改了某 app 的模型，并附带对应的迁移文件，你的项目能否顺利升级，取决于你是否 fork 过该 app、fork 时是否动过模型；
• fork 之后，你的本地 app 拥有自己的一套迁移历史，Oscar 上游新增的迁移无法自动生效，需要手动对接。

在动手升级前，建议先确认以下几点：

1. 你的INSTALLED_APPS中哪些是直接引用oscar.apps.*，哪些已经替换为本地同名 app；
2. 本地 app 是否复制了 Oscar 的migrations目录（迁移基线）；
3. 本地 app 的models.py是否继承并扩展了 Oscar 的抽象模型（如AbstractProduct、AbstractOrderAndItemCharges）。

下面进入三种迁移场景的详细处理方案。

场景一：未自定义的 app —— 直接使用 Oscar 上游迁移

如果你的INSTALLED_APPS中直接使用 Oscar 的原始 app（例如oscar.apps.shipping），那么升级会非常轻松：项目会自动继承 Oscar 新版本带来的迁移文件，你只需照常执行迁移命令即可。

以官方文档中的例子来说，假设你在INSTALLED_APPS中配置了oscar.apps.shipping，升级后只需运行：

./manage.py makemigrations shipping

接着执行迁移：

./manage.py migrate shipping

原理很简单：由于未 fork，Django 会直接从oscar.apps.shipping.migrations包读取迁移历史。新版本 Oscar 若在shipping应用中新增了迁移（比如新增字段、添加索引），这些迁移会作为依赖链上的新节点被 Django 检测并执行。

作为佐证，查看仓库中shippingapp 的迁移目录 src/oscar/apps/shipping/migrations/，可以看到一条完整的迁移链：

• 0001_initial.py：初始迁移，创建OrderAndItemCharges、WeightBand、WeightBased三个模型，且依赖address应用的0001_initial（因为这三个模型通过ManyToManyField关联address.Country）；
• 0002_auto_20150604_1450.py：调整countries字段的ManyToManyField定义；
• 0003_auto_20181115_1953.py：为name、upper_limit等字段添加db_index。

这些迁移正是「新版本 Oscar 附带迁移」的典型样例。未 fork 的项目升级时，Django 会按依赖顺序自动应用它们，无需任何手工干预。

场景二：自定义了 app 但模型未变 —— 拷贝迁移

如果你 fork 了某个 app（比如把oscar.apps.shipping换成了本地的myshop.shipping），但没有修改任何模型、也没有自己写过迁移，那么最稳妥的做法是：把新版本 Oscar 的迁移文件整体拷贝到你的本地 app 中，然后照常迁移。

这种做法的最大优势在于：能一并把上游的数据迁移（data migrations）带进来。Oscar 的部分历史版本会通过RunPython执行数据修复，例如重写 slug、迁移旧的取值等，这类逻辑只有通过拷贝迁移文件才能完整继承。

具体操作步骤（以shipping为例）：

1. 在虚拟环境中定位新版 Oscar 的安装路径，或直接 clone Oscar 仓库并 checkout 到与升级目标一致的版本 tag；
2. 找到对应应用的迁移目录：

$ cdsitepackages oscar/apps/shipping/migrations

3. 将其中所有*.py文件拷贝到你的本地 app 迁移目录：

$ copy *.py <your_project>/myshop/shipping/migrations/

注意：这里需要按你的实际项目路径调整，例如把<your_project>/myshop/shipping/migrations/换成你本地shipping应用的迁移目录。

4. 照常运行迁移：

./manage.py migrate shipping

在拷贝之前，务必确认你的本地 app尚未创建任何自定义迁移。一旦本地迁移历史与上游出现分叉，简单拷贝就不再适用，请直接进入场景三。

场景三：自定义了 app 且模型已变 —— 全面接管迁移链

如果你的 fork 已经走到「修改了模型」这一步（例如给模型加了字段、改了约束），那么你实际上已经从 Oscar 的迁移历史上彻底分叉（fork away）。此时没有捷径，需要逐一处理新版本 Oscar 发布的全部迁移。官方文档明确提醒了两点：

1. 必须通读该版本的 release notes——文档位于 docs/source/releases/（如 v4.2 发布说明），其中通常会点名提示哪些迁移比较棘手（例如涉及数据迁移或破坏性变更的）；
2. 如果存在数据迁移，你需要弄清它们做了什么，并大概率要在本地模仿实现同样的逻辑。

3.1 处理数据迁移（data migrations）

Oscar 发布的数据迁移通常使用RunPython操作。对于这类迁移，可行的策略是：把上游数据迁移中的RunPython函数体拷贝到你的本地迁移中，但要特别留意迁移依赖顺序——你的数据迁移必须声明正确的dependencies，确保它在相关 schema 变更之后、且在正确的时机执行。

例如，假设上游迁移对OrderAndItemCharges做了数据修复，你可以写一个本地迁移：

from django.db import migrations def fix_charges(apps, schema_editor): OrderAndItemCharges = apps.get_model("shipping", "OrderAndItemCharges") # ... 模仿上游 RunPython 的数据修复逻辑 class Migration(migrations.Migration): dependencies = [ ("shipping", "0003_auto_20181115_1953"), ] operations = [ migrations.RunPython(fix_charges, migrations.RunPython.noop), ]

这里dependencies指向你本地迁移链中的最新节点，从而保证执行顺序正确。

3.2 处理 schema 迁移（schema migrations）

对于纯结构变更的迁移，有时可以简单地对齐：

./manage.py makemigrations shipping

让 Django 根据你本地模型与迁移历史的状态差异自动生成新迁移，从而“镜像”Oscar 上游做过的模型变更。但这条命令并非万能：模型自定义与上游变更叠加时，生成的迁移可能与上游不完全一致，需要人工核对。

3.3 处理依赖错误：创建同名空迁移

分叉后最常见的报错是依赖错误（dependency errors）：新版 Oscar 的某个迁移dependencies中引用了你本地不存在的迁移节点（因为你的历史已经分叉）。

官方给出的解决思路是：创建一个与缺失迁移同名的空迁移（empty migration）来占位。空迁移只有name和dependencies，没有任何 operations，作用是让 Django 认为该节点存在，从而满足依赖解析：

from django.db import migrations class Migration(migrations.Migration): dependencies = [ ("shipping", "0001_initial"), # 这里列出来自上游、但你本地缺失的迁移 ] operations = []

这样上游迁移在声明依赖时就能找到对应节点，迁移计划得以继续执行。官方文档指出，如果遇到具体问题，可以在 django-oscar 邮件列表中寻求帮助。

3.4 借助oscar_fork_app降低手工成本

如果你尚未 fork、而是准备 fork 某个 app，仓库提供了自动化命令oscar_fork_app，定义于 src/oscar/management/commands/oscar_fork_app.py。它的核心逻辑调用oscar.core.customisation.fork_app（见 src/oscar/core/customisation.py），会自动完成「创建同名模块、复制 models/admin、复制 migrations 目录」等手工步骤，用法：

./manage.py oscar_fork_app shipping myshop/shipping

在 fork 时就把迁移基线一并复制好，可以避免后续升级时手动拷贝迁移的麻烦。完整的 fork 细节参见 Forking an app，模型扩展与「自定义模型不被识别」的排查技巧参见 How to customise models。

以shipping应用为例：从迁移链看懂三种场景

仓库中shipping应用的三条迁移正好可以用来对照上述场景：

假如你 fork 了shipping且给WeightBased加了max_weight字段，那么升级到附带0003的版本时，你就处于场景三：需要把0002、0003的变更意图（无论是通过拷贝迁移还是makemigrations生成）合并进你本地已分叉的迁移链，并为上游引用的迁移节点创建同名空迁移来解除依赖错误。

升级迁移清单与最佳实践

综合官方文档与仓库源码，一次稳妥的 Oscar 升级迁移可以按以下清单执行：

1. 盘点定制范围：确认每个 app 处于场景一、场景二还是场景三；
2. 阅读 release notes：查看 docs/source/releases/ 中对应版本的说明，留意被点名的棘手迁移；
3. 场景一：直接./manage.py migrate（或按 app 执行./manage.py migrate <app>）；
4. 场景二：从新版 Oscar 拷贝migrations目录到本地 app，再照常迁移；
5. 场景三：审查上游全部迁移；数据迁移模仿RunPython逻辑并声明正确依赖；schema 变更用makemigrations对齐或手工编写；对缺失的依赖节点创建同名空迁移占位；
6. 迁移前后对比验证：升级完成后检查django_migrations表记录与数据完整性，必要时在预发布环境先行演练。

几点提醒：不要轻易相信makemigrations能自动解决一切——模型自定义与上游变更叠加时，自动生成的迁移需要人工核对；数据迁移必须理解其业务意图而非机械拷贝；空迁移占位只是解除依赖错误的权宜之计，后续仍需保证你的本地迁移真正覆盖上游的变更效果。只要按这三种场景逐一处理，Oscar 的升级迁移过程就是可控且可复现的。

• 后端
• 电商