SecurityRonin/nameback
GitHub: SecurityRonin/nameback
基于元数据提取和 OCR 技术的智能文件重命名工具，帮助恢复文件的可读性名称。
Stars: 10 | Forks: 0
# nameback
根据文件元数据重命名文件。自动从文件中提取标题、日期和描述，赋予它们有意义的名称。
**可用工具：**
- 🖥️ **CLI** - 用于自动化和脚本编写的命令行工具
- 🎨 **GUI** - 适用于所有平台的可视化双栏界面（Midnight Commander 风格）
## 功能介绍
利用嵌入的元数据将无意义的文件名转换为描述性文件名：
```
IMG_2847.jpg → 2024-03-15_sunset.jpg
document.pdf → Annual_Report_2024.pdf
screenshot_20241015.png → 輸入_姓名.png (Chinese OCR)
VID_20241015.mp4 → Product_Demo_Video.mp4 (frame OCR)
IMG_3847.heic → Family_Reunion_2024.heic
```
## 安装说明
### macOS
```
brew tap h4x0r/nameback
brew install nameback
```
自动安装所有依赖项。
### Windows
从 [releases](https://github.com/h4x0r/nameback/releases/latest) 下载并安装 `nameback-x86_64-pc-windows-msvc.msi`
**你将获得：**
- **CLI**：在任何终端中输入 `nameback`（自动添加到 PATH）
- **GUI**：从开始菜单 → nameback 启动
- **自动安装依赖项**：自动安装 exiftool, tesseract, ffmpeg, imagemagick
无需手动设置 - 开箱即用！
**静默安装：** `msiexec /i nameback-x86_64-pc-windows-msvc.msi /quiet`
### Linux
#### CLI 工具（命令行）
```
cargo install nameback
nameback --install-deps # Interactive dependency installation
```
#### GUI 应用程序（可视化界面）
```
cargo install nameback --bin nameback-gui
nameback-gui
```
#### Debian/Ubuntu/Kali（.deb 软件包）
```
# 从 releases 下载
wget https://github.com/h4x0r/nameback/releases/latest/download/nameback_0.4.1_amd64.deb
sudo dpkg -i nameback_0.4.1_amd64.deb
sudo apt-get install -f # Install dependencies
```
`.deb` 软件包同时包含 CLI 和 GUI 工具。
[查看所有安装选项](docs/GUIDE.md#installation-options)
## 安全与验证
所有发布产物都使用 SLSA 构建来源证明进行签名，以确保供应链安全。您可以验证下载的文件是真实的，且未被篡改。
### 验证下载的文件
**前置条件：** 安装 [GitHub CLI](https://cli.github.com/)
**验证任何产物：**
```
# 验证 MSI 安装程序
gh attestation verify nameback-x86_64-pc-windows-msvc.msi --owner h4x0r
# 验证 DMG 安装程序
gh attestation verify nameback-x86_64-apple-darwin.dmg --owner h4x0r
# 验证 .deb 包
gh attestation verify nameback_0.5.0-1_amd64.deb --owner h4x0r
```
**这验证了什么：**
- ✅ 由官方 h4x0r/nameback 仓库构建
- ✅ 从官方发布工作流构建
- ✅ 构建后未被篡改
- ✅ 显示构建它的确切 commit SHA
**使用校验和进行额外验证：**
从 [发布页面](https://github.com/h4x0r/nameback/releases/latest) 下载 `checksums.txt`，然后：
```
# macOS
shasum -a 256 -c checksums.txt --ignore-missing
# Linux
sha256sum -c checksums.txt --ignore-missing
# Windows (PowerShell)
Get-Content checksums.txt | Select-String "nameback.*windows" | ForEach-Object {
$hash, $file = $_ -split ' '
if ((Get-FileHash $file -Algorithm SHA256).Hash -eq $hash.ToUpper()) {
"✓ $file verified"
} else {
"✗ $file FAILED"
}
}
```
`--ignore-missing` 标志允许您仅验证下载的文件，而不会因其他平台的文件而报错。
为了最大程度的安全，请**同时**使用来源验证（证明真实性）和校验和验证（证明完整性）。
## 快速入门
### CLI（命令行）
```
# 预览变更内容（安全，不做任何修改）
nameback ~/Pictures --dry-run
# 重命名文件
nameback ~/Pictures
```
### GUI（所有平台）
**Windows：** 开始菜单 → nameback
**macOS (Homebrew)：** 在终端中运行 `nameback-gui`
**Linux (cargo install)：** 在终端中运行 `nameback-gui`
**Linux (.deb 软件包)：** 从应用程序菜单启动或运行 `nameback-gui`
1. 点击 **"📁 Select Directory"** 选择文件夹
2. 在右侧栏中查看建议的重命名（左侧为原始名称）
3. 勾选/取消勾选要重命名的文件
4. 点击 **"✅ Rename X Files"** 应用更改
**功能特性：**
- 📂 可视化双栏界面（Midnight Commander 风格）
- ✅ 单个文件的复选框选择
- 🔄 重命名前的实时预览
- ✔️ 颜色编码状态（待处理、成功、错误）
## 常见示例
```
# 整理数据恢复中恢复的文件
nameback /tmp/photorec --dry-run
# 使用 OCR 处理截图文件夹
nameback ~/Desktop/Screenshots --verbose
# 清理 iPhone 照片导出（支持 HEIC）
nameback ~/Desktop/iPhone_Export
# 整理下载的文档
nameback ~/Downloads --dry-run
```
## 功能特性
- **智能命名启发式** - 质量评分系统，从多个来源中选择最佳名称
- **智能照片重命名** - 使用 JPEG, PNG, HEIC/HEIF 中的 EXIF 数据（日期、描述、GPS 位置）
- **PDF 智能** - 从元数据或文档内容中提取标题，支持扫描 PDF 的 OCR
- **增强文本提取** - Markdown frontmatter, CSV 语义列, 嵌套 JSON/YAML 字段
- **上下文感知命名** - 利用目录结构和文件名分析生成更好的名称
- **多帧视频分析** - 提取多个帧（1s, 5s, 10s）并选择最佳 OCR 结果（默认行为）
- **序列检测** - 自动检测并维护文件序列编号（例如：vacation_001.jpg, vacation_002.jpg）
- **特定格式处理器** - 电子邮件文件、网络存档、存档、源代码 docstrings
- **位置与时间戳增强** - 可选的 GPS 坐标和格式化的时间戳包含在文件名中
- **多语言 OCR** - 支持繁体中文、简体中文、英文（以及 160 多种其他语言）
- **高级过滤** - 自动拒绝低质量名称（错误、设备名称、通用占位符）
- **HEIC 支持** - 原生支持 Apple 的高效图像格式
- **安全可靠** - 预览模式、不覆盖、阻止 root 执行、仅限同目录操作
## 选项
```
nameback
# Rename files (includes GPS location & timestamps by default)
nameback --dry-run # Preview changes only
nameback --verbose # Show detailed progress
nameback --skip-hidden # Skip hidden files
nameback --no-location # Exclude GPS location from filenames
nameback --no-timestamp # Exclude timestamps from filenames
nameback --no-geocode # Use raw GPS coordinates instead of city names
nameback --fast-video # Use single-frame video analysis (faster, less accurate)
nameback --check-deps # Check dependencies
nameback --install-deps # Install dependencies
```
**默认行为：** 默认情况下，nameback 在文件名中包含 GPS 位置（反向地理编码为城市名称，如 "Seattle_WA"）和时间戳（如果可用）。使用 `--no-location`, `--no-timestamp`, 或 `--no-geocode` 禁用这些功能。
## 了解更多
- [完整指南](docs/GUIDE.md) - 安装选项、高级功能、故障排除
- **[智能命名启发式](docs/naming-heuristics.md)** - nameback 如何使用质量评分、内容提取和智能过滤来选择最佳文件名
- [元数据提取详情](docs/GUIDE.md#metadata-extraction-details) - nameback 如何优先处理不同的元数据字段
- [高级功能](docs/GUIDE.md#advanced-features) - 多语言 OCR, HEIC 支持, 视频帧提取
- [故障排除](docs/GUIDE.md#troubleshooting) - 常见问题及解决方案
## 安全
Nameback 是按照安全最佳实践开发的。如果您想在 GitHub 仓库中进行自动化安全控制，请查看同一作者 的 [1-click-github-sec](https://github.com/h4x0r/1-click-github-sec) - 自动化 Dependabot, CodeQL, 密钥扫描等。
## 第三方依赖
Nameback 使用以下开源依赖项：
### 必需
- **[ExifTool](https://exiftool.org/)** by Phil Harvey - 元数据提取
- 许可证：GPL-1.0-or-later OR Perl Artistic License
- 参见：[third_party/exiftool/NOTICE](third_party/exiftool/NOTICE)
### 可选
- **[Tesseract OCR](https://github.com/tesseract-ocr/tesseract)** by Google Inc. - 光学字符识别
- 许可证：Apache-2.0
- 参见：[third_party/tesseract/NOTICE](third_party/tesseract/NOTICE)
- **[FFmpeg](https://ffmpeg.org/)** - 用于视频帧提取的多媒体框架
- 许可证：LGPL-2.1-or-later（仅限 LGPL 构建）
- 本软件使用来自 FFmpeg 项目的库，基于 LGPLv2.1
- 源代码：https://ffmpeg.org/download.html
- 参见：[third_party/ffmpeg/NOTICE](third_party/ffmpeg/NOTICE)
- **[ImageMagick](https://imagemagick.org/)** by ImageMagick Studio LLC - HEIC 图像格式支持
- 许可证：ImageMagick License（类 Apache）
- 参见：[third_party/imagemagick/NOTICE](third_party/imagemagick/NOTICE)
所有许可证文本均可在 [LICENSES](LICENSES/) 目录中找到。有关详细的归属信息，请参阅 [third_party/README.md](third_party/README.md)。
### 安装回退机制
Nameback 使用 4 层回退系统，以确保即使在受限的网络环境中也能成功安装依赖项：
1. **主要包管理器**（Scoop/Chocolatey/Homebrew/apt）
2. **DNS 回退** - 使用公共 DNS 服务器（8.8.8.8, 1.1.1.1）重试
3. **备用包管理器** - MacPorts, dnf, yum, pacman, snap
4. **捆绑安装程序** - 从 GitHub Releases 下载（新增！）
这确保了在企业防火墙、VPN 和区域限制下也能达到约 99% 的安装成功率。
## 文档
📚 **[完整文档 →](docs/README.md)**
- **[用户指南](docs/user/guide.md)** - 全面的使用指南
- **[开发文档](docs/dev/)** - 贡献、TDD、重构计划
- **[架构文档](docs/architecture/)** - 技术设计和实现细节
- **[发布流程](RELEASING.md)** - 如何创建发布
## 维护者须知
有关使用 cargo-release 的发布流程，请参阅 [RELEASING.md](RELEASING.md)。
## 许可证
MIT 许可证 - 详情请参阅 [LICENSE](LICENSE) 文件
由 Albert Hui ([@4n6h4x0r](https://github.com/h4x0r)) 创建
使用 [Claude Code](https://claude.com/claude-code) 构建标签：ExifTool, HTTP工具, OCR识别, PDF处理, Rust, Tesseract, 二进制发布, 元数据提取, 元数据清洗, 可视化界面, 名称恢复, 图形界面, 图片处理, 开源工具, 批量重命名, 效率工具, 数字取证, 数字取证, 数据恢复, 文件管理, 文件重命名, 网络安全审计, 网络流量审计, 自动化脚本, 自动化脚本, 视频处理, 进程保护, 通知系统