feat: 初始化 kdbx-viewer 项目
实现服务端解密的 KeePass 网页查看器，包含登录门户口令与验证码、RSA+会话级 AES 加密通道、审计日志持久化、HTTPS 自动证书、Docker 部署配置及端到端测试。
这个提交包含在：
@@ -0,0 +1,187 @@
|
||||
# kdbx-viewer
|
||||
|
||||
一个**服务端解密**的 KeePass（`.kdbx`）网页查看器，定位为 [KeeWeb](https://keeweb.info/) 的轻量自托管替代品。
|
||||
|
||||
核心思想：**密钥文件与明文永不出服务端**。浏览器只提交“用服务端公钥加密后的口令”，服务端用内存中的私钥解密、加载数据库、再用**会话级 AES** 把响应体加密后回传，前端解密渲染。明文仅在服务端进程内存中存在，落盘只有密文。
|
||||
|
||||
---
|
||||
|
||||
## 特性
|
||||
|
||||
- **服务端解密**：kdbx 主密码 / keyfile 在服务端内存中校验，前端不接触明文主密码、不接触 keyfile。
|
||||
- **通道加密**：登录协商会话级 AES-256-GCM 密钥，所有 API 响应体均加密传输；传输用 RSA-OAEP(SHA256) 保护登录/解锁口令。
|
||||
- **动态密钥**：每次登录重新协商 AES 密钥，默认 1 小时过期后需重新解锁。
|
||||
- **HTTPS 强制**：检测到证书即自动启用 HTTPS 并把 HTTP 301 重定向到 HTTPS；**未配置证书时，系统会自动生成一份自签证书并默认启用 HTTPS**（便于容器/一键部署即安全）。生产环境请替换为受信任 CA 签发的证书。
|
||||
- **门户口令 + 验证码**：登录需通过门户口令（支持 `日期+固定串` 动态口令或固定口令）与图形验证码，防爆破。
|
||||
- **IP 封锁**：单 IP 5 次失败或触发风险行为后封锁 30 分钟。
|
||||
- **审计日志**：
|
||||
- 记录完整来源信息：真实客户端 IP、内网/外网类型、直连地址（remote）、完整 `X-Forwarded-For` 链、UA、Referer、方法、路径、状态码、业务错误码等。
|
||||
- 本地文件持久化（JSON Lines），按大小自动切分（`audit.log` → `audit.1.log` …），并维护 **索引文件** `audit.index.json` 记录各文件起始/结束序号、条数、总条数。
|
||||
- 登录后可访问独立审计页 `/audit.html`，支持分页、筛选（IP / IP 类型 / 错误码 / 方法 / 路径 / 仅失败 / 时间区间）。
|
||||
- **后端搜索**：条目搜索在服务端完成，仅回传加密后的命中结果。
|
||||
- **只读 / 可编辑**：默认只读（数据库绝不被改动）；可配置 `WRITABLE=true` 开放网页端编辑并写回。
|
||||
- **安全响应头**：CSP、X-Frame-Options、X-Content-Type-Options、Referrer-Policy 等。
|
||||
|
||||
---
|
||||
|
||||
## 快速开始（本地）
|
||||
|
||||
```bash
|
||||
# 1. 安装依赖
|
||||
npm install
|
||||
|
||||
# 2. 准备环境变量（复制示例并修改）
|
||||
cp .env.example .env
|
||||
# 编辑 .env：设置 APP_PW_DYNAMIC / APP_PW_STATIC、SESSION_SECRET 等
|
||||
|
||||
# 3.（可选）生成本地自签证书用于 HTTPS
|
||||
node gen-cert.js # 生成 ssl/key.pem、ssl/cert.pem
|
||||
|
||||
# 4. 放入你的密码库
|
||||
mkdir -p vault
|
||||
cp your.kdbx vault/vault.kdbx
|
||||
# 若使用 keyfile：cp your.key vault/vault.key
|
||||
|
||||
# 5. 启动
|
||||
npm start
|
||||
```
|
||||
|
||||
访问 `https://localhost:3000`（无证书时为 `http://localhost:3000`）。
|
||||
|
||||
> 测试：`npm test`（解密验证）、`npm run test:e2e`（端到端流程 + 审计校验）。
|
||||
|
||||
---
|
||||
|
||||
## 部署（Docker）
|
||||
|
||||
所有配置通过**同目录的 `.env` 文件注入**，无需在 `docker-compose.yml` 中写死（`compose` 会自动读取 `.env` 并用 `${VAR}` 替换）。
|
||||
|
||||
```bash
|
||||
# 1. 准备 .env（复制示例并修改敏感项）
|
||||
cp .env.example .env
|
||||
# 编辑 .env：设置 APP_PW_DYNAMIC / APP_PW_STATIC、SESSION_SECRET 等
|
||||
|
||||
# 2. 构建并启动
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
默认仅绑定 `127.0.0.1:8080`，建议前置 Nginx / Caddy 做 HTTPS 反代。
|
||||
|
||||
关键挂载与配置：
|
||||
|
||||
| 挂载 | 说明 |
|
||||
| --- | --- |
|
||||
| `./vault:/app/vault:ro` | 密码库目录，**只读**；开启 `WRITABLE=true` 须改 `:rw` |
|
||||
| `./logs:/app/logs` | 审计日志与索引持久化 |
|
||||
| `./ssl:/app/ssl:rw` | 证书目录；**未提供证书时容器会自动生成自签证书到此目录并持久化**，避免重建后证书变化 |
|
||||
|
||||
> 证书说明：若 `SSL_KEY`/`SSL_CERT` 指向的文件不存在，服务会自动生成自签证书并启用 HTTPS；生产环境请将受信任证书挂载到该路径覆盖默认值。
|
||||
|
||||
---
|
||||
|
||||
## 配置项
|
||||
|
||||
所有配置优先读取**同名环境变量**（便于 Docker / 密管注入），未设置时回退 `config.js` 默认值。
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `APP_PW_MODE` | `dynamic` | 门户口令模式：`dynamic`（日期+固定串）或 `static`（固定口令） |
|
||||
| `APP_PW_DATE_FMT` | `yyyymmdd` | 动态口令日期格式 |
|
||||
| `APP_PW_DATE_POS` | `prefix` | 日期位置：`prefix` 或 `suffix` |
|
||||
| `APP_PW_DYNAMIC` | 空 | 动态口令的固定串部分（**敏感，用环境变量注入**） |
|
||||
| `APP_PW_STATIC` | 空 | 静态模式下的固定口令（**敏感**） |
|
||||
| `KDBX_PATH` | `/app/vault/vault.kdbx` | 密码库路径 |
|
||||
| `KEYFILE_PATH` | `/app/vault/vault.key` | keyfile 路径（可选） |
|
||||
| `WRITABLE` | `false` | 是否开放网页端编辑写回 |
|
||||
| `SESSION_SECRET` | 空（随机） | 会话签名密钥（**敏感，生产必填**） |
|
||||
| `SESSION_MAX_AGE` | `1800000` | 会话有效期（毫秒，默认 30 分钟） |
|
||||
| `LOG_DIR` | `./logs` | 审计日志目录（含 `audit.index.json`） |
|
||||
| `AUDIT_FILE_MAX` | `5M` | 单日志文件切分阈值，支持 `K/M/G` 单位 |
|
||||
| `AUDIT_FILE_KEEP` | `10` | 切分文件最大保留份数 |
|
||||
| `SSL_KEY` | `ssl/key.pem` | HTTPS 私钥路径 |
|
||||
| `SSL_CERT` | `ssl/cert.pem` | HTTPS 证书路径 |
|
||||
| `PORT` | `3000` | 监听端口 |
|
||||
|
||||
---
|
||||
|
||||
## 审计日志
|
||||
|
||||
- **位置**：`LOG_DIR` 下，`audit.log`（当前）与切分文件 `audit.1.log … audit.N.log`，以及索引 `audit.index.json`。
|
||||
- **索引文件** `audit.index.json` 结构：
|
||||
```json
|
||||
{
|
||||
"total": 1234,
|
||||
"nextSeq": 1235,
|
||||
"files": [
|
||||
{ "file": "audit.log", "startSeq": 1, "endSeq": 1234, "count": 1234, "bytes": 123456, "firstTime": "...", "lastTime": "..." }
|
||||
]
|
||||
}
|
||||
```
|
||||
- **分页**：前端先拉取索引计算分布，再按文件精确提取，保证页面条数与磁盘一致。
|
||||
- **记录字段**：`seq, t, ip, ipType(internal/external), remote, xff, ua, referer, method, path, status, code, ok, sid, detail`。
|
||||
|
||||
相关接口（均需登录）：`GET /api/audit`、`GET /api/audit/index`、`GET /api/audit/file`、`GET /api/audit/blocks`、`POST /api/audit/unblock`。
|
||||
|
||||
---
|
||||
|
||||
## 技术栈
|
||||
|
||||
- 运行时：Node.js（>=18，Docker 镜像基于 `node:20-alpine`）
|
||||
- Web 框架：Express + express-session
|
||||
- 密码学：Node `crypto`（AES-256-GCM、RSA-OAEP-SHA256）；前端 Web Crypto API
|
||||
- KeePass 解析：[`kdbxweb`](https://github.com/keeweb/kdbxweb) + [`hash-wasm`](https://github.com/G PBrouwer/hash-wasm)（Argon2）
|
||||
|
||||
---
|
||||
|
||||
## 开源声明
|
||||
|
||||
本项目以 **MIT License** 开源。
|
||||
|
||||
### 第三方依赖与许可
|
||||
|
||||
本项目在合规前提下使用了以下开源组件，版权归各自作者所有，并遵循其许可协议：
|
||||
|
||||
| 组件 | 用途 | 许可 |
|
||||
| --- | --- | --- |
|
||||
| [Express](https://github.com/expressjs/express) | Web 框架 | MIT |
|
||||
| [express-session](https://github.com/expressjs/session) | 会话管理 | MIT |
|
||||
| [dotenv](https://github.com/motdotla/dotenv) | 环境变量加载 | BSD-2-Clause |
|
||||
| [kdbxweb](https://github.com/keeweb/kdbxweb) | KeePass 数据库解析 | MIT |
|
||||
| [hash-wasm](https://github.com/GPBrouwer/hash-wasm) | Argon2（WASM） | MIT |
|
||||
| [node-forge](https://github.com/digitalbazaar/forge) | 本地自签证书生成 | BSD-3-Clause |
|
||||
| [KeePass](https://keepass.info/) / [KeeWeb](https://keeweb.info/) | 设计参考与兼容格式 | 参见各自许可 |
|
||||
|
||||
### 声明
|
||||
|
||||
- 本项目为**自托管工具**，使用者需自行负责部署安全（强口令、HTTPS、密钥管理、最小权限）。
|
||||
- 本项目与 KeePass / KeeWeb 官方**无隶属关系**，仅实现其文件格式的兼容解析。
|
||||
- 使用本软件所产生的一切风险与后果由使用者自行承担；作者不对任何数据丢失、泄露或滥用负责。
|
||||
- 若您在使用过程中发现安全漏洞，欢迎通过私有渠道反馈，请勿公开披露。
|
||||
|
||||
---
|
||||
|
||||
## 许可证
|
||||
|
||||
```
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 kdbx-viewer contributors
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
```
|
||||
在新工单中引用
屏蔽一个用户