kdbx-viewer/README.md 位于 master

wangchuanli/kdbx-viewer

派生 0

文件

T

wangchuanli 038be408d0 docs: 添加一键部署脚本说明与脚本文件

2026-08-26 11:24:42 +08:00

215 行

10 KiB

Markdown

原始文件 永久链接 Blame 文件历史

此文件含有可能会与其他字符混淆的 Unicode 字符。如果您是想特意这样的，可以安全地忽略该警告。使用 Escape 按钮显示他们。

 # 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）
 ### 一键部署脚本
 仓库提供一键部署脚本，自动完成「拉取 git 代码 → 校验/生成 `.env` → 准备挂载目录 → `docker compose` 构建并启动」：
 - **Linux / macOS**：`deploy.sh`
   ```bash
   chmod +x deploy.sh
   ./deploy.sh                 # 默认仓库与 ./kdbx-viewer 目录
   ./deploy.sh /opt/kdbx       # 指定部署目录
   REPO=https://... ./deploy.sh  # 指定 git 仓库地址
   ```
 - **Windows（cmd）**：`deploy.bat`
   ```bat
   deploy.bat                 # 默认仓库与 kdbx-viewer 目录
   deploy.bat D:\kdbx         # 指定部署目录
   set REPO=https://... && deploy.bat   # 指定 git 仓库地址
   ```
 脚本行为：
 . 目录已存在 git 仓库则 `git pull`，否则 `git clone`（仓库地址见脚本顶部 `REPO`，可被环境变量覆盖）。
 . 无 `.env` 时从 `.env.example` 复制，并**中断提示填写敏感项**（`APP_PW_DYNAMIC` / `APP_PW_STATIC` / `SESSION_SECRET`）；若仍为占位值也会拒绝启动。
 . 创建 `vault/`、`logs/`、`ssl/` 挂载目录。
 . 检查 `docker` 与 `docker compose v2` 是否可用。
 . `docker compose up -d --build` 启动，并打印访问地址。
 ### 手动部署
 所有配置通过**同目录的 `.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.
 ```

215 行 10 KiB Markdown 原始文件 永久链接 Blame 文件历史 Unescape Escape

215 行

10 KiB

Markdown

原始文件永久链接 Blame 文件历史