archive/tar 解包时校验相对路径的安全实现

用 Go 的 archive/tar 解包外部文件时，最先要检查的不是文件内容，而是 tar.Header.Name。可靠的做法是：把条目名当成不可信输入，先用 filepath.IsLocal 拒绝绝对路径和会走出当前目录的路径，再根据条目类型决定是否写入。目录和普通文件可以进入受控写盘流程，符号链接、硬链接和设备节点则直接拒绝。

核心原则：检查必须发生在 filepath.Join 和创建目标文件之前；清理字符串不能替代边界判断，忽略 ErrInsecurePath 也不能替代应用层策略。

1. 先把 tar 条目名当成不可信路径

archive/tar 以流的方式逐个返回条目，条目名来自归档本身。若直接执行 filepath.Join(root, hdr.Name)，绝对路径、父目录组件或平台特殊名称就可能改变预期的落盘位置。

filepath.IsLocal 适合做第一道词法检查：它要求路径非空、非绝对，并且不会通过 .. 走出当前目录。它不检查文件系统中的符号链接，所以后面仍要限制链接条目，不能只依赖一个布尔值。

2. 在 tar.Reader.Next 处处理 ErrInsecurePath

当前 Go 的 tar.Reader.Next 会返回下一个条目；当启用 GODEBUG=tarinsecurepath=0 时，遇到非本地文件名会返回带有 tar.ErrInsecurePath 的头部。应用不要把这个错误当成普通提示后继续写盘，而应记录条目名并拒绝当前归档。

package extractor

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

// nextLocalEntry 只返回可以进入应用层写盘策略的本地路径条目。
func nextLocalEntry(tr *tar.Reader) (*tar.Header, error) {
    hdr, err := tr.Next()
    if err == io.EOF {
        return nil, io.EOF // 归档正常结束，由调用方结束循环。
    }
    if err != nil {
        if errors.Is(err, tar.ErrInsecurePath) {
            return nil, fmt.Errorf("拒绝不安全的 tar 路径 %q: %w", hdrName(hdr), err)
        }
        return nil, fmt.Errorf("读取 tar 条目失败: %w", err)
    }
    if hdr == nil || !filepath.IsLocal(hdr.Name) {
        return nil, fmt.Errorf("拒绝非本地 tar 路径 %q", hdrName(hdr))
    }
    return hdr, nil
}

// hdrName 让异常日志在收到空头部时也能安全生成。
func hdrName(hdr *tar.Header) string {
    if hdr == nil {
        return ""
    }
    return hdr.Name
}

这里的错误处理有两个重点：一是先判断 err，因为某些版本和配置下可能同时返回头部与 ErrInsecurePath；二是即使没有收到该错误，也再次调用 filepath.IsLocal，把应用策略固定在代码中，而不是固定在进程环境变量中。

3. 先限制条目类型，再执行写盘

路径名是第一层边界，条目类型是第二层边界。普通文件和目录的语义相对清晰；符号链接可能把后续写入导向目标目录之外，硬链接和设备节点也不应被一个通用上传解包器默认创建。最小安全策略可以只接受目录与普通文件。

func allowedEntry(hdr *tar.Header) error {
    if hdr == nil {
        return fmt.Errorf("tar 条目为空")
    }
    switch hdr.Typeflag {
    case tar.TypeDir, tar.TypeReg, tar.TypeRegA:
        return nil // 目录和普通文件进入受控写盘分支。
    case tar.TypeSymlink, tar.TypeLink:
        return fmt.Errorf("拒绝链接条目 %q", hdr.Name) // 不解析链接目标。
    default:
        return fmt.Errorf("拒绝不支持的条目类型 %d: %q", hdr.Typeflag, hdr.Name)
    }
}

如果业务确实需要恢复符号链接，应把它设计成单独的能力：检查链接目标是否本地、限制链接创建顺序，并在写入时使用具备目录边界语义的文件 API。不要把“允许所有 Typeflag”当成兼容性选项。

4. 创建文件时保持目标目录边界

完成路径和类型检查后，才能拼接目标路径。下面的示例只接受目录和普通文件，并限制单个文件大小；文件内容先写入目标目录中的临时文件，成功后再重命名，避免错误中断时留下一个看似完整的半成品。

func extractEntry(tr *tar.Reader, root string, hdr *tar.Header, maxBytes int64) error {
    if err := allowedEntry(hdr); err != nil {
        return err
    }
    if !filepath.IsLocal(hdr.Name) {
        return fmt.Errorf("拒绝越界路径 %q", hdr.Name)
    }

    target := filepath.Join(root, filepath.FromSlash(hdr.Name))
    if hdr.Typeflag == tar.TypeDir || hdr.Name[len(hdr.Name)-1] == filepath.Separator {
        return os.MkdirAll(target, 0o755) // 目录只在路径确认后创建。
    }
    if hdr.Size  maxBytes {
        return fmt.Errorf("文件 %q 超过单文件大小限制", hdr.Name)
    }

    if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
        return fmt.Errorf("创建父目录失败: %w", err)
    }
    tmp, err := os.CreateTemp(filepath.Dir(target), ".extract-*")
    if err != nil {
        return fmt.Errorf("创建临时文件失败: %w", err)
    }
    tmpName := tmp.Name()
    defer os.Remove(tmpName) // 出错时清理未完成的临时文件。
    if _, err := io.CopyN(tmp, tr, hdr.Size); err != nil {
        _ = tmp.Close()
        return fmt.Errorf("写入 %q 失败: %w", hdr.Name, err)
    }
    if err := tmp.Close(); err != nil {
        return fmt.Errorf("关闭 %q 失败: %w", hdr.Name, err)
    }
    if err := os.Rename(tmpName, target); err != nil {
        return fmt.Errorf("提交 %q 失败: %w", hdr.Name, err)
    }
    return nil
}

示例需要补充 os、io、fmt 和 path/filepath 导入。实际项目还应处理同名目标是否允许覆盖、权限模式是否采用固定值，以及目标目录是否由更严格的目录句柄 API 管理。代码中的 filepath.IsLocal 是词法检查，不是对符号链接的解析。

5. 大文件、环境开关与运维处理

不要用 io.Copy 无限制地把归档内容写入磁盘。tar.Header.Size 是当前条目的逻辑大小，可以在复制前做上限判断；整包还应有总大小、条目数量和目录深度等配额，避免大量小文件耗尽 inode 或句柄。

GODEBUG=tarinsecurepath=0 可帮助把非本地条目暴露为 ErrInsecurePath，但它不是应用层的完整安全策略：官方文档明确指出该检查只针对文件名，不针对链接目标。应用仍要保留 IsLocal 和条目类型限制，并把拒绝原因写入结构化日志。

# 在受控环境中开启非本地 tar 路径的显式报错。
GODEBUG=tarinsecurepath=0 go run ./cmd/extractor ./incoming/archive.tar ./workdir

上线排查时，重点看三类信号：被拒绝的原始条目名、归档来源与请求标识、解包配额是否触发。回滚时删除本次任务的临时目标目录，不要只删除最后一个失败文件；若归档来源不可信，优先丢弃整包并要求重新上传。

小结

常见问题

只调用 filepath.Clean 再判断前缀可以吗？

不建议。字符串前缀判断容易把相邻目录名误认为同一边界，且无法解决符号链接影响；优先使用 filepath.IsLocal，再配合条目类型限制。

为什么不直接忽略 ErrInsecurePath？

忽略它等于接受调用方未明确允许的非本地条目名。除非业务有清晰的兼容策略并且已经把最终落盘限制在受控目录，否则应拒绝归档。

必须支持符号链接怎么办？

把符号链接作为单独需求处理：验证链接目标、限制创建顺序，并使用具备目录边界保护的文件 API。不要因为 tar 能读出该条目，就默认它适合直接恢复。