macOS元数据保卫战:TimeCapsuleSMB的FinderInfo、资源分叉与xattr迁移架构深剖
macOS元数据保卫战:TimeCapsuleSMB的FinderInfo、资源分叉与xattr迁移架构深剖
TimeCapsuleSMB 让老旧的 Apple AirPort Time Capsule 运行现代 Samba,其中最难啃的骨头是 macOS 元数据:FinderInfo、资源分叉(Resource Fork)和扩展属性(xattr)。这篇文章带你完整看懂它的 FinderInfo 原生存储、资源分叉直通方案,以及部署时的两阶段 xattr 迁移架构,理解为什么 SMB 与 AFP 能共享同一份 Mac 元数据。
为什么元数据迁移是 TimeCapsuleSMB 的核心难题?
macOS 客户端对 SMB 网络盘的要求远不止"能读写文件"。一个文件能否正确显示:
- Finder 图标、窗口位置、文件夹配色 —— 这些存在 32 字节的 FinderInfo 里
- 颜色标签(标签 xattr) —— 存在
com.apple.*扩展属性里 - 旧式资源分叉数据(QuickTime 老视频、旧应用二进制依赖它)
在 Time Capsule 的 HFS 磁盘上,Apple 自家 AFP 服务把这些信息存在 HFS 目录项的原生属性 中。而早期 Samba 版本(vfs_fruit 默认行为)则把同样的信息写进 ._文件名(AppleDouble 侧车文件)或 xattr.tdb 数据库里。两边各存一份,就会出现 Finder 图标丢失、标签错乱这类经典故障。
TimeCapsuleSMB 的解法只有一句话:让 Samba 直接读写 HFS 原生元数据,与 AFP 共用同一份存储。
三种 Mac 元数据,三种原生载体
项目技术参考文档 DETAIL.md 中有一张关键的架构映射表,明确了每类元数据"从哪来、归谁管、存哪里":
| Mac 概念 | SMB 流表示 | 负责的 VFS 层 | HFS 原生存储位置 | 迁移输入 → 输出 |
|---|---|---|---|---|
| FinderInfo | :AFP_AfpInfo:$DATA |
fruit |
com.apple.FinderInfo 目录属性 |
TDB 元数据 → 原生 FinderInfo |
| 标签等 Mac xattr | :com.apple.…:$DATA |
streams_xattr → xattr_tdb |
标准 HFS xattr | TDB 流 → 标准 HFS xattr |
| 资源分叉 | :AFP_Resource:$DATA |
fruit |
文件/..namedfork/rsrc |
AppleDouble 资源条目 → 原生资源分叉 |
| 仅 Windows 的 ADS | 普通命名流 | streams_xattr → xattr_tdb |
编码/分片的 HFS xattr | TDB 流 → 原生 HFS xattr |
| NT ACL | Samba 安全 xattr | acl_xattr → xattr_tdb |
原生 HFS 安全 xattr | TDB → 原生 HFS xattr |
三个设计细节值得新手注意 📌:
- 全零 FinderInfo 等于"没有" —— Apple 内核不保留全零值,Samba 的
fruit层与迁移器都遵循这个语义,避免写入垃圾数据。 - 资源分叉不走 xattr —— 它通过
文件/..namedfork/rsrc以真实文件描述符打开,因此大分叉用普通偏移 I/O,不受 HFS 普通 xattr 约 3802 字节的容量上限约束。 - 非 HFS 文件系统保留 TDB 回退路径 —— 为未来 FAT32 支持预留了
fruit:metadata = netatalk|stream后端选择。
打通私有 ABI:Apple 内核的"隐藏系统调用"
Time Capsule 的 NetBSD 4/6 内核带有 Darwin 风格的 xattr 系统调用,但没有对应的 libc 入口。TimeCapsuleSMB 通过设备专属的封装层直接调用这些私有 ABI,核心定义在 airport_native_xattr.h:
#define TC_FINDERINFO_XATTR "com.apple.FinderInfo"
#define TC_RESOURCEFORK_XATTR "com.apple.ResourceFork"
头文件同时封装了带文件锁(flock)的原子写路径,保证 SMB 与 AFP 并发修改同一属性时不会互相踩踏。
在 Samba 补丁系列中,这套能力由三块拼图完成(见 series 补丁清单):
- 0055 补丁:
fruit在 HFS 共享上从原生com.apple.FinderInfo属性合成 60 字节的AFP_AfpInfo流,实现见 tc_fruit_native_finderinfo.c。它严格校验 32 字节长度,且绝不在符号链接目标上误改 FinderInfo。 - 0056 补丁:
AFP_Resource流直通原生资源分叉,实现见 tc_fruit_native_rsrc.c,按 AFP 服务自己的方式打开<文件>/..namedfork/rsrc。 - 0038 补丁:HFS 共享上
xattr_tdb自动切换为原生后端,普通 Mac xattr 直接落在标准 HFS xattr 上,不再触碰 TDB 数据库。
最终生效的 VFS 栈是(DETAIL.md):
catia → fruit → streams_xattr → acl_xattr → xattr_tdb
其中 fruit 最先截获两条特殊 Mac 流,其余命名流继续向下走。
两阶段 xattr 迁移:从 TDB 和 ._ 文件到原生存储
老版本 Samba 留下的遗留元数据有两个来源:xattr.tdb 数据库(位于 /Volumes/dkX/.samba4/private/xattr.tdb)和磁盘上成堆的 ._文件名 AppleDouble 文件。迁移器 tc_xattr_hfs_migrate.c 是一个仅在部署时运行的独立静态工具,执行 inspect → copy → cleanup → retire 四个动作:
- copy 阶段:遍历每个可用的 HFS 卷,把所有只读输入数据库中的逻辑属性合并、写入原生 HFS 存储;
- cleanup 阶段:回读校验合并后的原生值,移除已验证的
._侧车文件; - retire 阶段:按源优先级整库退役数据库。
几个新手容易忽略的容错设计:
- 冲突仲裁用四元组:
(mtime 秒, 纳秒, 规范化卷 UUID, 路径字节)最大的来源获胜,中断后重跑不会丢数据; - 超大值原地保留:Apple 内核单条 HFS 属性上限是 3802 字节(8 KiB B-tree 节点),macOS 沙盒容器里 8~41 KB 的
com.apple.data-container-personality无法原生化。迁移器会把这类值留在原处,数据库隔离为xattr.tdb.orphaned.N,永不删除; - 孤儿行甄别:设备号行若属于未挂载的磁盘,被判定为 unresolved 而非 proven orphan,等磁盘接回、重新
deploy后再迁移(DETAIL.md); - 进度可恢复:
xattr.tdb.migration-progress.json记录已完成的卷与已验证键覆盖,后续部署自动跳过,不打扰原生编辑过的数据。
主机侧的编排逻辑在 src/timecapsulesmb/deploy/migration.py,它通过 SSH 驱动设备上的原生工具,逐卷执行 copy/cleanup 两阶段并解析报告;部署服务的进度上报与"超大值保留"的用户提示在 src/timecapsulesmb/services/deploy.py。
质量保障:原生元数据也有回归测试
这套私有路径并非"能跑就行"。仓库的 Samba 回归测试套件(tests/samba/README.md)在应用完整补丁序列后,编译真实 Samba 4.25.0rc2 源码运行用例,其中 tc_native_metadata_test.c 用受控的底层 VFS 与私有系统调用后端,逐层验证 fruit 与 xattr_tdb 的 HFS 原生读写路径;tc_xattr_migrate_test.c 则覆盖迁移器本身。CI 在 Linux 上关闭 pthread 并启用 AddressSanitizer/UBSan 运行,交叉构建后还在真机 HFS 卷上复验。
总结
TimeCapsuleSMB 的元数据架构可以浓缩为三步:
- 直通原生存储 —— FinderInfo、xattr、资源分叉全部落在 HFS 原生位置,SMB 与 AFP 共用一份数据,macOS 的"开箱即用"体验得以完整复刻;
- 私有 ABI 封装 —— 设备专属头文件桥接 Apple 内核未导出的 xattr 系统调用,补丁系列(0038/0054/0055/0056/0057)分层落地;
- 可恢复的两阶段迁移 —— 部署时把遗留
xattr.tdb与 AppleDouble 文件安全地搬进原生存储,隔离而非删除无法原生化的数据,中断可随时重跑。
想深入了解完整约束与实现权衡,推荐阅读 DETAIL.md 的 "Native Mac Metadata Architecture" 章节,以及补丁清单 build/patches/samba4x/series 中 "Native Mac metadata" 一段的逐补丁说明。