# flutter-pass-log

**Repository Path**: mj-project/flutter-pass-log

## Basic Information

- **Project Name**: flutter-pass-log
- **Description**: 简洁的密码记录应用，纯本地运行，对关键数据进行加密存储
- **Primary Language**: Dart
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-06-20
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Flutter, Dart, getx, Android

## README

# PassLog

PassLog 是一个基于 Flutter 开发的本地密码记录应用，面向个人场景，在本设备加密保存账号、密码和备注信息，并支持通过 `.passlog` 迁移文件在设备之间导出与导入密码数据。

## 功能概述

### 密码记录管理

* 新增、编辑、删除密码记录
* 按分类查看密码记录
* 通过关键字搜索密码记录
* 一键复制账号
* 登录密码默认以圆点遮罩显示，点按显示后按记录独立倒计时展示 15 秒

每条密码记录包含以下字段：

* 密码名称
* 登录账号
* 登录密码
* 所属分类
* 备注信息

### 分类管理

* 内置默认分类
* 新增分类
* 编辑分类名称和图标
* 拖拽调整分类顺序
* 删除分类

删除分类时，该分类下已有的密码记录会自动迁移到默认分类，避免数据丢失。

### 锁屏与安全

* 首次启动要求创建 6 位解锁密码（即本机解锁密码）
* 每次进入应用需要先解锁
* 支持生物识别解锁，可启用、重新绑定或关闭
* 在设置页修改解锁密码，修改时会对现有密码数据重新加密
* 支持设置应用在后台锁定前的等待时长（立即锁定、30 秒、1 分钟、5 分钟或 15 分钟），未设置过时默认立即锁定
* 已展示的登录密码会在离开页面、进入后台或应用锁定时自动隐藏

### 本地加密存储

* 密码记录写入 Hive 本地数据库前先加密
* 密码记录与密钥封装均带完整性校验码，可识别内容是否被篡改
* 旧版本升级来的数据，会在后续使用本机解锁密码解锁时自动升级为带完整性校验的加密格式，并提升口令派生强度
* 应用解锁后会派生当前会话使用的加密密钥
* 数据迁移文件使用源文件密码加密保护

### 数据迁移

* 导出全部密码数据
* 按全量或部分模式导出，部分模式通过选择树逐项勾选
* 导入 `.passlog` 格式迁移文件
* 当前版本导出的迁移文件为受保护格式，自带文件级完整性校验，导入时可确认内容未被篡改
* 导入无法确认完整性的旧版迁移文件前，会先提示风险，经确认后才继续
* 导入前先解析并预览内容，再选择部分数据导入
* 导入时需要输入源文件密码完成校验
* 导入重名或 ID 冲突的数据时自动处理，尽量避免覆盖现有内容
* 导出、导入属于敏感操作，开始前需要先完成操作验证

#### 迁移文件格式版本说明

导出的 `.passlog` 文件顶层的 `version` 字段表示该迁移文件的封装格式版本，与 App 版本号相互独立。升级 App（例如从 1.2.0 到 1.3.0）不会改变迁移文件的格式版本，因此更新 App 后导出的文件仍显示 `version: 3` ，这是正常现象。

不要把文件顶层版本与加密内容前缀混淆：当前版本导出的文件，其顶层封装格式版本为 3，属带完整性校验的受保护格式，能够识别文件内容在导出后是否被篡改；文件中受保护内容的密文带有 `v4:` 前缀，那是表示单条数据带完整性校验的加密格式标识，与文件顶层的封装版本是两套不同的编号。两者都不随 App 版本号变化。早于受保护格式导出的迁移文件不携带文件级校验码，导入前会提示无法确认完整性。

### 密码排序

* 支持持久化保存密码的排列顺序

### 主题设置

* 切换主题主色
* 主题色会持久化保存

## 技术栈

* Flutter
* Dart
* GetX
* Hive
* Material 3

主要依赖：

* `get`
* `hive`
* `isar_flutter_libs`
* `flutter_easyloading`
* `flutter_iconpicker`
* `flutter_slidable`
* `animated_reorderable_list`
* `flutter_screen_lock`
* `file_picker`
* `flutter_secure_storage`
* `crypto`
* `dart_sm`
* `package_info_plus`

## 快速开始

### 运行环境

* Flutter 3.24.0
* Dart 3.5.0

`pubspec.yaml` 中声明的 Dart SDK 范围为：

```yaml
sdk: '>=3.3.0 <4.0.0'
```

### 本地运行

首次运行项目需要先执行以下命令，生成 `flutter_iconpicker` 的图标资源：

```bash
flutter pub get
dart run flutter_iconpicker:generate_packs --clear
dart run flutter_iconpicker:generate_packs --packs roundedMaterial
```

后续运行项目只需执行：

```bash
flutter run
```

### 打包

推荐使用以下命令打包 Android APK：

```bash
flutter build apk --no-tree-shake-icons --split-per-abi --release
```

注意：

* 不能省略 `--no-tree-shake-icons`。项目使用了 `flutter_iconpicker`，省略后会导致图标资源缺失
* 可以使用 `--split-per-abi`。此前遇到的「选择图标时显示 No results」问题，根因是 `flutter_iconpicker` 的图标数据（生成到 pub cache 的 `MaterialRounded.dart`）在构建时处于空状态，与 `--split-per-abi` 无关。构建前请确保已执行上方两条 `generate_packs` 命令（不要只执行 `--clear`），如仍异常，先 `flutter clean` 再重新构建

## 项目结构

```text
lib/
  main.dart             应用入口（启动引导、初始化失败重试）
  app/
    core/               核心工具、主题、加密与全局服务
    data/               Provider 与本地服务
    modules/            页面模块（首页、锁屏、分类、密码、排序、迁移、设置）
    routes/             路由配置
```

已实现页面：

* 首页：密码列表、分类分组、搜索、复制账号、查看登录密码
* 锁屏页：首次创建解锁密码与后续解锁、生物识别解锁
* 分类管理页：分类增删改、图标选择、拖拽排序
* 密码编辑页：表单录入与修改
* 密码排序页：调整密码排列顺序
* 数据迁移页：导入 / 导出 / 预览
* 系统设置页：主题主色、修改解锁密码、生物识别、自动锁定时长

## 界面预览

| 锁屏页 | 首页 | 菜单 |
|:---:|:---:|:---:|
| ![](lib/pic/Screenshot_2026-08-30-02-16-42-459_com.kaminarly.pass_log-edit_5_2026-08-30_02-17-17_175.jpg) | ![](lib/pic/Screenshot_2026-08-30-02-13-16-117_com.kaminarly.pass_log-edit_1_2026-08-30_02-17-17_152.jpg) | ![](lib/pic/Screenshot_2026-08-30-02-14-59-993_com.kaminarly.pass_log-edit_2_2026-08-30_02-17-17_158.jpg) |

| 数据迁移 | 系统设置 | 添加密码 |
|:---:|:---:|:---:|
| ![](lib/pic/Screenshot_2026-08-30-02-15-19-790_com.kaminarly.pass_log-edit_3_2026-08-30_02-17-17_164.jpg) | ![](lib/pic/Screenshot_2026-08-30-02-15-31-235_com.kaminarly.pass_log-edit_4_2026-08-30_02-17-17_169.jpg) | ![](lib/pic/Screenshot_2026-08-30-02-12-29-585_com.kaminarly.pass_log-edit_0_2026-08-30_02-17-17_144.jpg) |

## 注意事项

* 这是一个偏个人使用场景的本地应用，不依赖云端同步
* 如果忘记解锁密码，将无法读取当前已加密的数据
* 导入迁移文件时，必须输入导出该文件时对应 App 的源文件密码

## 许可证

项目根目录包含 [LICENSE](LICENSE) 文件，当前使用 MIT License。