archive/tar 解包时保留文件模式的处理方法

解包 tar 文件时，最容易被忽略的不是数据有没有写出来，而是文件原本的模式有没有留下来。只调用 os.Create 并把 tar.Reader 中的内容复制到目标文件，通常只能得到创建函数使用的默认权限；归档头里的 Header.Mode 不会自动替你调用 chmod。

可靠的处理顺序是：先读取成员头，限制成员名只能落在目标目录内，再按 Typeflag 区分目录、普通文件和符号链接。普通文件内容写完后，根据 Header.Mode 调用 os.Chmod；目录则在创建时使用模式，并在全部成员处理后再次恢复一次。这样既保留了权限信息，也不会把不同类型的成员混成一个分支。

关键点只有一个：archive/tar 负责提供元数据和内容流，真正落盘的权限仍要由解包程序显式应用。

现象：文件内容正确，执行权限却消失

假设归档中的 bin/start.sh 带有 0755 模式，解包代码却使用 os.Create(path) 创建它。文件内容可以完整写出，但最终模式受到创建参数和系统 umask 的影响，常见结果是脚本不能直接执行。只检查文件是否存在，无法发现这类问题。

这个现象的影响通常集中在三类成员：脚本需要执行位，配置文件需要保持只读约束，目录需要保留组写或搜索权限。它们都不是复制字节就能恢复的属性。

根因：Header.Mode 是元数据，不是写文件参数

archive/tar.Header 的 Mode 表示权限和模式位，Typeflag 表示当前条目是什么类型。Reader.Next 返回一个头后，当前 reader 才对应这个成员的数据；下一个 Next 会推进到下一个条目。

可以把一个成员拆成两条线理解：内容线由 io.Copy 写入，元数据线由 Mode 和成员类型决定。前者成功，不代表后者已经恢复。

先把路径和成员类型分开处理

解包前要先处理路径。归档成员名不应直接拼接到输出根目录；绝对路径或包含父目录跳转的名字会把写入位置带出目标目录。filepath.IsLocal 可以做词法层面的本地路径判断，但它不考虑符号链接实际指向哪里，所以符号链接还需要单独的策略。

下面的代码保留了一个小而完整的分支结构：目录只创建，普通文件复制内容并恢复模式，符号链接先拒绝。若业务确实要恢复链接，应在可信输入和明确的链接目标策略下单独实现。

package main

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

func extractTar(r io.Reader, dest string) error {
	tr := tar.NewReader(r)

	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			return nil
		}
		if err != nil {
			return fmt.Errorf("读取 tar 头失败: %w", err)
		}
		// 先限制归档成员名，避免把路径直接带到目标目录之外。
		if !filepath.IsLocal(filepath.ToSlash(hdr.Name)) {
			return fmt.Errorf("拒绝非本地归档路径: %q", hdr.Name)
		}
		target := filepath.Join(dest, filepath.FromSlash(hdr.Name))

		switch hdr.Typeflag {
		case tar.TypeDir:
			// 目录要先存在，最终再统一恢复一次模式。
			if err := os.MkdirAll(target, os.FileMode(hdr.Mode)); err != nil {
				return fmt.Errorf("创建目录 %q 失败: %w", target, err)
			}
			if err := os.Chmod(target, os.FileMode(hdr.Mode)); err != nil {
				return fmt.Errorf("恢复目录模式 %q 失败: %w", target, err)
			}
		case tar.TypeReg, tar.TypeRegA:
			// 父目录先创建，文件内容写完后才应用归档模式。
			if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
				return fmt.Errorf("创建父目录失败: %w", err)
			}
			f, err := os.OpenFile(target, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600)
			if err != nil {
				return fmt.Errorf("创建文件 %q 失败: %w", target, err)
			}
			_, copyErr := io.Copy(f, tr)
			closeErr := f.Close()
			if copyErr != nil {
				return fmt.Errorf("写入文件 %q 失败: %w", target, copyErr)
			}
			if closeErr != nil {
				return fmt.Errorf("关闭文件 %q 失败: %w", target, closeErr)
			}
			// 用归档头恢复权限，避免创建权限和 umask 把模式改掉。
			if err := os.Chmod(target, os.FileMode(hdr.Mode)); err != nil {
				return fmt.Errorf("恢复文件模式 %q 失败: %w", target, err)
			}
		case tar.TypeSymlink:
			// 不把链接目标当文件内容写入，业务需要时应增加独立的链接策略。
			return fmt.Errorf("暂不接受符号链接: %q -> %q", hdr.Name, hdr.Linkname)
		default:
			return fmt.Errorf("暂不支持 tar 成员类型 %d: %q", hdr.Typeflag, hdr.Name)
		}
	}
}

这里把普通文件的初始权限设为较保守的 0600，写完后再使用归档模式。这样文件还没写完时不会短暂暴露归档声明的权限；如果目标环境不支持某些 Unix 模式位，应把差异记录为平台策略，而不是默默假设所有系统一致。

修复动作：写完内容后显式恢复 Mode

普通文件的顺序不能颠倒。先 OpenFile、复制当前条目的全部内容并关闭文件，再调用 os.Chmod。关闭错误也要保留，因为底层写入可能在关闭时才报告失败。

目录需要稍微谨慎：MkdirAll 对已经存在的父目录不会重新应用模式，而目录还可能受 umask 影响。因此示例在创建目录后立即恢复模式；在更复杂的实现中，也可以把目录模式收集起来，所有文件处理完成后按路径深度从深到浅再统一应用。

Header.Mode 转换为 os.FileMode 后，权限位可以交给 os.Chmod。但 Go 官方文档也说明不同操作系统使用的模式子集不同：Unix 会使用权限位和部分特殊位，Windows 对这些位的支持不同，不能把 Unix 的执行位语义直接扩展到所有平台。

符号链接不能套用普通文件分支

符号链接的内容不是链接指向文件的正文，而是 Header.Linkname 中的目标名。如果把它当普通文件创建，得到的是一个包含目标路径文字的普通文件；如果直接创建链接，又必须继续判断链接目标是否会绕过输出根目录。

因此，最小可用策略是像示例一样拒绝符号链接，并在错误信息里保留链接目标，方便调用方决定是否允许。若必须支持链接，至少要分别约束链接名和链接目标，并在创建后复查真实路径；不能只对 hdr.Name 调一次 IsLocal 就认为整个写入过程安全。

复查：把模式恢复变成明确的维护清单

这类解包器上线前，复查可以围绕以下清单完成：

最后可以准备一个同时包含目录、普通文件、只读文件和可执行脚本的测试归档。在目标操作系统上检查文件是否存在、内容是否一致、权限是否符合预期；如果还要跨平台发布，则把“哪些模式位有意义”写成清晰的兼容说明，而不要仅比较一个 Unix 八进制数字。

常见问题

为什么不用 os.Create 的第三个参数直接传 Header.Mode？

可以传入初始权限，但新文件的创建仍可能受 umask 影响，而且这只覆盖普通文件。显式在写入结束后调用 Chmod，语义更清楚，也能与目录和后续维护策略保持一致。

Header.Mode 为零时应该怎么办？

不要把零当作“自动修复”。先根据归档格式和业务约定决定默认模式，并把默认值与归档声明值区分开；对于不可信输入，宁可采用受限默认权限。

filepath.IsLocal 能完全阻止路径穿越吗？

它能做词法层面的本地路径判断，但官方说明它不考虑符号链接。普通文件路径、链接目标、目标目录权限和运行账户权限仍要作为独立边界处理。

总结一下：archive/tar 解包的文件模式保留不是复制 API 的隐含行为，而是一个明确的元数据恢复步骤。先按类型分支，再在正确的落盘时机调用 os.Chmod，同时把路径和符号链接边界单独处理，才能让内容、权限与安全策略保持一致。