SQLite Virtual File System (SVFS)

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

特性

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

安装

从源码安装

# 克隆仓库
git clone <repository-url>
cd svfs

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

# 或者使用 pip
pip install -e .

使用 uv

项目使用 uv 作为包管理器和构建工具，确保已安装 uv：

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

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

使用方法

打包文件夹

# 基本用法
vfspack <源文件夹路径> <输出数据库路径>

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

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

# 排除特定文件模式
vfspack ./my_folder ./output.db --exclude "*.tmp" "*.log"

解包文件系统

# 解包整个文件系统
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

项目结构

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: 是否压缩

开发

设置开发环境

# 安装开发依赖
uv sync --dev

# 运行测试
pytest

# 构建包
uv build

代码示例

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 来改进项目。