174 lines
4.3 KiB
Markdown
174 lines
4.3 KiB
Markdown
# 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 来改进项目。
|
||
|