Warden 部署教程:把 Bitwarden 密码库搬上 Cloudflare Workers

摘要
Warden 用 Rust+WASM 把 Bitwarden 服务端搬上 Cloudflare Workers 免费层:D1 存储、Web Vault 内置,含 CLI 与 Actions 部署路线。
Warden 部署教程:把 Bitwarden 密码库搬上 Cloudflare Workers
用过 Vaultwarden 的人都知道自托管密码库的痛点:再轻量也得养一台 VPS。服务器漏缴费、跑路、或者只是忘了续期,密码库就跟着没了。Warden 换了条路——把 Bitwarden 兼容服务端编译成 WASM,跑在 Cloudflare Workers 上,数据落 D1。

仓库:qaz741wsd856/warden-worker(MIT)· 当前版本 v0.7.2(2026-08-09)· 完整部署文档见 docs/deployment.md。
一、它是什么,能做什么
Warden 的目标是「部署完就扔那儿不管」:没有服务器要维护、没有账单要续,官方 Bitwarden 客户端(浏览器扩展 / Android / iOS)直接连。
已支持:
密码与文件夹的增删改查,兼容官方客户端
文件附件:KV(单文件上限 25MB,无需绑卡)或 R2(100MB,流式 IO,需绑卡);两者都配时优先用 R2
Bitwarden Send:文本 Send 默认开启;文件 Send 需要存储后端
TOTP:存储并生成两步验证码
实时同步(WebSocket)与手机推送(可选)
设备管理(查看 / 吊销会话)、每日自动清理回收站
暂不支持(并且作者明说短期不打算做):分享、组织、紧急访问、TOTP 之外的 2FA 登录、管理后台类操作。它的定位就是个人密码库,别指望替代团队版 Bitwarden。
二、部署前要先想清楚的三件事
前端不再是独立部署。Warden 现在把 Web Vault 打进 Worker 的静态资源里,不再需要单独的 Cloudflare Pages 项目;如果你以前分开部署过,可以把那个 Pages 项目删掉。
*.workers.dev默认是关的,因为它可能触发 1101 错误。想用它得在wrangler.toml里设workers_dev = true;生产环境建议直接绑自定义域名。总有一个「必须手填」的环节——运行时 Secret。CI 只部署代码,Secret 不会跟着走,这是整套流程里最容易翻车的地方。
三、路线选择
路线 | 适合谁 | 特点 |
|---|---|---|
CLI 手动部署 | 想理解每个环节 | 全程本机操作,最直观 |
GitHub Actions(推荐) | 长期维护、追上游更新 | push 即部署,同一个 token 还能驱动每日 D1 备份 |
Cloudflare Workers Builds | 不想碰 GitHub Actions | 一次约 7 分钟,且要维护两套凭据 |
下面把第一条走一遍(理解原理),再讲推荐的那条。
四、路线 A:CLI 手动部署
1. 拉代码、建库
记下输出的 database_id,下一步要用。
2. 处理数据库 ID(不要进 Git)
建一个 .env(记得加进 .gitignore):
或者直接 export D1_DATABASE_ID="你的数据库ID"。
3. 下载 Web Vault 前端
Warden 复用 Vaultwarden 的 Web 前端(bw_web_builds,默认锁定 v2026.6.4):
4. 建表并部署
清理回收站的定时任务写在 wrangler.toml 的 [triggers] 里(默认每天 03:00 UTC),会跟着一起部署。
5. 设置三个 Secret(少了服务直接崩)
⚠️ 这三个变量缺任何一个,服务端会直接启动失败。这是整个流程里最容易漏的一步。
6. 配置客户端
Bitwarden 客户端登录页选「自托管」,填你的 Worker 地址即可。
五、路线 B:GitHub Actions(推荐)
这条路的核心优势是:同一个 CLOUDFLARE_API_TOKEN 既管部署,又驱动仓库自带的每日 D1 备份工作流。密码库这种数据,自动备份必须安排上。
1. Fork 仓库
把 qaz741wsd856/warden-worker Fork 到你自己的账号下。
2. 创建 Cloudflare API Token
Create Token → 选 Edit Cloudflare Workers 模板
权限里追加一行:Account → D1 → Edit(部署迁移与备份必需);用 KV 存附件的话还要 Account → KV → Edit
选好 Account / Zone 资源范围 → 创建,复制 Token(只显示一次)
3. 拿 Account ID
Dashboard 右侧边栏 Overview 页直接可见,或看地址栏 https://dash.cloudflare.com/<account-id>。
4. 配置仓库 Secrets
进入你 Fork 的仓库 → Settings → Secrets and variables → Actions → Secrets:
Secret | 必填 | 说明 |
|---|---|---|
| ✅ | 上一步创建的 Token |
| ✅ | 你的账户 ID |
| ✅ | 生产 D1 数据库 ID |
| 否 | 仅 |
同页 Variables 标签下的可选项:
变量 | 默认 | 说明 |
|---|---|---|
|
| 前端版本,设 |
|
| 设为 |
| 空 | 固定 domains 数据源,保证可复现部署 |
5. 可选:启用 R2 附件
默认用 KV 存附件(免费、单文件 25MB 上限)。想要 100MB 就走 R2:
Cloudflare Dashboard → Storage & databases → R2 → Create bucket,建好桶(如
warden-attachments)加一个 GitHub Secret:
R2_NAME= 桶名
工作流检测到 R2_NAME 存在时,会自动把 ATTACHMENTS_BUCKET 绑定追加进 wrangler.toml,不用去控制台手工配绑定。
6. 触发部署
自动:push 到
main即构建部署手动:Actions → Build → Run workflow
首次构建要装 Rust→WASM 工具链,比较慢,之后有缓存会快很多。
7. 到 Cloudflare 补运行时 Secret(最容易翻车)
CI 部署的是代码,运行时 Secret 不会跟着走。到 Workers & Pages → warden-worker → Settings → Variables and Secrets:
变量 | 类型 | 值 |
|---|---|---|
| Secret | 你的邮箱,支持 |
| Secret | 长随机串 |
| Secret | 另一个不同的长随机串 |
想在前端露出「创建账户」按钮,再加一个文本变量 DISABLE_USER_REGISTRATION = false(默认 true,只在 UI 层隐藏,服务端行为不变)。
手机推送(可选):PUSH_ENABLED=true、PUSH_RELAY_URI、PUSH_IDENTITY_URI 设为文本;PUSH_INSTALLATION_ID、PUSH_INSTALLATION_KEY 设为 Secret(这两个从 bitwarden.com/host 免费获取)。
8. 验证
访问你的 Worker 域名,看到 Web Vault 登录页即为成功。然后用 Bitwarden 客户端自托管登录,跑一遍注册 → 保存 → 同步。
六、绑自定义域名(强烈建议)
*.workers.dev 默认禁用,部分地区访问也不畅。两步:
DNS:Cloudflare → 你的域名 → DNS → 加一条
A记录,Name 填子域(如vault),IPv4 随便填192.0.2.1,Proxy status 必须是 Proxied(橙云)Route:Workers & Pages → warden-worker → Settings → Domains & Routes → Add Route,填
vault.example.com/*
七、常见问题排查
现象 | 可能原因 | 处理 |
|---|---|---|
部署后打不开 / 1101 错误 | 默认禁用了 workers.dev | 绑自定义域名,或设 |
服务启动即崩溃 | 漏了 | 补齐三个 Secret |
看不到注册按钮 |
| 在 UI 显示需要设为 |
附件传不了大文件 | KV 硬上限 25MB | 要 100MB 就配 R2(需绑卡) |
长文本 Send 发不出 | D1 单行 2MB 限制 | 文本 Send 上限约 1.8 MiB,属预期 |
登录特别慢 | 服务端 PBKDF2 默认 600000 次迭代 | 属安全特性;算力重的接口可配 |
本地调试 | — |
|
其余可调变量(都写进 wrangler.toml 的 [vars] 或 Dashboard):
变量 | 默认 | 作用 |
|---|---|---|
| 600000 | PBKDF2 迭代次数,最小 600000 |
| 30 | 回收站保留天数,设 0 或负数关闭 |
| 30 | 导入/删除批大小,0 关闭分批 |
| — | 单个附件上限,如 |
| 300 | 附件上传/下载链接有效期,最小 60 |
| ≈1.8 MiB | 文本 Send 上限 |
| 自动推导 | 反代场景下固定对外地址,不要带路径 |
八、三条路线怎么选
方式 | 适合谁 | 成本 |
|---|---|---|
CLI 手动 | 一次性部署 / 想搞懂原理 | 全程本机操作 |
GitHub Actions(推荐) | 长期维护、追上游 | push 即部署,token 顺带管备份 |
Workers Builds | 不想碰 Actions | 部署慢(约 7 分钟),且要维护两套凭据 |
若选 Workers Builds:构建命令填
bash scripts/cf-build.sh、部署命令填bash scripts/cf-deploy.sh,并给自动生成的 build token 补 Account → D1 → Edit 权限;同时务必禁用 GitHub Actions 的Build工作流,否则main会被部署两次。
写在最后
自托管密码库的核心从来不是「省钱」,而是「可控」。Warden + Cloudflare 免费层这个组合真正消掉的风险,是「服务器跑路导致密码库丢失」——数据在你自己的 Cloudflare 账号里,D1 每天自动备份。
但可控也意味着责任转移:主密码丢了没人能帮你找回,加密备份要自己离线存好。部署之前先问自己一句:如果这台机器明天消失,我还能打开我的密码库吗?能,再开始搬。
(顺带说明:本项目的定位是个人密码库,不支持组织与分享。团队协作场景请用官方 Bitwarden 或 Vaultwarden。)
