Go archive/tar 解包怎么防路径穿越：清理文件名、目录边界与链接条目验收

线上导入备份时，最容易被忽略的不是 tar 文件能不能读，而是条目里的文件名会不会把内容写到输出目录之外。`archive/tar` 只负责读取归档格式，不会替你做路径边界和链接类型判断。一个稳妥的解包器应该先把条目名限制为本地相对路径，再把写入动作锁在指定根目录内，同时拒绝符号链接和硬链接条目，最后用越界、覆盖和异常中断测试验收。

先看一个会“写出目录”的条目

归档里的文件名可能是 config/app.yaml，也可能是 ../../outside.txt、/tmp/notice.txt，甚至包含 Windows 风格的盘符。直接把名称拼到输出目录后调用写文件函数，代码看起来很短，却把归档作者的路径带进了本机文件系统。

这类问题还有一个误区：把 filepath.Join(outDir, header.Name) 当成安全边界。Join 会清理路径，但清理后仍可能得到输出目录的父级路径。边界判断必须发生在写入之前，且要对拒绝条目给出可审计的原因。

第一道门：只接受本地相对路径

先把 tar 头里的名称当作不可信输入，不要先创建目录。Go 的 filepath.IsLocal 可以覆盖绝对路径、空路径和包含父级跳转的常见情况；再把清理后的相对路径交给后续写入逻辑。

func localEntry(name string) (string, error) {
    if !filepath.IsLocal(name) {
        return "", fmt.Errorf("拒绝非本地路径: %q", name)
    }
    clean := filepath.Clean(name)
    if clean == "." || clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
        return "", fmt.Errorf("拒绝越界路径: %q", name)
    }
    return clean, nil
}

这里的返回值仍然是相对路径。不要在这个函数里偷偷拼接工作目录，也不要把错误转换成空字符串继续写入；调用方应该把该条目标记为拒绝并继续或终止，取决于业务是否允许部分导入。

第二道门：把写入动作放进输出根目录

路径通过第一道检查后，才可以组成目标文件名。目录条目只负责创建目录；普通文件则创建父目录，再写入内容。示例用 os.OpenRoot 把相对路径交给根目录句柄，减少业务代码反复拼接绝对路径的机会。项目如果仍兼容更早的 Go 版本，也至少要保留前面的本地路径检查，并在部署环境补充符号链接测试。

func extractRegular(root *os.Root, name string, r io.Reader, mode fs.FileMode) error {
    clean, err := localEntry(name)
    if err != nil {
        return err
    }
    parent := filepath.Dir(clean)
    if parent != "." {
        if err := root.MkdirAll(parent, 0750); err != nil {
            return fmt.Errorf("创建父目录 %q: %w", parent, err)
        }
    }
    f, err := root.OpenFile(clean, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, mode.Perm())
    if err != nil {
        return fmt.Errorf("创建归档文件 %q: %w", clean, err)
    }
    defer f.Close()
    if _, err := io.Copy(f, r); err != nil {
        return fmt.Errorf("写入归档文件 %q: %w", clean, err)
    }
    return f.Close()
}

文件覆盖策略要单独决定。导入临时目录时可以允许覆盖，但生产恢复往往更适合“目标已存在就失败”，避免一个旧文件被静默替换。无论选哪种策略，都要让日志中出现条目名、类型、字节数和结果。

第三道门：链接条目默认拒绝

tar 头不仅有普通文件和目录，还可能携带符号链接、硬链接、设备文件等类型。把链接当普通文件处理，会让“看起来在输出目录内”的路径最终跟随到别处；硬链接还会带来覆盖已有文件的额外风险。除非业务有明确的兼容协议，否则最小权限策略是只接收目录和普通文件。

func acceptHeader(h *tar.Header) error {
    switch h.Typeflag {
    case tar.TypeDir, tar.TypeReg, tar.TypeRegA:
        return nil
    default:
        return fmt.Errorf("拒绝归档条目类型 %d: %q", h.Typeflag, h.Name)
    }
}

不要只根据文件名后缀判断类型，也不要因为链接目标看起来像 safe.txt 就放行。条目类型来自 tar 头，拒绝原因应保留在结构化日志里，方便定位是谁生成了不兼容的归档。

异常、大小和重复条目也要有边界

路径安全解决的是“写到哪里”，不是“写多少”。解包前应设置总字节数和单文件大小上限，读取时用 io.LimitReader 或带计数的读取器保护资源。条目名重复时要决定是拒绝、覆盖还是保留首个；我更建议恢复类任务默认拒绝重复条目，因为它能暴露归档生成端的异常。

处理失败时不要把半成品目录直接当成功结果。可以把输出写到本轮临时目录，全部条目通过后再由业务层切换目录；如果无法原子切换，至少在结果中区分“完整成功”“部分完成”和“已拒绝”。

用四组测试验收，而不是只测一个正常包

• 越界组：../a、../../a、绝对路径和 Windows 风格路径都不能产生输出目录外文件。
• 类型组：普通文件、目录可以按策略通过，符号链接、硬链接和未知类型必须有明确结果。
• 资源组：超大文件、总量超限、截断内容和磁盘写满要返回失败，不能伪装成完整成功。
• 重复组：同名文件和文件/目录冲突要固定行为，并在日志中保留条目顺序。

测试结束后用临时输出根目录的绝对路径做一次清单比对，确认每个成功文件都位于该根目录下。这个断言比“函数没有返回错误”更有价值。

常见问题

只用 filepath.Clean 能防路径穿越吗？

不能。它会规范化字符串，但不会自动拒绝规范化后的父级路径。应先判断本地相对路径，再把结果交给受限根目录的写入接口。

为什么不直接保留符号链接？

因为链接的最终指向可能超出输出目录，也可能覆盖已有目标。除非导入协议明确需要它并有额外的链接目标校验，否则拒绝更容易审计。

解包到新目录还需要做边界检查吗？

需要。新目录降低了覆盖风险，却没有改变路径条目本身的不可信性质；边界检查、类型策略和资源上限仍然要保留。

发布前检查清单

把路径判断、类型策略、大小上限和失败语义写进测试，再观察拒绝日志是否包含足够上下文。真正值得上线的解包器不是“能读出 tar”，而是在异常条目出现时，既不越界写入，也能让值班人员知道哪一条被拒绝、为什么被拒绝。