# 7z 压缩格式支持说明

## 概述

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

与现有的 `file_zip` 工具不同，7z 功能由独立的 7z 二进制文件提供（来自 [MCSManager/Zip-Tools](https://github.com/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 已就绪`
- **不存在**：自动从 GitHub Releases 下载对应平台的二进制文件
- **下载失败**：记录警告日志但不阻塞服务启动，7z 相关功能降级为不可用

### 下载地址

运行时从 GitHub Releases 下载：

- `https://github.com/MCSManager/Zip-Tools/releases/latest/download/`

### 存放位置

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

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

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

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

1. 从 [Zip-Tools Releases](https://github.com/MCSManager/Zip-Tools/releases/latest) 下载对应平台的 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` 参数格式完全不同：

### 解压

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

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

### 压缩

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

## 注意事项

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