# MiVault

**Repository Path**: borisliu/mi-vault

## Basic Information

- **Project Name**: MiVault
- **Description**: **密巢（MiVault）** 是一个基于国密算法（SM2 / SM3 / SM4）的开源密码管理器，致力于为中国用户和企业提供 **符合信创、商用密码、等保要求** 的安全密码存储与管理解决方案。  

- **Primary Language**: TypeScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-12
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🐚 密巢 · MiVault

> 让密码安全回归你的掌控  
> Secure Your Secrets, Locally & Compliantly

---

## 📘 项目简介

**密巢（MiVault）** 是一个基于 Tauri + Vue 3 的跨平台密码工具，提供密码复杂度检测和密码生成功能。项目采用 **FST + mmap** 方案实现高效的弱密码检测，支持 Windows、macOS、Linux 三大平台。

---

## 🧩 核心特性

### 密码复杂度检测
- 使用 **zxcvbn** 算法进行强度评估（0-100 分）
- 实时显示密码强度等级（弱/中/强/极强）
- 提供改进建议和破解时间估算
- **弱密码字典检测**：集成 243 个常见弱密码，通过 FST 快速查询
- 只有达到 100% 强度才显示绿色对钩

### 密码生成器
- 可配置密码长度（8-64 位）
- 支持多种字符集选择（大小写字母、数字、特殊字符）
- 使用加密安全的随机数生成（`crypto.getRandomValues`）
- 一键复制到剪贴板

### 技术特点
- **跨平台支持**：Windows / macOS / Linux（已测试）
- **本地运行**：完全离线，数据不出本地
- **高性能**：FST + mmap 方案，内存占用 < 30MB
- **轻量级**：基于 Tauri 框架，体积小、启动快

---

## 🛠️ 技术栈

### 前端
- **Vue 3** + **TypeScript** - 现代化前端框架
- **Element Plus** - Vue 3 组件库
- **Vite** - 快速构建工具
- **zxcvbn** - 密码强度检测库

### 后端
- **Tauri** - 轻量级桌面应用框架
- **Rust** - 系统编程语言
- **FST** - 有限状态转换器（弱密码字典）
- **memmap2** - 内存映射（低内存占用）

---

## 📦 环境要求

### 必需依赖
- **Node.js** 18+ （推荐 20+）
- **npm** 或 **yarn**
- **Rust** 1.70+ （包含 cargo）

### 平台特定要求

**Windows:**
- WebView2（Windows 10/11 通常已预装）
- Visual Studio C++ Build Tools（如遇到编译错误再安装）

**Linux:**
```bash
sudo apt-get install -y \
  libssl-dev \
  libgtk-3-dev \
  libwebkit2gtk-4.0-dev \
  libayatana-appindicator3-dev \
  libsoup2.4-dev \
  libjavascriptcoregtk-4.0-dev \
  pkg-config \
  build-essential
```

**macOS:**
- Xcode Command Line Tools（通常已预装）

---

## 🚀 快速开始

### 1. 克隆项目
```bash
git clone <repository-url>
cd mi-vault
```

### 2. 安装依赖
```bash
npm install
```

### 3. 下载弱密码字典（可选，推荐）

**方式一：使用自动下载脚本（推荐）**
```bash
npm run download:dict
```

这将从 SecLists 项目下载常用弱密码字典文件到 `public/dictionaries/` 目录，包括：
- Top 10万 常用密码（约 1MB）
- Top 1万 常用密码（约 100KB）
- 短密码列表等

**方式二：手动下载完整字典**

如需使用完整的一千万密码列表，可以：

1. **使用 Git 克隆 SecLists 仓库**（推荐）：
```bash
git clone https://github.com/danielmiessler/SecLists.git
# 复制需要的字典文件到 public/dictionaries/ 目录
cp SecLists/Passwords/Common-Credentials/*.txt public/dictionaries/
```

2. **或手动下载大文件**到 `public/dictionaries/` 目录

### 4. 生成 FST 弱密码字典文件
```bash
npm run build:fst
```

- 如果已下载字典文件：将从 `public/dictionaries/` 目录读取所有 `.txt` 文件并构建 FST
- 如果未下载字典：将从 `weakPasswords.ts` 提取内置弱密码（约 243 个）并构建 FST

**注意**：大规模字典（如 1000万+ 密码）构建可能需要几分钟时间，请耐心等待。

### 5. 开发模式

**Linux 用户（推荐使用启动脚本）:**
```bash
./run-dev.sh
```

**其他平台:**
```bash
npm run tauri:dev
```

### 6. 构建生产版本
```bash
npm run tauri:build
```

构建完成后，可执行文件位于 `src-tauri/target/release/` 目录。

---

## 📁 项目结构

```
mi-vault/
├── src/                    # 前端源码
│   ├── components/         # Vue 组件
│   │   ├── PasswordChecker.vue    # 密码复杂度检测
│   │   └── PasswordGenerator.vue  # 密码生成器
│   ├── composables/        # Composition API
│   │   ├── usePasswordCheck.ts     # 密码检测逻辑
│   │   └── usePasswordGen.ts      # 密码生成逻辑
│   ├── utils/              # 工具函数
│   │   ├── clipboard.ts    # 剪贴板操作
│   │   └── weakPasswords.ts       # 弱密码检测
│   ├── App.vue             # 根组件
│   └── main.ts             # 入口文件
├── src-tauri/              # Tauri 后端
│   ├── src/
│   │   ├── main.rs         # Rust 主入口
│   │   └── weak_dict.rs    # 弱密码字典模块
│   ├── resources/
│   │   └── weak.fst        # FST 弱密码字典文件
│   ├── Cargo.toml          # Rust 依赖配置
│   └── tauri.conf.json     # Tauri 配置文件
├── scripts/
│   ├── build-fst/          # FST 构建工具
│   └── extract-dictionary-data.js  # 字典数据提取
├── docs/                   # 文档目录
└── package.json            # Node.js 依赖
```

---

## 📚 文档索引

以下文档均可从本 README 访问，按主题分类：

### 构建与编译
- [Linux 编译指南](docs/LINUX_BUILD_GUIDE.md) — Linux 环境下编译与运行的完整步骤
- [编译过程总结](docs/BUILD_SUMMARY.md) — 编译流程概览与关键配置
- [构建优化](docs/BUILD_OPTIMIZATION.md) — 构建优化说明
- [构建优化分析](docs/BUILD_OPTIMIZATION_ANALYSIS.md) — 构建优化分析与评估

### 弱密码字典
- [弱密码字典设置指南](docs/DICTIONARY_SETUP_GUIDE.md) — 下载与集成大规模字典
- [字典状态说明](docs/DICTIONARY_STATUS.md) — 字典来源与状态
- [字典优化策略](docs/DICTIONARY_OPTIMIZATION_STRATEGY.md) — 字典优化策略
- [字典优化评估](docs/DICTIONARY_OPTIMIZATION_EVALUATION.md) — 字典优化方案评估
- [FST + mmap 方案评估](docs/FST_MMAP_EVALUATION.md) — FST 与内存映射方案评估
- [FST 打包评估](docs/FST_PACKAGING_EVALUATION.md) — FST 打包与分发评估

### 发布与分发
- [发布指南（Tag 与 Release）](docs/RELEASE_GUIDE.md) — Git 标签与 Gitee 发布流程
- [分发指南](docs/DISTRIBUTION_GUIDE.md) — 安装包构建与分发方式
- [v0.2.0 发布说明](docs/RELEASE_0.2.0.md) — 0.2.0 版本发布说明

### 历史与总结
- [工作小结 2024-12-13](docs/WORK_SUMMARY_2024-12-13.md)
- [工作小结 2024-12-30](docs/WORK_SUMMARY_2024-12-30.md)

---

## 🎯 使用说明

### 密码复杂度检测
1. 在左侧"密码复杂度检测"区域输入密码
2. 系统会实时显示：
   - 强度评分（0-100）
   - 强度等级（弱/中/强/极强）
   - 改进建议
   - 估算破解时间
   - 弱密码检测结果

### 密码生成器
1. 在右侧"密码生成器"区域：
   - 调整密码长度滑块（8-64 位）
   - 选择需要的字符集
2. 点击"生成密码"按钮
3. 点击"复制密码"复制到剪贴板

---

## 🔒 安全说明

- **本地运行**：所有操作在本地完成，密码不会上传到任何服务器
- **随机数生成**：使用 `crypto.getRandomValues()` 生成加密安全的随机数
- **密码检测**：使用 zxcvbn 算法，基于实际密码破解数据评估强度
- **弱密码字典**：使用 FST + mmap 方案，高效且低内存占用

---

## 📚 弱密码字典实现

### 技术方案
- **FST + mmap**：使用 Rust `fst` 库构建有限状态转换器
- **内存映射**：使用 `memmap2` 实现低内存占用（< 30MB）
- **快速查询**：通过 Tauri command 从 Rust 后端调用
- **降级方案**：内置 243 个常见弱密码作为备用

### 字典来源

**内置字典**（默认）：
- 常见数字序列（123456、12345678 等）
- 键盘排列模式（qwerty、asdfgh 等）
- 常见英文弱密码（password、admin 等）
- 常见中文拼音弱密码
- 常见年份、重复字符模式等

**外部字典**（可选，推荐）：
- **SecLists**：https://github.com/danielmiessler/SecLists
  - 10-million-password-list-top-100000.txt（Top 10万）
  - 10-million-password-list-top-10000.txt（Top 1万）
  - 完整的一千万密码列表（需手动下载）

### 字典规模

- **小规模**（内置）：243 个弱密码，FST 文件约 2KB
- **中等规模**（推荐）：10万+ 弱密码，FST 文件约 10-20MB
- **大规模**：1000万+ 弱密码，FST 文件约 50-100MB

**性能说明**：
- 无论字典规模大小，查询速度都极快（< 1微秒）
- 内存占用低（< 30MB），使用 mmap 按需加载
- 构建时间：小规模 < 1秒，大规模可能需要几分钟

---

## 🧭 开发路线图

### ✅ 已完成（v0.1.0）
- [x] 密码复杂度检测
- [x] 密码生成器
- [x] 基础 UI 界面
- [x] 弱密码字典集成（FST + mmap）
- [x] 跨平台支持（Windows / macOS / Linux）

### 🚧 计划中
- [ ] 本地数据库（SQLite）
- [ ] 基于 SM4 的加密存储
- [ ] 密码库管理（增删改查）
- [ ] 用户账户体系
- [ ] 浏览器插件
- [ ] 团队共享功能

---

## 📝 更新日志

### v0.3.0 (2025-02)

**✨ 功能与发布**
- 新增 Windows 便携版：`密巢_<version>_portable.zip`（解压即用，无需安装）
- 新增 `npm run build:portable` 脚本生成便携版

**📦 发布流程**
- releases 目录仅保留可下载安装包（安装版 exe + 便携版 zip），自动清理临时文件
- 新增 [发布指南](docs/RELEASE_GUIDE.md)（Tag 与 Gitee Release 流程）
- 文档索引：README 可访问 [docs](docs/) 下全部文档

### v0.2.0 (2024-12)

**✨ 新功能**
- 界面底部显示已加载的弱密码字典总数
- 科学精简策略：FST 从约 60 MB 优化至约 21 MB，密码数约 358 万

**📦 发布与分发**
- 同时提供安装包与便携版可执行文件
- 自动复制资源到 releases 目录，完善分发支持

**🔧 技术改进**
- 构建脚本精简，改进错误处理与文件读取逻辑

### v0.1.2 (2024-12-13)

**✨ 功能优化**
- 密码强度显示逻辑优化：只有达到 100% 才显示绿色对钩
- 布局优化：固定左侧面板宽度（480px），避免宽度变化
- 窗口尺寸调整：1000x650px，避免滚动条

**🐛 问题修复**
- 修复 Vite 配置中的无效 glob 模式错误
- 修复 macOS 环境下的构建脚本（extract-dictionary-data.js）
- 修复应用启动时的白屏问题

**📚 代码精简**
- 删除未使用的 `dictionaryLoader.ts`
- 精简剪贴板操作代码
- 整理和合并文档

**✅ 跨平台测试**
- Windows 测试通过
- Linux 测试通过
- macOS 测试通过

### v0.1.1 (2024-12-12)

**✨ FST + mmap 弱密码字典优化**
- 使用 Rust FST 库构建弱密码字典
- 使用内存映射实现低内存占用（< 30MB）
- 通过 Tauri command 从 Rust 后端调用

**🐛 Linux 编译支持**
- 添加完整的 Linux 编译指南
- 配置 pkg-config 环境变量
- 创建开发环境启动脚本

### v0.1.0 (2024-01-XX)

- ✨ 初始版本发布
- ✨ 密码复杂度检测功能
- ✨ 密码生成器功能
- ✨ 基于 Tauri + Vue 3 + Element Plus 的桌面应用

---

## 📄 开源协议

本项目以 **AGPL v3** 协议开源。  
允许研究、学习与非商业性使用，商业化前需取得授权。

---

## 👤 作者与理念

> "AI 不是取代个人，而是放大一个人的生产力。"

作者是一名长期从事网络安全与反诈工作的技术从业者，  
通过 AI 工具链探索如何以"一人团队"模式，  
打造符合中国安全标准的密码管理产品。

---

## 🌟 支持项目

如果你也关心 **中国本土的安全软件生态**，欢迎：

- ⭐ Star 本项目
- 🐛 提交 Issue / PR
- 🧩 一起共建国密生态

---

**MiVault — 让密码安全回归你的掌控。**