arzisxam/apfs-excavate

# apfs-excavate 从损坏、受损或加密的 APFS 磁盘镜像中恢复文件 —— 即使驱动器的文件系统完全无法读取。 **apfs-excavate** 是一个完全使用 C 语言编写的高性能命令行工具。它可以在 macOS 和 Linux 上运行。 ## 快速开始 ``` ./apfs-excavate damaged.img /Volumes/ExternalDrive/recovery/ ``` 就是这样。该脚本会在首次运行时自动构建工具 —— 无需安装或手动编译。 ## 常见用途 ``` # 基本恢复 ./apfs-excavate damaged.dmg out/ # 加密卷 (FileVault / APFS encryption) ./apfs-excavate encrypted.dmg out/ --password "your passphrase" # 在提取任何内容前查看可恢复的内容 ./apfs-excavate damaged.dmg out/ --scan-only # 仅恢复特定文件类型 ./apfs-excavate damaged.dmg out/ --filter-ext jpg,pdf,mov,docx # 在 SSD 上加速扫描（使用 4 个线程） ./apfs-excavate damaged.dmg out/ --workers 4 # 恢复中断的恢复（默认自动） ./apfs-excavate damaged.dmg out/ ``` ## 输出内容 成功运行后，输出文件夹将包含： | 文件夹 / 文件 | 内容 | |---|---| | `recovered_files/` | 保留原始文件夹结构的文件 | | `recovered_orphans/` | 找到但无法确定路径的文件 —— 按类型重命名 (jpg, pdf, …) | | `recovered_unknown_format/` | 无法识别或解码的文件 | | `recovered_deleted/` | 已删除的原始文件片段（仅在使用 `--deleted` 时生成） | | `file_list.md` | 找到的所有文件的完整列表及其大小 | | `recovery_summary.md` | 运行统计信息（找到的文件、已恢复的文件、耗时） | | `unrecovered_files.md` | 工具找到但无法提取的文件 | | `logs/` | 完整的执行日志、错误日志和大小过滤跳过列表 | ## 系统要求 - **macOS:** 安装 OpenSSL —— `brew install openssl` - **Linux:** `apt install libssl-dev zlib1g-dev` 无其他依赖。运行此工具不需要安装 Python。 ## 延伸阅读 | 文档 | 内容简介 | |---|---| | [用户指南](docs/user-guide.md) | 所有选项、高级用法和完整示例 | | [辅助工具](docs/tools.md) | 用于诊断复杂镜像的辅助脚本 | | [终端输出参考](docs/terminal-output-reference.md) | 各种运行场景的示例输出（恢复、Ctrl-C、仅扫描等） | | [架构设计](docs/architecture.md) | 模块划分、阶段处理管线和检查点格式 | | [执行流程](docs/execution-flow.md) | 每个阶段的详细逐步解析 | | [加密处理管线](docs/encryption.md) | AES-XTS 解密、密钥派生和按区段加密机制 | | [路线图](ROADMAP.md) | 计划中的功能和未来改进 | ## 当前状态与限制 - **未经测试的功能：** 已删除文件片段的恢复（`--deleted`）和加密卷的恢复（`--password`）已经实现，但尚未进行充分测试。Linux 上的编译和执行也尚未经过全面测试。 - **仅支持 APFS：** 此工具严格适用于 APFS 文件系统。如果在 ExFAT、FAT32 或 NTFS 镜像上运行，它将立即中止并提示 "No valid APFS container superblock found" 错误。 - **故障排除：** 如果在尝试运行 `./apfs-excavate` 时收到 "Permission denied" 错误，您可能需要先赋予脚本可执行权限：`chmod +x apfs-excavate`。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：APFS, Awesome, C11, FileVault, HTTP工具, SSD优化, 删除文件恢复, 加密磁盘解密, 存储解析, 孤立项重建, 安全测试工具, 客户端加密, 库, 应急响应, 开源, 损坏磁盘修复, 数字取证, 数据恢复, 文件提取, 文档结构分析, 断点续传, 硬盘修复, 系统管理, 系统运维, 自动化脚本, 高并发