个人密码管理器 —— 本地优先、信封加密、拷贝即迁移。
你的密码用一把随机"库主密钥(VMK)"加密后存进本地 SQLite;这把 VMK 又被你保管的"访问密钥"层层包裹。没有你的访问密钥,即便整个数据库被拷走也解不开。
📚 这是个人练手 / 学习项目(用于实践全栈开发与安全工程),非生产级产品;存放真正重要的密码请使用成熟的密码管理器。
- 信封加密(借鉴 VeraCrypt):多把访问密钥 + 离线恢复码;增删/更换密钥只改"包裹",不重新加密数据
- 敏感字段(密码 / 备注 / TOTP)加密存储;明文字段(平台 / 账号 / 标签)可搜索
- 复制密码后自动清空剪贴板;列表只显示圆点,从不显示明文
- 回收站(软删除 → 可恢复 / 彻底删除)、收藏置顶、搜索、显示编号
- 关闭程序即上锁(解出的密钥只在内存,不落盘)
- 两种发行:免安装版(解压即用)+ 安装版(
setup.exe,支持覆盖升级、数据保留)
| 层 | 用什么 |
|---|---|
| 后端 | Python · FastAPI · SQLModel · SQLite · cryptography(AES-256-GCM)· argon2-cffi(Argon2id)· PyJWT |
| 前端 | Vue 3 · TypeScript · Vite · Element Plus · Pinia · Vue Router |
| 打包 | PyInstaller(免安装版)· Inno Setup(安装版) |
| 测试 | pytest(测试驱动开发) |
- 访问密钥(access key):你解锁用的钥匙,首次运行生成、只显示一次,需自己保存。它不是脑子记的密码,而是像 SSH 私钥一样妥善保管的高熵随机串。
- 恢复码(recovery code):应急用。丢了访问密钥时用它重置全部密钥(数据不丢)。同样只显示一次。
- VMK(库主密钥):随机生成、真正加密你数据的钥匙,从不明文存储;被每把访问密钥/恢复码各"包裹"一份。(概念即"主密钥",缩写借自 VeraCrypt/BitLocker。)
- 信封加密 / 密钥包裹:用"访问密钥派生出的钥匙"去加密 VMK,而非直接加密数据 → 支持多钥匙、换钥匙只改包裹。(行业标准模式,AWS / Google KMS 等都在用。)
- Argon2id:从"访问密钥 + 盐"派生包裹密钥的算法(内存硬、抗暴力破解;密码哈希竞赛冠军)。
- AES-256-GCM:加密数据的对称算法,自带完整性校验(密文被改一字节就解不开)。
- 盐(salt):每把密钥一段随机、公开的值,防"彩虹表"预计算;公开存储无妨。
原则:加密原语全部采用现成标准件(Argon2id / AES-GCM / 信封加密),绝不自造算法;keybox 只负责把它们正确组装。
- ✅ 守得住:没有访问密钥就进不来;数据库文件 / 密文被偷,也解不开。
⚠️ 防不住(单机自托管的固有边界):对手物理控制你整台已解锁的机器。- 🔑 找回:丢访问密钥 → 用恢复码重置;访问密钥与恢复码全丢 → 无法找回(这是安全设计,而非缺陷)。
普通用户
- 安装版:下载
keybox-setup-x.x.x.exe双击安装(免管理员,装到当前用户目录)。 免安装版:下载keybox-x.x.x-portable.zip,解压后双击keybox.exe。 - 浏览器自动打开 → 首次使用点"生成我的密钥" → 立即复制保存访问密钥 + 恢复码(只显示一次!) → 进入解锁。
- 输入访问密钥解锁 → 添加 / 搜索 / 复制你的账号密码。
- 关闭那个命令行窗口即停止 keybox。
升级:装新版 setup.exe 直接覆盖,数据保留。
换设备:把整个免安装目录(或其中的 keybox.db)拷到新机,用原访问密钥解锁即可——数据全程加密、不脱密。
开发运行:
# 后端
cd backend
python -m venv venv && .\venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt
uvicorn app.main:app --port 8080
# 前端(另开终端)
cd frontend && npm install && npm run dev # http://localhost:5200打包:
cd frontend && npm run build # 产出 dist
pyinstaller backend/run.py --name keybox --onedir \
--add-data "frontend/dist;frontend_dist" --collect-submodules uvicorn \
--distpath release/1.0.0 # 免安装版
ISCC.exe packaging/keybox.iss # 安装版(需 Inno Setup)backend/ FastAPI 后端:core/crypto(信封)· db(存储)· auth(认证)· vault(密码管理)· api · settings
frontend/ Vue 前端:解锁 / 保险库 / 回收站 / 设置
packaging/ Inno Setup 安装脚本
个人项目。信封加密方案参考 VeraCrypt Encryption Scheme。