NodeWarden 部署教程：在 Cloudflare Workers 上搭建免费 Bitwarden 密码库

什么是 NodeWarden？

NodeWarden 是一个兼容 Bitwarden 的第三方服务端实现，专为 Cloudflare Workers 无服务器架构设计。它让你无需租用 VPS 或维护服务器，就能拥有完全私有的密码管理服务，支持所有 Bitwarden 官方客户端（Windows、macOS、Linux、iOS、Android、浏览器扩展）。

核心优势

功能对比：NodeWarden vs Bitwarden 官方

必要条件

在开始部署前，请确保你已准备好：

1. Cloudflare 账号（需要绑定域名和信用卡/支付方式，用于开通 R2 存储）
2. GitHub 账号（用于 Fork 仓库和自动部署）
3. 一个域名（建议使用已在 Cloudflare 托管的域名，便于绑定自定义域名）

存储方案选择：

• R2 模式（推荐）：需要绑卡，单个附件上限 100MB，免费额度 10GB
• KV 模式：无需绑卡，单个附件上限 25MB（Cloudflare 限制），免费额度 1GB

部署步骤

第一步：Fork GitHub 仓库

1. 访问 NodeWarden 官方仓库：https://github.com/shuaiplus/NodeWarden
2. 点击右上角的 Fork 按钮，将仓库复制到你的 GitHub 账号下
3. （可选）给你的 Fork 点个 Star 支持项目

第二步：一键部署到 Cloudflare

NodeWarden 提供了便捷的 Web 部署方式：

1. 在你 Fork 的 GitHub 仓库页面，找到并点击 "Deploy to Cloudflare Workers" 按钮（通常在 README 中有显示）
2. 页面会跳转到 Cloudflare Workers 部署界面
3. 点击 "Continue with GitHub" 授权 Cloudflare 访问你的 GitHub 仓库
4. 选择你 Fork 的 NodeWarden 仓库
5. 配置部署命令：
   • 默认使用 R2 存储：npm run deploy
   • 如果未开通 R2，改用 KV 存储：将部署命令改为 npm run deploy:kv

6. 点击 部署，等待 Cloudflare 完成构建和部署

第三步：初始化 NodeWarden 配置

部署成功后，Cloudflare 会提供一个临时 Workers 地址，格式类似：

https://your-nodewarden.your-subdomain.workers.dev

1. 访问初始化页面：在浏览器中打开上述地址
2. 如果打不开，被墙了，建议在 Cloudflare 控制台为此 Workers 绑定一个域名，可以绑定其他家免费二级域名，进行托管，这里推荐直接在他家买一个长数字的xyz域名，一年也就七八块钱 ，在图片中位置绑定你购买的那个域名即可，后续就不用操作，Cloudflare会帮你设置好证书，做好dns解析，以及网站的防护。

初始化设置包括以下关键步骤 ：

3.1 设置 JWT_SECRET

• 这是一个用于加密会话的安全密钥
• 生成方法：在终端运行以下命令生成强随机字符串：

  openssl rand -hex 32

• 将生成的字符串填入 JWT_SECRET 字段

3.2 配置自动更新（可选）

• 设置 GitHub 自动同步，确保能及时获取上游更新
• 支持手动同步（Sync fork）或自动同步（通过 GitHub Actions 每天凌晨 3 点自动同步）

3.3 创建主账号

• 设置你的主登录邮箱和密码（这是你的管理员账号）
• 注意：此密码是解锁密码库的主密码，务必使用高强度密码并牢记

3.4 启用二次验证（TOTP）

• 强烈建议开启 TOTP 二次验证
• 使用任意 TOTP 应用（如 Google Authenticator、Microsoft Authenticator、Bitwarden 内置验证器等）扫描二维码绑定
• 保存恢复码：这是在你丢失验证设备时恢复账号的唯一方式

客户端配置与登录

NodeWarden 完全兼容 Bitwarden 官方客户端，配置方法如下：

Windows / macOS / Linux 桌面端

1. 下载并安装 Bitwarden 桌面客户端
2. 打开应用，在登录界面点击左上角的 ⚙️ 设置（齿轮图标）
3. 选择 "自托管环境"（Self-hosted Environment）
4. 在 服务器 URL 处输入你的 NodeWarden 地址：
   • 例如：https://bitwarden.yourdomain.com 或 https://your-nodewarden.workers.dev
5. 点击 保存，返回登录界面
6. 使用初始化时设置的邮箱和主密码登录
7. 如果开启了 TOTP 2FA，输入验证码完成登录

iOS / Android 移动端

1. 下载 Bitwarden App
2. 在登录页面点击 ⚙️ 设置
3. 选择 "自托管"
4. 输入你的 NodeWarden 服务器 URL
5. 保存后使用账号密码登录

浏览器扩展

1. 安装 Bitwarden 浏览器扩展
2. 右键点击扩展图标 → 选项
3. 找到 "自托管环境" 设置
4. 填入你的服务器 URL 并保存

数据导入与备份

从其他密码管理器迁移

NodeWarden 支持多种导入格式 ：

• Bitwarden JSON / CSV
• Bitwarden 密码库 + 附件 ZIP
• 其他浏览器/密码管理器格式（通过网页导入器）

导入步骤：

1. 登录 NodeWarden Web 界面（你的 Workers 地址）
2. 进入工具 → 导入数据
3. 选择源格式并上传文件

数据备份策略

NodeWarden 提供多种备份方式 ：

本地备份：

• 定期导出 Bitwarden JSON 或加密 JSON 文件
• 带附件的完整 ZIP 导出

云端备份（高级功能）：

• 支持 WebDAV 和 E3 协议
• 可设置自动备份到私有云存储
• 附件采用增量备份，避免重复上传

恢复机制：

• 从备份 ZIP 恢复时，附件会从 attachments/ 目录按需读取
• 缺失的附件会被安全跳过，不会留下脏数据

更新与维护

保持 NodeWarden 更新

自动更新（推荐）：

1. 进入你 Fork 的 GitHub 仓库
2. 点击 Actions → Sync upstream → Enable workflow
3. 系统会在每天凌晨 3 点自动同步上游更新

手动更新：

• 打开 Fork 仓库，看到顶部同步提示后，点击 Sync fork → Update branch
• Cloudflare 会自动重新部署最新版本

CLI 手动部署（开发者适用）

如果你需要二次开发或更精细的控制：

# 克隆项目
git clone https://github.com/shuaiplus/NodeWarden.git
cd NodeWarden

# 安装依赖
npm install

# 登录 Cloudflare
npx wrangler login

# 部署（R2 模式）
npm run deploy

# 或 KV 模式
npm run deploy:kv

# 本地开发
npm run dev

安全建议

1. JWT_SECRET 安全：这是系统的核心密钥，务必使用强随机字符串，不要泄露给他人
2. 主密码强度：使用至少 12 位以上的强密码，包含大小写字母、数字和符号
3. 定期备份：虽然 Cloudflare 提供高可用性，仍建议定期导出 JSON 备份到本地安全位置
4. 开启 2FA：务必启用 TOTP 二次验证，并妥善保存恢复码
5. 域名 HTTPS：使用自定义域名时确保开启 HTTPS（Cloudflare 自动提供）
6. 隐藏管理页面：生产环境建议隐藏初始化设置页面，减少攻击面

常见问题

Q: NodeWarden 完全免费吗？
A: 是的，基于 Cloudflare 免费额度，个人使用基本不会产生费用。但 R2 存储需要绑定支付方式（信用卡/PayPal）。

Q: 支持多用户吗？
A: NodeWarden 定位单用户密码库。v1.2.0 版本后已支持多用户管理功能，但主要设计初衷是个人使用 。

Q: macOS 客户端兼容性如何？
A: 目前 macOS 桌面端尚未完整验证，Windows、Linux、移动端和浏览器扩展均已测试通过 。

Q: 附件大小限制是多少？
A: R2 模式下软限制为 100MB（可在代码中调整），KV 模式下受 Cloudflare 限制为 25MB 。

Q: 如果 Cloudflare 封禁了怎么办？
A: 由于数据存储在 D1 和 R2 中，你可以随时导出数据迁移到其他 Bitwarden 服务端（如 Vaultwarden）或官方服务。

通过以上步骤，你就可以在无需服务器的情况下，拥有一个功能完善、数据自主可控的私有密码管理系统。享受安全便捷的密码管理体验吧！