banner
约 2,400 字
8 分钟

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

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。

Warden 内置的 Web Vault 登录页(复用 Vaultwarden 前端,当前内置版本 2026.6.4)
Warden 内置的 Web Vault 登录页(复用 Vaultwarden 前端,当前内置版本 2026.6.4)

仓库: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。

二、部署前要先想清楚的三件事

  1. 前端不再是独立部署。Warden 现在把 Web Vault 打进 Worker 的静态资源里,不再需要单独的 Cloudflare Pages 项目;如果你以前分开部署过,可以把那个 Pages 项目删掉。

  2. *.workers.dev 默认是关的,因为它可能触发 1101 错误。想用它得在 wrangler.toml 里设 workers_dev = true;生产环境建议直接绑自定义域名。

  3. 总有一个「必须手填」的环节——运行时 Secret。CI 只部署代码,Secret 不会跟着走,这是整套流程里最容易翻车的地方。

三、路线选择

路线

适合谁

特点

CLI 手动部署

想理解每个环节

全程本机操作,最直观

GitHub Actions(推荐)

长期维护、追上游更新

push 即部署,同一个 token 还能驱动每日 D1 备份

Cloudflare Workers Builds

不想碰 GitHub Actions

一次约 7 分钟,且要维护两套凭据

下面把第一条走一遍(理解原理),再讲推荐的那条。

四、路线 A:CLI 手动部署

1. 拉代码、建库

bash
git clone https://github.com/qaz741wsd856/warden-worker.git
cd warden-worker

wrangler d1 create warden-db

记下输出的 database_id,下一步要用。

2. 处理数据库 ID(不要进 Git)

建一个 .env(记得加进 .gitignore):

bash
D1_DATABASE_ID="你的数据库ID"

或者直接 export D1_DATABASE_ID="你的数据库ID"。

3. 下载 Web Vault 前端

Warden 复用 Vaultwarden 的 Web 前端(bw_web_builds,默认锁定 v2026.6.4):

bash
BW_WEB_VERSION="${BW_WEB_VERSION:-v2026.6.4}"
wget "https://github.com/dani-garcia/bw_web_builds/releases/download/${BW_WEB_VERSION}/bw_web_${BW_WEB_VERSION}.tar.gz"
tar -xzf "bw_web_${BW_WEB_VERSION}.tar.gz" -C public/
rm "bw_web_${BW_WEB_VERSION}.tar.gz"

# 删掉 source map:不删会超出 Cloudflare 静态资源的单文件限制
find public/web-vault -type f -name '*.map' -delete

4. 建表并部署

bash
# 仅在首次部署前执行一次
wrangler d1 execute vault1 --file sql/schema.sql --remote

# 后续版本升级时执行迁移(不是重建表)
wrangler d1 migrations apply vault1 --remote

# 可选:导入全局等价域名数据(登录时自动匹配同站不同后缀的账号)
bash scripts/seed-global-domains.sh --db vault1 --remote

wrangler deploy

清理回收站的定时任务写在 wrangler.toml 的 [triggers] 里(默认每天 03:00 UTC),会跟着一起部署。

5. 设置三个 Secret(少了服务直接崩)

bash
wrangler secret put ALLOWED_EMAILS      # 允许注册的邮箱,支持 *@example.com 通配,逗号分隔
wrangler secret put JWT_SECRET          # 足够长的随机串
wrangler secret put JWT_REFRESH_SECRET  # 另一个不同的随机串

⚠️ 这三个变量缺任何一个,服务端会直接启动失败。这是整个流程里最容易漏的一步。

6. 配置客户端

Bitwarden 客户端登录页选「自托管」,填你的 Worker 地址即可。

五、路线 B:GitHub Actions(推荐)

这条路的核心优势是:同一个 CLOUDFLARE_API_TOKEN 既管部署,又驱动仓库自带的每日 D1 备份工作流。密码库这种数据,自动备份必须安排上。

1. Fork 仓库

把 qaz741wsd856/warden-worker Fork 到你自己的账号下。

2. 创建 Cloudflare API Token

  1. 打开 dash.cloudflare.com/profile/api-tokens

  2. Create Token → 选 Edit Cloudflare Workers 模板

  3. 权限里追加一行:Account → D1 → Edit(部署迁移与备份必需);用 KV 存附件的话还要 Account → KV → Edit

  4. 选好 Account / Zone 资源范围 → 创建,复制 Token(只显示一次)

3. 拿 Account ID

Dashboard 右侧边栏 Overview 页直接可见,或看地址栏 https://dash.cloudflare.com/<account-id>。

4. 配置仓库 Secrets

进入你 Fork 的仓库 → Settings → Secrets and variables → Actions → Secrets:

Secret

必填

说明

CLOUDFLARE_API_TOKEN

✅

上一步创建的 Token

CLOUDFLARE_ACCOUNT_ID

✅

你的账户 ID

D1_DATABASE_ID

✅

生产 D1 数据库 ID

D1_DATABASE_ID_DEV

否

仅 dev 分支部署时需要

同页 Variables 标签下的可选项:

变量

默认

说明

BW_WEB_VERSION

v2026.6.4

前端版本,设 latest 跟随上游

SEED_GLOBAL_DOMAINS

true

设为 false 跳过全局等价域名导入

GLOBAL_DOMAINS_URL

空

固定 domains 数据源,保证可复现部署

5. 可选:启用 R2 附件

默认用 KV 存附件(免费、单文件 25MB 上限)。想要 100MB 就走 R2:

  1. Cloudflare Dashboard → Storage & databases → R2 → Create bucket,建好桶(如 warden-attachments)

  2. 加一个 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:

变量

类型

值

ALLOWED_EMAILS

Secret

你的邮箱,支持 *@example.com 通配与逗号分隔

JWT_SECRET

Secret

长随机串

JWT_REFRESH_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 默认禁用,部分地区访问也不畅。两步:

  1. DNS:Cloudflare → 你的域名 → DNS → 加一条 A 记录,Name 填子域(如 vault),IPv4 随便填 192.0.2.1,Proxy status 必须是 Proxied(橙云)

  2. Route:Workers & Pages → warden-worker → Settings → Domains & Routes → Add Route,填 vault.example.com/*

七、常见问题排查

现象

可能原因

处理

部署后打不开 / 1101 错误

默认禁用了 workers.dev

绑自定义域名,或设 workers_dev = true

服务启动即崩溃

漏了 ALLOWED_EMAILS / JWT_SECRET / JWT_REFRESH_SECRET

补齐三个 Secret

看不到注册按钮

DISABLE_USER_REGISTRATION 默认 true

在 UI 显示需要设为 false

附件传不了大文件

KV 硬上限 25MB

要 100MB 就配 R2(需绑卡)

长文本 Send 发不出

D1 单行 2MB 限制

文本 Send 上限约 1.8 MiB,属预期

登录特别慢

服务端 PBKDF2 默认 600000 次迭代

属安全特性;算力重的接口可配 HEAVY_DO(Durable Object)卸载

本地调试

—

wrangler dev --persist,前端下载后访问 http://localhost:8787

其余可调变量(都写进 wrangler.toml 的 [vars] 或 Dashboard):

变量

默认

作用

PASSWORD_ITERATIONS

600000

PBKDF2 迭代次数,最小 600000

TRASH_AUTO_DELETE_DAYS

30

回收站保留天数,设 0 或负数关闭

IMPORT_BATCH_SIZE

30

导入/删除批大小,0 关闭分批

ATTACHMENT_MAX_BYTES

—

单个附件上限,如 104857600(100MB)

ATTACHMENT_TTL_SECS

300

附件上传/下载链接有效期,最小 60

SEND_TEXT_MAX_BYTES

≈1.8 MiB

文本 Send 上限

BASE_URL

自动推导

反代场景下固定对外地址,不要带路径

八、三条路线怎么选

方式

适合谁

成本

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。)

END