CmdVault 部署使用维护指南

一个极简、安全、自毁保护的密码保险箱

一、项目简介

CmdVault 是一个前后端协同的密码管理器，数据使用 AES-256-GCM 加密存储，支持 HMAC 完整性校验、自毁保护、邮件备份恢复、PushDeer 实时推送通知。

特性	说明
加密存储	AES-256-GCM + PBKDF2 密钥派生
完整性校验	HMAC-SHA256 签名，防篡改
自毁保护	连续 10 次密码错误自动删除数据
邮件备份	第 5 次密码错误自动发送加密备份到邮箱
推送通知	PushDeer 实时推送安全告警
数据恢复	从邮件粘贴加密 JSON 一键恢复
密码生成	易记密码 / 强密码 / SSH 密钥
手机适配	响应式布局，拇指友好

二、环境要求

一台 Linux 服务器（Debian/Ubuntu/CentOS 均可）
安装 Docker 和 Docker Compose
开放端口 5200（可在 docker-compose.yml 中修改）
（可选）QQ 邮箱账号用于接收备份邮件
（可选）PushDeer App 用于接收推送通知

三、安装步骤

1. 解压安装包

mkdir /opt/cmdvault
tar -xzf cmdvault.tar.gz -C /opt/cmdvault
cd /opt/cmdvault

2. 确认文件完整

ls -la

应看到：docker-compose.yml、Dockerfile、requirements.txt、app.py、templates/

3. 配置邮件和推送（可选但推荐）

编辑 docker-compose.yml：

environment:
  - PUSHDEER_KEY=你的PushDeer密钥
  - ADMIN_EMAIL=你的邮箱@qq.com
  - SMTP_SERVER=smtp.qq.com
  - SMTP_PORT=587
  - SMTP_USER=你的邮箱@qq.com
  - SMTP_PASS=你的QQ邮箱授权码

获取 QQ 邮箱授权码：登录 QQ 邮箱 → 设置 → 账户 → POP3/SMTP 服务 → 开启 → 生成授权码。
获取 PushDeer Key：下载 PushDeer App → 注册 → 首页显示 PushKey。

4. 构建并启动

sudo docker compose up -d --build

5. 访问

浏览器打开 http://<服务器IP>:5200

重要：CmdVault 依赖浏览器 Web Crypto API，必须通过 HTTPS 或 localhost 访问才能使用加密功能。建议配置 Nginx 反代 + SSL 证书。

四、使用指南

1. 首次使用

打开 CmdVault，输入主密码（自己设定，务必牢记）
点击"解锁保险箱"
点击右下角 + 按钮添加密码
填写应用名称、用户名、密码，点击保存

忘记主密码 = 数据永久丢失。没有任何后门可以恢复。请务必牢记主密码。

2. 日常使用

查看密码：点击卡片 → 点击 👁 显示密码
复制密码：点击 📋 一键复制
编辑密码：点击卡片 → 点击"编辑"
删除密码：点击卡片 → 点击"删除"
锁定：点击右上角"锁定"按钮，5 分钟无操作自动锁定

3. 密码生成器

类型	说明	示例
📝 易记	4 个英文单词 + 2 位数字	tree-sun-moon-42
🔐 强密码	18 位随机混合字符	xK9#mP2$vL7@nQ4^wR6
🔑 密钥	RSA-2048 密钥对	公钥+私钥写入备注

4. 数据恢复

打开邮箱，找到主题为 "💥 CmdVault 已自毁" 的邮件
复制邮件中的完整 JSON 数据
打开 CmdVault 登录页 → 点击"恢复数据"
粘贴 JSON → 点击"恢复"
用原主密码登录

五、安全机制说明

失败次数	触发行为
3 次	PushDeer 推送 ⚠️ 警告
5 次	锁定 24 小时 + 邮件发送加密备份
8 次	PushDeer + 邮件 🚨 即将自毁警告
10 次	💥 数据自毁 + 邮件发送最后备份

锁定后继续输错也会计数。攻击者即使知道系统已锁定，继续尝试也会触发自毁。

六、日常维护

容器管理

# 进入项目目录
cd /opt/cmdvault

# 重启容器
sudo docker compose restart

# 停止容器
sudo docker compose down

# 查看日志
sudo docker logs cmdvault

# 重建镜像
sudo docker compose up -d --build

数据备份

# 手动备份数据库
cp /opt/cmdvault/data/vault.db /opt/cmdvault/data/vault.db.bak.$(date +%Y%m%d)

版本更新

cd /opt/cmdvault
sudo docker compose down
tar -xzf cmdvault.tar.gz
sudo docker compose up -d --build

数据不会丢失：data/ 目录已挂载到宿主机，覆盖代码不会影响数据库。

七、安全建议

主密码足够长：建议 12 位以上，混合大小写和数字
配置 HTTPS：使用 Nginx 反代 + Let's Encrypt 证书
配置邮件通知：确保能收到加密备份
定期手动备份：把 vault.db 复制到安全位置
不分享主密码：主密码是唯一入口
不要分享 data 目录：vault.db 包含加密数据

八、常见问题

Q: 忘记主密码怎么办？

A: 无法恢复。这是设计上的安全取舍——宁可数据丢失，也不留后门。

Q: 自毁后如何恢复？

A: 从邮箱中找到自毁通知邮件，复制其中的完整 JSON，点击登录页的"恢复数据"粘贴即可。

Q: 为什么提示"数据格式错误"？

A: 恢复时粘贴的 JSON 不完整。请确保从邮件中复制了完整的 JSON（包含 encrypted_data、salt、hmac 三个字段）。

Q: 为什么浏览器无法使用？

A: 必须通过 HTTPS 或 localhost 访问。HTTP 环境下 Web Crypto API 不可用。

Q: 可以多设备同步吗？

A: 不支持自动同步。你可以手动复制 vault.db 到其他设备，用相同主密码打开。

CmdVault · 一个真正安全的密码保险箱