Cherry Studio v1→v2 文件迁移器 FileMigrator 深度解析:从 Dexie files 表到 SQLite file_entry 的完整数据保全方案
Cherry Studio v1→v2 文件迁移器 FileMigrator 深度解析:从 Dexie files 表到 SQLite file_entry 的完整数据保全方案
导读
FileMigrator 是 Cherry Studio 数据库 v2 迁移体系中负责文件数据搬迁的核心组件:它将 v1 时代存储在 Dexie(IndexedDB)files 表中的全部文件元数据,流式迁移到 v2 的 SQLite file_entry 表。由于文件迁移直接关系用户物理数据的安全——迁移失败可能导致文件被孤儿清扫器回收、字节损坏或文件名永久丢失,本迁移器在 id 保留、origin 判定、存储名规范化、时间戳转换与校验采样等环节做了大量防御性设计。读完本文,你将掌握 FileMigrator 的完整数据流、字段映射规则、跨平台恢复与失败处理策略,以及其背后的源码级实现依据。
迁移背景:为什么需要 FileMigrator
Cherry Studio v2 将数据层从 Dexie(IndexDB)切换到 SQLite,文件元数据也从 v1 的 files 表迁移到 v2 的 file_entry 表。FileMigrator 正是承担这一职责的 migrator 类,其类级注释明确说明了定位:Migrates legacy v1 Dexie files table into the v2 file_entry SQLite table(FileMigrator.ts)。
该 migrator 的注册信息(见 FileMigrator.ts)为:
id:'file'name:'Files'description:'Migrate file entries from Dexie to SQLite file_entry table'order:2.7(决定其在迁移流水线中的执行顺序,测试用例在 FileMigrator.test.ts 中专门断言了该顺序)
数据源
| 数据 | 来源 | 文件/路径 |
|---|---|---|
| 文件元数据 | Dexie files 表 |
files.json(Dexie 导出文件) |
文件元数据对应的 v1 行结构定义在 legacyFile.ts:
export interface FileMetadata {
id: string
name: string
origin_name: string
path: string
size: number
ext: string
type: FileType
created_at: string
count: number
tokens?: number
purpose?: OpenAI.FilePurpose
}
流式分批读取:BATCH_SIZE = 500
源表通过 createStreamReader('files') 以 BATCH_SIZE(默认 500)为单位分批流式读取(FileMigrator.ts)。该批次大小的设计权衡是:500 足够大,能摊薄每批往返的开销;又足够小,使一批 FileMetadata 行在内存中占用的空间完全可控——即使面对大型文件集合,迁移过程中的峰值内存也保持有界。
const reader = ctx.sources.dexieExport.createStreamReader('files')
await reader.readInBatches<FileMetadata>(BATCH_SIZE, async (rows) => {
for (const row of rows) {
// ...逐行转换为 PreparedFileEntry
}
})
目标表
file_entry(其 Drizzle 表结构定义在 file.ts)
核心设计:ID 原样保留(无翻译映射)
迁移计划 §2.9 明确规定:v1 文件 id 原样写入 v2,不做任何翻译或重映射。这一决策带来一个关键收益——不发布跨 migrator 的共享状态:
No cross-migrator shared state is published:v1 file id is preserved verbatim into v2,so downstream migrators (ChatMigrator, KnowledgeMigrator, …) reference files by the same id they already have without needing a translation map.
也就是说,后续的 ChatMigrator、KnowledgeMigrator 等下游迁移器无需任何 id 翻译表,直接沿用它们手中已有的文件 id 即可完成关联。
源码层面有三个证据支撑:
FileEntryIdSchema = z.uuid()(file.ts)同时接受 v1 产出的 v4 id 和 v2 原生 v7 id。其注释明确说明:"New entries created in v2 are v7 (auto-generated byuuidPrimaryKeyOrdered()/FileEntryService.create); entries originating from a legacy data path may be v4."- v2 新建条目仍通过
uuidPrimaryKeyOrdered()生成 v7 id(file.ts),列上允许两种 id 形态共存。 - 测试用例专门验证:v7 id 与 v4 id 均被原样插入
file_entry,且ctx.sharedData.has('file.idRemap')为false,证明没有任何 id 重映射共享状态(FileMigrator.test.ts)。
Origin 判定:一切迁移行都是 internal
v1 语义下不存在 external 文件:v1 只有在把字节复制进 {userData}/Data/Files/ 之后才会持久化 files 行,因此 external 的 v1 行不存在,也永远不会被编造。
判定逻辑(FileMigrator.ts)如下:
| 条件 | 结果 |
|---|---|
row.path 以 {userData}/Data/Files/ 开头 |
internal,externalPath = null |
| 路径前缀检查失败,但磁盘上存在某个 storage-name 候选文件 | internal——该行可跨平台备份恢复(#15733):row.path 带着异平台分隔符,而文件就位 |
| 两者皆不满足 | 跳过并告警——这是 v1 删除未完成留下的死元数据 |
legacyStorageNames:从 id 重建存储名,绝不信任 row.name
storage-name 候选来自 legacyStorageNames(row)(legacyFileMappings.ts),由 {id} + {ext} 重建,绝不读取 row.name。原因是:v1 的去重上传路径会写入双重扩展名的 name({id}.pdf.pdf),该名字指向不存在的路径;若信任它,物理存在的文件会被误判为孤儿,进而被 FileManager.fileSweepTick 的孤儿清扫回收。
候选列表同时保留两种形态:
export function legacyStorageNames(row: Pick<FileMetadata, 'id' | 'ext'>): string[] {
const normalized = normalizeExt(row.ext)
const canonical = normalized ? `${row.id}.${normalized}` : row.id
const raw = `${row.id}${row.ext ?? ''}`
return raw === canonical ? [canonical] : [canonical, raw]
}
两种候选形态的原因是 v1 写入不一致:
- 规范形态
{id}.{normalizedExt}:uploadFile(.pdf)、saveBase64Image(png)以及畸形去重行实际写入磁盘的名字,也是 v2 布局使用的名字; - 原始形态
{id}{rawExt}:当rawExt不是.${normalized}时(如无点扩展名png,或带尾随空格/点的.exe),二者不同。在 POSIX 上磁盘文件名确实保留尾随空格,只有该候选能命中真实文件——删除该候选等于用一个数据丢失 bug 换另一个。
表驱动测试为每一种 v1 行生产者覆盖了候选覆盖性(legacyFileMappings.test.ts):
| v1 生产者 | ext | 磁盘真实名字 |
|---|---|---|
uploadFile(正常) |
.pdf |
{id}.pdf |
saveBase64Image(无点扩展名) |
png |
{id}.png |
uploadFile(无扩展名) |
'' |
{id} |
| 损坏行(null ext) | null |
{id} |
findDuplicateFile(畸形) |
.pdf |
{id}.pdf |
findDuplicateFile(无扩展名) |
'' |
{id} |
uploadFile(尾随空格 ext) |
.exe |
{id}.exe |
uploadFile(尾随点 ext) |
.exe. |
{id}.exe. |
非规范候选的字节复制:copyToCanonicalName
当命中非规范候选时,字节会被复制到 {id}.{normalizedExt} 再准备行(#18187):ext 以规范化形式写入,而 v2 运行时 resolvePhysicalPath 只组合规范名 {id}.{ext}——如果不复制,行虽然迁移成功,但对该文件的每次读取都会 ENOENT。
关键细节(FileMigrator.ts):
- 采用复制而非重命名:迁移中断时 v1 自身的
row.name查找仍然有效;遗留的原始 blob 不会被清扫,因为runFileSweep以 uuid 主干为孤儿键。 - 复制失败只告警、仍迁移该行:跳过它反而会让 blob 失去引用、落入孤儿清扫。
- 走 tmp + fsync + rename 流程(对应 file-manager-architecture §5.1):复制中途崩溃绝不能在规范路径上发布截断文件——下次运行的候选遍历会优先选择占据规范名的内容而非完好的原始 blob,重试就会在 v1
size之下迁移损坏字节且永不自我修复。残留物是同一目录下的.tmp-{uuid},由文件系统孤儿清扫统一收集。
中断复制场景有专门测试(FileMigrator.test.ts):模拟 copyFileSync 写一半抛 ENOSPC 后,目录里只有原始 blob(无截断规范文件、无残留 .tmp-),重跑后能从原始 blob 正确恢复出完整 payload。
扩展名规范化(Ext Normalization)
v1 的 ext 字段可能带前导点(.pdf、.txt)或为空。normalizeExt(legacyFileMappings.ts)处理规则:
- 前导点剥除后写入(
pdf、txt); - 空 / 纯空白 / 缺失 →
file_entry.ext为null。
export function normalizeExt(ext: string | undefined | null): string | null {
if (!ext || ext.trim() === '') return null
const stripped = ext.startsWith('.') ? ext.slice(1) : ext
const normalized = stripped.replace(/[\s.]+$/, '')
return normalized.length > 0 ? normalized : null
}
规范化的核心动机是与 v2 写路径的校验一致:SafeExtSchema(common.ts)是保守的裸扩展名 schema——拒绝点、空白、路径分隔符与 null 字节——因为扩展名会被组合进 {id}.{ext} 的物理路径,OS 默认打开安全检查可被平台规范化后缀(如 exe.、exe )绕过,分隔符则可能让扩展名超出单个路径段。空 / 纯空白扩展名统一为 null,与共享 common.ts 的空白保护一致,使迁移行通过与 v2 原生写入相同的校验。
normalizeExt 的表驱动测试覆盖了 .pdf→pdf、pdf→pdf、.exe →exe、.exe.→exe、空串/纯空格/./undefined/null → null 等全部边界(legacyFileMappings.test.ts)。
另外,FileMigrator.prepare 对规范化后的 ext 还会过一遍 SafeExtSchema.safeParse(FileMigrator.ts):由于 ext 列没有 DB CHECK,畸形值会静默落入 v2、直到读取行时 FileEntrySchema.parse 才爆掉,因此在准备阶段就把畸形 ext 视作畸形行跳过并告警。测试验证了含路径分隔符(pdf/exe)和含 null 字节(a\0b)的 ext 均被拒绝(FileMigrator.test.ts)。
时间戳转换:ISO 字符串 → 毫秒 epoch
parseTimestamp(FileMigrator.ts)将 v1 的 ISO 8601 字符串解析为毫秒 epoch 整数:
- 缺失 / 空
created_at→ 静默使用Date.now()(这是合法的 v1 场景,行本身有效只是没有时间戳); - 非空但不可解析 →
Date.now()并对行 id 记录告警(通过PrepareResult.warnings浮出); createdAt与updatedAt被设置为同一个解析值。
回退到"现在"而非 0,是为了让迁移行能与 v2 原生行一起正确排序;告警则是针对携带损坏日期的 v1 数据的诊断痕迹。相关测试验证了 ISO 转换的精确性、非法日期回退时间窗以及告警内容(FileMigrator.test.ts)。
名称派生与"原始文件名丢失"诊断
名称派生降级链
deriveSafeName(FileMigrator.ts)从 origin_name(回退到 name)派生用户可见名称,去掉扩展名;降级链为:原始值 → 净化值(取最后路径段并 trim)→ 行 id。
该函数绝不要求调用方跳过该行——被跳过的 internal 行会让其物理文件变成孤儿,被定时文件系统孤儿清扫(FileManager.fileSweepTick)回收,这是真实的数据丢失。由于 name 不参与物理路径组合(物理路径是 {id}.{ext}),降级它永远是安全的。
SafeNameSchema(file.ts)是带安全校验的名称 schema:拒绝 null 字节、路径分隔符、./..、纯空白,并限制 ≤255 字节(匹配 ext4/HFS+/NTFS 最严格的路径段限制)。测试覆盖了含分隔符名称被净化、超长名称回退 id、.. 回退 id 等场景(FileMigrator.test.ts)。
hasLostOriginalFilename:唯一生产者
v1 的去重上传路径会用内部存储名覆盖 origin_name,用户文件名在迁移运行前就已丢失。hasLostOriginalFilename(legacyFileMappings.ts)检测该签名并记录告警,派生名保持为 id——这是诚实的选择:id 就是该文件在磁盘上现在的名字,任何更友好的名字都是编造。
export function hasLostOriginalFilename(row: Pick<FileMetadata, 'id' | 'name' | 'origin_name' | 'ext'>): boolean {
const ext = row.ext ?? ''
return row.origin_name === `${row.id}${ext}` && row.name === `${row.origin_name}${ext}`
}
两个条件缺一不可,且第二个条件(双重扩展名指纹 name === origin_name + ext)承担主要权重:
saveBase64Image写入的origin_name本身就是存储名({id}.png)——生成图片本来就从未有过用户文件名,不应被标记。第一个条件只因为 v1 存储该行 ext 不带前导点(origin_name是{id}.png而{id}{ext}重建为{id}png)才错过它;真正排除这些行的仍是第二个条件的双重扩展名指纹,因为只有findDuplicateFile会产生它。- 第一个条件的价值在于阻止第二个条件在无扩展名行上退化为
name === origin_name——而那是每个 external 行都满足的。
表驱动测试逐一验证了这些边界(legacyFileMappings.test.ts),并在 FileMigrator.test.ts 中确认:正常上传不告警、base64 图片不告警、被引用两次的正常上传不告警(v1 count 是引用计数而非上传计数)、去重上传与去重无扩展名上传各告警一次。
该 migrator 是此诊断的唯一生产者:它拥有全局 files 行,因此每个损坏文件恰好触发一次;KnowledgeMappings 和 ChatMappings 通过每个 item/message 看到同一损坏却刻意保持沉默——因为引擎会把所有 migrator 的告警拼接成不去重的列表展示给用户,在那里告警会让通知数量随引用数量膨胀。
字段映射全景
源(v1 FileMetadata) |
目标(file_entry) |
说明 |
|---|---|---|
id |
id |
原样保留(迁移计划 §2.9) |
| (不派生) | origin |
恒为 internal;非 internal 行跳过而非映射 |
origin_name / name |
name |
去扩展名的 basename |
ext |
ext |
剥前导点;空 / 纯空白 → null |
size |
size |
恒非 null;v1 值非法时从磁盘恢复 |
| — | externalPath |
恒为 null |
| (恒 null) | deletedAt |
v1 无软删除状态 |
created_at |
createdAt |
ISO → 毫秒 epoch;解析失败回退 Date.now() + 告警 |
created_at |
updatedAt |
与 createdAt 相同 |
被丢弃的 v1 字段:count、tokens、purpose、type、origin_name(仅在名称派生中按原样使用)。测试断言 v2 行形状不包含这些字段(FileMigrator.test.ts)。
size 的磁盘恢复逻辑
size 列有 DB CHECK(fe_size_internal_only,见 file.ts)但接受 0(合法的空文件),因此垃圾 v1 size 不能简单强转为 0——那会在 v2 UI 中与空文件无法区分。而直接跳过更糟:能走到此处的行都是 internal,物理存在的文件会被搁置并成为孤儿清扫对象。因此优先从磁盘恢复真实大小(fs.statSync(physicalPath).size),仅当磁盘上无可恢复内容时才跳过(FileMigrator.ts)。
幂等性:引擎层清表 + 原样 id
该 migrator 可安全重跑。MigrationEngine.verifyAndClearNewTables 会在每次运行前清空文件关联表和 file_entry,因此 execute() 总是从空表开始。v1 id 原样保留,使得引擎层清表成为唯一不变量——migrator 层无需 onConflict 守卫或逐行预检查。重复执行同一 fixture 产生相同行的测试见 FileMigrator.test.ts。
execute() 按 BATCH_SIZE 分批在事务中插入并上报进度(key:migration.progress.migrated_files);事务抛错时返回 success=false 与错误信息(FileMigrator.ts)。
校验行为:计数检查 + 物理文件采样
validate()(FileMigrator.ts)执行两项检查:
- 计数检查:断言
SELECT count(*) FROM file_entry >= preparedEntries.length,不匹配时产生file_entry_count_mismatch错误(期望值 vs 实际值)。 - 物理文件采样:最多
VALIDATE_SAMPLE_LIMIT = 10条记录,通过fs.existsSync检查{userData}/Data/Files/{id}.{ext}(规范legacyStorageNames候选)上的物理文件。10足够小使大迁移校验保持廉价、足够大能及早捕获系统性的"Files 目录被移动/丢失"问题;每行 I/O 有意受限,因为迁移自身的物理复制步骤才是权威的完整性边界。只探测规范候选——这也正是运行时解析的路径;blob 在原始候选下找到的行已在 prepare 阶段复制到规范路径,所以这是诚实的可读性检查而非候选遍历。
缺失物理文件通过 recordWarning 记录(而非校验错误)——v1 经常遗留悬空的 file_entry 行(已删除附件、中断的上传),即使字节已消失,DB 行也保留历史引用。测试验证了缺失文件只告警不失败、全部存在则成功(FileMigrator.test.ts)。
失败处理矩阵
| 问题 | 检测方式 | 处理 |
|---|---|---|
| 畸形行(缺 id/path/name) | toFileEntry() 返回 null |
跳过;skippedCount++;记录告警 |
| v1 源中的重复 id | prepare() 中的 seenIds 集合 |
第二次出现跳过;记录告警 |
| 插入错误(DB 约束、磁盘满) | 事务抛错 | execute() 返回 success=false 与错误信息 |
| 缺失 files 表 | tableExists('files') 返回 false |
prepare 返回成功、0 条 item、一条告警 |
| 孤儿行(非 internal 且无物理文件) | 前缀检查与每个 storage-name 候选均失败 | 跳过;记录告警 |
| 原始文件名丢失 | hasLostOriginalFilename() 签名匹配 |
以 id 作为名称完整迁移;记录告警 |
关于孤儿行还有一处细节:跳过时告警会携带 origin_name(或 name)——这是被永久丢弃的行留下的唯一痕迹,光一个 uuid 无法告诉用户哪份文件丢了。
写侧校验 ≥ 读侧校验的不变量
toFileEntry 在返回前会通过运行时读路径所用的同一 schema(rowToFileEntry → FileEntrySchema.parse)探测准备好的条目(FileMigrator.ts),确保畸形行永远无法进入 SQLite 并在读取时爆炸(#15733)。按当前构造这不可达——它是针对未来字段/schema 漂移的守卫。FileEntrySchema 是按 origin 判别联合的品牌化 schema(InternalEntrySchema/ExternalEntrySchema,见 file.ts),DB 层另有 fe_origin_consistency、fe_size_internal_only、fe_external_no_delete、fe_contenthash_external_null 四条 CHECK 约束表达同一套不变量(file.ts)。测试对每个 prepared entry 执行该探测并断言 probe.success === true(FileMigrator.test.ts)。
实现文件索引
- FileMigrator.ts —— migrator 主类(prepare / execute / validate / 元数据)
- legacyFileMappings.ts —— v1
files行语义(normalizeExt、legacyStorageNames、hasLostOriginalFilename),与KnowledgeMappings共享 - FileMigrator.test.ts —— 单元测试(1044 行,覆盖 id 保留、origin 判定、ext 规范化、size 恢复、跨平台恢复 #15733、写读校验不变量等)
- legacyFileMappings.test.ts —— 表驱动用例,每种 v1 行生产者一行
- file.ts ——
file_entry表结构与 CHECK 约束 - file.ts ——
FileEntrySchema/FileEntryIdSchema/SafeNameSchema/CleanupPolicySchema - common.ts ——
SafeExtSchema - legacyFile.ts —— v1
FileMetadata行定义 - 相关架构参考:file-manager-architecture.md(§5.1 原子写入流程)、file-entry-cleanup.md(§7.2 引用状态分类)、database-migration(v2 迁移总体框架)