Go tar 解包的路径过滤与文件类型处理方案

Go 的 archive/tar 能按顺序读取归档条目，但“读到条目”不等于“可以直接写入磁盘”。真正容易出问题的地方有三个：成员名可能跳出输出目录，Linkname 可能绕过成员名检查，目录、普通文件、符号链接和设备节点也不能用同一套写法。

这篇只处理 tar 解包的路径过滤与文件类型边界。推荐的落地组合是：把归档解到专门创建的空目录；先用 filepath.IsLocal 拒绝绝对路径和 .. 路径；再按 Header.Typeflag 只允许目录和普通文件；最后对每个输出路径做相对路径边界检查。对不受信任的链接和设备节点，默认拒绝。

先明确解包时真正要保护的边界

假设业务把归档写入 /srv/app/releases/current。归档里出现 etc/app.conf 时，目标应该是该目录下的文件；出现 ../../etc/passwd 或 /tmp/out 时，目标不能被拼接出来。仅仅调用 filepath.Clean 不够，因为它只做词法整理，不代表路径已经被限制在某个根目录里。

三种方案怎么选

我在工程里通常会把解包方案按风险分成三档。第一档是词法路径过滤：对每个成员名调用 filepath.IsLocal，再用 Join 和 Rel 做边界判断。它适合把归档写进新建的临时目录，且归档中的链接全部拒绝。

第二档是“词法过滤加专用空目录”。这是本文代码采用的方案：输出目录由程序创建，解包前不放入业务已有的符号链接，也不允许覆盖旧文件。这样可以把成员路径、输出目录和文件类型的规则写得很清楚。

第三档是文件系统级隔离。若输出目录可能被其他进程同时修改，或者解包进程权限很高，单纯的字符串检查还不够，需要使用操作系统提供的目录句柄、openat/O_NOFOLLOW 一类能力，或当前 Go 版本提供的根目录 API，把每次创建动作绑定到已打开的根目录。它的工程成本更高，但适合多租户和高权限服务。

用 filepath.IsLocal 固定输出目录边界

tar.Header.Name 是归档成员名，不应直接传给 filepath.Join。先把 tar 使用的斜杠转换为当前系统路径，再用 IsLocal 检查它是否为非空、非绝对且不含跳出当前层级的路径。之后再把结果和输出根目录拼接，并用 Rel 做一次可读的边界判断。

下面的函数把检查集中在一个位置。Rel 的判断不是为了替代 IsLocal，而是让“目标仍在 root 内”这个业务约束在代码里显式出现。

package tarfilter

import (
	"fmt"
	"path/filepath"
	"strings"
)

// localTarget 把归档成员名转换成输出根目录下的目标路径。
func localTarget(root, archiveName string) (string, error) {
	// tar 名称使用斜杠，先转换为当前系统的路径分隔符。
	name := filepath.FromSlash(archiveName)
	if name == "" || !filepath.IsLocal(name) {
		return "", fmt.Errorf("拒绝非本地归档路径: %q", archiveName)
	}

	clean := filepath.Clean(name)
	if clean == "." {
		return "", fmt.Errorf("拒绝空归档路径: %q", archiveName)
	}

	target := filepath.Join(root, clean)
	rel, err := filepath.Rel(root, target)
	if err != nil {
		return "", fmt.Errorf("计算输出边界失败: %w", err)
	}
	// Rel 返回 .. 或以 .. 开头时，目标已经跳出了 root。
	if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) || filepath.IsAbs(rel) {
		return "", fmt.Errorf("归档路径越过输出目录: %q", archiveName)
	}
	return target, nil
}

按 Header.Typeflag 处理目录与普通文件

archive/tar.Reader.Next 会逐个返回 Header，普通文件的数据随后从同一个 reader 读取，目录和链接等特殊类型则没有普通文件数据。解包循环必须先决定类型，再决定是否创建目录或复制数据。

目录只需要 MkdirAll。普通文件建议用 O_EXCL 创建，避免一个归档条目悄悄覆盖输出目录中已有的文件。模式位也应做收敛，示例只保留常见权限位，不把归档里的特殊类型位直接传给文件创建函数。

func createRegularFile(path string, mode int64, src io.Reader, size int64) error {
	// 只保留普通权限位，并为异常的零权限条目给出可读的默认值。
	perm := os.FileMode(mode) & 0o777
	if perm == 0 {
		perm = 0o600
	}

	// O_EXCL 防止把解包当成覆盖写；调用方应使用专用空目录。
	f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, perm)
	if err != nil {
		return err
	}

	written, copyErr := io.CopyN(f, src, size)
	closeErr := f.Close()
	if copyErr != nil {
		return fmt.Errorf("写入 %s 失败，已写 %d/%d 字节: %w", path, written, size, copyErr)
	}
	if closeErr != nil {
		return fmt.Errorf("关闭 %s 失败: %w", path, closeErr)
	}
	return nil
}

上面的函数需要和 archive/tar、io、os、fmt 一起导入。它不负责判断路径，也不处理链接，职责保持单一：只创建一个新的普通文件并复制指定长度的数据。

为什么默认拒绝符号链接和硬链接

路径检查只看 Header.Name，但符号链接的目标放在 Header.Linkname。如果先创建一个指向输出目录外部的链接，再写入同名文件，后续写入可能跟着链接走。硬链接同样有目标语义，设备节点和 FIFO 则可能带来完全不同的系统行为。

因此，除非业务明确需要恢复链接并且有专门的目标校验，否则可以用白名单处理类型：

func extractTar(src io.Reader, root string) error {
	tr := tar.NewReader(src)
	for {
		hdr, err := tr.Next()
		if errors.Is(err, io.EOF) {
			return nil
		}
		if err != nil {
			return fmt.Errorf("读取 tar 条目失败: %w", err)
		}

		target, err := localTarget(root, hdr.Name)
		if err != nil {
			return err
		}

		switch hdr.Typeflag {
		case tar.TypeDir:
			// 目录只创建层级，不读取普通文件内容。
			if err := os.MkdirAll(target, 0o750); err != nil {
				return fmt.Errorf("创建目录 %s 失败: %w", target, err)
			}
		case tar.TypeReg, tar.TypeRegA:
			// 普通文件才从当前 tar reader 复制 hdr.Size 字节。
			if err := os.MkdirAll(filepath.Dir(target), 0o750); err != nil {
				return fmt.Errorf("创建父目录 %s 失败: %w", filepath.Dir(target), err)
			}
			if err := createRegularFile(target, hdr.Mode, tr, hdr.Size); err != nil {
				return err
			}
		default:
			// 不跟随 Linkname，也不创建设备节点、FIFO 等特殊对象。
			return fmt.Errorf("拒绝 tar 特殊类型 %q: name=%q link=%q", hdr.Typeflag, hdr.Name, hdr.Linkname)
		}
	}
}

这个白名单还有一个实际好处：Next 会在进入下一个条目前自动丢弃当前条目剩余数据，但对拒绝的条目我们直接返回错误，不把归档继续当作可信输入处理。若产品希望“跳过链接继续导入”，也应记录跳过原因，而不是创建一个看似成功但内容不完整的目录。

把资源关闭和专用空目录放进完整函数

调用方不要把业务目录直接传给解包函数。更稳妥的做法是先创建临时目录，把归档完整写入临时目录，后续再由发布流程做一次明确的目录替换。下面的包装函数负责打开归档、创建输出目录并关闭输入文件；真正的文件类型规则仍由 extractTar 负责。

func UnpackTar(archivePath string) (string, error) {
	// 临时目录由系统创建，避免复用可能残留的旧目录。
	root, err := os.MkdirTemp("", "tar-unpack-")
	if err != nil {
		return "", fmt.Errorf("创建解包目录失败: %w", err)
	}

	in, err := os.Open(archivePath)
	if err != nil {
		os.RemoveAll(root)
		return "", fmt.Errorf("打开归档失败: %w", err)
	}

	if err := extractTar(in, root); err != nil {
		// 失败时清理半成品，避免调用方误把不完整目录当作成功结果。
		_ = in.Close()
		_ = os.RemoveAll(root)
		return "", err
	}
	if err := in.Close(); err != nil {
		_ = os.RemoveAll(root)
		return "", fmt.Errorf("关闭归档失败: %w", err)
	}
	return root, nil
}

这里的返回值是临时目录路径，调用方在完成校验、发布或移动后应负责 os.RemoveAll。如果业务必须落到固定目录，可以先解包到临时目录，再通过同文件系统内的原子重命名切换版本，避免读者看到半套文件。

哪些场景不能直接套用这段实现

• 需要恢复软链接的备份工具：不能把链接简单改成普通文件，应该单独校验 Linkname 的本地性、目标范围和创建顺序，并评估并发替换风险。
• 允许覆盖已有目录的升级器：要明确覆盖清单、旧文件删除策略和回滚目录，不能只把 O_EXCL 改成 O_TRUNC。
• 高权限多租户服务：使用目录句柄或根目录 API 约束系统调用，避免其他进程在检查和创建之间插入符号链接。
• 超大归档：还要增加总条目数、总解压字节数和单文件大小限制；路径过滤并不能防止资源耗尽。

最终决策表

常见问题

只调用 filepath.Clean 能防止路径穿越吗？ 不能。Clean 是词法整理，必须配合 IsLocal 或 Rel 判断，并让创建动作落在受控目录。

为什么不直接使用 Header.Linkname？ 因为链接目标与成员名是两套路径输入，且创建链接后再写文件可能把写入引到输出目录外。默认拒绝更容易保证边界。

tar.Reader 会自动阻止危险路径吗？ 新版 Go 在特定 GODEBUG 设置下会报告非本地成员名，但它只检查文件名，不检查链接目标；业务仍应显式执行自己的白名单策略。

为什么要用临时目录而不是直接写发布目录？ 临时目录把失败半成品隔离出来，也让最终切换可以成为单独的发布动作。

小结：安全解包的关键不是寻找一个“万能解压函数”，而是把成员路径、输出根目录和文件类型拆成三个可审查的边界。对普通导入场景，IsLocal + Rel + 专用空目录 + 类型白名单 已经能覆盖最常见的路径穿越与链接风险；当并发和权限风险上升时，再升级到文件系统级隔离。