# hash_storage

**Repository Path**: lvhaodeyeye/hash_storage

## Basic Information

- **Project Name**: hash_storage
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-28
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hash Storage

基于 MinIO 的去重网络存储 Python 包，通过 SHA256 文件哈希实现内容去重和本地缓存。

## 特性

- **内容去重**：相同内容的文件只存储一份，自动识别并跳过重复上传
- **本地缓存**：下载的文件缓存到 `~/.cache/hash_storage/`，再次下载无需网络请求
- **目录支持**：完整保留上传目录的层级结构
- **文件管理**：重命名、删除文件或目录（仅修改 meta 信息，不删除实际内容）
- **GUI 客户端**：树形结构浏览，文件大小异步加载，点击插队优先获取，支持搜索过滤

## 安装

需要 Python >= 3.8 和 [uv](https://github.com/astral-sh/uv)。

```bash
# 仅核心库
uv sync

# 含 GUI
uv sync --extra gui
```

## 配置

创建 `.env` 文件：

```env
ACCESS_KEY=your_minio_access_key
SECRET_KEY=your_minio_secret_key
URL=http://your-minio-server:9000
BUCKET=your_bucket_name
```

## Python API

```python
from hash_storage import HashStorage

# 从 .env 读取配置
storage = HashStorage()

# 或直接传入参数
storage = HashStorage(
    access_key="...", secret_key="...",
    url="http://localhost:9000", bucket="my-bucket"
)

# 上传文件 / 目录
storage.upload("document.pdf")
storage.upload("document.pdf", filename="renamed.pdf")
storage.upload("my_folder/")

# 下载文件 / 目录
storage.download("document.pdf", "./downloads/document.pdf")
storage.download("my_folder", "./downloads/my_folder")

# 列出文件
storage.list_files()                        # 全部文件
storage.list_files("my_folder")             # 指定目录
storage.list("my_folder", join_dir_name=False)  # 返回 {"dirs": [...], "files": [...]}

# 文件信息
info = storage.get_file_info("document.pdf")
# {"filename", "hash", "size", "has_cache", "same_content_files"}

# 重命名 / 删除（仅修改 meta，不删除 .bin 内容）
storage.rename_file("old.txt", "new.txt")
storage.rename_directory("old_dir", "new_dir")
storage.delete_file("document.pdf")
storage.delete_directory("my_folder")

# 清理本地缓存
storage.clear_cache()
```

## GUI 客户端

```bash
uv run python run_gui.py
```

### 主要功能

| 功能 | 说明 |
|---|---|
| 连接 / 断开 | Header 右上角按钮切换，也可通过菜单操作 |
| 文件树 | 树形展示所有目录和文件，文件大小后台异步加载 |
| 搜索 | 文件树上方搜索框，实时过滤，自动展开匹配目录 |
| 点击插队 | 点击文件或目录时，将其 size 请求插到后台队列最前 |
| 上传 | 支持单文件和目录，可自定义存储名称，显示上传进度 |
| 下载 | 右键菜单下载文件或整个目录，显示下载进度 |
| 重命名 / 删除 | 右键菜单操作，仅修改 meta 信息 |
| 详细信息 | 点击文件/目录，右侧面板显示哈希值、大小、缓存状态、重复文件列表 |

### 加载性能说明

首次连接时文件大小通过 `stat_object` 逐 hash 从 MinIO 异步获取（后台运行，不阻塞 UI）。加载完成后 `hash_to_size` 写回 `meta.json`，后续刷新直接读取缓存，无需网络请求。

## 存储结构

MinIO Bucket 中的对象：

```
meta.json          # 元数据（文件名 <-> 哈希 双向映射 + 文件大小缓存）
<sha256>.bin       # 实际文件内容，以哈希值命名，去重存储
```

`meta.json` 格式：

```json
{
  "version": "1.0",
  "hash_to_files": {
    "abc123...": ["file1.txt", "folder/file2.txt"]
  },
  "file_to_hash": {
    "file1.txt": "abc123...",
    "folder/file2.txt": "abc123..."
  },
  "hash_to_size": {
    "abc123...": 102400
  },
  "last_updated": "2024-01-01T00:00:00"
}
```

## 注意事项

- 删除文件/目录只移除 meta 映射，`.bin` 内容不会被删除
- 同名文件重新上传时，若内容变化则自动更新哈希映射
- 文件路径统一使用 `/` 分隔符（跨平台兼容）
- 缓存位置：`~/.cache/hash_storage/<hash>.bin`

## 许可证

MIT License