svfs/README.md

# SQLite Virtual File System (SVFS)

一个基于 SQLite 的虚拟文件系统实现，可以将本地文件夹打包成单个 SQLite 数据库文件，并支持从数据库中解包还原文件。

## 特性
- 高效存储: 使用 SQLite 数据库存储文件和目录结构
- 压缩支持: 可选的文件压缩功能，节省存储空间
- 完整元数据: 保留文件权限、创建时间、修改时间等元数据
- 目录结构保持: 完整的目录层级结构保持
- 简单易用: 提供命令行工具，支持打包和解包操作
- 跨平台: 支持 Windows、Linux、macOS

## 安装
### 从源码安装
```bash
# 克隆仓库
git clone <repository-url>
cd svfs

# 使用 uv 安装（推荐）
uv sync

# 或者使用 pip
pip install -e .
```
### 使用 uv
项目使用 uv 作为包管理器和构建工具，确保已安装 uv：

```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 在项目目录中安装依赖
uv sync
```

## 使用方法
### 打包文件夹
```bash
# 基本用法
vfspack <源文件夹路径> <输出数据库路径>

# 启用压缩
vfspack ./my_folder ./output.db --compress

# 指定文件系统名称
vfspack ./my_folder ./output.db --name "MyFileSystem"

# 排除特定文件模式
vfspack ./my_folder ./output.db --exclude "*.tmp" "*.log"
```
### 解包文件系统
```bash
# 解包整个文件系统
vfsunpack <数据库路径> <目标文件夹路径>

# 仅列出根目录内容
vfsunpack ./output.db ./output --list-root

# 解包特定文件或目录
vfsunpack ./output.db ./output --path "docs/readme.txt"
vfsunpack ./output.db ./output --path "images/"

# 忽略时间戳错误（仅导出文件内容）
vfsunpack ./output.db ./output --ignore-timestamps
```
## 项目结构
```text
svfs/
├── pyproject.toml          # 项目配置和依赖
├── src/svfs/
│   ├── __init__.py
│   ├── core.py             # 核心 SQLiteVFS 类
│   ├── folder_packer.py    # 文件夹打包逻辑
│   ├── folder_unpacker.py  # 文件夹解包逻辑
│   └── cli/
│       ├── __init__.py
│       ├── packer.py       # 打包命令行工具
│       └── unpacker.py     # 解包命令行工具
└── README.md
```
## 核心组件
### SQLiteVFS 类
主要功能类，提供以下功能：

- 创建和管理 SQLite 虚拟文件系统数据库
- 添加/删除文件和目录
- 读取文件内容
- 导出文件到本地文件系统
- 压缩和解压缩文件内容

### FolderPacker 类
文件夹打包工具：

- 遍历本地文件夹结构
- 将文件和目录信息存储到 SQLite 数据库
- 支持文件排除模式

### FolderUnpacker 类
文件夹解包工具：

- 从 SQLite 数据库恢复文件系统
- 验证数据库完整性
- 支持部分导出和完整导出

## 数据库结构
### filesystem_metadata 表
存储文件系统元数据，包括名称、创建时间、文件总数和总大小。

### files 表
存储所有文件和目录信息：

- path: 文件/目录路径（唯一）
- name: 文件名
- parent_path: 父目录路径
- is_directory: 是否为目录
- file_size: 文件大小
- created_time: 创建时间
- modified_time: 修改时间
- permissions: 文件权限
- content: 文件内容（BLOB）
- compressed: 是否压缩

## 开发
### 设置开发环境
```bash
# 安装开发依赖
uv sync --dev

# 运行测试
pytest

# 构建包
uv build
```
### 代码示例
```python
from svfs.core import SQLiteVFS

# 创建文件系统
vfs = SQLiteVFS("my_files.db", compress=True)
vfs.connect()

# 获取文件系统统计信息
stats = vfs.get_stats()
print(f"文件系统: {stats['name']}")
print(f"文件数量: {stats['total_files']}")

# 列出目录内容
for item in vfs.list_directory("/"):
    print(f"{'DIR' if item['is_directory'] else 'FILE'}: {item['name']}")

vfs.close()
```
## 性能说明
- 压缩功能默认对大于 1KB 的文件启用
- 使用 zlib 压缩，压缩级别为 6（平衡压缩比和速度）
- 文件索引优化，支持快速路径查找
- 批量操作减少数据库事务开销

## 注意事项
1. 文件路径统一使用正斜杠（/）存储，与操作系统无关
2. 时间戳使用 UTC 时间存储
3. 文件权限使用 Unix 权限位表示
4. 数据库文件可以在不同平台间迁移
5. 大文件处理建议启用压缩以减少数据库大小

## 许可证
MIT License

## 贡献
欢迎提交 Issue 和 Pull Request 来改进项目。