Go archive/tar 限制解包路径与文件大小

用 Go 的 archive/tar 读取压缩包时，真正需要补上的不是“再调用一个解包函数”，而是两道应用层边界：条目名称必须始终落在目标根目录内，条目大小和累计大小必须先经过预算检查。tar.Reader 会按顺序给出每个 Header，但不会替你决定绝对路径、.. 路径、符号链接或磁盘配额是否可以接受。

下面的实现只允许普通文件和目录，拒绝绝对路径、路径穿越、链接类型以及超过单文件或总量上限的条目。它适合作为上传 tar 包、导入离线资源、构建临时工作区时的迁移骨架；如果业务确实需要链接或保留特殊权限，应先单独设计策略，不要把它们顺手放开。

先区分 tar 读取能力和解包安全策略

archive/tar.Reader.Next 返回当前条目的头部，Header.Name 是归档内保存的名称，Header.Size 是当前条目声明的大小。读取库需要忠实呈现归档内容，而“这个名字能否写到本地”“允许占用多少空间”属于调用方的业务约束。

因此迁移旧的解包代码时，可以先用下面这张清单划边界：

把条目名称收敛到目标根目录

路径检查应在创建目录和文件之前完成。下面的辅助函数先把 tar 使用的斜杠路径转成当前系统形式，再清理路径，最后用 filepath.Rel 反向确认目标仍位于根目录中。第二次检查不是多余的：它把“字符串看起来安全”变成了“拼接后的实际目标可解释”。

package extractor

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

// safeTarget 只返回目标根目录内的路径，不创建任何文件。
func safeTarget(root, entryName string) (string, error) {
    // tar 名称按斜杠分隔，先统一成逻辑路径再做判断。
    name := strings.TrimSpace(filepath.ToSlash(entryName))
    if name == "" || strings.HasPrefix(name, "/") {
        return "", fmt.Errorf("拒绝绝对或空路径: %q", entryName)
    }

    // path.Clean 只处理归档里的斜杠，不会提前访问文件系统。
    clean := path.Clean(name)
    if clean == "." || clean == ".." || strings.HasPrefix(clean, "../") {
        return "", fmt.Errorf("拒绝路径穿越: %q", entryName)
    }

    // 从干净的归档路径拼出本机路径，并再次确认没有逃出 root。
    target := filepath.Join(root, filepath.FromSlash(clean))
    rel, err := filepath.Rel(root, target)
    if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
        return "", fmt.Errorf("目标不在解包根目录内: %q", entryName)
    }
    return target, nil
}

这段检查针对“条目名直接映射文件”的场景。生产代码还要把根目录固定为应用创建的专用目录，并尽量使用绝对路径；不要把用户可控的 root 和归档名称混成一个字符串后再判断。

目录、普通文件和链接类型要分开处理

路径安全通过后，还要看 Header.Typeflag。最小安全策略是只接收目录和普通文件：目录只创建目录，普通文件才打开文件并复制内容；符号链接、硬链接、设备节点和未知类型直接返回错误。这样可以避免“文件名本身安全，但链接创建后指向根目录外”的第二条逃逸路径。

func acceptType(typeFlag byte) error {
    switch typeFlag {
    case tar.TypeDir, tar.TypeReg, tar.TypeRegA:
        return nil
    default:
        // 不自动创建链接或特殊文件，业务需要时应另写白名单策略。
        return fmt.Errorf("不支持的 tar 条目类型: %d", typeFlag)
    }
}

如果目录条目名称末尾带斜杠，path.Clean 会去掉它，但这不影响使用 TypeDir 判断类型。不要仅根据名称后缀决定是否创建目录。

先检查 Header.Size，再扣减总量预算

单文件上限和总量上限解决的是两个不同问题：单文件上限防止一次性写入异常大的条目，总量上限防止很多个“单个都不大”的条目累积占满磁盘。检查时先拒绝负数，再使用减法形式比较剩余预算，避免把不可信的大小直接相加后发生整数溢出。

const (
    // 业务应按临时目录容量和请求大小调整这两个值。
    maxFileSize  int64 = 64  maxFileSize {
        return used, fmt.Errorf("单文件超过上限: %d", size)
    }
    if used > maxTotalSize || size > maxTotalSize-used {
        return used, fmt.Errorf("解包总量超过上限: used=%d size=%d", used, size)
    }
    return used + size, nil
}

这里的“预留”发生在打开输出文件之前。若后续写入失败，当前请求应整体失败并删除已经写出的目标目录，或者把解包放在新建临时目录中，成功后再原子替换到业务目录。

把路径和大小策略合并到读取循环

下面的函数把前面的规则串起来。它不修改归档中的权限，不创建链接，也不依赖“复制完以后再清理”的补救。io.LimitReader 将当前读取限制在 Header.Size，复制后再比较字节数，可以识别流提前结束导致的部分文件。

package extractor

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

func ExtractTar(r io.Reader, root string) error {
    tr := tar.NewReader(r)
    var used int64

    for {
        hdr, err := tr.Next()
        if err == io.EOF {
            // 读到归档末尾，说明所有条目都处理完成。
            return nil
        }
        if err != nil {
            return fmt.Errorf("读取 tar 头失败: %w", err)
        }
        if err := acceptType(hdr.Typeflag); err != nil {
            return err
        }

        target, err := safeTarget(root, hdr.Name)
        if err != nil {
            return err
        }
        if hdr.Typeflag == tar.TypeDir {
            // 目录不消耗文件大小预算，但仍受路径边界保护。
            if err := os.MkdirAll(target, 0750); err != nil {
                return fmt.Errorf("创建目录 %q 失败: %w", hdr.Name, err)
            }
            continue
        }

        nextUsed, err := reserveSize(used, hdr.Size)
        if err != nil {
            return err
        }
        if err := os.MkdirAll(filepath.Dir(target), 0750); err != nil {
            return fmt.Errorf("创建父目录失败: %w", err)
        }

        f, err := os.OpenFile(target, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0600)
        if err != nil {
            return fmt.Errorf("创建文件 %q 失败: %w", hdr.Name, err)
        }

        // 只复制当前条目的声明长度，避免读过下一个条目。
        n, copyErr := io.Copy(f, io.LimitReader(tr, hdr.Size))
        closeErr := f.Close()
        if copyErr != nil || closeErr != nil || n != hdr.Size {
            // 删除部分文件，避免失败重试时把半成品当成完整文件。
            _ = os.Remove(target)
            if copyErr != nil {
                return fmt.Errorf("写入 %q 失败: %w", hdr.Name, copyErr)
            }
            if closeErr != nil {
                return fmt.Errorf("关闭 %q 失败: %w", hdr.Name, closeErr)
            }
            return fmt.Errorf("条目 %q 数据不完整: got=%d want=%d", hdr.Name, n, hdr.Size)
        }
        used = nextUsed
    }
}

示例把普通文件权限固定为 0600，目录固定为 0750，这是为了让归档内容不能直接扩大新文件的可见范围。若应用需要保留权限，应把权限映射为明确白名单，并在创建后再次检查，而不是直接套用 Header.Mode。

迁移旧解包代码时的回归清单

把现有实现迁移到这套边界时，重点不是增加更多字符串替换，而是逐项确认输入、预算和失败状态：

1. 正常目录和嵌套普通文件可以被写入，目标目录由调用方预先创建或专门分配。
2. 绝对路径、../、归一化后才出现的父级路径都在创建文件前被拒绝。
3. 符号链接、硬链接、设备节点和未知类型不会进入文件系统。
4. 单文件超过上限时，目标文件尚未创建；总量超过上限时，不再处理后续条目。
5. 复制错误、关闭错误和实际字节数不足都会删除当前半成品，并把原始错误带回调用方。
6. 如果业务要求“失败不留任何文件”，应在临时目录内完成整包解包，函数成功后再由上层执行替换。

结语：让 tar 负责读，让应用负责边界

archive/tar 适合顺序读取归档条目，但路径安全和空间预算必须由应用明确决定。迁移时可以把逻辑压缩成三句话：先把条目名收敛到根目录内，再用单文件和总量预算挡住写入，最后只允许经过白名单的条目类型进入文件系统。这样即使以后替换压缩层或增加上传入口，核心安全边界仍然可以复用。

相关问题

• 为什么不能只用 filepath.Join 判断路径安全？ 因为 Join 会清理路径，但调用方仍应明确拒绝绝对路径、父级路径和链接类型，并用 Rel 确认最终目标。
• io.LimitReader 能代替总量限制吗？ 不能。它只限制当前条目的读取长度，总量仍要由每个 Header.Size 的累计预算控制。
• 可以直接恢复 Header.Mode 吗？ 不建议默认这样做。权限应按业务白名单映射，避免归档携带的模式扩大新文件的访问范围。
• 压缩 tar.gz 是否需要另一套路径规则？ 不需要。先用 gzip 解出 tar 流，再把同一套路径、类型和大小策略交给 tar 解包层。