# Password

**Repository Path**: ximengsr/password

## Basic Information

- **Project Name**: Password
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Password 密码管家

![Node](https://img.shields.io/badge/Node.js-22.5%2B-339933?logo=node.js)
![Vue](https://img.shields.io/badge/Vue-3.4.0-42b883?logo=vue.js)
![Express](https://img.shields.io/badge/Express-4.19.2-000000?logo=express)
![SQLite](https://img.shields.io/badge/SQLite-node%3Asqlite-003B57)
![Vite](https://img.shields.io/badge/Vite-5.2.0-646CFF?logo=vite)
![License](https://img.shields.io/badge/License-MIT-green)

### 基于 Vue 3 + Node 的零知识密码管理器

服务端**只保存密文、无法解密**账号内容；支持跨设备同步、离线优先、自动锁定。可单机部署，也可容器化后部署到 NAS / 服务器实现多端共享。

[功能特性](#功能特性) · [技术架构](#技术架构) · [快速开始](#快速开始) · [项目结构](#项目结构) · [数据安全](#数据安全) · [部署](#部署) · [常见问题](#常见问题)

> 另提供飞牛 fnOS 应用包（见 [部署 · 方式四：飞牛 fnOS 应用](#方式四飞牛-fnos-应用)），可一键安装到飞牛 NAS 桌面。

---

## 功能特性

- **零知识存储**：账号字段经 AES-256-CBC 加密，密钥由主密码派生且仅存于内存；服务端只保存密文，无主密码则不可解密。
- **跨设备同步**：服务端 SQLite 作为权威真源；系统全局仅一个密码本，所有设备访问同一后端即共享同一套加密账号库，前端双向同步。
- **离线优先**：后端不可达时，若本机已有解锁记录，仍可建分组与账号（先写入浏览器 IndexedDB，恢复连接后自动同步）；**首次创建密码本需连接后端**。
- **会话安全**：刷新不闪解锁页、记住登录（1 天免输）、空闲自动锁定，本地解锁用 BCrypt 校验。
- **极简部署**：后端基于 Node 内置 `node:sqlite`（零 npm 原生编译），生产环境同时托管前端静态与 `/api`，单进程即可运行，亦支持 Docker。

## 技术架构

| 层 | 选型 |
| --- | --- |
| 前端 | Vue 3（`<script setup>`）+ Vite + Pinia + Vue Router + LESS |
| 加密 | crypto-js（AES-256-CBC / MD5）+ bcryptjs（BCrypt / PBKDF2 派生鉴权串） |
| 后端 | Node + Express |
| 存储 | SQLite（Node 内置 `node:sqlite`），单一密码本（固定 `vault` 标识），WAL 模式 |

### 数据存储架构

账号数据采用**零知识双层存储**，服务端 SQLite 与浏览器 IndexedDB 均为加密密文，但角色不同：

| 位置 | 路径 / 标识 | 存储内容 | 作用 |
| --- | --- | --- | --- |
| **SQLite（权威真源）** | `server/data/password.db` | 全部加密文档（`group/*`、`account/*` 密文）+ 密码本锁 `bcryptpass`（登录鉴权哈希 `deriveAuthHash`） | 跨设备同步的源、全局唯一密码本 |
| **IndexedDB（本地缓存 + 本地锁）** | 浏览器 `password-web` 库（store `docs`） | 同样的加密文档缓存 + 本地 `bcryptpass`（本地主密码 bcrypt，用于解锁解密）；`localStorage` 存 `LOGIN_INFO`、`theme-mode` | 离线可用、刷新不丢、本地解锁 |

- 两者通过前端 `vault.syncAll` 双向同步：服务端空 + 浏览器有 → 推上去；浏览器空 + 服务端有 → 拉下来。
- 服务端 `bcryptpass` 存鉴权串，浏览器 `bcryptpass` 存本地解锁哈希，**同名但含义不同**；同步已做隔离，互不污染。

### SQLite 文件位置

`server/data/password.db`，由 `server/src/store.js` 在**服务端启动时自动创建**（自动建 `data/` 目录并开启 WAL，运行时还会产生 `password.db-wal`、`password.db-shm`）。**无需手动建库**，开源也不会提交该文件。

## 快速开始

无需手动初始化数据库，clone 后直接启动即可：

```bash
# 1. 安装前后端依赖
npm install --prefix server
npm install --prefix web

# 2. 构建前端静态文件（必须先于启动后端）
npm run build --prefix web

# 3. 启动后端（监听 3000，同时托管 web/dist 与 /api）
npm run start --prefix server
```

打开浏览器访问 `http://localhost:3000`：
0. 新设备打开时，前端先请求 `GET /api/has-vault` 探测后端是否已存在密码本，自动显示「解锁」或「设置」；
1. 首次（后端无密码本）时 `login` 接口返回 `firstTime: true`；
2. 前端显示「**设置主密码**」页面；
3. 设置主密码后自动创建默认分组并推送服务端，初始化完成。

> **没有数据库文件 = 正常首次使用**：clone 后直接 `npm install && npm run build && npm run start` 即可，无需任何初始化脚本。

### 开发模式（热重载）

```bash
# 终端 1：后端（node --watch 自动重启）
npm run dev --prefix server          # http://localhost:3000

# 终端 2：前端（Vite 开发服务器）
npm run dev --prefix web             # http://localhost:5173
```

前端 Vite 已配置开发代理（`vite.config.js`）：`/api` 代理到 `http://localhost:3000`，避免跨域。

## 项目结构

```
password/
├─ server/        # Node + Express 后端（同步 API，SQLite 存储密文）
│  ├─ src/        # index.js 入口 / store.js 存储层 / auth.js 鉴权 / routes/
│  └─ package.json
├─ web/           # Vue 3 + Vite 前端（构建产物 dist/）
├─ tests/         # 测试（本地验证用，不入库）
└─ README.md      # 本文
```

## 数据安全

1. 主密码经 **BCrypt** 哈希用于本地解锁；服务端鉴权采用固定盐的确定性 `deriveAuthHash`（PBKDF2），仅做等值比对。
2. 账号字段经 **AES-256-CBC** 加密，密钥由主密码派生，仅存在于内存，从不落盘。
3. 无主密码则无法推出密钥，所有密文不可解密（零知识）。

## 部署

### 方式一：本地单机（最简，推荐起步）

适合内网、单机、自托管。一个进程同时提供页面与接口：

```bash
npm install --prefix server
npm install --prefix web
npm run build --prefix web      # 必须先构建前端
npm run start --prefix server   # 访问 http://localhost:3000
```

- 后端在 `server/src/index.js` 检测 `web/dist` 是否存在，存在则托管并对非 `/api` 路由回退到 `index.html`（SPA）。
- 健康检查：`GET /api/health`（无需鉴权）。
- 配置项：监听端口 `PORT`（默认 `3000`）；数据存储 `server/data/password.db`（自动创建）。

### 方式二：Docker 部署（推荐服务器 / NAS）

已发布预构建多架构镜像 `ximengs/password`（amd64 + arm64，自动适配本机 CPU），**无需本地代码与构建**，直接拉取运行即可。

#### Compose 部署（推荐）

新建 `docker-compose.yml`：

```yaml
services:
  password:
    image: ximengs/password:latest
    container_name: password
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      # 持久化 SQLite 数据（password.db / -wal / -shm）
      - password-data:/app/server/data

volumes:
  password-data:
```

启动：

```bash
docker compose up -d
docker compose logs -f
```

#### 纯命令运行

```bash
docker pull ximengs/password:latest
docker run -d --name password --restart unless-stopped \
  -p 3000:3000 -v password-data:/app/server/data \
  ximengs/password:latest
```

- 访问 `http://<宿主机IP>:3000`；数据持久化到命名卷 `password-data`（容器内 `/app/server/data`）。
- 自定义端口：修改 `ports`（如 `"8080:3000"`）。
- 容器内以非 root 用户 `node`（uid 1000）运行，命名卷权限已就绪；若改用宿主机目录绑定挂载，需 `chown -R 1000:1000 ./data`。
- 升级：`docker compose pull && docker compose up -d`（数据卷保持不变，原有密文仍在）。
- **数据与隔离**：镜像本身不含任何用户数据（数据库由挂载卷 `password-data` 提供），每位使用者部署后持有自己的主密码与数据库，彼此隔离、互不可见。本应用为「单一密码本」模型，**一个运行实例仅对应一个密码本**——请让每位使用者独立部署实例，勿在同一实例上多人共用（否则所有人共享同一套账号）。
### 方式四：飞牛 fnOS 应用

面向飞牛私有云（fnOS）用户，提供官方应用包（`fnnas/` 目录），可打包为 `.fpk` 一键安装到飞牛桌面，底层仍运行 `ximengs/password` 容器镜像，数据持久化到应用数据目录。

#### 目录结构

```
fnnas/
├─ manifest                    # 应用元数据（display_name、service_port 等）
├─ app/docker/docker-compose.yaml   # 引用 ximengs/password 镜像 + 端口 + 数据卷
├─ app/ui/config               # 桌面入口（iframe 打开容器 3000 端口页面）
├─ app/ui/images/              # 桌面图标（icon_64.png / icon_256.png）
├─ cmd/                        # 生命周期脚本（install_init / main / upgrade_* 等，空占位 + 状态检查）
├─ config/{privilege,resource} # 权限声明 + Docker 资源声明
├─ wizard/.gitkeep             # fnpack 打包占位目录
├─ ICON.PNG / ICON_256.PNG / ICON_512.PNG  # 应用商店列表图标
└─ README.md                   # 应用包说明
```

#### 图标规范

| 用途 | 文件 | 要求 |
| --- | --- | --- |
| 应用商店列表图标 | `ICON.PNG` / `ICON_256.PNG` / `ICON_512.PNG`（根目录） | PNG，建议透明背景，像素尺寸与文件名一致 |
| 桌面入口图标 | `app/ui/images/icon_64.png` / `icon_256.png` | 飞牛按桌面实际像素请求 `icon_{0}.png`，按需补齐对应尺寸 |

> 替换图标后**无需改动代码**，重新打包即可生效（图标是应用包素材，与容器镜像无关）。

#### 打包（需本机安装 `fnpack`）

`fnpack` 为飞牛官方打包工具（v1.2.3+），从飞牛应用开放平台下载对应平台二进制，清除 macOS 隔离标记后置于 `PATH`：

```bash
xattr -d com.apple.quarantine /usr/local/bin/fnpack   # macOS 去除 Gatekeeper 拦截
fnpack --help
```

进入应用包目录重新打包（图标有变动时同样执行此步）：

```bash
cd fnnas
fnpack build          # 校验文件齐全后生成 password.fpk（覆盖旧包）
```

#### 安装 / 更新到飞牛

- 飞牛设备：应用中心 → 我的应用 → 上传 / 更新 `password.fpk`，或卸载后重新安装即可看到新图标。
- 命令行（飞牛设备）：`appcenter-cli install-fpk password.fpk`。

#### 前端 UI 在嵌入场景的适配

飞牛以 iframe 内嵌运行，前端做了两点适配（源码在 `web/`，改动后需重新构建镜像才会在飞牛生效，见 [方式二](#方式二docker-部署推荐服务器--nas)）：

- **主界面铺满**：`App.vue` 检测 iframe（或 `?embed=1`）给 `<html>` 加 `fnos-embed`，`.home` 在嵌入场景下铺满窗口、去除居中卡片外壳。
- **弹窗自适应**：`Dialog.vue` 限制弹窗最大高度（`85dvh`）并让内容区内部滚动（滚动条隐藏），小窗口下表单不被截断、操作按钮始终可见。

### 方式三：公网 / 反向代理（务必启用 HTTPS）

- **必须启用 HTTPS**：鉴权令牌 `authHash` 经请求头 `x-auth-hash` 明文传输，明文 HTTP 下会被窃听冒用。请在反向代理层终止 TLS。
- **前后端需同源**：前端 `API_BASE` 写死为相对路径 `/api`，页面与 `/api` 须同域（由 Nginx/Caddy 同源反代即可，零 CORS 问题）。
- **单一密码本模型**：系统全局仅一个密码本，`user_id` 固定为 `vault`，所有设备访问同一后端即共享同一套数据，不再支持多用户隔离。公网部署请评估风险（加访问控制、反代加 Basic Auth、或仅内网暴露）。

最小 TLS 终止示例（Caddy，`Caddyfile`）：

```caddyfile
pwd.example.com {
  reverse_proxy localhost:3000
}
```

或 Nginx：

```nginx
server {
  listen 443 ssl;
  server_name pwd.example.com;
  ssl_certificate     /path/fullchain.pem;
  ssl_certificate_key /path/privkey.pem;
  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}
```

### 进程保活（非容器）

- **pm2**：`pm2 start server/src/index.js --name password-server && pm2 save && pm2 startup`
- **systemd**：新建 `/etc/systemd/system/password-server.service`，`ExecStart=/usr/bin/node /opt/password/server/src/index.js`，`Environment=PORT=3000`，`Restart=on-failure`。

### 数据备份

服务端数据全部在 `server/data/`（含 `password.db` / `password.db-wal` / `password.db-shm`，需一起备份）：

```bash
cp -r server/data /backup/password-data-$(date +%F)
```

## 常见问题

| 现象 | 可能原因 | 处理 |
| --- | --- | --- |
| 后端启动报 `node:sqlite` 不可用 | Node 版本低于 22.5.0 | 升级 Node 到 22.5.0+（推荐 24 LTS）；启动时的 `ExperimentalWarning` 告警可忽略 |
| 访问站点空白 / 资源 404 | 忘记先 `npm run build` 或后端在构建前已启动 | 重新 `npm run build --prefix web` 并重启后端 |
| 前端一直「离线」 | 后端未启动或 `/api/health` 不可达 | 确认进程、端口、防火墙；反代是否覆盖 `/api` |
| 公网跨域报错 | 前后端不同源，后端未开 CORS | 改为同源部署（同域名反代 `/api`），或后端加 CORS 中间件 |
| 端口被占用 | 已有实例在跑 | `lsof -ti tcp:3000` 查杀，或改 `PORT` 环境变量 |
| 容器无写入权限 | 数据卷所属用户非 node | 使用命名卷（默认），或 bind 挂载目录 `chown -R 1000:1000` |

## 开源说明

- `node:sqlite` 为 Node 内置模块（22.5.0+，零 npm 依赖、零原生编译），无需本地编译环境。
- 本仓库以 **MIT 许可证**开源，详见根目录 `LICENSE`；可自由使用、修改、再分发，仅需保留版权声明。