零成本自托管密码库：Warden 部署教程——把 Bitwarden 服务端搬上 Cloudflare Workers（含 GitHub Actions CI/CD）

GitHub：https://github.com/qaz741wsd856/warden-worker 部署文档：https://github.com/qaz741wsd856/warden-worker/blob/main/docs/deployment.md 开源协议：MIT · 当前版本 v0.7.2 · 运行于 Cloudflare Workers 免费层

一、Warden 是什么？为什么值得部署？

用过 Bitwarden / Vaultwarden 的朋友都知道自托管密码库的痛点：Vaultwarden 再轻量也得养一台 VPS——服务器漏缴费，密码库就没了。

Warden 换了个思路：把 Bitwarden 兼容服务端直接编译成 WASM 跑在 Cloudflare Workers 上，数据存 Cloudflare D1（免费额度内零成本），附件可选 KV / R2。部署完就「扔那儿不管」：没有服务器要维护、没有账单要续费，官方客户端（浏览器扩展 / Android / iOS）直接连。

功能一览：

• 密码 / 文件夹的增删改查，兼容官方 Bitwarden 客户端

• 文件附件（KV 单文件上限 25MB；R2 可到 100MB，但 R2 需要绑卡）

• Bitwarden Send（文本 Send 默认开启，上限约 1.8 MiB）

• TOTP 两步验证码存储与生成

• 实时同步（WebSocket）+ 手机推送通知（可选）

• 设备管理（查看 / 吊销会话）、每日自动清理回收站

目前的限制（面向个人使用）：不支持组织 / 分享 / 紧急访问 / 2FA 登录（TOTP 验证码本身支持）。

下面讲三种部署方式：CLI 手动部署、GitHub Actions CI/CD（官方推荐）、Cloudflare Workers Builds（备选）。赶时间可直接跳到第三节。

二、方式一：CLI 手动部署（理解原理用）

先手动走一遍，能帮你搞清楚 CI/CD 自动做的事。

1. 准备工作

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

需要本机有 Node.js（跑 Wrangler CLI）。创建 D1 数据库：

wrangler d1 create warden-db

记下输出的 database_id，后面要用。

2. 配置数据库 ID（不进 git）

在项目根目录建 .env 文件（记得加进 .gitignore）：

D1_DATABASE_ID="your-database-id-goes-here"

或者直接用环境变量：export D1_DATABASE_ID="你的数据库ID"。

3. 下载前端（Web Vault）

Warden 复用 Vaultwarden 的 Web 前端（bw_web_builds，默认锁定 v2026.6.4）：

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. 建表 + 部署

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

# （可选）导入全局等价域名数据
bash scripts/seed-global-domains.sh --db vault1 --remote

wrangler deploy

5. 设置运行时 Secrets（不做服务器起不来）

wrangler secret put ALLOWED_EMAILS      # 允许注册的邮箱，如 you@example.com（支持 *@example.com 通配，逗号分隔）
wrangler secret put JWT_SECRET          # 一串足够长的随机字符串
wrangler secret put JWT_REFRESH_SECRET  # 同上，另一个随机串

⚠️ 这三个变量缺一个，服务端直接崩溃。这是整个部署流程里最容易漏的一步。

6. 配置客户端

Bitwarden 客户端登录界面选「自托管」，填你的 Worker URL 即可。注意：*.workers.dev 域名默认禁用（可能报 1101 错误），强烈建议绑自定义域名（见第五节）。

三、方式二：GitHub Actions CI/CD（官方推荐，重点）

这是文档里明确写的生产环境推荐方式：每次 push 到 main 自动构建部署，而且同一个 CLOUDFLARE_API_TOKEN 还能驱动每日 D1 备份工作流——一个 token 覆盖部署 + 备份两件事，这是它相比其他方案的核心优势。

第 1 步：Fork 仓库

把 qaz741wsd856/warden-worker Fork 到你自己的 GitHub 账号下（后续 Actions 在你的仓库里跑）。

第 2 步：创建 Cloudflare API Token

1. 访问 https://dash.cloudflare.com/profile/api-tokens

2. 点 Create Token，选 Edit Cloudflare Workers 模板

3. 在 Permissions 里追加一行：Account → D1 → Edit（部署迁移和备份必需；用 KV 存附件的话还要 Account → KV → Edit，模板里通常已含）

4. 选择 Account Resources 和 Zone Resources

5. Continue to Summary → Create Token，复制生成的 Token（只显示一次）

第 3 步：拿到 Account ID

登录 Cloudflare Dashboard，右侧边栏 Overview 页就有 Account ID；或者直接看 URL：https://dash.cloudflare.com/<account-id>。

第 4 步：配置 GitHub Secrets

进入你 Fork 的仓库 → Settings → Secrets and variables → Actions，添加：

可选 Variables（同页面的 Variables 标签）：

第 5 步：（可选）启用 R2 附件存储

默认用 KV 存附件（免费额度内零成本，单文件 25MB 上限）。想上 R2（100MB、流式 IO，但开通需绑卡）：

1. 在 Cloudflare Dashboard Storage & databases → R2 → Create bucket，建好生产桶（如 warden-attachments）

2. 添加 GitHub Secret：R2_NAME → 桶名

工作流检测到 R2_NAME 存在时会自动把 ATTACHMENTS_BUCKET 绑定追加进 wrangler.toml——不需要去 Cloudflare 控制台手动配绑定。

第 6 步：触发部署

• 自动：push 到 main 即构建部署；

• 手动：仓库 Actions 标签页 → 选 Build 工作流 → Run workflow。

首次构建会编译 Rust→WASM 工具链，比较慢，耐心等；后续有构建缓存会快很多。在 Actions 页实时看日志。

第 7 步：在 Cloudflare 设置运行时 Secrets（最容易翻车的一步）

CI 部署的是代码，运行时 Secrets 不会跟着走，要去 Cloudflare Dashboard 手动配：Workers & Pages → warden-worker → Settings → Variables and Secrets：

⚠️ 再次强调：缺这三个变量服务器会崩溃。想在前端显示「创建账户」按钮，再加一个 DISABLE_USER_REGISTRATION（Text 类型）设为 false。

手机推送（可选）：PUSH_ENABLED=true、PUSH_RELAY_URI、PUSH_IDENTITY_URI 设为 Text；PUSH_INSTALLATION_ID、PUSH_INSTALLATION_KEY 设为 Secret（这两个从 https://bitwarden.com/host/ 免费获取）。

第 8 步：验证

访问你的 Worker URL（自定义域名），看到 Web Vault 登录页就成功了。用 Bitwarden 客户端自托管登录测试注册 → 保存 → 同步全流程。

日常维护体验：之后想更新版本，只需要在 GitHub 上 git pull 上游 → push 到你的 main——部署全自动，这正是 CI/CD 方式的价值。

附赠：CLOUDFLARE_API_TOKEN 配好后，仓库自带的 Backup D1 Database 工作流也会用它，每天自动备份你的 D1 数据库——密码库这种数据，备份必须安排上。

四、方式三：Cloudflare Workers Builds（简要）

这是 Cloudflare 原生 Git 集成：Dashboard 里连一次仓库，git push 就在 Cloudflare 侧构建部署。对这种 Rust→WASM 项目，构建命令填 bash scripts/cf-build.sh、部署命令填 bash scripts/cf-deploy.sh，并给自动生成的 build token 补一个 Account → D1 → Edit 权限。

两个权衡（官方文档原话）：

• 备份工作流仍需要 GitHub 上的 CLOUDFLARE_API_TOKEN，等于要维护两套凭据；

• Cloudflare 构建环境性能有限，一次部署约 7 分钟，且会消耗你的 Workers 构建时长。

若采用此方式，务必禁用 GitHub Actions 的 Build 工作流（Actions → Build → Disable workflow），否则 main 会被部署两次。

五、绑定自定义域名（强烈建议）

*.workers.dev 默认禁用（可能 1101 报错），而且部分地区访问不畅。绑自定义域名两步：

1. DNS：Cloudflare Dashboard → 你的域名 → 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，绑自定义域名；或在 wrangler.toml 设 workers_dev = true。

• 服务启动即崩溃 → 八成是漏了 ALLOWED_EMAILS / JWT_SECRET / JWT_REFRESH_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。

七、总结

密码库是数字资产里最不能丢的一类，而 Warden + Cloudflare 免费层的组合把「服务器跑路导致密码库丢失」这个最大风险直接消掉了——D1 每日自动备份 + 数据在你自己的 Cloudflare 账号里。如果你正打算从 VPS 版 Vaultwarden 搬家，这是个值得认真考虑的去处。