Go tar 解包后文件权限异常怎样还原

我在把 Go 生成的 tar 包解到另一台 Linux 主机时，最容易误判的一类问题就是“归档里的权限已经变了”。实际情况通常是两层权限叠在一起：tar.Header.Mode 保存的是归档头里的权限位，而文件系统创建时还会受到目标系统 umask 影响。目录如果已经存在，os.MkdirAll 也不会替你重新设置它的最终权限。

官方地址：https://pkg.go.dev/archive/tar

因此，可靠的还原方式是：先从 Header 取出权限位，再按条目类型创建，最后显式调用 Chmod。本文的示例只讨论普通文件和目录的权限还原；符号链接作为独立边界处理，不把它当作普通文件覆盖。

先确认：Header.Mode 不是落盘后的最终权限

archive/tar 的 Header 用 Mode 表示权限和模式位，Typeflag 表示普通文件、目录或链接等条目类型。通过 Header.FileInfo() 可以得到一个 fs.FileInfo，它的 Mode() 适合用来观察条目的文件模式。

排查时可以先把两个值分开看：

• 归档来源：fs.FileMode(header.Mode).Perm()，例如 0644 或 0755。
• 目标落盘：创建函数传入的模式，再经过操作系统的 umask，随后才是实际权限。

所以只把权限传给 os.OpenFile 或 os.MkdirAll，并不能保证最终结果与归档完全一致。特别是部署目录已经存在时，创建函数甚至可能没有机会修改原权限。

只提取权限位，不把条目类型混进模式

还原函数先把 Header.Mode 转为 fs.FileMode，然后调用 Perm() 取出读、写、执行三组权限。这样做的好处是把“权限”与“这是目录还是链接”分开，后面的分支更容易检查。

package main

import (
	"archive/tar"
	"fmt"
	"io/fs"
)

// entryPerm 只提取 tar 头中的权限位，避免把类型信息当作权限使用。
func entryPerm(header *tar.Header) (fs.FileMode, error) {
	if header == nil {
		return 0, fmt.Errorf("tar header 为空") // 先拒绝无效条目，避免后续解引用崩溃。
	}

	perm := fs.FileMode(header.Mode).Perm()
	if perm == 0 && header.Typeflag != tar.TypeDir {
		return 0, fmt.Errorf("条目 %q 没有可用权限位", header.Name) // 允许目录使用 000，但普通文件要显式确认。
	}
	return perm, nil
}

目录的 000 在某些归档中可能是有意的，因此生产代码可以把“零权限是否允许”改成配置项。文章中的关键点不是强行替换权限，而是不要把 Mode 原值直接当成 os.FileMode 的全部语义。

普通文件和目录必须分开还原

对普通文件，我会保留创建时的权限参数，但创建成功后再调用一次 Chmod。这一步抵消了 umask 对最终结果的影响。对目录则先 MkdirAll，再 Chmod，因为目录可能早已存在，创建函数不会更新它。

package main

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

// restoreEntry 把当前 tar 条目写入目标目录，并在创建后恢复权限。
func restoreEntry(tr *tar.Reader, header *tar.Header, targetDir string) error {
	if !filepath.IsLocal(header.Name) {
		return fmt.Errorf("拒绝非本地路径 %q", header.Name) // 防止归档路径跳出目标目录。
	}

	perm := fs.FileMode(header.Mode).Perm()
	dst := filepath.Join(targetDir, filepath.FromSlash(header.Name))

	switch header.Typeflag {
	case tar.TypeDir:
		if err := os.MkdirAll(dst, perm); err != nil {
			return fmt.Errorf("创建目录 %q: %w", header.Name, err)
		}
		if err := os.Chmod(dst, perm); err != nil {
			return fmt.Errorf("恢复目录权限 %q: %w", header.Name, err)
		}
		return nil

	case tar.TypeReg, 0:
		file, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, perm)
		if err != nil {
			return fmt.Errorf("创建文件 %q: %w", header.Name, err)
		}
		defer file.Close() // 无论复制是否成功，都要释放文件描述符。

		if _, err := io.Copy(file, tr); err != nil {
			return fmt.Errorf("写入文件 %q: %w", header.Name, err)
		}
		if err := file.Chmod(perm); err != nil {
			return fmt.Errorf("恢复文件权限 %q: %w", header.Name, err)
		}
		return nil

	default:
		return fmt.Errorf("暂不自动写入特殊条目 %q，类型 %q", header.Name, header.Typeflag)
	}
}

这里的 file.Chmod 放在复制完成后，是为了让“内容写入”和“最终权限”各自有清晰的失败点。目录分支没有读取 tr，因为目录条目没有普通文件数据体。

符号链接不要走普通文件分支

符号链接的权限语义与普通文件不同，直接使用 OpenFile 可能跟随已有链接，造成写入目标不符合预期。更稳妥的做法是先明确产品是否需要恢复链接，再单独校验 header.Linkname 并调用 os.Symlink；如果当前需求只恢复普通文件和目录，就像示例一样显式返回“不支持”，不要静默当作普通文件。

同样，归档中的设备节点、FIFO 等特殊条目也不应在没有明确策略时自动创建。Header.Typeflag 的分支越明确，权限异常越容易被定位到具体条目。

权限异常时按这份清单排查

1. 先打印或记录 header.Name、header.Typeflag 和 fs.FileMode(header.Mode).Perm()，确认归档头本身没有丢权限。
2. 确认目标目录是否已经存在；如果存在，MkdirAll 不会替换它的权限。
3. 确认创建后是否执行了 Chmod，并且传入的是提取后的权限位，而不是未经区分的模式值。
4. 检查运行进程的 umask。如果只看创建瞬间的权限，往往会误以为 tar 解包丢了权限。
5. 最后区分普通文件、目录、符号链接和特殊条目，避免用一套代码覆盖所有类型。

我自己的取舍是：部署包只自动恢复普通文件和目录，遇到链接等特殊条目就记录条目名并停止当前条目处理。这样比“尽量解出来”更容易保证结果可解释；如果业务确实需要链接，再为它增加单独的白名单和校验。

常见问题

为什么创建时传了 0755，结果却不是 0755？

创建模式还会经过目标系统的 umask；另外目录可能已经存在。创建后调用 Chmod，并分别覆盖新旧目录，才能把归档权限作为最终目标。

Header.FileInfo() 能直接恢复文件权限吗？

它能提供一个用于观察的 fs.FileInfo，但真正落盘仍要由你的创建和 Chmod 逻辑完成。常见写法是从 FileInfo().Mode().Perm() 或 Header 的 Mode 提取权限位，再按条目类型处理。

总结一下：先看归档头，再分条目类型；创建时传模式，创建后再 Chmod；把 umask、已存在目录和特殊条目单独列为排查项。这样“解包后权限异常”就能从模糊现象变成几个可定位的分支。