当前位置：首页 > 文章列表 > 文章 > python教程 > Python tarfile 如何安全解压归档：成员路径检查、过滤器与失败清理

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

来源：17golang原创 2026-08-30 02:39:17 0浏览收藏

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

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

要点速览

用 getmembers() 先看成员数量和名称，拒绝明显越界路径。
在支持的 Python 版本中显式传入 filter=tarfile.data_filter，不要依赖默认值。
把 extractall() 放进 TemporaryDirectory，失败时删除半成品，成功后再做文件验收。

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

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) 不是万能事务；它只是把“半成品目录”与“对外可见目录”分开，目标路径仍需由业务规则保证没有并发占用。