AmazeVault 快速开始，打造个人专属桌面密码管理器

系列文章目录

Amazevault 是一款专注于本地安全的桌面密码管理器
AmazeVault 核心功能分析，认证、安全和关键的功能
AmazeVault 快速开始，打造个人专属桌面密码管理器

---

---

环境准备

在开始部署和运行不得了（AmazeVault）应用之前，请确保您的本地环境满足以下要求：

• Python 版本：必须为 Python 3.10 或更高版本。项目文档明确指出依赖 Python 3.10+。
• 操作系统：支持 Windows、macOS 和 Linux。
• 工作目录：建议将项目克隆或解压至用户具有写权限的路径，例如桌面或文档文件夹，以便程序能够创建数据目录。

安装依赖

完成环境准备后，接下来需要安装项目所需的 Python 依赖包。

1. 打开命令行终端（Windows 使用 CMD 或 PowerShell，macOS/Linux 使用 Terminal）。

2. 导航到项目根目录：

   cd c:\Users\XXX\Desktop\amazevault
   

3. 推荐使用虚拟环境以避免依赖冲突。可选步骤如下：

   # 创建虚拟环境
   python -m venv .venv
   # 激活虚拟环境（Windows）
   .venv\Scripts\activate
   # 激活虚拟环境（macOS/Linux）
   source .venv/bin/activate
   

4. 安装所有依赖项：

   pip install -r requirements.txt
   

预期输出示例：

Collecting PySide6>=6.6
  Downloading PySide6-6.7.0-cp310-cp310-win_amd64.whl (123.4MB)
...
Successfully installed PySide6-6.7.0 cryptography-42.0.0 argon2-cffi-23.1.0 ...

安装完成后，所有必需的库（如 PySide6、cryptography、argon2-cffi 等）都将就绪。

运行应用

当依赖安装完成后，即可启动应用。

1. 确保当前工作目录为项目根目录。

2. 执行主程序：

   python run.py
   

预期行为：

• 首次运行时，系统会提示您设置 5×5 图形解锁图案。

• 设置完成后，会提示保存“恢复密钥”，该密钥要妥善保管，如果遗失，后续如果忘记解锁图形，密码就找不回来了！

• 应用支持单实例运行：如果已有一个实例在运行，再次启动将激活现有窗口。
• 系统托盘图标将在后台常驻，允许通过右键菜单进行锁定或退出操作。
  
• 后续每次启动都需要绘制相同的图形来解锁主界面。

打包可执行文件

对于终端用户，可以通过打包脚本生成独立的可执行文件，无需安装 Python 环境即可运行。

Windows 打包步骤

1. 安装 PyInstaller：

   pip install PyInstaller
   

2. 使用提供的批处理脚本进行打包：

   packaging\build_windows.bat
   

   默认生成单文件可执行程序（onefile）。若需生成目录模式（onedir），请运行：

   packaging\build_windows.bat dir
   

输出位置：

• 单文件模式：dist\AmazeVault-1.0.0.exe
• 目录模式：dist\AmazeVault-1.0.0\AmazeVault-1.0.0.exe
  

注意事项：

• 打包脚本会自动读取 __version__ 作为版本号。
• 若存在 amazevault/resources/icons/app.ico，将自动嵌入图标。
• 生成的可执行文件包含所有依赖项，并通过 pyi_rth_pyside6.py 运行时钩子确保 Qt 插件路径正确。

开发者调试模式

针对开发者，推荐使用以下方式启动应用以方便调试：

调试启动方式

直接运行主脚本即可进入开发模式：

python run.py

此模式下：

• 日志输出到 ./data/logs/amazevault.log，便于追踪错误。
• 支持热重载界面资源（如 QSS 样式表）。
• 可通过系统托盘图标快速重启或退出。

调试技巧

1. 启用详细日志：在 storage/settings.py 中调整日志级别。
2. 单实例调试：若需同时运行多个实例进行测试，可临时注释 main.py 中的单实例检查逻辑。
3. 审计日志：所有操作记录在 data/vault.db 的 audit 表中，可用于行为追踪。

开发者可通过修改 ui/ 目录下的组件进行界面调整，并利用 PySide6 提供的 Qt Designer 工具进行可视化编辑。