NodeWarden

项目定位#

一个轻量的 Bitwarden 兼容服务端，支持密码管理、密码同步、密码加密等功能。

1.1 项目背景#

密码管理器里，Bitwarden 是为数不多客户端和服务端都开源的产品，但官方服务端部署起来相当重：依赖 Docker、要跑数据库、吃内存，还得有一台 24 小时开机的服务器。

于是社区出现了 Vaultwarden（Rust 重写的第三方兼容服务端），资源占用大幅降低，但它依然需要一台 VPS：你要自己装 Docker、配 HTTPS 证书、盯着更新、记得备份。

NodeWarden 走了第三条路——把整个 Bitwarden 兼容服务端直接跑在 Cloudflare Workers 上。不用买服务器，不用管 SSL，不用做进程守护，Cloudflare 免费额度就够用。项目 2026 年 2 月开源，使用 LGPL-3.0 协议，技术栈为 TypeScript + Preact。

1.2 技术架构#

NodeWarden 完全构建在 Cloudflare 的免费基础设施之上：

最重要的一点：它延续了 Bitwarden 的零知识（Zero-Knowledge）架构，加解密全部在你的客户端本地完成，服务端（以及 Cloudflare）拿到的只是密文。即使服务端数据泄露，攻击者没有你的主密码也无法解密。

1.3 核心功能#

根据官方 README，目前支持的能力包括：

• ✅ 原版 Web Vault 界面，并支持 PWA 安装、离线使用
• ✅ 官方 Bitwarden 客户端全兼容：Windows / Linux 桌面端、手机 App、浏览器扩展（macOS 桌面端尚未完全验证）
• ✅ 密码同步、自动填充、实时推送同步（多设备）
• ✅ TOTP 两步验证，甚至支持 steam:// 格式的 Steam 令牌
• ✅ Passkey 无密码登录、YubiKey、2FA 恢复码
• ✅ 附件与 Bitwarden Send（R2 模式单文件最大 100 MB，KV 模式 25 MiB）
• ✅ 导入 / 导出（Bitwarden JSON、CSV、ZIP）
• ✅ 云端备份中心：定时 WebDAV / S3 增量备份（官方免费版都没有的功能）
• ✅ 设备管理、跨设备登录请求审批
• ✅ API Key、域名规则（等效域名、全局排除）、fill-assist
• ✅ 多用户：通过邀请码注册
• ❌ 不支持组织 / 集合 / 成员角色、SSO / SCIM / 企业目录

1.4 主要特点#

1. 真正零成本：Workers、D1、KV/R2 都在 Cloudflare 免费额度内，个人使用完全够。
2. 免运维：没有服务器要维护，HTTPS 证书由 Cloudflare 自动处理，全球边缘节点加速。
3. 部署门槛低：点点鼠标（Workers Builds）或一行 npm run deploy 都能完成，D1 数据表在首次访问时自动初始化，不需要手动导入 SQL。
4. 升级省心：Fork 仓库后在 GitHub 点一下 Sync fork 即可；也可以开启仓库自带的 Actions，每天自动同步上游。
5. 数据自持：所有数据都在你自己的 Cloudflare 账号里。

1.5 适用 / 不适用场景#

适合：

• 想自托管密码库、但不想买 VPS / 折腾 Docker 的个人用户
• 已经在用 Cloudflare、希望一切服务都收敛到一个面板里的人
• 需要手机、电脑、浏览器扩展多端同步，并且看重 TOTP、附件、Send 的用户
• 预算为零的学生党、白嫖党

不适合：

• 团队共享密码库（需要组织 / 集合 / 权限角色）——这类需求请用官方 Bitwarden 组织版或 Vaultwarden
• 网络环境无法稳定访问 Cloudflare / workers.dev 域名，且没有可接入 Cloudflare 的自定义域名的用户
• 对 macOS 桌面端有强依赖的用户（目前尚未完全验证，可用浏览器扩展替代）

1.6 与同类方案对比#

一句话总结：个人用选 NodeWarden，团队用选 Vaultwarden / 官方版。

2.1 必备账号#

2.2 先选好存储模式：R2 还是 KV？#

部署前唯一需要做的决策，是附件存储用 R2 还是 KV：

选择建议：

• 只是存密码、偶尔传小附件 → KV 模式足矣，免去绑卡；
• 需要传大附件、截图、证件扫描件 → 选 R2 模式。

💡 密码库本身的文本数据存在 D1，与附件存储互不影响，以后想换模式重新部署即可。

2.3 本地 CLI 部署才需要的环境（方式一可跳过本节）#

如果你选择面板部署，可以直接跳到第三章。CLI 部署需要本机准备：

验证安装：

1
node -v
2
# 期望输出 v20.x.x（或 >= v18.12）
3

4
npm -v
5
git --version

Windows 用户推荐用 PowerShell 或 Windows Terminal；macOS / Linux 直接用终端即可。

第 1 步：Fork 仓库#

1. 浏览器打开项目主页：https://github.com/shuaiplus/NodeWarden
2. 点击页面右上角的 Fork 按钮；
3. 跳转到创建页面后，仓库名保持默认 NodeWarden 即可，Copy the main branch only 保持默认勾选，直接点击 Create fork；
4. 稍等几秒，你会得到一个属于自己的仓库，地址形如 https://github.com/你的用户名/NodeWarden。

🔑 为什么必须先 Fork？因为 Cloudflare 要连接你自己的仓库来构建；以后更新也全靠这个 Fork（见第七章）。

第 2 步：在 Cloudflare 创建 Worker 并连接 GitHub#

1. 打开 Cloudflare 创建入口：Workers & Pages → Create
2. 在创建页面找到 Import a repository（导入仓库）/ Connect to Git 一类入口，点击 Continue with GitHub；
3. 第一次连接时按提示授权 Cloudflare 访问你的 GitHub，可以只勾选 NodeWarden 这一个仓库；
4. 回到选择列表，选中你刚刚 Fork 的 NodeWarden 仓库，点击 Begin setup / 开始设置。

第 3 步：填写构建配置#

在构建配置页面，按下表填写：

填好后点击 Deploy（部署）。

第 4 步：等待首次构建完成#

1. 保存后会自动跳转到部署日志页，滚动能看到 npm install → build → deploy 的过程；
2. 第一次大约需要 1～3 分钟，看到 Deployment complete / 绿色对勾即为成功；
3. 部署过程中会自动创建所需的资源绑定（D1 数据库、R2 存储桶或 KV 命名空间），名字由仓库根目录的 wrangler.toml（R2 模式）或 wrangler.kv.toml（KV 模式）定义，无需手动新建。

⚠️ R2 模式下，如果账号从未开通 R2，日志可能提示你先启用 R2（需要绑定信用卡验证）。按日志里的链接到面板开通后，重新部署一次即可。完全不想绑卡就改用 KV 模式：把部署命令换成 npm run deploy:kv 后重新触发部署。

第 5 步：设置 JWT_SECRET（必做，最重要的一步）#

1. 部署完成后，打开 Worker 的访问地址（如 https://dash.cloudflare.com/a9d21f407514e204238da710be47c992/workers/services/view/nodewarden/production/settings）；
2. 页面会提示 缺少 JWT_SECRET——这是服务端签发登录令牌用的密钥，必须配置一个强随机值，且不要使用任何示例值；
3. 生成一个至少 32 位的随机字符串，任选一种方式或者使用NodeWarden页面生成的随机串：

macOS / Linux 终端：

1
openssl rand -base64 24

Windows PowerShell（本机装了 Node.js 时最省事，跨平台通用）：

1
node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"

4. 回到 Cloudflare 面板：进入 Workers & Pages → 你的 nodewarden 服务 → Settings（设置）→ Variables and Secrets（变量和机密）；
5. 点击 添加变量，密钥：JWT_SECRET，值值粘贴刚才生成的随机串，然后点击小三角保存，而不是部署，接着点击编辑类型选择 Secret（密钥），部署即可；
6. 保存后 Worker 会自动重新部署，等待几十秒后刷新你的站点页面。

🔒 JWT_SECRET 一定要用 Secret 类型而不是普通文本变量；一旦设置不要随意更换，否则所有已登录设备需要重新登录。请把它和主密码一样妥善保管。

第 6 步：按需添加可选变量#

同在 Variables and Secrets 页面，还可以配置：

不需要就全部留空。删除变量或把 HIDE_WEB_VAULT 改成非 1 的值即可恢复网页版。

第 7 步：跟随初始化向导创建账号#

再次打开站点，NodeWarden 自带一个初始化向导（Setup），按提示一路 Next：

1. JWT_SECRET 检查：通过则继续；
2. 同步策略（可选）：讲解如何 Fork 同步更新，可先跳过；
3. 创建账号：填写邮箱、主密码、姓名，注册你的第一个（也是管理员）账号；
4. 登录 TOTP（可选）：向导会生成一个 Base32 种子和二维码，需要的话先去设置 TOTP_SECRET，再用验证器扫码；
5. 完成：页面显示你的服务器 URL，后续所有 Bitwarden 客户端都填这个地址。

👤 主密码是整个密码库的唯一加密密钥，零知识架构下遗忘无法找回。建议同时把主密码离线记录在安全的地方。

第 1 步：拉取源码并安装依赖#

1
git clone https://github.com/shuaiplus/NodeWarden.git
2
cd NodeWarden
3
npm install

第 2 步：登录 Cloudflare#

1
npx wrangler login

执行后会自动打开浏览器，登录你的 Cloudflare 账号并点击 Allow 授权。回到终端看到 Successfully logged in 即成功。

第 3 步：部署#

1
# 默认：R2 模式（单附件最大 100 MB，免费 10 GB，账号需绑卡验证 R2）
2
npm run deploy
3

4
# 或者：KV 模式（免信用卡，单文件 25 MiB，免费 1 GB）
5
npm run deploy:kv

部署脚本会自动完成 Worker 发布以及 D1、R2/KV 绑定的创建，日志末尾会输出 Worker 的访问 URL。

第 4 步：设置 JWT_SECRET#

1
# 生成随机密钥
2
node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"
3

4
# 写入 Secret（执行后粘贴上一步生成的值，回车确认）
5
npx wrangler secret put JWT_SECRET

可选的登录 TOTP 种子同理：

1
npx wrangler secret put TOTP_SECRET

第 5 步：本地开发调试（可选）#

1
npm run dev       # R2 模式本地开发
2
npm run dev:kv    # KV 模式本地开发

本地调试完成后，再执行 npm run deploy 发布即可。

4.1 关于权限与配置文件#

• 绑定名称统一写在仓库根目录的 wrangler.toml（R2）/ wrangler.kv.toml（KV）中，不要随意改动资源名，否则代码里的绑定会找不到；
• D1 数据表在第一次请求站点时自动迁移创建，无需手动上传 SQL；
• CLI 部署默认使用你 wrangler 当前登录的账号（npx wrangler whoami 可查看），注意别部署错账号。

5.1 通用原则：把服务器地址改成你自己的#

所有客户端的登录/注册页，都要找到自托管（Self-hosted）服务器设置入口，填入：

1
https://nodewarden.你的子域.workers.dev

注意：

• 必须带 https://，结尾不要加斜杠；
• 填的是你自己的 Worker 域名，不是 nodewarden.app，也不是官方地址。

5.2 浏览器扩展#

1. 打开 Bitwarden 扩展，点击登录页左下角的 齿轮图标（Settings）；
2. 在 Self-hosted environment / 自托管环境 区域，勾选自定义服务器；
3. Server URL 填入你的 Worker 地址，保存；
4. 回到登录页，点击 Create account（注册账号）——如果你还没在网页向导注册，也可以直接在这里注册；
5. 用主密码登录，先手动点一次同步，看到密码库出现即为成功。

5.3 桌面端 / 手机 App#

• 桌面端（Windows / Linux）：登录窗口左下角同样有齿轮图标，入口与扩展一致；
• 手机 App：登录页点击右上角/左下角的 设置（齿轮），找到「自托管服务器」，填入地址后保存，再登录。

5.4（可选）给登录开启 TOTP 两步验证#

1. 先在 Worker 的 Variables and Secrets 中添加 TOTP_SECRET（初始化向导会提供一个 Base32 种子与二维码）；
2. 用 Google Authenticator、Authy、2FAS 等验证器扫描二维码；
3. 以后在新设备登录时，除主密码外还需输入 6 位动态码。

这与密码库条目的 TOTP 是两回事：前者保护账号登录，后者用来自动填充其他网站的验证码。

5.5 绑定自定义域名（可选，但国内网络建议配置）#

workers.dev 默认域名在部分网络环境下可能无法直连。如果你的域名已接入 Cloudflare：

1. 进入 Workers & Pages → nodewarden → Settings → Domains & Routes；
2. 添加一个你自己的子域名，例如 vault.example.com；
3. 证书自动签发，等一两分钟生效；
4. 把客户端里的服务器地址换成新域名。

7.1 手动更新（推荐先看 changelog）#

1. 打开你 Fork 的 GitHub 仓库主页；
2. 文件列表上方若出现 This branch is behind ... 提示条，点击 Sync fork；
3. 点击 Update branch，等待几秒；
4. 因为你的 Worker 连接了这个 Fork，同步提交会自动触发 Cloudflare 重新构建部署，去 Cloudflare 部署日志页确认成功即可。

7.2 自动更新#

仓库自带了每日同步上游的 GitHub Actions 工作流：

1. 进入你的 Fork → Actions 标签页；
2. 点击绿色按钮 I understand my workflows, go ahead and enable them；
3. 默认每天 03<00> 自动检查并同步；也可以随时点击对应工作流 → Run workflow 立即执行。

建议大版本更新前先去 Releases 页面看一眼 changelog，确认是否有需要手动处理的变更。

7.3 从一键部署示例仓库换成自己的 Fork#

如果你最初是通过别人给的一键部署按钮创建的服务，需要先解绑示例仓库：Cloudflare 面板 → 你的服务 → Settings → Builds and deployments → Source code，解除当前绑定后，重新绑定你自己的 Fork，之后才能正常收到更新。