PHP PharData 打包备份如何避免路径穿越：归档条目校验与解包边界

备份脚本能把目录打成 tar，并不代表解包是安全的。真正容易出事的地方，是把归档里的文件名直接拼到目标目录：一个带有 ../ 或绝对路径的条目，就可能写到预期目录之外。PHP 的 PharData 负责读写归档，条目路径的信任边界仍然要由业务代码自己守住。

先把打包和解包分成两条边界

PharData 可以创建 tar、添加文件和目录，也可以读取已有归档。备份流程里最好把“生成归档”和“恢复文件”拆成两个明确阶段：打包阶段只允许收集备份根目录下的文件；解包阶段把归档条目当成外部输入，重新做路径校验。

下面的示例用 backup/source 作为备份源，用 backup.tar 作为归档文件。示例中的关键节点是 PharData、归档条目、路径校验 和 安全解包，后面的每一步都围绕这条链路展开。

buildFromDirectory(__DIR__ . '/backup/source');

foreach (new RecursiveIteratorIterator($archive) as $entry) {
    echo $entry->getPathName(), PHP_EOL;
}

为什么能打开 tar 还不够

归档格式只说明条目如何存储，不说明条目最终应该落在哪里。下面三个名字都不能直接交给文件写入函数：

这里别急着只做字符串替换。把 ../ 删除后，原条目的语义已经变了，而且不同平台的目录分隔符也可能让简单替换漏掉边界。更稳妥的判断顺序是：拒绝绝对路径，拆分路径段，拒绝 ..，再把候选目标做规范化并确认它仍位于解包根目录内。

用规范化路径锁住解包根目录

下面的 safeTargetPath 只负责把可信的解包根目录和不可信的条目名拼成安全目标。它不创建文件，也不替调用方决定是否覆盖已有文件。

这个函数的判断链只有一个目的：让每个“写入目标”都能回到同一个 路径校验 结论。生产代码还应根据业务决定是否允许覆盖文件、是否保留权限，以及是否拒绝符号链接条目；这些选择不能被一个通用解包函数悄悄替换。

先校验全部条目，再执行写入

如果一边遍历一边写文件，遇到第 20 个条目才发现路径非法，前 19 个文件已经落盘，恢复目录就处于半完成状态。更可控的流程是先建立待写列表，所有条目通过后才进入 安全解包 阶段。

getPathName();
    $target = safeTargetPath($root, $name);
    $plan[] = ['entry' => $entry, 'target' => $target];
}

foreach ($plan as $item) {
    $item['entry']->extractTo(dirname($item['target']), basename($item['target']), true);
}

示例把校验阶段和写入阶段分开，方便在写入前记录条目数量、拒绝原因和目标目录。这里的 写入目标 只有在全部条目通过校验后才会出现。实际项目中可以把文件内容先写入临时目录，全部完成后再原子地切换目录名，避免恢复过程中被其他请求读到半套文件。

测试要覆盖哪些路径

1. 正常文件。 使用 report.csv 和 logs/2026-08/app.log，确认目录创建和内容校验都成功。
2. 向上路径。 使用 ../outside.txt，确认异常发生在写入前，restore 目录外没有新文件。
3. 绝对路径。 使用 /tmp/out.txt 和 Windows 风格盘符路径，确认两类绝对路径都被拒绝。
4. 链接和覆盖。 对符号链接、同名文件和重复条目单独设策略，不能让默认覆盖行为替你做安全决策。

验证时不要只看异常文本。至少同时检查目标目录树、文件内容、文件权限和失败后的残留目录。若恢复目录会被 Web 服务读取，还要确认临时目录没有被配置在可直接访问的静态资源目录下。

常见问题

PharData 会自动阻止路径穿越吗？

不能把它当成业务安全边界。PharData 负责归档读写，解包目标目录、条目路径和覆盖策略仍需要应用代码校验。

把 ../ 替换为空字符串可以吗？

不建议。替换会改变条目含义，也可能漏掉绝对路径、重复分隔符和其他平台路径形式；应拒绝不符合规则的条目。

为什么要先校验再写入？

这样能避免遇到恶意条目后留下半套恢复文件，并且可以在真正写入前给出完整的拒绝记录。

只用 realpath 检查目标够不够？

不够。目标文件尚不存在时，realpath 可能无法返回结果；还要先检查绝对路径和 ..，并对父目录做规范化和根目录前缀校验。

把恢复动作收口在可验证边界内

PHP PharData 让归档读写变得简单，但“简单打开”与“安全恢复”是两件事。稳定的恢复流程应该先枚举 归档条目，再完成 路径校验，全部通过后才写入 安全解包 目录；遇到非法条目立即拒绝并保留证据。只要把这条顺序写进代码和测试，备份格式变化时也不会把目录安全性一起交给归档文件决定。