如何把 Bitwarden 官方客户端接入 NodeWarden：Windows、手机 App 与浏览器扩展完整实操教程

如何把 Bitwarden 官方客户端接入 NodeWardenWindows、手机 App 与浏览器扩展完整实操教程【免费下载链接】nodewardenBitwarden-compatible server running on Cloudflare Workers项目地址: https://gitcode.com/gh_mirrors/no/nodewardenNodeWarden 是一个运行在 Cloudflare Workers 上的 Bitwarden 兼容服务器自建密码管理器部署完成后你可以把 Bitwarden 官方客户端——Windows 桌面端、手机 App、浏览器扩展——直接指向自己的服务器地址即可免费获得实时多端同步、TOTP、附件、Send 等完整功能。本文手把手带新手走完「部署 → 注册 → 配置客户端 → 验证同步」全流程无需写代码。一、NodeWarden 是什么凭什么替代官方服务NodeWarden 复刻了 Bitwarden 的 Identity / Sync / Attachments / Send 等服务端接口因此官方客户端无需任何修改即可直连。相比 Bitwarden 免费版它还有不少增强能力摘自 README_ZH.md 的能力对比表能力Bitwarden 免费版NodeWarden网页密码库✅✅ 原创 Web Vault 界面TOTP 验证码❌✅ 含steam://支持PWA / 离线使用❌✅ 可安装、可离线Passkey 无密码登录✅✅实时推送同步✅✅ 网页/扩展/电脑/手机附件 / Send✅✅ 存储于 Cloudflare R2 或 KV云端备份中心❌✅ 定时 WebDAV / S3 增量备份登录请求跨设备审批✅✅组织 / 官方目录 / SSO✅❌ 未实现⚠️ 官方已测试通过的客户端Windows 桌面端、手机 App、浏览器扩展、Linux 桌面端macOS 桌面端尚未完整验证。服务端的环境配置Identity、Vault、Notifications 地址等由src/config-response.ts统一生成客户端首次访问你的服务器地址时会自动读取这是「免配置直连」的关键。二、5 分钟部署 NodeWarden免代码流程连接客户端前先准备一个可用的服务器地址。官方提供「可视化快速部署」全程在 Cloudflare 控制台点选完成Fork NodeWarden 仓库到自己账号建议在 Fork 时把仓库名改掉例如2233warden避免后续连接 GitHub 时出现 404打开 Cloudflare 控制台的Workers Pages → Create选择Continue with GitHub并选中你的仓库构建命令填npm run build部署命令填npm run deploy如果你不想绑信用卡改用 KV 存储模式把部署命令改为npm run deploy:kv等待部署完成打开生成的 Workers 域名就是你的自建密码管理器地址了。两个常见「踩坑点」提示缺少JWT_SECRET在 Workers 设置 → 变量和机密中把它添加为Secret运行时变量不是构建变量值建议 32 位以上随机字符串。相关配置逻辑见 src/handlers/identity.ts 与 src/utils/jwt.tsWorkers 默认域名打不开部分网络环境无法直连*.workers.dev请到 Workers 设置里绑定一个自定义域名客户端将使用这个域名。两种存储模式的差异也很影响体验存储是否需绑卡单文件上限免费额度R2默认需要100 MB软限制可调10 GBKV可选不需要25 MiB1 GB绑定关系在 wrangler.toml / wrangler.kv.toml 中定义Worker 首次收到请求时会自动初始化 D1 数据库结构无需手动上传 SQL。三、注册账号在 Web Vault 上完成初始化浏览器打开你的 NodeWarden 地址会看到原创的 Web Vault 界面支持 PWA 安装与离线使用注册邮箱并设置主密码注册入口由 src/handlers/accounts.ts 处理支持 PBKDF2-SHA256 与 Argon2id 两种 KDF参数校验遵循 Bitwarden 最低安全要求如果是多人使用服务端可通过邀请码控制注册管理端能力位于 src/handlers/admin.ts建议立即开启登录 2FATOTP / YubiKey / Passkey 均支持并保存 2FA 恢复码把密码库备份到本地导出 Bitwarden JSON / CSV / ZIP这是安全使用自建服务的第一步。四、核心步骤把 Bitwarden 官方客户端指向你的服务器NodeWarden 兼容 Bitwarden 自托管协议所有客户端的配置动作都只有一句话填写你的服务器地址。以下分端说明。4.1 Windows 桌面端自托管服务器配置最快安装 Bitwarden 桌面客户端官网或系统应用商店均有提供打开客户端 → 右下角齿轮设置→ 自托管服务器Self-hosted server勾选「使用自托管服务器」在「服务器地址」中填入你的 NodeWarden 域名例如https://vault.example.com只填域名不带/api等路径点保存并登录邮箱 主密码即可。首次连接时客户端会自动请求/config接口获取环境地址对应 src/config-response.ts 中生成的environment字段之后登录、同步、附件上传全部走你的服务器。4.2 手机 AppiOS / Android 操作步骤一致安装 Bitwarden 手机版在登录页底部选择「使用自托管服务器」不同版本入口略有差异有的在登录后进入 设置 → 自托管服务器填入 NodeWarden 域名并继续登录登录成功后允许 App 的推送通知权限——NodeWarden 通过 src/services/push-relay.ts 中的推送中继实现手机端的实时同步通知。手机端的「跨设备登录审批」体验很好当你在别的设备想登录时手机 App 会弹出确认请求登录请求功能见 src/handlers/auth-requests.ts点一下即可免密通过。4.3 浏览器扩展三步接入在浏览器商店安装 Bitwarden 扩展打开扩展 → 齿轮设置 →自托管服务器填入 NodeWarden 域名、保存、登录。之后访问网站时扩展可以直接自动填充账号密码并可通过服务端POST /fill-assist规则接口优化域名匹配见 src/handlers/fill-assist.ts。 小贴士桌面端、手机、扩展、Web Vault使用同一套账号密码登录四端数据实时推送同步改一处全端生效。五、接入后验证确认一切正常依次检查这几点全部通过就说明接入成功同步在 Web Vault 新建一条登录记录几秒内桌面端和手机应自动出现附件给一条记录添加小文件附件再删除各端都应保持一致R2 模式单文件上限 100 MBSend创建一个 Send 链接并分享接收方应能访问️设备管理进入 设置 → 安全设备应能看到各端登录记录可移除不需要的设备见 src/handlers/devices.ts图标加载列表中正常显示网站 favicon说明 icons 服务地址也已正确配置。六、常见问题与避坑清单问题原因与解决客户端一直转圈 / 连接失败网络环境无法直连默认 Workers 域名请绑定自定义域名确认地址只填域名不带路径提示JWT_SECRET缺失需配置在Variables and Secrets的运行时区域并保存为 Secret见 README_ZH.md 常见问题删掉重新部署后注册又要邀请码删除 Worker不会删除 D1 数据库和 KV 命名空间里的旧数据想从零开始需同时删除 D1 与 KV移动端登录验证方式里看不到 Passkey检查设备是否支持 WebAuthnNodeWarden 的 Passkey 连接器位于 webapp/public/webauthn-connector.html 与 webapp/public/webauthn-mobile-connector.html需要组织共享 / SSONodeWarden 暂未实现组织、集合与 SSO属个人使用定位七、安全使用建议重要定期备份本项目定位为学习与交流用途请养成每周导出密码库的习惯或利用内置的云端备份中心定时 WebDAV / S3 增量备份见 src/services/backup-uploader.tsJWT_SECRET务必用 Secret 保存避免明文变量在重新部署时被覆盖详细建议见 SECURITY.md开启 2FA 保存恢复码TOTP、YubiKey、Passkey 三种登录二次验证均可用实现见 src/handlers/identity.ts只想自用可隐藏 Web Vault在 Workers 变量中加HIDE_WEB_VAULT1服务端前端页面将返回 404但客户端所需接口照常工作逻辑见 src/web-vault-visibility.ts升级时到 Fork 仓库点击Sync fork → Update branch拉取更新即可。写在最后整套流程走完后你拥有的是一台免费、无服务器、多端实时同步的 Bitwarden 兼容自建密码管理器Windows 桌面端负责日常管理与 TOTP手机 App 负责随时取用和跨设备登录审批浏览器扩展负责自动填充。核心动作永远只有一个——把客户端的服务器地址指向你的 NodeWarden 域名。再次提醒本项目与 Bitwarden 官方无关仅供学习与交流请务必坚持定期备份你的密码库 【免费下载链接】nodewardenBitwarden-compatible server running on Cloudflare Workers项目地址: https://gitcode.com/gh_mirrors/no/nodewarden创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考