Go archive/tar 解压如何阻断路径逃逸：文件名清理、目标目录校验与回滚

上传一个 tar 包时，最危险的地方通常不是读取字节，而是把 Header.Name 当成普通文件名，直接拼到解压目录后写盘。条目里只要出现绝对路径、../，或者先写入一个指向目录外的符号链接，解压结果就可能越过预期目录。稳妥的做法是先检查每个条目，再写入独立临时目录，全部通过后才替换正式目录。

先把解压目标从正式目录隔离出来

假设服务把用户包展开到 /srv/app/releases/current。不要边读边写这个目录，而是为本次请求创建同级临时目录，例如 /srv/app/releases/.upload-xxxx。临时目录只负责承接本次结果，后续的文件名检查、大小限制和完整性检查都围绕它进行。

方案选择上，直接拼接路径最省代码，但无法回答“结果是否仍在目标目录内”；仅检查 strings.HasPrefix 又会把 /srv/app/releases-old 错认为子目录。相对路径校验和临时目录落盘多几步，却把失败影响面压缩到了一个可删除目录。

用 IsLocal 和 Rel 拦住条目名

Go 的 archive/tar 会按顺序返回每个 Header。应用层可以先拒绝非本地路径，再把清理后的相对路径与目标目录组合，最后用绝对路径关系复核一次：

func safeTarget(root, name string) (string, error) {
    if !filepath.IsLocal(name) {
        return "", fmt.Errorf("unsafe tar name: %q", name)
    }
    clean := filepath.Clean(filepath.FromSlash(name))
    if clean == "." || clean == string(filepath.Separator) {
        return "", fmt.Errorf("empty tar name")
    }
    target := filepath.Join(root, clean)
    rel, err := filepath.Rel(root, target)
    if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
        return "", fmt.Errorf("tar entry escapes root: %q", name)
    }
    return target, nil
}

检查点不在于把 .. 替换掉，而在于遇到不满足条件的条目就停止。否则攻击者可以用“清理后看起来正常”的路径覆盖已有文件，错误也很难追溯。

普通文件、目录和链接不要共用一条写入路径

目录只需要创建；普通文件需要限制 Header.Size 并用 io.CopyN 读取；符号链接和硬链接则要单独决策。一个面向上传包的默认策略是拒绝链接类型，这比先创建链接再猜它是否指向 root 外部更简单。

const maxFile = 32  maxFile { return fmt.Errorf("file too large: %s", h.Name) }
    if err := os.MkdirAll(filepath.Dir(target), 0750); err != nil { return err }
    f, err := os.OpenFile(target, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
    if err != nil { return err }
    _, copyErr := io.CopyN(f, tr, h.Size)
    closeErr := f.Close()
    if copyErr != nil { return copyErr }
    if closeErr != nil { return closeErr }
default:
    return fmt.Errorf("unsupported tar type: %d", h.Typeflag)
}

O_EXCL 让重复条目不能悄悄覆盖同一文件；生产代码还应累计条目总数和总字节数，并在超过限制时停止读取。这里的限制不是安全边界的替代品，它主要防止一个合法路径把磁盘和进程时间耗尽。

校验通过后再替换，失败只回滚临时目录

临时目录内的文件全部写完后，再检查清单中必须存在的文件、文件权限和总大小。切换正式目录时要保留旧版本，采用“current 指向新目录”的发布方式更容易回退：新目录验收失败就删除临时目录；发布后发现业务检查不通过，就把 current 指回上一个已验收目录。

不要在解压中途更新数据库里的“已完成”状态，也不要把临时目录直接暴露给请求路由。解压成功、目录验收成功、指针切换成功这三个动作应分别记录，日志中至少保留包标识、条目数、展开字节数和拒绝原因。

四个容易漏掉的边界

• 跨平台分隔符：tar 名称通常使用斜杠，落到 Windows 前要先用 filepath.FromSlash，不能假设反斜杠只是普通字符。
• 符号链接：即便链接名本身在 root 内，链接目标仍可能指向外部；不需要链接语义时直接拒绝。
• 读取不完整：Header.Size 是逻辑大小，复制后要确认读满该大小，并处理尾部数据和下一个条目的边界。
• 资源上限：同时限制单文件、总展开大小、条目数量和单次请求耗时，避免路径校验正确但服务仍被压垮。

常见问题

只调用 filepath.Clean 是否足够？

不够。Clean 是词法清理，不能单独证明最终目标仍在 root 内，也不能处理符号链接带来的真实文件系统跳转。

为什么不直接把 ../ 替换为空？

替换会改变用户提交的条目语义，还可能把两个不同文件压成同一个名字。更安全的策略是发现非本地路径后拒绝整个包。

archive/tar 的 ErrInsecurePath 能替代应用层检查吗？

不能完全替代。它受 Go 版本和 GODEBUG 行为影响，应用仍需决定是否允许链接、最大展开量以及如何回滚。

解压失败时应该删除哪些内容？

只删除本次临时目录，并保留旧的已验收目录和拒绝日志。若正式目录已切换，再按版本指针回退，不要用不完整临时结果覆盖旧版本。

落地前的检查清单

上线前可以用包含 ../outside、绝对路径、重复文件、符号链接和超大条目的测试包逐项验证：路径拒绝是否发生在写盘前，临时目录是否清理，旧版本是否仍可访问，以及日志是否能定位到具体 Header.Name。这样才能确认防护是一个闭环，而不是只在代码里出现了几个检查函数。