Go archive/tar 怎么限制解包路径不越出目标目录

用 Go 的 archive/tar 解包时，真正可靠的边界不是 filepath.Join(dest, hdr.Name) 的字符串结果，而是“条目名先通过本地路径检查，文件创建再由根目录对象执行”。这样既能挡住 ../ 和绝对路径，也能避免归档里的符号链接把后续文件带到目标目录之外。

先把“路径穿越”和“链接逃逸”分开

归档条目名为 docs/../config.yaml、/etc/app.conf 或 Windows 盘符路径时，属于文件名本身就不应落盘的情况。Go 当前的 archive/tar 可以在 GODEBUG=tarinsecurepath=0 时通过 tar.ErrInsecurePath 报告非本地文件名，但文档也说明它只校验文件名，不校验链接目标。

第二类更隐蔽：归档先写入一个指向目标目录外的符号链接，再写入看似正常的 link/out.txt。即使第二个名字没有 ..，普通的路径拼接也可能跟随已经创建的链接。因此，安全解包要同时做名称检查和文件系统根目录约束。

Next 后先检查名称，再筛选条目类型

不要忽略 Next 返回的第二个结果，也不要只用 filepath.Clean 把危险名字“修正”后继续写入。清理会改变归档语义，拒绝更容易审计。下面的判断同时覆盖 Go 自己报告的错误与显式本地路径检查：

package main

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

func nextRegularEntry(tr *tar.Reader) (*tar.Header, error) {
    hdr, err := tr.Next()
    if err == io.EOF {
        return nil, io.EOF // 归档结束，交给上层正常收尾
    }
    if err != nil && !errors.Is(err, tar.ErrInsecurePath) {
        return nil, err // 损坏头部等解析错误不能继续写文件
    }
    if hdr == nil || errors.Is(err, tar.ErrInsecurePath) || !filepath.IsLocal(hdr.Name) {
        return nil, fmt.Errorf("拒绝非本地条目: %q", hdrName(hdr)) // 不把危险名字清洗后落盘
    }
    if hdr.Typeflag != tar.TypeReg && hdr.Typeflag != tar.TypeDir {
        return nil, fmt.Errorf("拒绝特殊条目 %q, type=%d", hdr.Name, hdr.Typeflag) // 链接和设备文件不进入默认解包器
    }
    return hdr, nil
}

func hdrName(hdr *tar.Header) string {
    if hdr == nil {
        return "" // 保留错误上下文，避免错误处理再次 panic
    }
    return hdr.Name
}

这个辅助函数只负责读取与分类，真正写入时还要使用根目录句柄。若业务确实需要支持链接，必须另做目标解析、权限和竞态设计，不能把它们混入普通文件分支。

用 os.Root 让创建动作留在目标目录内

Go 1.24 引入的 os.OpenRoot 可以打开一个目录根，Root.MkdirAll、Root.OpenFile 等方法以这个根为边界处理相对名称。下面的示例只接受目录和普通文件，并把单文件大小限制也放在写入前：

package main

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

const maxFileSize = 128  maxFileSize {
                return fmt.Errorf("文件过大: %q (%d)", hdr.Name, hdr.Size) // 先限额再打开文件
            }
            if err := root.MkdirAll(filepath.Dir(name), 0750); err != nil {
                return err // 创建父目录时仍受同一个根约束
            }
            out, err := root.OpenFile(name, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0600)
            if err != nil {
                return err // Root.OpenFile 不把 name 解析到根目录之外
            }
            _, copyErr := io.CopyN(out, tr, hdr.Size) // 只复制当前 Header.Size 指定的数据
            closeErr := out.Close() // 及时关闭，避免大量条目耗尽描述符
            if copyErr != nil {
                return copyErr
            }
            if closeErr != nil {
                return closeErr
            }
        default:
            return fmt.Errorf("不支持的条目类型: %q", hdr.Name) // 拒绝软链接、硬链接和设备文件
        }
    }
}

这里没有根据 filepath.Join 的结果做“是否仍在根目录”的字符串比较，因为这类比较无法替代文件系统级的链接防护。os.Root 也不意味着可以放松条目筛选：链接目标和特殊文件仍然应按业务需要显式处理。

旧版本 Go 的降级方案与检查清单

如果项目暂时不能使用 os.Root，至少保留 filepath.IsLocal、拒绝链接和特殊文件、使用固定权限、限制单文件大小，并让解包目录本身是专用的临时目录。仅靠 filepath.Clean 或 strings.HasPrefix 不足以抵抗符号链接竞态；高风险、多用户或攻击者可修改目标目录的场景应升级 Go，或采用专门提供根目录安全打开能力的实现。

相关问题

为什么不能只判断 strings.HasPrefix？

规范化路径、大小写、分隔符和符号链接都可能让字符串前缀判断与实际落盘位置不一致。文件名检查和根目录 API 要一起使用。

archive/tar 的 ErrInsecurePath 会检查符号链接吗？

不会。官方文档明确它只校验文件名，不校验链接目标，所以示例直接拒绝链接条目。

必须保留软链接时怎么办？

不要直接复用普通文件分支。先定义允许的链接目标范围，处理创建顺序和竞态，再使用能在根目录内安全操作的文件 API。