Wagtail添加新集合触发Integrity Error：违反唯一约束

问题概述 #

在Wagtail中为100余名用户各创建独立集合后，通过管理界面重命名集合，后续添加新集合时常触发Integrity Error，提示违反唯一约束/重复键。该问题已在全新Wagtail环境中复现。

复现步骤 #

• 基于Wagtail 2.15.5、Python 3.6、Django 3.2、SQLite搭建环境，创建超级用户后启动服务器
• 进入后台管理地址http://127.0.0.1:8000/admin，依次点击Settings → Collections
• 创建根集合的子集合：A collection、M collection、Z collection、Test collection
• Wagtail默认按名称字母顺序排序集合，Treebeard自动调整新集合路径，因此Test collection被排序在M collection和Z collection之间
• 将Test collection重命名为A Test collection，但集合的path字段未自动更新
• 尝试添加根集合的子集合A new collection，触发Integrity Error

原因分析 #

Treebeard的MP树排序逻辑依赖集合的path字段，但Wagtail管理界面重命名集合时，不会自动更新path以匹配新的名称排序。当添加名称排序在M collection之前的新集合时，Treebeard会执行以下路径更新SQL：

UPDATE "wagtailcore_collection" SET path='00010003'||SUBSTR(path, 9) WHERE path LIKE '00010002%'

此时A Test collection的路径已经是00010003，SQL执行后会导致路径重复，触发唯一约束错误。

从数据库查询结果可明确看到名称排序与路径的矛盾：

sqlite> select id, name, path from wagtailcore_collection order by name;
5|A Test collection|00010003
2|A collection     |00010001
3|M collection     |00010002
1|Root             |0001
4|Z collection     |00010004

解决方案与规避方法 #

1. 非破坏性路径修复（生产环境推荐） #

手动调整集合路径，使其与名称排序一致。可通过Django shell执行以下逻辑（执行前务必备份数据库）：

from wagtail.core.models import Collection
from django.db.models import F

# 获取根集合
root = Collection.get_first_root_node()
# 按名称排序根集合的子节点
sorted_children = root.get_children().order_by('name')

# 批量更新路径，确保顺序匹配
with Collection.objects.delay_mptt_updates():
    for index, child in enumerate(sorted_children, start=1):
        # 生成新路径：根路径 + 4位序号（补零）
        new_path = f"{root.path}{index:04d}"
        old_path = child.path
        
        if old_path != new_path:
            # 更新当前节点路径
            child.path = new_path
            child.save()
            
            # 更新该节点所有后代的路径前缀
            child.get_descendants().update(
                path=F('path').replace(old_prefix=old_path, new_prefix=new_path)
            )

操作建议：选择低峰时段执行，避免影响正常业务。

2. 日常操作规避方法 #

• 重命名集合后，手动在后台通过拖拽调整集合的排序位置，触发Treebeard自动更新路径，确保路径与排序一致
• 新增集合时，先创建名称排序在现有集合末尾的临时集合，再重命名并调整到目标位置，避免触发路径冲突
• 升级Wagtail版本：后续Wagtail版本已优化Treebeard的兼容逻辑，可尝试升级至最新稳定版（注意验证版本兼容性）

3. 临时应急修复 #

若已触发错误，可尝试使用非破坏性修复命令（不会删除关联的图片/文档）：

from wagtail.core.models import Collection
Collection.fix_tree(destructive=False)

注意：执行前需在测试环境验证效果，确保数据安全。

内容的提问来源于stack exchange，提问作者Kristin