# zips

**Repository Path**: wangweiyong/zips

## Basic Information

- **Project Name**: zips
- **Description**: zip加密、解压的集成脚本，主要用来快速备份项目，放到开发项目根目录使用。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-30
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zip 加密解压工具 (zips.py)

一个功能强大的 Python 脚本，用于自动化打包、解压和管理 ZIP 文件，支持密码加密、智能排除和交互式操作。

## 功能特性

### 核心功能
- **智能打包**：自动打包当前目录，排除开发环境目录（如 `.venv`, `node_modules`, `.git` 等）
- **密码加密**：支持使用密码加密 ZIP 文件
- **智能解压**：支持普通解压和清理后解压（先删除现有文件再解压）
- **交互式选择**：从备份目录中交互式选择要操作的 ZIP 文件
- **配置管理**：可自定义排除目录和文件列表

### 文件命名规范
- 自动生成格式：`{目录名}_{YYYYMMDD}_{HHMM}.zip`
- 例如：`myproject_20241230_1530.zip`

### 备份管理
- 自动创建 `backup_zips` 目录存储所有备份
- 按修改时间排序，方便查找最新备份

## 安装要求

### 系统要求
- Python 3.6 或更高版本
- 无需额外依赖（使用 Python 标准库）

### 快速开始
1. 将 `zips.py` 复制到您的项目目录
2. 确保 Python 已安装并添加到 PATH
3. 在命令行中运行脚本

## 使用方法

### 基本命令

```bash
# 显示帮助信息
python zips.py --help

# 打包当前目录
python zips.py pack

# 使用密码打包
python zips.py pack -p "your_password"

# 解压指定文件
python zips.py unpack myproject_20241230_1530.zip

# 使用密码解压
python zips.py unpack myproject_20241230_1530.zip -p "your_password"

# 清理后解压（先删除现有文件）
python zips.py clean myproject_20241230_1530.zip

# 交互式选择并解压
python zips.py unpack-select

# 交互式选择并清理后解压
python zips.py clean-select
```

### 命令别名
为方便使用，所有命令都有简写别名：

| 完整命令 | 别名 | 功能描述 |
|---------|------|----------|
| `pack` | `p` | 打包当前目录 |
| `unpack` | `u` | 解压 ZIP 文件 |
| `clean` | `c` | 清理后解压 |
| `unpack-select` | `us` | 交互式选择并解压 |
| `clean-select` | `cs` | 交互式选择并清理后解压 |
| `list` | `l` | 显示排除列表 |
| `config` | `cfg` | 显示配置信息 |
| `add-exclude` | `a` | 添加排除项 |
| `remove-exclude` | `r` | 移除排除项 |

### 高级选项

```bash
# 指定备份存储目录
python zips.py --storage-dir /path/to/backups pack

# 解压到指定目录
python zips.py unpack myproject.zip -o /path/to/extract

# 添加排除目录
python zips.py add-exclude .cache -t dir

# 添加排除文件
python zips.py add-exclude .env -t file

# 显示当前配置
python zips.py config

# 显示排除列表
python zips.py list
```

## 配置说明

### 默认排除项
脚本默认排除以下目录和文件，避免打包不必要的开发环境文件：

**排除目录：**
- `.venv` - Python 虚拟环境
- `node_modules` - Node.js 依赖
- `.git` - Git 版本控制
- `__pycache__` - Python 缓存
- `.idea` - JetBrains IDE 配置
- `.vscode` - VS Code 配置

**排除文件：**
- `.DS_Store` - macOS 系统文件
- `Thumbs.db` - Windows 缩略图缓存
- `desktop.ini` - Windows 桌面配置

### 自定义配置
您可以通过命令行动态添加或移除排除项：

```bash
# 添加新的排除目录
python zips.py add-exclude dist
python zips.py add-exclude build -t dir

# 添加新的排除文件
python zips.py add-exclude .env.local -t file
python zips.py add-exclude config.ini

# 移除排除项
python zips.py remove-exclude .git
python zips.py remove-exclude .DS_Store -t file
```

## 使用示例

### 场景1：日常项目备份
```bash
# 进入项目目录
cd /path/to/myproject

# 打包当前项目（自动排除 node_modules, .git 等）
python zips.py pack

# 输出：myproject_20241230_1530.zip 已创建在 backup_zips 目录
```

### 场景2：恢复项目到特定版本
```bash
# 列出可用的备份
python zips.py config

# 交互式选择要恢复的版本
python zips.py unpack-select

# 或者直接指定文件（清理后解压）
python zips.py clean myproject_20241230_1200.zip
```

### 场景3：安全备份敏感项目
```bash
# 使用密码加密备份
python zips.py pack -p "MySecretPassword123"

# 使用密码解压
python zips.py unpack myproject_20241230_1530.zip -p "MySecretPassword123"
```

### 场景4：自定义备份位置
```bash
# 备份到指定目录
python zips.py --storage-dir ~/project_backups pack

# 从指定目录恢复
python zips.py --storage-dir ~/project_backups unpack-select
```

## 脚本结构

```
zips.py
├── ZipTool 类
│   ├── __init__() - 初始化配置
│   ├── pack() - 打包当前目录
│   ├── unpack() - 解压 ZIP 文件
│   ├── clean_and_unpack() - 清理后解压
│   ├── select_zip_interactive() - 交互式选择
│   ├── list_zip_files() - 列出备份文件
│   └── 配置管理方法
└── main() - 命令行接口
```

### 主要方法说明

1. **pack(password=None)**
   - 打包当前目录到 ZIP 文件
   - 自动排除配置的目录和文件
   - 支持密码加密
   - 文件保存在 `backup_zips` 目录

2. **unpack(zip_file, password=None, extract_path=None)**
   - 解压 ZIP 文件到指定目录
   - 支持密码解密
   - 自动在多个位置查找文件

3. **clean_and_unpack(zip_file, password=None, extract_path=None)**
   - 先清理当前目录（保留排除目录）
   - 然后解压 ZIP 文件
   - 适用于完全恢复场景

4. **select_zip_interactive()**
   - 交互式选择备份文件
   - 显示文件大小和修改时间
   - 支持键盘中断取消

## 注意事项

### 安全警告
1. **密码安全**：密码以明文形式传递，请避免在共享环境中使用
2. **文件覆盖**：`clean` 命令会删除现有文件，操作前请确认
3. **排除目录保护**：清理操作会保留排除目录，但其中的文件可能被覆盖

### 兼容性
- 支持 Windows、macOS 和 Linux
- 使用标准 ZIP 格式，兼容所有 ZIP 工具
- 路径处理使用 `pathlib`，确保跨平台兼容性

### 性能优化
- 使用 `zipfile.ZIP_DEFLATED` 压缩，平衡速度与压缩率
- 遍历时实时过滤排除项，减少内存占用
- 大文件支持：使用流式处理，避免内存溢出

## 故障排除

### 常见问题

**Q: 打包时提示 "权限被拒绝"**
A: 检查当前用户对目录的读写权限，尝试以管理员身份运行

**Q: 解压时提示 "密码错误"**
A: 确认使用的密码与打包时设置的密码一致，注意大小写

**Q: 找不到备份文件**
A: 使用 `python zips.py config` 查看备份目录和文件列表

**Q: 排除项不生效**
A: 使用 `python zips.py list` 确认当前排除列表，使用 `add-exclude` 添加新项

**Q: 脚本无法运行**
A: 确保 Python 3.6+ 已安装：`python --version`

### 调试模式
如需查看详细操作日志，可临时修改脚本中的 `print` 语句或添加调试输出。

## 扩展开发

### 添加新功能
脚本采用模块化设计，易于扩展：

1. **添加新的排除规则**：修改 `should_exclude()` 方法
2. **支持新的压缩格式**：继承 `ZipTool` 类并重写相关方法
3. **添加云存储支持**：集成云服务 API

### 集成到其他工具
```python
# 在 Python 代码中直接使用
from zips import ZipTool

tool = ZipTool()
tool.pack(password="secret")
tool.unpack("backup.zip", password="secret")
```

## 版本历史

### v1.0.0 (当前版本)
- 基本打包和解压功能
- 密码加密支持
- 交互式文件选择
- 配置管理接口
- 跨平台兼容性

### 计划功能
- [ ] 增量备份支持
- [ ] 云存储集成（Google Drive, Dropbox）
- [ ] 图形用户界面（GUI）
- [ ] 定时自动备份
- [ ] 备份策略管理

**提示**：定期备份您的重要项目，这个工具让备份变得简单高效！