NodeWarden 是一个运行在 Cloudflare Workers 上的轻量级 Bitwarden 兼容服务端。它无需单独购买 VPS，也不用维护 Docker、数据库进程或反向代理，适合希望低成本搭建个人密码库的用户。

项目提供原创 Web Vault，并兼容常见 Bitwarden 官方客户端，支持密码同步、TOTP、Passkey、附件、Send、实时推送和云端备份等功能。

NodeWarden 是第三方开源项目，与 Bitwarden 官方无关，仅建议用于学习和交流。密码库属于重要数据，请使用高强度主密码、开启两步验证，并定期制作可验证的加密备份。

项目地址

• GitHub：shuaiplus/NodeWarden
• 官方文档：NodeWarden Wiki
• Telegram：频道 / 群组

功能介绍

NodeWarden 已实现日常个人密码库所需的大部分功能：

• 原创 Web Vault，支持 PWA 安装与离线使用
• 兼容 Bitwarden Windows、Linux、移动端及浏览器扩展
• 密码登录、Passkey 登录和 API Key 登录
• TOTP、YubiKey、Passkey 两步验证及恢复码
• 多设备管理、可信设备和实时推送同步
• 密码、文件夹、附件及 Bitwarden Send
• Bitwarden JSON、CSV、ZIP 导入与导出
• WebDAV、S3 兼容存储的定时增量备份
• 邀请码注册和多用户使用
• 自定义等效域名和全局域名规则

目前尚未实现组织、集合、成员权限、SSO、SCIM 和企业目录等企业功能。

已测试客户端

部署前的准备

开始之前需要准备：

1. 一个 GitHub 账号；
2. 一个 Cloudflare 账号；
3. 一个不少于 32 个字符的随机 JWT_SECRET；
4. 根据附件需求选择 R2 或 KV 存储。

NodeWarden 使用以下 Cloudflare 服务：

• Workers：运行服务端接口并提供网页；
• D1：保存用户、密码库密文、附件元数据及配置；
• R2 或 KV：保存附件和 Send 文件；
• Durable Objects：提供实时通知；
• Cron Triggers：执行定时备份任务。

R2 和 KV 应该怎么选

如果 Cloudflare 账号可以绑定支付方式，优先选择 R2。KV 部署更简单，但文件大小和容量限制更明显。

通过 Cloudflare 控制台部署

1. Fork 项目

打开 NodeWarden GitHub 仓库，点击右上角的 Fork，将项目复制到自己的 GitHub 账号。

2. 创建 Workers 项目

进入 Cloudflare Workers & Pages，选择通过 GitHub 导入项目，然后选择刚刚 Fork 的 NodeWarden 仓库。

3. 填写构建命令

使用 R2 存储时填写：

1
2
3
4
5

# 构建命令
npm run build

# 部署命令
npm run deploy

如果使用 KV 存储，将部署命令改为：

1

npm run deploy:kv

项目中的 wrangler.toml 或 wrangler.kv.toml 会定义所需的资源绑定。Worker 第一次收到请求时会自动初始化 D1 数据库，不需要手动上传 SQL 文件。

4. 配置 JWT_SECRET

部署完成后，进入 Worker 的“设置 → 变量和机密”，新增一个加密 Secret：

1
2

变量名：JWT_SECRET
变量值：不少于 32 个字符的高强度随机字符串

请勿使用项目示例值，也不要将真实密钥写入 GitHub 仓库、wrangler.toml、日志或截图中。

JWT_SECRET 用于登录令牌、附件和 Send 短期令牌，以及备份配置加密。正式使用后不要随意更换，否则现有登录状态和部分备份设置会失效。

5. 访问并注册管理员

打开 Cloudflare 生成的 Workers 地址。第一次注册的用户会成为管理员，后续用户通常需要邀请码才能注册。

部分网络环境可能无法正常访问默认的 workers.dev 域名，建议在 Worker 设置中绑定自己的域名。

使用命令行部署

如果希望在本地完成部署，可以依次执行：

1
2
3
4
5
6
7
8
9
10
11

git clone https://github.com/shuaiplus/NodeWarden.git
cd NodeWarden

npm install
npx wrangler login

# 默认使用 R2
npm run deploy

# 或者使用 KV
npm run deploy:kv

部署完成后添加 Secret：

1

npx wrangler secret put JWT_SECRET

本地开发命令如下：

1
2
3
4
5

# R2 模式
npm run dev

# KV 模式
npm run dev:kv

隐藏网页密码库

如果只使用 Bitwarden 官方客户端，不希望公开 Web Vault，可以在 Worker 的“设置 → 变量和机密”中添加普通文本变量：

1
2

变量名：HIDE_WEB_VAULT
变量值：1

启用后，服务器上的前端页面和静态资源会返回 404 Not Found，但登录、同步、附件、图标和通知等客户端接口仍然可用。删除该变量或把值改为非 1 即可恢复 Web Vault。

已经安装或被浏览器缓存的 PWA 仍可能继续使用本地前端，因此该设置不能代替设备端的退出登录和缓存清理。

连接 Bitwarden 客户端

在 Bitwarden 官方客户端登录页面选择“自托管”或“自定义服务器”，将服务器 URL 设置为 NodeWarden 的完整域名，例如：

1

https://vault.example.com

服务器地址末尾不要添加 /api。保存设置后，使用在 NodeWarden 中注册的邮箱和主密码登录即可。

更新项目

打开自己 Fork 的 GitHub 仓库，如果页面提示上游存在新提交，依次点击：

1

Sync fork → Update branch

同步完成后，Cloudflare 会自动重新构建和部署。更新前建议先创建备份，并确认原有 JWT_SECRET、D1、R2/KV 和 Durable Objects 绑定没有被删除。

安全建议

密码库服务一旦失守，影响往往远大于普通网站。部署后建议完成以下设置：

• Cloudflare 和 GitHub 账号均开启 Passkey 或硬件密钥两步验证；
• 主密码使用从未在其他网站使用过的长随机密码；
• NodeWarden 账号开启两步验证，并离线保存恢复码；
• 使用自定义域名并始终通过 HTTPS 访问；
• 不要直接启用来源不明的 Fork 或未经检查的自动更新；
• 定期导出加密备份，并将备份保存到另一家存储服务；
• 定期实际测试备份能否成功恢复；
• 不要把主密码、恢复码和 Cloudflare 恢复信息全部只保存在同一个密码库中。

常见问题

页面提示缺少 JWT_SECRET

进入 Worker 的变量设置，确认添加的是加密 Secret，名称必须准确写成 JWT_SECRET，值不少于 32 个字符。配置后重新部署或刷新页面。

默认 Workers 地址无法访问

部分网络环境无法稳定访问 workers.dev。可以在 Cloudflare Worker 中绑定自己的域名，并确认 DNS 和 HTTPS 证书已经生效。

上传附件失败

首先确认已经正确绑定 R2 或 KV。使用 KV 时，单个对象不能超过 25 MiB；如果经常保存附件，建议改用 R2。

Bitwarden 客户端无法登录

检查客户端填写的服务器地址是否包含多余的 /api，并确认 /identity/accounts/prelogin 可以正常访问。还需要检查 JWT_SECRET、D1 和 Durable Objects 是否绑定成功。

总结

NodeWarden 利用 Cloudflare Workers、D1 和 R2/KV，将传统密码管理服务端改造成了几乎免运维的 Serverless 应用。它部署简单、成本较低，也能够连接常见 Bitwarden 客户端。

不过，NodeWarden 是非官方第三方实现，不能因为使用了 Cloudflare 就忽略应用自身的安全风险。正式保存重要数据前，应当了解项目边界，配置强认证和异地加密备份，并谨慎处理每一次更新。

开源协议与致谢

NodeWarden 使用 LGPL-3.0 协议开源，其设计和实现参考或使用了以下项目及平台：

• Bitwarden：原始设计与官方客户端；
• Vaultwarden：服务端实现参考；
• Cloudflare Workers：Serverless 运行平台。