Python tarfile 如何安全解压归档：成员路径检查、过滤器与失败清理

上传服务收到一个 tar.gz 后，最容易被忽略的不是压缩格式，而是归档里的成员名可能把文件写到目标目录之外。Python 的 tarfile 可以把解压动作收进一个临时目录，并显式使用 data 过滤器，再在成功验收后交付目录；遇到异常则清掉这次半成品。

安全解压的关键是“先限制成员，再写入临时目录，最后验收并移交”，不要把用户上传的归档直接解到业务目录。

先把归档当成输入数据，而不是目录快照

tar 格式可以保存普通文件、目录、链接和权限信息。问题在于，成员名并不天然等于目标目录下的安全相对路径；绝对路径、.. 路径以及会影响后续成员的链接，都可能让“解压”产生超出预期的写入效果。

Python 3.12 增加了提取过滤器，Python 3.14 把默认过滤器调整为 data。为了让运行在 Python 3.12、3.13 和 3.14 上的行为更容易对照，业务代码仍建议显式写出过滤器，同时把归档检查和目录交付分开。

用成员清单挡住最明显的路径越界

getmembers() 会返回归档成员列表。它适合做数量、名称和类型的第一轮检查，但不能替代提取过滤器：检查结束到实际写盘之间仍然由 extractall() 处理成员，过滤器必须留在最终写入路径上。

from pathlib import Path
import tarfile

def inspect_members(archive: Path, limit: int = 1000) -> list[str]:
    with tarfile.open(archive, mode="r:*") as tar:
        members = tar.getmembers()
        if len(members) > limit:
            raise ValueError("archive has too many members")

        names = []
        for member in members:
            name = Path(member.name)
            if name.is_absolute() or ".." in name.parts:
                raise ValueError(f"unsafe member path: {member.name}")
            names.append(member.name)
        return names

这里的检查只负责尽早拒绝明显异常，并限制成员数量。不要把它写成“检查通过就一定安全”：链接目标、文件类型和提取时的目标目录仍应交给 data_filter，未知来源归档也不应直接覆盖已有业务文件。

把 data_filter 放在真正的写盘动作上

过滤器会在每个成员提取前收到 TarInfo 和目标路径。命名过滤器 data_filter 面向跨平台数据归档，会限制绝对路径、目标目录之外的路径和部分链接行为；若它拒绝成员，提取可能在中途抛出异常，已经写出的文件不会自动回滚。

import shutil
import tempfile
from pathlib import Path
import tarfile

def safe_extract(archive: Path, destination: Path) -> None:
    destination.parent.mkdir(parents=True, exist_ok=True)
    staging = Path(tempfile.mkdtemp(prefix="tar-stage-", dir=destination.parent))
    try:
        with tarfile.open(archive, mode="r:*") as tar:
            if not hasattr(tarfile, "data_filter"):
                raise RuntimeError("Python 3.12+ data_filter is required")
            tar.extractall(path=staging, filter=tarfile.data_filter)

        extracted = [p for p in staging.rglob("*") if p.is_file()]
        if not extracted:
            raise ValueError("archive contains no regular files")
        if destination.exists():
            raise FileExistsError(destination)
        staging.replace(destination)
    except Exception:
        shutil.rmtree(staging, ignore_errors=True)
        raise

这个流程有三个可观察状态：staging 表示正在写入，extracted 表示已经完成基本结果检查，destination 只有在验收后才出现。staging.replace(destination) 不是万能事务；它只是把“半成品目录”与“对外可见目录”分开，目标路径仍需由业务规则保证没有并发占用。

兼容 Python 3.12 到 3.14 时别猜版本号

官方文档建议用 hasattr(tarfile, "data_filter") 判断过滤器能力，因为部分旧版本可能通过安全更新获得相关能力。若业务不能接受缺少过滤器时的风险，最清晰的策略就是直接失败，让调用方升级运行时或走人工检查。

如果归档完全可信并且确实需要保留特殊 Unix 文件语义，才考虑更宽松的过滤策略；普通上传、导入和备份恢复通常只需要跨平台数据文件。即使使用 data_filter，也要限制归档大小、成员数量和业务可接受的文件类型。

常见问题

Python 3.11 能否直接使用 data_filter？

不能假设它一定存在。代码应先用 hasattr(tarfile, "data_filter") 检查；如果安全要求不能降级，就在能力缺失时停止，而不是无条件调用默认提取。

过滤器拒绝成员后，已解压的文件会自动消失吗？

不会。extractall() 可能留下部分结果，所以示例把写入放到 staging 目录，并在异常分支调用 shutil.rmtree 清理。

只检查 member.name 是否含有 .. 就够了吗？

不够。还要考虑绝对路径、链接目标、文件类型、重复成员和目标目录已有内容；成员预检只能缩小风险，最终写盘仍需要过滤器和隔离目录。

收尾：验收通过后再让目录可见

tarfile 的安全边界不在某一个函数名，而在交付顺序：读取成员清单，显式使用 data_filter，写入隔离的临时目录，检查结果，最后再移交到业务目录。把失败清理写成正常分支，归档内容就不会因为一次异常而长期留在可见目录里。