企业官网建设流程全解析

PhotoCraft .pcraft 无损文档格式揭秘：ZIP + BLAKE3 内容寻址 + zstd 的存储原理

【免费下载链接】photocraftAn open-source, clean-room reimplementation of Adobe Photoshop in pure Rust项目地址: https://gitcode.com/gh_mirrors/pho/photocraft

PhotoCraft 是一个用纯 Rust 编写的开源 Photoshop 替代品，它的原生无损文档格式.pcraft把「版本化 JSON 清单 + BLAKE3 内容寻址瓦片 + zstd 压缩」封装进一个 ZIP 包里。本文带你拆解 PhotoCraft 是如何做到像素级无损、增量保存、崩溃不丢数据的。

上面这张截图里的《神奈川冲浪里》，图层、文字、曲线调整全部保存在一个.pcraft文件中——不丢任何像素。

一、.pcraft 到底是什么：一个 ZIP 包

.pcraft文件本质上就是一个 ZIP 压缩包（也可以用普通文件夹存放，两种布局完全等价）。内部结构如下：

manifest.json 版本化文档树（JSON） tiles/<blake3>.zst 内容寻址的 256×256 像素瓦片（zstd 压缩） blobs/<blake3>.zst 内容寻址的二进制数据（ICC 色彩配置、EXIF、PSD 块、智能对象） thumb.png 可选的缩略图 composite/preview.png 可选的扁平化预览图

这个布局定义在 manifest.rs 和 lib.rs 的文档注释里。几个要点：

• manifest.json 放在 ZIP 第一个条目，程序通过PK\x03\x04签名 + manifest 路径即可快速识别这是一个.pcraft文档（见 is_pcraft()）。
• 二进制数据从不直接写进 JSON——JSON 里只有结构描述，像素一律以瓦片哈希为键存放。
• 格式版本字段format_version带迁移链（migrate.rs），旧版文件可逐步升级读取；比当前构建更新的版本会明确报错拒绝，而不是静默加载出错误内容。

二、BLAKE3 内容寻址：文件名就是哈希值

这是.pcraft最巧妙的设计：每个瓦片和二进制块的文件名，就是它未压缩原始字节的 BLAKE3 哈希值（64 位十六进制）：

tiles/3f9a2c1b…d4e8.zst ← 文件名 = 内容哈希 blobs/7c01be44…91fa.zst ← 文件名 = 内容哈希

内容寻址带来三个好处：

1. 天然去重：两张图层引用同一块像素时，磁盘上只存一份瓦片。
2. 自校验：打开文档时，读取器对解出的每个瓦片重新计算 BLAKE3，与文件名比对，任何一个字节被篡改都会立刻报「内容不匹配其哈希」错误（见 store.rs 的LoadFetch）。
3. 增量写入：保存时按哈希判断哪些对象是「新的」，只写新文件。

图中这些曲线、 Vibrance 调整图层、文字层的每一帧像素，都以 256×256 瓦片为单位、按 BLAKE3 哈希寻址存入文档。

三、zstd 压缩与并行编码

每个瓦片用zstd 最快速档（CompressionLevel::Fastest）压缩后落盘——既保证解压速度，又对像素数据有不错的压缩率。全量保存时，新瓦片会在最多 32 个工作线程上并行压缩（par_compress），因为 zstd 压缩是全量保存中最耗时的环节。

ZIP 容器本身由项目自研的极简实现（zip.rs）生成，只写 STORE 条目（内容已经 zstd 压缩过，不再二次压缩），但读取时兼容 STORE 和 DEFLATE——即使你用其他工具解包再重新打包，文档依然能打开。

四、增量保存：只写「新瓦片」

PcraftWriter（store.rs）会为每个打开的文档保留一份「已压缩对象缓存」，它靠Arc指针身份识别瓦片——没被编辑过的图层瓦片指针不变，哈希直接复用。

目录模式保存时的行为：

• 已存在的对象跳过不写；
• 只写缺失的对象，最后原子替换manifest.json；
• 清理不再被引用的旧对象（垃圾回收）。

这就是为什么连续保存一份 3000×2000 的 PSD 级文档，第二次保存可能只花几毫秒。

五、崩溃安全：原子写入 + 后台自动保存

所有落盘都走atomic_write（atomic.rs）：先在同目录写临时文件并sync_all刷盘，再rename覆盖目标文件、fsync 目录。任何一步失败，原文件都保持原样——不存在「保存一半损坏文档」的可能。

自动保存系统（autosave.rs）在后台线程以目录 bundle形式定期快照文档，同样享受增量写入：重复自动保存只写变化过的瓦片。程序崩溃后，启动时扫描恢复目录，即可列出所有可恢复文档并一键还原。

六、安全边界：加载不信任的 bundle

.pcraft文件也视为不可信输入，默认LoadOptions设置三道闸门（lib.rs）：

ZIP 读取器拒绝加密条目、校验 CRC-32、对每个偏移做带检查的算术运算，防止恶意构造的压缩包触发越界读取（zip.rs）。

七、总结

PhotoCraft 的.pcraft格式用三个经典技术的组合实现了现代无损文档存储：

• ZIP / 目录 bundle：跨平台、可用任何工具浏览，单文件友好；
• BLAKE3 内容寻址：去重 + 内容完整性自校验；
• zstd + 增量写入 + 原子替换：快速保存、崩溃零损失。

完整规格见官方文档 The .pcraft format，格式概览与迁移机制见 migrate.rs 与 formats overview。

【免费下载链接】photocraftAn open-source, clean-room reimplementation of Adobe Photoshop in pure Rust项目地址: https://gitcode.com/gh_mirrors/pho/photocraft