GeneralZip
命名空间: GeneralZip、GeneralZip.Abstractions | 主要入口: GeneralZip.CompressAsync / ExtractAsync、GeneralZipReader、GeneralZipWriter | NuGet 包: GeneralZip
1. 组件简介
1.1 组件概述
GeneralZip 是一个跨格式、可加密(含国密)、事件驱动的 .NET 压缩组件。它用一套统一的 API 覆盖 ZIP、7z、RAR、TAR、GZ、BZ2、XZ、Zstd、LZ4、Brotli、CPIO、ISO9660、CAB 等十余种常见归档/压缩格式,打开归档时按魔数自动探测格式;压缩与解压全程提供事件系统(进度、交互式取密、覆盖决策、错误策略),全 API 支持 CancellationToken,并支持并行压缩/解压、流到流操作与 IAsyncEnumerable 条目枚举。加密方面内置 WinZip AES(通用互通)、SM4-GM 国密(文档化自定义 ZIP 扩展)与 SM2-GM 国密信封(公钥封装、无共享口令)三套方案,一个 EncryptionAlgorithm 开关切换。核心包零第三方 NuGet 依赖:SM3/SM4/SM2 密码学原语与 TAR/CPIO 容器为纯 C# 实现(GB/T 标准向量锁定),7z/bzip2/xz/zstd/lz4/brotli 由可选的 Rust 原生核心提供,核心缺失时优雅降级。
一行式 Append / Remove / Convert、流到流重载、并行压缩/解压、Glob 条目过滤、ZIP 扩展压缩方法(BZip2/Zstd/LZMA)、SM2-GM 信封加密、可插拔 KDF 注册表、分卷 ZIP、Unix 属性/符号链接、CPIO/ISO9660/CAB/Brotli 格式与 gz 命令行工具——完整清单见发布日志。
核心能力:
| 能力 | 说明 |
|---|---|
| 一套 API 多格式 | 所有格式映射到统一条目模型 IArchiveEntry,门面/读取器/写入器对全部格式行为一致,学一次即可处理所有格式 |
| 魔数自动探测 | 打开归档时按文件头魔数识别格式,扩展名兜底;内容与后缀不符也能正确处理 |
| 加密与国密 | WinZip AES-128/256(AE-2,与 WinZip/7-Zip/Windows 资源管理器互通)+ SM4-GM 国密(SM4-CTR + SM3-HMAC,容器规范文档化);ZipCrypto 遗留格式可读 |
| 事件驱动 | 条目生命周期、条目级与整体进度、交互式口令(PasswordRequired)、覆盖询问(OverwriteQuery)、错误上报(ErrorReport) |
| 取消与进度 | 全 API 支持 CancellationToken;事件与 IProgress<ArchiveProgress> 双通道进度,含百分比、吞吐与 ETA |
| 安全解包 | 拒绝绝对路径与路径穿越条目;错误口令经校验值快速失败(常数时间比较),不会静默产生坏数据 |
| 零第三方依赖 | 除微软官方维护的包外不引用任何第三方 NuGet;SM3/SM4/TAR/CRC32 纯 C# 自研,经 GB/T 32905-2016 / GB/T 32907-2016 标准向量锁定 |
| 优雅降级 | Rust 原生核心缺失时,ZIP/TAR/TAR.GZ/GZ(纯托管)与全部 ZIP 系加密照常可用,仅 7z/RAR 与原生编解码不可用 |
| 开放扩展 | 格式注册表(IArchiveFormat)与加密注册表(IEncryptionProvider)双扩展点,自定义格式/算法一行注册 |
解决的业务痛点:
- 业务系统接收的压缩包来源多样(zip / tar.gz / 7z / rar / gz …),为每种格式引入专门库导致 API 碎片化、依赖膨胀
- 政务、金融等合规场景要求使用国密算法(SM4)加密归档,主流压缩库均不提供
- 面向终端用户的应用需要进度条、口令弹窗、覆盖确 认、失败重试等交互能力,而多数压缩库只提供"压缩/解压"两个函数
- 处理不受信任来源的压缩包时,需要防范路径穿越等解包安全问题
- 第三方压缩依赖带来安全审计与版本升级负担
GeneralZip 是 GeneralLibrary 家族中独立于 GeneralUpdate 的通用压缩组件:它不感知版本号、更新策略或服务端协议,只负责"打包与解包"。补丁包生成、数据备份、日志归档、导出文件加密等场景都可以直接复用它的统一 API 与加密能力。
业务使用场景:
- 桌面/服务端应用的文件备份与归档(ZIP / TAR.GZ)
- 更新补丁包、数据导出包的生成与解包
- 国密合规场景的加密归档(SM4-GM)
- 日志与数据的单文件压缩(GZ / XZ / ZSTD / LZ4)
- 外部来源压缩包的格式探测、完整性校验与安全解包
- 交互式解压 UI(口令输入、覆盖确认、错误重试)的后端支撑
1.2 环境与依赖
| 项目 | 说明 |
|---|---|
| 版本 | 2.0.0 |
| 目标框架 | netstandard2.0、net8.0(netstandard2.0 兼容 .NET Framework 4.6.1+ / .NET Core 2.0+ / .NET 5+) |
| NuGet 依赖 | 仅微软官方维护的包:Microsoft.Bcl.AsyncInterfaces、System.Text.Json(均仅 netstandard2.0);核心包零第三方 NuGet 依赖 |
| 原生核心 | 内置 Rust cdylib generalzip_native(提供 7z / RAR / BZ2 / XZ / ZSTD / LZ4 / Brotli),NuGet 包捆绑 win-x64、linux-x64、linux-musl-x64、linux-arm64、win-arm64、win-x86、osx-x64、osx-arm64 八个平台的预编译产物 |
| 降级策略 | 原生核心缺失时 7z/RAR 与原生编解码不可用,其余能力(ZIP/TAR/TAR.GZ/CPIO/GZ + 全部 ZIP 系加密)不受影响 |
| 许可协议 | MIT |
2. 组件功能列表
| 功能名称 | 功能描述 | 类型 | 是否必填 | 备注限制 |
|---|---|---|---|---|
| 一行式压缩 | 目录或单文件 → 归档,扩展名决定格式 | 基础 | 推荐 | CompressAsync,全 API 可取消 |
| 一行式解压 | 归档 → 目录,返回结果摘要 | 基础 | 推荐 | ExtractAsync,返回 ArchiveResult |
| 格式探测 | 魔数优先、扩展名兜底 | 基础 | 可选 | DetectFormat,无法识别返回 null |
| 流式写入 | 逐条目添加文件/目录/流,Finish 收尾 | 基础 | 可选 | GeneralZipWriter,Dispose 自动收尾 |
| 流式读取 | 条目枚举、惰性解压流、单条目解压 | 基础 | 可选 | GeneralZipReader.OpenEntryStream |
| 完整性测试 | CRC/HMAC/结构校验,不落盘 | 基础 | 可选 | Test / TestAll |
| 加密写入 | WinZip AES-128/256、SM4-GM(ZIP 容器) | 拓展 | 可选 | EncryptionAlgorithm + Password |
| 加密读取 | ZipCrypto / WinZip AES / SM4-GM / 7z AES-256 / RAR | 拓展 | 可选 | 口令预置或事件交互 |
| 进度上报 | 事件与 IProgress<T> 双通道,含吞吐与 ETA | 拓展 | 可选 | 条目内约每 64KB 一次 |
| 交互策略 | 口令询问、覆盖决策(5 种)、错误策略(3 种) | 拓展 | 可选 | OverwritePolicy / ErrorPolicy |
| 安全解包 | 拒绝绝对路径与路径穿越条目 | 基础 | 自动 | 记入 ArchiveResult.Failures |
| 自定义格式 | 实现 IArchiveFormat 后注册 | 拓展 | 可选 | GeneralZip.Registry.Register |
| 自定义加密 | 实现 IEncryptionProvider 后注册 | 拓展 | 可选 | GeneralZip.Encryption.Register |
| 原生格式 | 7z(LZMA2,读写 + AES-256)、RAR4/RAR5(只读) | 拓展 | 可选 | 需 Rust 原生核心 |
| 原生编解码 | BZ2 / XZ / ZSTD / LZ4 / Brotli、TAR.BZ2 | 拓展 | 可选 | 需 Rust 原生核心;回调式流式转码零临时文件 |
| 一行式追加/删除/转换 | 向既有归档追加条目、按名称/谓词删除条目、跨格式转换 | 拓展 | 可选 | Append / Remove / Convert,读出→重写语义 |
| 流到流操作 | Stream→Stream 压缩/解压/测试,无需落盘 | 拓展 | 可选 | Compress / Extract / Test 流重载 |
| 并行压缩/解压 | 条目级并行,写侧分片、读侧多 worker | 拓展 | 可选 | MaxDegreeOfParallelism,默认 1 串行 |
| Glob 条目过滤 | ** 跨层匹配、字符类的包含/排除模式 | 拓展 | 可选 | IncludePatterns / ExcludePatterns |
| 分卷 ZIP | 按字节上限切分 .001/.002/…,打开 .001 自动拼接 | 拓展 | 可选 | ArchiveWriteOptions.VolumeSize |
| Unix 属性/符号链接 | Unix mode 读写、符号链接写入(默认跳过) | 拓展 | 可选 | IUnixEntry / SymlinkPolicy / PreserveUnixAttributes |
| 命令行工具 | gz dotnet 全局工具:a/x/t/l/c/rm/i/detect/keygen | 拓展 | 可选 | GeneralZip.Cli |
格式与加密矩阵
| 格式 | 读 | 写 | 加密读 | 加密写 | 实现层 |
|---|---|---|---|---|---|
| ZIP(Store/Deflate/BZip2/Zstd/LZMA/Zip64) | ✓ | ✓ | ZipCrypto / WinZip AES / SM4-GM / SM2-GM | ✓ | 自研引擎(纯 C#) |
| 7z(LZMA2) | ✓ | ✓ | AES-256 | AES-256 | Rust 原生核心 |
| RAR4/RAR5 | ✓ | —(专有) | ✓ 密码 | — | Rust 原生核心 |
| TAR / TAR.GZ | ✓ | ✓ | — | — | 自研 ustar + .NET GZipStream |
| TAR.BZ2 | ✓ | ✓ | — | — | 自研 ustar + 原生核心 |
| GZ(.gz/.gzip) | ✓ | ✓ | — | — | .NET 内置 GZipStream |
| BZ2 / XZ / ZSTD / LZ4 / Brotli | ✓ | ✓ | — | — | Rust 原生核心(回调式流式转码) |
| CPIO(newc/odc/binary) | ✓ | ✓(newc) | — | — | 自研容器(纯 C#) |
| ISO9660(+Joliet/Rock Ridge) | ✓ | —(只读) | — | — | 自研引擎(纯 C#) |
| CAB | ✓(NONE 存储) | —(只读) | — | — | 自研引擎(纯 C#) |
部分 "—" 的原因:
- RAR 不可写 —— RAR 压缩算法为 RARLAB 专有,公开的 unrar 许可证明确禁止用于实现压缩器;读取(含密码解密)由原生核心完整支持。
- TAR / GZ / BZ2 / XZ / ZSTD / LZ4 / Brotli / CPIO 无加密列 —— 这些格式的规范中不存在加密机制,没有存放 KDF 参数、IV 或认证标签的位置;需要加密时可在应用层"先加密后压缩",或改用 ZIP + WinZip AES / SM4-GM / SM2-GM。
- ISO9660 / CAB 只读 —— 写支持未实现;CAB 仅 NONE 存储文件夹可读(MSZIP/LZX 压缩文件夹明确不支持)。
- SM4-GM 仅落地于 ZIP 是刻意设计 —— ZIP 的 extra field 机制天生支持第三方扩展,容器二进制规范已在 docs/CRYPTO-SPEC.md 完整文档化;向 7z 这类标准化容器注入自定义加密会产出其他工具无法打开的归档。
- ZipCrypto 写入默认关闭 —— 56 位弱加密,仅限遗留兼容,需显式设置
AllowWeakZipCrypto = true。
3. API 配置说明
3.1 配置字段(属性 Props)
ArchiveWriteOptions(创建归档):
| 字段名 | 数据类型 | 默认值 | 是否必填 | 枚举/取值范围 | 说明 |
|---|---|---|---|---|---|
Level | CompressionLevelChoice | Optimal | 否 | NoCompression(0) / Fastest(1) / Optimal(2) / SmallestSize(3) | 压缩级别;ZIP 写侧 SmallestSize 映射为 Deflate Optimal,NoCompression 使用 Store(不压缩) |
EncryptionAlgorithm | string? | null(不加密) | 加密时必填 | "ZipCrypto" / "WinZipAES128" / "WinZipAES256" / "SM4-GM" / 自定义 AlgorithmId | 加密算法标识,按名称查默认加密注册表 |
Password | string? | null | EncryptionAlgorithm 非空时必填 | — | 加密口令,应从密钥管理服务获取,切勿硬编码 |
KdfIterations | int | 10_000 | 否 | 正整数 | KDF 迭代次数(SM4-GM 等支持自定义 KDF 的算法) |
EncryptionProvider | IEncryptionProvider? | null | 否 | — | 直接注入加密提供者,优先于按 EncryptionAlgorithm 查注册表 |
EntryNameEncoding | Encoding | UTF-8(无 BOM) | 否 | — | 条目名编码;默认值同时设置 ZIP UTF-8 标志(0x0800),中文不乱码 |
ArchiveComment | string? | null | 否 | — | 归档级注释(部分格式支持) |
DefaultLastWriteTime | DateTimeOffset? | null | 否 | — | 条目未提供时间戳时使用;null 表示当前时间 |
Progress | IProgress<ArchiveProgress>? | null | 否 | — | 进度接收器,与事件并行可用 |
ZipCompressionMethod | ZipCompressionMethodChoice | Auto(Deflate) | 否 | Auto(0) / Deflate(1) / BZip2(2) / Zstd(3) / Lzma(4) | ZIP 条目压缩方法(其它格式忽略);扩展方法与 7-Zip / Info-ZIP 互通 |
MaxDegreeOfParallelism | int | 1(串行) | 否 | ≥1 | 条目级并行压缩度(写侧分片并行) |
VolumeSize | long | 0(不分卷) | 否 | 字节数 | 分卷 ZIP:按上限切分 .001/.002/…,打开 .001 自动拼接 |
KdfAlgorithmId | string? | null(算法默认) | 否 | 注册表中的 KdfId | KDF 提供者开关(内置 SM3-PBKDF2 / PBKDF2-SHA256) |
RecipientPublicKey | string? | null | SM2-GM 加密时必填 | hex 公钥(04||X||Y 130 字符或 X||Y 128 字符) | SM2-GM 信封收件人公钥(无共享口令写路径) |
AllowWeakZipCrypto | bool | false | 否 | true / false | 是否允许写入 ZipCrypto(弱加密,仅遗留兼容场景),显式开启才可写 |
ArchiveOpenOptions(打开归档):
| 字段名 | 数据类型 | 默认值 | 是否必填 | 枚举/取值范围 | 说明 |
|---|---|---|---|---|---|
Password | string? | null | 加密归档需要 | — | 预置口令(仅首次询问生效);设置 PasswordProvider 后本字段失效 |
PasswordProvider | IPasswordProvider? | null | 否 | — | 动态口令供给器(弹窗等交互场景);返回 null 表示放弃解密 |
MaxPasswordAttempts | int | 3 | 否 | 正整数 | 单条目/整包口令最大尝试次数,超过则抛出 |
EntryNameEncoding | Encoding? | null | 否 | — | 条目名编码;null 时由格式自判(ZIP 优先 UTF-8 标志,否则回退 IBM437) |
Progress | IProgress<ArchiveProgress>? | null | 否 | — | 进度接收器 |
SourceName | string? | null | 否 | — | 来源文件名;单文件编解码格式用于推导条目名(门面层自动填充) |
ExtractionOptions(解压):
| 字段名 | 数据类型 | 默认值 | 是否必填 | 枚举/取值范围 | 说明 |
|---|---|---|---|---|---|
OverwritePolicy | OverwritePolicy | Throw | 否 | Throw(0) / Overwrite(1) / Skip(2) / Ask(3) / Rename(4) | 目标已存在时的策略;Ask 触发 OverwriteQuery 事件 |
ErrorPolicy | ErrorPolicy | Throw | 否 | Throw(0) / SkipAll(1) / RaiseEvent(2) | 条目级错误策略;RaiseEvent 触发 ErrorReport 事件 |
MaxRenameAttempts | int | 64 | 否 | 正整数 | 自动重命名上限(name (2).ext 形式),超出后抛出 |
Filter | Predicate<IArchiveEntry>? | null | 否 | — | 只解压满足条件的条目(目录条目除外) |
Flatten | bool | false | 否 | true / false | 忽略条目内部路径,全部落在目标根目录 |
PreserveTimestamps | bool | true | 否 | true / false | 回写文件时间戳;持续集成等场景可关闭 |
PropagateEventExceptions | bool | false | 否 | true / false | 事件处理器抛出的异常是否透传;默认隔离并按 Skip 处理 |
MaxRetryPerEntry | int | 3 | 否 | 正整数 | RaiseEvent 策略下处理器连选 Retry 的上限 |
BufferSize | int | 81920 | 否 | 正整数 | 单条目复制缓冲区大小(字节) |
MaxDegreeOfParallelism | int | 1(串行) | 否 | ≥1 | 条目级并行解压度(每 worker 重开归档) |
IncludePatterns | IReadOnlyList<string>? | null(全部) | 否 | Glob 模式 | 只解压命中任一模式的条目(** 跨层、字符类) |
ExcludePatterns | IReadOnlyList<string>? | null | 否 | Glob 模式 | 跳过命中任一模式的条目(优先于包含模式) |
SymlinkPolicy | SymlinkPolicy | Skip | 否 | 枚举 | 符号链接条目处理策略(默认安全优先,不落盘链接) |
PreserveUnixAttributes | bool | false | 否 | true / false | 解压保留 Unix mode 位(需条目提供 IUnixEntry) |
事件应答枚举:
| 枚举值 | 数值 | 说明 |
|---|---|---|
OverwriteAction.Overwrite | 0 | 直接覆盖 |
OverwriteAction.Skip | 1 | 跳过该条目(事件参数默认值) |
OverwriteAction.Rename | 2 | 自动重命名(name (2).ext) |
OverwriteAction.Abort | 3 | 中止整个解压操作(等效取消) |
ErrorAction.Retry | 0 | 重试该条目 |
ErrorAction.Skip | 1 | 跳过该条目(事件参数默认值) |
ErrorAction.Abort | 2 | 中止整个解压操作 |