Go tar 解包怎样处理绝对路径和父目录

我在把用户上传的 tar 包解到临时目录时，最容易忽略的不是 tar.Reader 怎么遍历，而是 Header.Name 根本不能直接当成本地文件路径使用。归档项可能写成 /etc/app.conf，也可能写成 ../outside.txt；如果直接执行 filepath.Join(baseDir, hdr.Name) 再创建文件，解包目录的边界就没有真正建立起来。

这篇只处理一个边界：Go tar 解包时，怎样规范化和约束 Header.Name，拒绝绝对路径与父目录。核心做法是先用 filepath.IsLocal 做词法判断，再把通过判断的名字拼到固定根目录；符号链接和硬链接另行拒绝，因为它们的目标不由 Header.Name 自动保护。

官方地址：https://pkg.go.dev/archive/tar

先记住这一条最小配方

不要先拼接再判断，也不要只调用 filepath.Clean。先判断归档名称是否为本地路径：

if !filepath.IsLocal(hdr.Name) {
    // 绝对路径、包含父目录的路径和 Windows 保留名都不进入落盘流程。
    return fmt.Errorf("拒绝不安全的归档路径 %q", hdr.Name)
}

localName := filepath.FromSlash(hdr.Name)
dst := filepath.Join(baseDir, localName)

IsLocal 是纯词法判断：它排除绝对路径、空路径和不能留在当前子树中的路径；对包含 .. 的父目录路径也会返回 false。通过后再执行 Join，才有资格把结果当作目标目录内的路径使用。

为什么 Clean 不能替代 IsLocal

filepath.Clean 只负责把路径做词法整理。例如 pkg/../config.yaml 会被整理成 config.yaml，而 ../../outside.txt 仍然可能是一个带父目录的相对结果。整理路径不等于确认它属于解包根目录。

另外，IsLocal 不会访问文件系统，也不会解析符号链接。这个特点很适合在 Next 返回归档头之后做第一道边界判断，但不能让它承担完整的落盘安全职责。

Next 返回 ErrInsecurePath 时怎么处理

当前 Go 的 tar.Reader.Next 在 GODEBUG=tarinsecurepath=0 时，会对非本地文件名返回 tar.ErrInsecurePath，同时仍可能返回对应的 Header。这可以作为运行时的额外提醒，但应用代码不应依赖环境变量才拒绝危险名称。

hdr, err := tr.Next()
if errors.Is(err, io.EOF) {
    // 没有更多归档项，正常结束。
    return nil
}
if err != nil {
    // 包含 ErrInsecurePath 在内的头部错误都不继续写文件。
    return fmt.Errorf("读取 tar 头部 %q 失败: %w", hdrName(hdr), err)
}
if !filepath.IsLocal(hdr.Name) {
    // 不把 Go 版本或 GODEBUG 配置当成唯一防线。
    return fmt.Errorf("归档路径越出本地范围: %q", hdr.Name)
}

上面的判断顺序有两个好处：先处理 io.EOF，再处理其它读取错误；即使运行环境没有主动返回 ErrInsecurePath，应用自己的 IsLocal 判断也仍然生效。

落盘时还要区分目录、普通文件和链接

通过名称判断后，目录和普通文件可以使用同一套根目录拼接逻辑，但文件类型不能全部当成普通文件处理。尤其是符号链接与硬链接：Header.Name 只是归档项自身的名字，链接真正指向哪里要看 Header.Linkname。

对不可信上传包，最简单且容易复查的策略是拒绝两种链接；如果业务必须保留链接，则需要围绕链接目标做额外的目标解析和落盘约束，不能只复用 IsLocal(hdr.Name)。

一段可直接改造的安全解包骨架

下面这段代码把关键判断集中在一个循环里：先读头部，再拒绝不安全名称和链接，最后按类型创建目录或复制普通文件。示例没有改变文件权限的高位标志，只保留常见的 Unix 权限位；生产环境还应按业务限制文件数量、单文件大小和总解包容量。

package unpack

import (
    "archive/tar"
    "errors"
    "fmt"
    "io"
    "os"
    "path/filepath"
)

// UnpackTar 将归档内容限制在 baseDir 内，并拒绝非本地名称和链接。
func UnpackTar(r io.Reader, baseDir string) error {
    tr := tar.NewReader(r)

    for {
        hdr, err := tr.Next()
        if errors.Is(err, io.EOF) {
            // Next 返回 EOF 表示归档已完整遍历。
            return nil
        }
        if err != nil {
            // 不忽略 ErrInsecurePath 等头部错误。
            return fmt.Errorf("读取 tar 头部失败: %w", err)
        }
        if !filepath.IsLocal(hdr.Name) {
            // 绝对路径、父目录路径和空名称不允许落盘。
            return fmt.Errorf("拒绝归档路径 %q", hdr.Name)
        }
        if hdr.Typeflag == tar.TypeSymlink || hdr.Typeflag == tar.TypeLink {
            // Linkname 的目标不受 Header.Name 的本地性判断保护。
            return fmt.Errorf("拒绝归档链接 %q -> %q", hdr.Name, hdr.Linkname)
        }

        // tar 名称使用斜杠，转换后再与固定根目录拼接。
        localName := filepath.FromSlash(hdr.Name)
        dst := filepath.Join(baseDir, localName)

        switch hdr.Typeflag {
        case tar.TypeDir:
            // 目录项没有数据体，只需要建立目录。
            if err := os.MkdirAll(dst, 0o755); err != nil {
                return fmt.Errorf("创建目录 %q 失败: %w", dst, err)
            }
        case tar.TypeReg, tar.TypeRegA:
            // 父目录先创建，避免归档顺序不规范时写文件失败。
            if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
                return fmt.Errorf("创建父目录 %q 失败: %w", filepath.Dir(dst), err)
            }
            mode := os.FileMode(hdr.Mode) & 0o777
            f, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, mode)
            if err != nil {
                return fmt.Errorf("创建文件 %q 失败: %w", dst, err)
            }
            // 先复制归档数据，再显式关闭文件并返回关闭错误。
            _, copyErr := io.Copy(f, tr)
            closeErr := f.Close()
            if copyErr != nil {
                return fmt.Errorf("写入文件 %q 失败: %w", dst, copyErr)
            }
            if closeErr != nil {
                return fmt.Errorf("关闭文件 %q 失败: %w", dst, closeErr)
            }
        default:
            // 不认识的特殊类型不擅自创建设备或 FIFO。
            return fmt.Errorf("不支持的 tar 类型 %q: %d", hdr.Name, hdr.Typeflag)
        }
    }
}

// hdrName 让错误处理在 Header 为空时也能安全输出名称。
func hdrName(hdr *tar.Header) string {
    if hdr == nil {
        return ""
    }
    return hdr.Name
}

几个容易漏掉的边界

• 不要只检查开头的斜杠。 ../outside.txt、a/../../b 和 Windows 保留名同样不应进入落盘流程，交给 filepath.IsLocal 统一判断。
• 不要把 ErrInsecurePath 当成全部保护。 它受 Go 运行时配置影响，应用自己的名称判断应该始终保留。
• 不要把 Header.Name 的安全误认为 Linkname 安全。 代码拒绝链接是最清楚的默认策略；需要支持链接时必须单独设计目标约束。
• 不要忽略归档资源限制。 路径合法不代表文件数量、单文件大小或总解包大小合理，这些限制应在读取和复制时另行累计。

相关问题

只调用 filepath.Clean 后再 Join 可以吗？ 不建议。Clean 是规范化，不是越界判定；应先用 filepath.IsLocal 拒绝不安全名称。

为什么示例拒绝符号链接？ 因为链接目标在 Header.Linkname 中，名称判断无法证明最终访问的文件仍在解包目录内。

能不能忽略 tar.ErrInsecurePath 继续处理？ 对不可信归档不应这样做。即使确实要兼容非本地名称，也应该明确承担它带来的路径风险，而不是静默忽略错误。

Windows 上还需要做什么？ 仍然先做 IsLocal，再使用 filepath.FromSlash 或较新 Go 提供的路径本地化能力，让平台分隔符和保留名规则由标准库处理。

归档解包的关键不是“把名称清洗得像路径”，而是让每个归档名称先通过本地性判断，再进入固定根目录；目录、普通文件和链接也要有不同的处理策略。这样，绝对路径和父目录会在写盘前被拒绝，剩余的文件类型风险也不会被一个看似简单的 Join 掩盖。