# FileSafe

**Repository Path**: logicliu/file-safe

## Basic Information

- **Project Name**: FileSafe
- **Description**: 文件保险箱
- **Primary Language**: Kotlin
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-09-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Kotlin, Android

## README

# FileSafe 文件保险箱

一个注重隐私的 Android 本地文件保险箱应用：将图片、视频、文档等文件**隐藏**或**加密**保存在应用私有目录中，通过密码 / 指纹解锁访问。

> ⚠️ 所有数据仅保存在设备本地，应用**未申请网络权限**，无云同步、无任何数据上传。

## 功能特性

- 🔐 **多因素解锁**：主密码 + 可选指纹（Biometric）双重验证；支持修改密码、密保问题找回
- 🛡️ **文件加密**：
  - AES-256-GCM（Android Keystore 硬件级密钥保护）
  - XChaCha20-Poly1305（Bouncy Castle，每文件独立随机密钥）
  - 超过 10MB 自动分块（8MB/块）并行加密，导入导出均有前台服务进度通知
  - Hide（仅隐藏）/ Encrypt（加密存储）两种模式，算法与模式可在安全设置中切换
- 📁 **文件管理**：单个 / 批量导入、文件夹组织、重命名、导出、安全回收站（可恢复 / 永久删除）
- 🖼️ **媒体查看**：内置图片查看（缩放、左右滑动翻页）与视频播放器（播放控制、倍速、全屏、双指缩放）
- ⏱️ **应用安全**：自动锁定（可设为永不锁定）、防截屏 / 录屏（FLAG_SECURE）、后台返回自动锁定
- 🎨 **界面**：Material 3、浅色 / 深色 / 跟随系统主题、列表 / 平铺两种浏览模式、媒体缩略图

## 当前版本与状态

- `versionName 1.0` / `versionCode 1`（首个发布候选版本）
- 兼容 Android 7.0（API 24）至 Android 16（API 36），targetSdk 36
- **备份与恢复**：UI 入口目前显示"功能开发中"，暂未开放，敬请期待后续版本
- 已知发布前事项（签名配置、通知权限、自动备份策略等）尚未处理完毕

## 技术栈

| 类别 | 选型 |
|------|------|
| 语言 / UI | Kotlin 2.2.10 · Jetpack Compose + Material3（BOM 2024.12.01） |
| 架构 | MVVM（ViewModel + StateFlow）+ Repository 模式 · 单 Activity + Navigation Compose 2.8.5 |
| 存储 | Room 2.7.0（预留）· DataStore Preferences 1.1.1（运行数据源） |
| 加密 | AES-256-GCM（Android Keystore）· XChaCha20-Poly1305（Bouncy Castle 1.78）· PBKDF2WithHmacSHA256 |
| 安全 | Biometric API 1.2.0-alpha05 |
| 媒体 | Media3 ExoPlayer 1.5.1 · Coil 2.7.0 |
| 构建 | AGP 9.2.1 · Gradle KTS + Version Catalog · KSP |

## 项目结构

```
app/src/main/java/cn/logicliu/filesafe/
├── data/          # 数据层：Room 实体/DAO、FileDataStore、FileRepository
├── security/      # CryptoManager、PasswordManager、BiometricHelper、密保/安全设置
├── service/       # EncryptionService（前台服务）、ThumbnailManager
└── ui/            # Compose UI：navigation、screens、components、theme、viewmodel
```

## 构建

环境要求：JDK 17+（建议 21）、Android SDK（platform 36）、支持 AGP 9.x 的最新稳定版 Android Studio。

```batch
:: Debug 构建
.\gradlew.bat assembleDebug

:: 产物路径
:: app\build\outputs\apk\debug\app-debug.apk
```

> 注意：当前工程**未配置 Release 签名**。正式发布需自行配置 keystore 签名（`assembleRelease` 产物默认未签名）。

## 数据与隐私说明

| 项目 | 说明 |
|------|------|
| 数据位置 | 文件与元数据均存于应用私有目录（`filesDir`），卸载应用即清除 |
| 权限 | 媒体读取（选择导入文件）、指纹（USE_BIOMETRIC）、通知 / 前台服务（导入导出进度）。无需存储权限，导入导出走系统文件选择器 |
| 密码存储 | 密码经 SHA-256 摘要后再用 AES-256-GCM（Keystore）加密保存，密文不可逆 |
| 联网 | 未声明 INTERNET 权限，无网络通信 |

## 开源许可

本项目基于 [MIT License](LICENSE) 开源，Copyright (c) 2026 LogicLiu。详见 [LICENSE](LICENSE) 文件。