从零搭建一套
可协作的私有密码库

1. 我们在解决什么问题

先对齐「为什么值得做」，再谈怎么装。工具是手段，工作流才是价值。

2. 架构与选型

三个关键选择：Vaultwarden、Cloudflare Tunnel、默认关闭公开注册。

组件分工

• Vaultwarden：Bitwarden 兼容服务端，资源占用相对官方栈更轻，适合单机 Docker。
• 官方 Bitwarden 客户端：手机、桌面、浏览器插件，把「服务器 URL」改成你的域名即可。
• Cloudflare Tunnel（cloudflared）：从 VPS 主动出站建隧，公网不必为业务端口大开安全组。
• Docker Compose：服务、网络、重启策略一次声明，升级可重复。

为什么是 Tunnel 而不是裸奔 443

传统做法是：VPS 安全组放行 80/443，Nginx/Caddy 反代并申请证书。 可行，但攻击面更大，证书与防火墙都要自己盯。 Tunnel 把「对公网开洞」变成「出站连 Cloudflare」，域名与 TLS 在边缘处理，VPS 侧可只暴露 SSH（甚至 SSH 也收紧）。

和常见方案比一眼

3. 前置准备清单

动手前把账号与信息备齐，避免装到一半卡住。

建议的占位符（写文档时也这样）

• 域名：vault.example.com
• 管理员：you@example.com
• 第二管理员：owner2@example.com
• 组织名：例如 Acme Team

4. 申请并登录免费/低成本 VPS

目标：拿到一台能 SSH 的 Linux，有出网能力。厂商控制台名称会变，以「能力」为准。

选型建议

• 内存：1GB 可以只跑 Vaultwarden + cloudflared；不要同时塞 VPN、大型数据库、一堆面板。
• 磁盘：保险库本身不大，但系统、日志、镜像、备份会占空间；预留余量，盯磁盘使用率。
• 地域：选你和协作者访问延迟可接受的区域；免费档常有容量限制，创建失败就换区或换规格。
• 系统：Ubuntu LTS 类发行版文档最多，新手更友好。

通用创建流程（厂商无关）

1. 创建虚拟网络（VCN/VPC） 若向导要求：公有子网、可分配公网 IP、出网路由。
2. 安全组/防火墙 至少允许你的 IP 访问 22（SSH）。业务 80/443 可以不放行（走 Tunnel 时）。
3. 创建实例 选免费/低配规格，挂载足够启动盘，下载或生成 SSH 密钥。
4. 确认公网 IP 或 SSH 入口 部分厂商默认无私网 IP 出网策略，按控制台文档启用。
5. 首次 SSH 用密钥登录，做一次 sudo apt update（或对应包管理器）确认网络正常。

ssh -i /path/to/your-key.pem ubuntu@YOUR_VPS_IP

5. 部署 Vaultwarden 与 Cloudflare Tunnel

完成标志：域名 HTTPS 打开是 Vault 页面；VPS 业务端口不必对全世界打开。

5.1 安装 Docker

在 VPS 上安装 Docker Engine 与 Compose 插件（以 Ubuntu 为例，具体以官方文档为准）：

# 安装 Docker 后验证
docker --version
docker compose version

5.2 准备目录与配置

mkdir -p ~/vaultwarden
cd ~/vaultwarden

准备 compose.yml（示意，按你模板调整）：

services:
  vaultwarden:
    image: vaultwarden/server:latest
    restart: unless-stopped
    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "false"
      ADMIN_TOKEN: "${VW_ADMIN_TOKEN}"
    volumes:
      - vw-data:/data
    # 建议仅监听本机或 compose 网络，不直接映射公网
    # ports:
    #   - "127.0.0.1:8080:80"

  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: unless-stopped
    command: tunnel --no-autoupdate run
    environment:
      TUNNEL_TOKEN: "${CF_TUNNEL_TOKEN}"
    depends_on:
      - vaultwarden

volumes:
  vw-data:

准备 .env（勿提交到公开仓库）：

VW_ADMIN_TOKEN=请用 openssl rand -base64 48 生成
CF_TUNNEL_TOKEN=从 Cloudflare Zero Trust 控制台复制

openssl rand -base64 48

5.3 Cloudflare 隧道

1. Cloudflare 控制台 → Zero Trust → Networks → Tunnels → Create。
2. 选择 Cloudflared，复制 Token 写入 VPS 的 .env。
3. 为隧道添加 Public Hostname：
   • Subdomain：vault
   • Domain：你的根域名
   • Service：HTTP → vaultwarden:80（或你的实际回源地址）
4. 域名 NS 已指向 Cloudflare（若用 CF DNS）。

5.4 启动与验证

cd ~/vaultwarden
docker compose pull
docker compose up -d
docker compose ps
docker compose logs -f --tail=100

# 公网应能打开 Vault（示例域名）
curl -sI https://vault.example.com | head -1

# 本机存活（若映射了 127.0.0.1:8080）
curl -s http://127.0.0.1:8080/alive

完成标志：

• 手机浏览器打开 https://vault.example.com 看到 Bitwarden/Vaultwarden 界面
• docker compose ps 中相关容器为 running
• Cloudflare 隧道状态 Healthy

6. 第一个用户与安全基线

先能登录，再立刻关掉公开注册；客户端改自建服务器地址。

6.1 注册策略

生产基线建议 SIGNUPS_ALLOWED=false（禁止公开注册）。 但「世界上第一个用户」有时会卡住：没有用户就无法登录，没有 SMTP 就收不到邀请邮件。

可行路径（选一）：

1. 临时开放注册：把 SIGNUPS_ALLOWED 改为 true， docker compose up -d 重建/重载后注册管理员，再改回 false 并重启。
2. Admin 邀请：用 /admin + Admin Token 进入管理后台发送邀请 （需要 SMTP 时邮件才到；部分情况可配合邀请链接流程，以你版本文档为准）。

6.2 管理后台 /admin

• 地址：https://vault.example.com/admin
• 用 ADMIN_TOKEN 登录
• 用途：用户列表、诊断、运维向操作
• 不是创建 Organization 的地方

6.3 官方客户端连接自建服

1. 安装 Bitwarden 官方 App 或浏览器插件。
2. 登录页找到 自托管 / Self-hosted 或服务器设置。
3. 服务器 URL 填：https://vault.example.com（不要多写路径）。
4. 用你的邮箱与主密码登录，开启同步与解锁。

6.4 强烈建议马上做

• 账户开启两步登录（2FA）
• 主密码仅自己知道，使用密码管理习惯本身存好恢复手段
• 在客户端创建几条测试条目，换设备验证同步

7. 组织、集合与协作

协作价值从 Organization 开始；权限靠 Collection / Group，而不是「一个大杂烩库」。

7.1 在哪里创建组织

1. 浏览器打开 https://vault.example.com
2. 用普通用户登录 Web Vault（不是 /admin）
3. 找到 New organization / 新建组织（界面文案可能随版本变化）
4. 创建后你是 Owner，再邀请第二位 Owner

7.2 集合（Collections）示例

7.3 群组授权思路

优先「人 → 加入 Group → Group 拥有 Collection 权限」，少给个人直接绑一堆例外。

• core-ops：生产相关读写
• engineers：开发相关 + 共享服务
• everyone：共享服务只读

7.4 入职 / 离职

入职：邀请 → 注册并开 2FA → 加入 Group → 确认可见集合符合预期。

离职：

1. 从 Organization 移除成员（立即失去集合访问）
2. 对其曾可写的共享条目做 密码轮换
3. 若是机器账号：移除后轮换相关 Token

7.5 策略建议

• 组织策略中开启 Require two-step login（要求两步登录）
• 附件：先保存条目，再在条目菜单中管理附件（不同客户端入口略有差异）
• SMTP：配好后邀请体验最好；没配好也能先靠临时注册或其它邀请方式起步

8. 真实使用场景

装好只是一半；下面这些故事才是方案要传递的价值。

9. 备份、升级与加固

能上线不算成功；能恢复、能升级、少裸奔才算。

9.1 备份什么

• Vaultwarden 数据卷（SQLite、附件、配置相关数据目录）
• 你的 compose.yml / .env 的私密离线副本（注意 .env 含密钥）
• Cloudflare 隧道与 DNS 的关键配置说明（可明文记在私人文档）

cd ~/vaultwarden
docker compose stop vaultwarden
# 备份命名卷或绑定目录，例如：
# docker run --rm -v vw-data:/data -v "$PWD:/backup" alpine \
#   tar czf /backup/vw-$(date +%F).tar.gz -C /data .
docker compose start vaultwarden

9.2 升级

cd ~/vaultwarden
docker compose pull
docker compose up -d
docker compose ps

升级前先备份；关注 Vaultwarden 发行说明中的破坏性变更。

9.3 加固清单（由易到难）

• 公开注册关闭
• 强 Admin Token，不进 Git
• SSH 密钥登录，禁止密码登录（可选但推荐）
• 用 Cloudflare Access 保护 /admin
• WAF / 限流保护登录接口，降低撞库噪声
• 组织强制 2FA
• 磁盘监控与备份失败告警（哪怕只是邮件/IM）

10. 成本、风险与和商业方案的对比

自托管的「便宜」往往用时间与责任换。写清楚，读者才不会被教程卖惨或卖安利。

主要风险（请默认会发生）

• 免费实例被回收、磁盘写满、误删卷
• Token 或 SSH 密钥泄露
• 只有一名 Owner，人员变动后无法管理组织
• 长期不备份，或备份从未恢复验证过

11. 常见问题 FAQ

打不开域名 / 502

• 查隧道是否 Healthy、cloudflared 日志
• 查 Public Hostname 回源地址是否与 Compose 网络一致
• 查 vaultwarden 是否在跑：docker compose ps

提示无法注册 / 注册被禁用

这是 SIGNUPS_ALLOWED=false 的预期行为。首用户用临时开放或邀请流程；完成后保持关闭。

邀请邮件收不到

多半未配置 SMTP 或邮件进垃圾箱。先保证 Admin/SMTP 配置正确；过渡期可用临时注册策略。

在管理后台找不到「创建组织」

请到 Web Vault 用户界面创建。Admin 是运维面板。

客户端找不到附件入口

许多客户端需先保存条目，再从条目菜单「附件/Attachments」管理。以你使用的客户端版本为准。

1GB 内存够吗？

仅 Vaultwarden + cloudflared 通常可以。若再叠加重服务，先加监控，不够再升级规格。

能不能当团队唯一密码来源？

技术上可以，但请配套：双 Owner、2FA、备份演练、入离职流程。关键生产权限仍建议最小化。

12. 上线检查清单

• HTTPS 域名可打开 Vault
• 公开注册已关闭
• 管理员已开 2FA
• 至少一台手机 + 一个桌面客户端同步成功
• 协作场景：Organization 已建，Owner ≥ 2
• 集合与群组权限符合「谁不该看见什么」
• Admin Token / Tunnel Token 已私下保管
• 至少有一份可恢复的数据备份
• （可选）/admin 已加 Access 等额外保护
• 写了一页给同伴的「怎么登录、服务器填什么」说明

附录

术语表

常用运维命令速查

cd ~/vaultwarden
docker compose up -d
docker compose logs -f --tail=200
docker compose pull && docker compose up -d
docker compose ps
curl -s http://127.0.0.1:8080/alive

延伸阅读（官方）

• Vaultwarden 项目与 Wiki（镜像名、环境变量、Admin）
• Cloudflare Tunnel / Zero Trust 文档
• Bitwarden 帮助中心：自托管服务器配置、组织与集合
• Docker 官方安装文档

你可以怎么继续完善自己的文档

• 把本文的占位符换成内部 runbook（勿公开 Token）
• 为非技术同伴单独写一页「只含登录步骤」的说明
• 备份脚本、恢复演练日期写进团队日历