GameServerManager/docs/7z-support.md

7z 压缩格式支持说明

概述

项目在现有 Zip-Tools 集成基础上，新增了 7z（.7z）格式的压缩和解压支持。7z 格式以高压缩率著称，适合需要更小体积的场景。

与现有的 file_zip 工具不同，7z 功能由独立的 7z 二进制文件提供（来自 MCSManager/Zip-Tools 项目），是标准的 7-Zip 命令行工具，需要单独下载和管理。

支持的操作

操作	说明
压缩	将文件/文件夹压缩为 .7z 格式
解压	解压 .7z 格式的压缩包
在线部署	支持 .7z 格式的游戏服务端文件自动解压

使用方式

前端压缩

1. 在文件管理器中选择需要压缩的文件或文件夹
2. 右键菜单 → 压缩
3. 在压缩格式下拉列表中选择 7Z (高压缩率)
4. 点击确认开始压缩

注意：7z 格式不支持自定义压缩级别，选择 7z 格式时压缩级别选项会自动禁用。

前端解压

1. 在文件管理器中找到 .7z 文件
2. 右键菜单 → 解压
3. 选择解压目标路径
4. 点击确认开始解压

在线部署

在线部署模块已支持 .7z 格式的游戏服务端文件。系统会根据下载文件的扩展名自动选择解压方式：

• .7z 文件 → 使用 7z 工具解压
• .zip 文件 → 使用 file_zip 工具解压

无需额外配置，部署流程与之前一致。

7z 二进制文件管理

自动下载机制

服务端启动时会自动检测 7z 二进制文件是否存在：

• 已存在：跳过下载，记录日志 7z 已就绪
• 不存在：自动下载对应平台的二进制文件（双源策略）
• 下载失败：记录警告日志但不阻塞服务启动，7z 相关功能降级为不可用

下载源优先级

1. 自建镜像（主）：优先从自建镜像下载（国内加速）
2. GitHub Releases（备用）：https://github.com/MCSManager/Zip-Tools/releases/latest/download/

运行时优先从自建镜像下载，失败后自动回退到 GitHub Releases。

存放位置

7z 二进制文件与 file_zip 存放在同一目录，使用多路径尝试策略查找：

1. {项目根目录}/data/lib/ — 打包后环境
2. {项目根目录}/server/data/lib/ — 开发环境

手动放置二进制文件（离线环境）

如果服务器无法访问外部网络，可以手动下载并放置二进制文件：

1. 从 Zip-Tools Releases 下载对应平台的 7z 二进制文件
2. 将文件放置到 server/data/lib/ 或 data/lib/ 目录下
3. Linux/macOS 平台需要设置可执行权限：chmod 755 7z_linux_x64

支持的平台和架构

操作系统	CPU 架构	二进制文件名
Windows	x64	7z_win32_x64.exe
Windows	ARM64	7z_win32_arm64.exe
Linux	x64	7z_linux_x64
Linux	ARM64	7z_linux_arm64
Linux	ia32	7z_linux_386
Linux	ARM	7z_linux_arm
macOS	x64	7z_darwin_x64
macOS	ARM64	7z_darwin_arm64

注意：7z 的命名规则与 file_zip 不同。file_zip 中 darwin/x64 映射为 amd64，而 7z 直接使用 x64。

打包和部署

打包脚本

打包脚本（scripts/package.js）在构建时会自动从 GitHub Releases 下载目标平台的 7z 二进制文件并内置到产物中，与 file_zip 的下载流程并列执行，确保用户部署后无需额外下载。

Docker 镜像

Dockerfile 在构建阶段会根据目标架构（TARGETARCH）自动下载对应的 7z 二进制文件：

• amd64 → 下载 7z_linux_x64
• arm64 → 下载 7z_linux_arm64

下载后自动设置可执行权限（chmod 755），容器启动后 7z 功能开箱即用。

7z 命令行参数格式

7z 使用标准的 7-Zip 命令行参数，与 file_zip 的 -mode 参数格式完全不同：

解压

7z x {压缩包路径} -o{目标目录}

注意：-o 和目标目录之间没有空格，这是 7z 的标准格式。

压缩

7z a {输出文件路径} {文件1} {文件2} ...

注意事项

1. 压缩级别：7z 压缩不支持通过命令行参数自定义压缩级别，使用默认压缩级别
2. 下载失败不阻塞启动：7z 二进制文件下载失败不会阻止服务启动，仅 7z 相关功能不可用，其他功能正常运行
3. 独立管理：7z 和 file_zip 的生命周期完全独立，互不影响。即使 7z 不可用，ZIP 格式的压缩解压仍正常工作
4. 现有格式不受影响：ZIP、TAR、TAR.GZ、TAR.XZ 等现有格式的处理逻辑保持不变
5. 文件格式识别：前端文件管理器已支持识别 .7z 文件为压缩文件，右键菜单会自动显示解压选项