Go archive/tar Header.Gname 怎样保留归档条目的组名

归档后发现组名为空，常见根因不是 Reader.Next 读错了，而是写入端只设置了文件名和权限，没有把组元数据放进 tar.Header。Go 的 archive/tar 会把 Header.Gname 和 Header.Gid 当作条目元数据写入归档；读取时再从 Reader.Next 返回的 Header 取回。要注意，这些字段描述归档里的记录，不会修改当前机器上的真实用户组或文件权限。

官方参考：https://pkg.go.dev/archive/tar#Header

影响面：为什么归档后组名会丢

这类问题通常出现在备份、发布包或跨机器传输中：源文件在本机上看得到所属组，但重新读取 tar 后，Gname 为空，或者只有 Gid 没有可显示的组名。故障影响的是归档元数据的可读性和还原策略，不等于正文文件已经损坏。

Go 的 tar.Header 同时保存 Uid、Gid、Uname、Gname。其中 ID 更适合做稳定的机器标识，名字更适合给人看；两者应该按项目需要一起写入。组名是字符串元数据，不能用来替代操作系统在解包时的权限校验。

时间线：写入、读取和出错的位置

把链路拆开后，问题通常只发生在三个节点：

1. 构造 tar.Header 时只填写了 Name、Mode 和 Size，没有填写 Gname、Gid。
2. 调用 WriteHeader 后才修改字段，修改已经不会影响刚写出的条目头。
3. 读取端只打印当前系统根据 Gid 查出的名字，却没有先查看归档头中的 Gname。

正确顺序是：准备完整的 Header，调用一次 WriteHeader 写入条目头，再写入正文；读取时调用 Next 得到头，再把 Gname 和 Gid 当成归档内的原始字段处理。

触发条件：只设置文件权限，不设置组元数据

最小写法往往像这样：给条目设置名字、模式和正文长度，然后直接写入。它可以生成可读取的 tar，但组名字段仍然是零值。另一个容易忽略的触发条件是，WriteHeader 之后再补字段；此时条目头已经落入输出流，后改的字段只会留在内存对象里。

下面的结构说明图把元数据和正文分成两个边界，关键是把 Gname、Gid 放在 WriteHeader 之前：

根因：Header 字段是归档数据，不是延迟查询配置

archive/tar 的 Writer.WriteHeader 负责把给定的 Header 编码成当前条目头。它不会在未来读取时替你访问原机器的组数据库，也不会根据 Gid 自动补出一个名字。因此，想让归档跨机器仍保留组名，就必须在写入阶段明确设置字符串字段。

如果你是从 fs.FileInfo 开始的，可以使用 FileInfoHeader 生成基础头，再覆盖需要固定的归档元数据。当前 Go 文档还提供了 FileInfoNames 接口：当传入的 FileInfo 实现了它时，FileInfoHeader 可以直接取得 Uname 和 Gname，减少依赖系统名称查找的机会。

修复动作：在 WriteHeader 前显式写入 Gname 和 Gid

下面的函数把组名和组 ID 写入一个内存中的 tar。示例故意把字段准备、写头、写正文和关闭 writer 分开，便于定位每一步的责任：

package main

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

func buildTarEntry() ([]byte, error) {
    var archive bytes.Buffer
    tw := tar.NewWriter(&archive)

    body := []byte("release manifest\n")
    header := &tar.Header{
        // Name、Mode 和 Size 描述条目本身；Gid、Gname 描述归档中的组元数据。
        Name:  "meta/manifest.txt",
        Mode:  0640,
        Size:  int64(len(body)),
        Gid:   2001,
        Gname: "release",
        Uid:   1001,
        Uname: "builder",
    }

    // WriteHeader 之后再修改 header，不会回写已经输出的条目头。
    if err := tw.WriteHeader(header); err != nil {
        return nil, fmt.Errorf("写入 tar 头失败: %w", err)
    }
    // 正文长度必须与 Header.Size 对应，避免归档写入在后续条目处报错。
    if _, err := tw.Write(body); err != nil {
        return nil, fmt.Errorf("写入 tar 正文失败: %w", err)
    }
    // Close 会写出尾部；即使目标是 bytes.Buffer，也要检查关闭错误。
    if err := tw.Close(); err != nil {
        return nil, fmt.Errorf("关闭 tar writer 失败: %w", err)
    }
    return io.ReadAll(bytes.NewReader(archive.Bytes()))
}

这里的 Gname 只代表 tar 条目里的组名文本，Gid 只代表写入的数字 ID。解包程序是否采用它们、是否映射到本机账号，以及是否允许恢复权限，都属于另一层策略。

读取结果：用 Reader.Next 取回归档中的组名

写入成功后，读取端不应该依赖当前机器的组名查询来判断归档是否保留元数据。直接从 Next 返回的头读取：

func readGroupMetadata(data []byte) error {
    tr := tar.NewReader(bytes.NewReader(data))
    for {
        header, err := tr.Next()
        if err == io.EOF {
            // 读到归档尾部，说明没有更多条目。
            return nil
        }
        if err != nil {
            return fmt.Errorf("读取 tar 条目头失败: %w", err)
        }

        // Header 中的名字和 ID 是归档内记录，不能直接当作本机权限结论。
        fmt.Printf("%s: gid=%d group=%q\n", header.Name, header.Gid, header.Gname)

        // 这里只消费当前普通文件的正文；Next 会在切换条目前自动丢弃剩余数据。
        if header.Typeflag == tar.TypeReg {
            if _, err := io.Copy(io.Discard, tr); err != nil {
                return fmt.Errorf("读取 %q 正文失败: %w", header.Name, err)
            }
        }
    }
}

如果输出中的 gid=2001 group="release" 能对应写入端，就说明归档头里确实保存了组信息。这个判断不需要当前机器存在名为 release 的组，因为验证的是 tar 元数据本身。

边界：tar 格式容量和 FileInfoHeader 的选择

Header 文档列出了三种常见格式对 Uname/Gname 的差异：USTAR 为 32 字节，PAX 不限长度，GNU 也为 32 字节。没有指定格式时，writer 会选择能够容纳当前头字段的格式；如果业务必须兼容旧的 USTAR 读取器，就应主动把组名控制在它的容量内，而不是等到写入时才发现字段过长。

当组名可能超出传统字段容量，显式使用 tar.FormatPAX 更容易表达意图：

func makePAXHeader(size int64) *tar.Header {
    return &tar.Header{
        // PAX 更适合需要较长 Uname/Gname 或更丰富时间元数据的归档。
        Format: tar.FormatPAX,
        Name:   "data/item.bin",
        Mode:   0600,
        Size:   size,
        Gid:    2001,
        Gname:  "analytics-release-group-with-long-name",
    }
}

如果元数据来自 fs.FileInfo，可以先调用 FileInfoHeader，再根据跨机器发布规则覆盖 Gid 和 Gname。不要把“当前文件系统的显示名称”当成唯一事实来源；归档格式和兼容目标决定了最终应写入什么。

防复发：发布前用六项清单排查

归档元数据问题的根因通常很具体：字段没有在写头前准备好，或者格式兼容目标没有提前确定。把“字段含义、写入时机、格式容量、读取来源”四件事固定下来，组名就不会再依赖偶然的本机环境。

常见问题

只设置 Gid，不设置 Gname，可以吗？

可以生成 tar，但读取方只能稳定拿到数字 ID，是否能显示组名要依赖后续程序。需要跨机器可读时，通常同时写入 Gid 和 Gname。

Gname 为空是不是 tar 损坏？

不一定。先检查写入端是否给 Header 设置了 Gname，再检查所选格式和兼容读取器；空字符串可能只是写入了零值。

FileInfoHeader 会自动填充组名吗？

当输入的 fs.FileInfo 实现了 FileInfoNames 时，文档允许它提供 Uname 和 Gname；否则不要假设它一定能跨平台完成名称查找，必要时应显式覆盖字段。

写入后修改 Header.Gname 还来得及吗？

来不及。WriteHeader 已经编码并写出了条目头，应该在调用它之前准备完整的 Header。