kdbx-viewer/README.md

kdbx-viewer

一个服务端解密的 KeePass（.kdbx）网页查看器，定位为 KeeWeb 的轻量自托管替代品。

核心思想：密钥文件与明文永不出服务端。浏览器只提交“用服务端公钥加密后的口令”，服务端用内存中的私钥解密、加载数据库、再用会话级 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 等。

---

快速开始（本地）

# 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} 替换）。

# 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 结构：

  {
    "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 + [hash-wasm](https://github.com/G PBrouwer/hash-wasm)（Argon2）

---

开源声明

本项目以 MIT License 开源。

第三方依赖与许可

本项目在合规前提下使用了以下开源组件，版权归各自作者所有，并遵循其许可协议：

组件	用途	许可
Express	Web 框架	MIT
express-session	会话管理	MIT
dotenv	环境变量加载	BSD-2-Clause
kdbxweb	KeePass 数据库解析	MIT
hash-wasm	Argon2（WASM）	MIT
node-forge	本地自签证书生成	BSD-3-Clause
KeePass / KeeWeb	设计参考与兼容格式	参见各自许可

声明

• 本项目为自托管工具，使用者需自行负责部署安全（强口令、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.