Bitwarden 详细部署教程：自建密码管理服务器完整指南

1.1 什么是Bitwarden#

Bitwarden是一款开源的密码管理解决方案，采用端到端加密技术，确保用户数据在传输和存储过程中的安全性。作为目前最受欢迎的开源密码管理器之一，Bitwarden支持用户将所有的密码、信用卡信息、安全笔记等敏感数据集中存储在一个加密的保险库中，并通过客户端应用随时随地安全访问。

Bitwarden最初于2016年发布，由8bit Solutions LLC开发维护，其源代码在GitHub上完全开源，接受社区的安全审计和贡献。服务端采用 ASP.NET Core开发，支持Docker容器化部署，这为用户自建密码服务器提供了技术基础。

1.2 特点与优势#

Bitwarden具备以下核心特点：

开源透明：完整的源代码开放给公众审查，用户可以自行审计代码安全性，不会存在后门或隐藏的数据收集行为。这对于重视隐私和安全的用户来说是不可替代的优势。

跨平台支持：Bitwarden提供覆盖全平台的客户端应用，包括Windows、macOS、Linux的桌面客户端，iOS和Android的移动端App，支持所有主流浏览器的插件（Chrome、Firefox、Safari、Edge、Opera等），以及功能完整的Web Vault。无论使用何种设备，都能保持一致的体验。

功能丰富：除基础的密码存储外，Bitwarden还支持生成强密码、安全笔记、文件附件（付费功能或自建高配版）、密码健康报告、两步登录（2FA）功能、密码分享、紧急访问等高级功能。

免费使用：个人免费版已包含密码存储、密码生成器、跨平台同步、浏览器插件等核心功能，相比1Password、LastPass等商业竞品，Bitwarden的免费计划更为慷慨。

端到端加密：采用AES-256位加密算法，所有敏感数据在本地加密后才上传服务器，服务端仅存储密文。即使服务器被攻破，攻击者也无法获取用户的明文密码。

1.3 为什么要自建密码服务器#

尽管Bitwarden提供官方云服务（免费版和付费版），但自建密码服务器在以下场景下具有显著优势：

完全数据控制：将数据完全存储在自己的服务器上，不依赖第三方服务，避免云服务可能存在的数据泄露风险。

成本优化：官方付费版（Premium）每年收费36美元，自建服务只需承担服务器成本，可大幅降低长期使用成本。

自定义功能：自建服务可以绕过官方的一些限制，如附件存储空间、组织架构规模等限制。

企业场景：企业可以在内网环境中部署密码服务器，满足合规要求和数据不出网的安全策略。

学习研究：通过部署过程深入了解密码管理机制、容器化技术、反向代理配置等系统管理技能。

2.1 官方Bitwarden（Bitwarden RS）#

官方Bitwarden服务器是基于 ASP.NET Core的全功能实现，与Bitwarden客户端完全兼容，支持所有官方功能，包括Send（一次性文件/文本分享）、Active Directory集成、企业策略管理等高级特性。

然而，官方服务器对硬件资源要求较高，官方建议至少4GB RAM（推荐8GB），需要SQL Server或MySQL数据库，安装过程相对复杂。对于个人用户或小型团队而言，部署和维护成本较高。

2.2 Vaultwarden（轻量级开源实现）#

Vaultwarden（原名Bitwarden RS）是Bitwarden服务器的开源 Rust 实现，专注于轻量级部署和资源效率。它与官方Bitwarden客户端保持API兼容，大部分功能完全兼容，同时对硬件要求极低（推荐512MB RAM即可运行）。

Vaultwarden的优势在于：

• 资源占用极低，适合树莓派、小型VPS等低配置环境

• 安装配置简单，官方提供Docker镜像

• 开源活跃，社区支持良好

• 功能足够满足大多数个人和团队需求

2.3 方案对比#

推荐选择：对于大多数用户，推荐使用Vaultwarden。其资源效率极高，足以覆盖密码管理的核心需求，且维护成本低。本文将重点介绍Vaultwarden的部署流程。

3.1 硬件要求#

Vaultwarden的最低硬件要求非常亲民：

对于生产环境，建议使用推荐配置以获得更好的性能和稳定性。磁盘空间主要用于存储SQLite数据库（密码数据本身占用极小），但需考虑未来的备份文件存储。

3.2 Docker安装#

Docker是运行Vaultwarden的前提条件。以Ubuntu/Debian系统为例：

bash

1
# 更新系统包
2
sudo apt update && sudo apt upgrade -y
3

4
# 安装依赖包
5
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
6

7
# 添加Docker官方GPG密钥
8
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
9

10
# 添加Docker仓库
11
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
12

13
# 安装Docker
14
sudo apt update
15
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
16

17
# 验证安装
18
sudo docker --version
19
sudo docker compose version

启动Docker服务：

bash

1
sudo systemctl start docker
2
sudo systemctl enable docker

将当前用户加入docker组（避免每次使用sudo）：

bash

1
sudo usermod -aG docker $USER
2
newgrp docker

3.3 域名和SSL证书准备#

自建密码服务器需要域名和SSL证书以启用HTTPS：

域名准备：

• 注册一个域名（如 example.com）

• 配置DNS A记录指向服务器IP

• 等待DNS生效（通常5分钟到48小时）

SSL证书获取（使用Let’s Encrypt免费证书）：

bash

1
# 安装Certbot
2
sudo apt install -y certbot python3-certbot-nginx
3

4
# 申请证书（需要域名已正确解析）
5
sudo certbot certonly --standalone -d vault.example.com --agree-tos --email admin@example.com --non-interactive
6

7
# 证书存放位置
8
# /etc/letsencrypt/live/vault.example.com/fullchain.pem
9
# /etc/letsencrypt/live/vault.example.com/privkey.pem

3.4 防火墙配置#

开放必要的端口：

bash

1
# 开放80端口（用于Let's Encrypt验证）
2
sudo ufw allow 80/tcp
3

4
# 开放443端口（HTTPS）
5
sudo ufw allow 443/tcp
6

7
# 开放22端口（SSH）
8
sudo ufw allow 22/tcp
9

10
# 启用防火墙
11
sudo ufw enable

4.1 创建目录结构#

创建用于存放Vaultwarden配置和数据文件的目录：

bash

1
# 创建主目录
2
mkdir -p ~/vaultwarden/{vault,nginx,ssl}
3

4
# 创建子目录结构
5
cd ~/vaultwarden
6
mkdir -p vault/{data,logs}
7
mkdir -p nginx/{conf.d,ssl}
8

9
# 设置权限（Vaultwarden容器内使用root运行）
10
chmod -R 700 ~/vaultwarden/vault/data

4.2 编写docker-compose.yml#

创建Vaultwarden的Docker编排配置文件：

yaml

1
version: '3.8'
2

3
services:
4
  vaultwarden:
5
    image: vaultwarden/server:latest
6
    container_name: vaultwarden
7
    restart: unless-stopped
8
    environment:
9
      # 时区设置
10
      TZ: Asia/Shanghai
11
      # 数据库配置
12
      DATABASE_URL: "sqlite:///data/vaultwarden.db"
13
      # SMTP邮件配置（用于发送验证码等）
14
      SMTP_HOST: smtp.example.com
15
      SMTP_FROM: noreply@example.com
16
      SMTP_FROM_NAME: Vaultwarden
17
      SMTP_PORT: 587
18
      SMTP_SECURITY: starttls
19
      SMTP_USERNAME: noreply@example.com
20
      SMTP_PASSWORD: "your_smtp_password"
21
      # 功能开关
22
      SIGNUPS_ALLOWED: "true"      # 允许注册，关闭后需管理员创建用户
23
      WEB_VAULT_ENABLED: "true"   # 启用Web界面
24
      ADMIN_TOKEN: "your_admin_token_hashed"  # 管理员面板Token
25
      # 安全设置
26
      ROCKET_PORT: 8080
27
      # 日志配置
28
      LOG_FILE: "/data/logs/vaultwarden.log"
29
      EXTENDED_LOGGING: "true"
30
    volumes:
31
      - ./vault/data:/data
32
      - ./vault/logs:/data/logs
33
    ports:
34
      - "127.0.0.1:8080:8080"
35

36
  nginx:
37
    image: nginx:latest
38
    container_name: vaultwarden-nginx
39
    restart: unless-stopped
40
    ports:
41
      - "80:80"
42
      - "443:443"
43
    volumes:
44
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
45
      - ./ssl:/etc/nginx/ssl:ro
46
      - /etc/letsencrypt:/etc/letsencrypt:ro
47
    depends_on:
48
      - vaultwarden

4.3 生成管理员Token#

管理员Token需要使用SHA256哈希生成：

bash

1
# 安装依赖
2
sudo apt install -y apache2-utils
3

4
# 生成哈希值（将 your_password 替换为你的密码）
5
echo -n "your_password" | sha256sum | cut -d' ' -f1
6

7
# 将生成的哈希值填入 ADMIN_TOKEN 环境变量

4.4 Nginx反向代理配置#

创建Nginx配置文件：

nginx

1
# 重定向HTTP到HTTPS
2
server {
3
    listen 80;
4
    server_name vault.example.com;
5

6
    location /.well-known/acme-challenge/ {
7
        root /usr/share/nginx/html;
8
    }
9

10
    location / {
11
        return 301 https://$host$request_uri;
12
    }
13
}
14

15
# HTTPS配置
16
server {
17
    listen 443 ssl http2;
18
    server_name vault.example.com;
19

20
    # SSL证书配置
21
    ssl_certificate /etc/letsencrypt/live/vault.example.com/fullchain.pem;
22
    ssl_certificate_key /etc/letsencrypt/live/vault.example.com/privkey.pem;
23

24
    # SSL安全配置
25
    ssl_protocols TLSv1.2 TLSv1.3;
26
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
27
    ssl_prefer_server_ciphers off;
28
    ssl_session_cache shared:SSL:10m;
29
    ssl_session_timeout 1d;
30

31
    # 安全头
32
    add_header X-Frame-Options "SAMEORIGIN" always;
33
    add_header X-Content-Type-Options "nosniff" always;
34
    add_header X-XSS-Protection "1; mode=block" always;
35
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
36

37
    # 上传文件大小限制（Bitwarden支持附件）
38
    client_max_body_size 525M;
39

40
    # WebSocket支持（用于实时通知）
41
    location /notifications/hub {
42
        proxy_pass http://vaultwarden:8080/notifications/hub;
43
        proxy_set_header Upgrade $http_upgrade;
44
        proxy_set_header Connection "upgrade";
45
        proxy_http_version 1.1;
46
        proxy_set_header Host $host;
47
        proxy_set_header X-Real-IP $remote_addr;
48
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
49
        proxy_set_header X-Forwarded-Proto $scheme;
50
    }
51

52
    # API和Web Vault代理
53
    location / {
54
        proxy_pass http://vaultwarden:8080;
55
        proxy_set_header Host $host;
56
        proxy_set_header X-Real-IP $remote_addr;
57
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
58
        proxy_set_header X-Forwarded-Proto $scheme;
59

60
        # 超时设置
61
        proxy_connect_timeout 60s;
62
        proxy_send_timeout 60s;
63
        proxy_read_timeout 60s;
64
    }
65
}

4.5 启动服务#

完成配置后，启动Vaultwarden服务：

bash

1
# 进入Vaultwarden目录
2
cd ~/vaultwarden
3

4
# 拉取镜像
5
docker compose pull
6

7
# 启动服务（后台运行）
8
docker compose up -d
9

10
# 查看服务状态
11
docker compose ps
12

13
# 查看日志
14
docker compose logs -f

访问 https://vault.example.com 验证服务是否正常运行。如果看到Bitwarden Web Vault界面，说明部署成功。

4.6 使用Caddy作为反向代理（可选）#

如果觉得Nginx配置复杂，可以使用Caddy简化配置：

yaml

1
version: '3.8'
2

3
services:
4
  vaultwarden:
5
    image: vaultwarden/server:latest
6
    container_name: vaultwarden
7
    restart: unless-stopped
8
    environment:
9
      TZ: Asia/Shanghai
10
      DATABASE_URL: "sqlite:///data/vaultwarden.db"
11
      SIGNUPS_ALLOWED: "true"
12
      WEB_VAULT_ENABLED: "true"
13
      ADMIN_TOKEN: "your_admin_token_hashed"
14
      SMTP_HOST: smtp.example.com
15
      SMTP_FROM: noreply@example.com
16
      SMTP_FROM_NAME: Vaultwarden
17
      SMTP_PORT: 587
18
      SMTP_SECURITY: starttls
19
      SMTP_USERNAME: noreply@example.com
20
      SMTP_PASSWORD: "your_smtp_password"
21
    volumes:
22
      - ./vault/data:/data
23
      - ./vault/logs:/data/logs
24
    ports:
25
      - "127.0.0.1:8080:8080"
26

27
  caddy:
28
    image: caddy:latest
29
    container_name: vaultwarden-caddy
30
    restart: unless-stopped
31
    ports:
32
      - "80:80"
33
      - "443:443"
34
    environment:
35
      - ACME_EMAIL=admin@example.com
36
    volumes:
37
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
38
      - ./caddy_data:/data
39
    depends_on:
40
      - vaultwarden

对应的Caddyfile配置：

plaintext

1
vault.example.com {
2
    reverse_proxy /notifications/hub* vaultwarden:8080 {
3
        transport http {
4
            versions http1.1
5
        }
6
        websocket
7
    }
8

9
    reverse_proxy vaultwarden:8080
10

11
    encode gzip
12

13
    log {
14
        output file /data/access.log
15
    }
16
}

5.1 Web Vault使用#

Web Vault是浏览器中访问密码服务器的入口。首次使用需要注册账号：

1. 访问 https://vault.example.com

2. 点击 “Create Account” 创建账户

3. 填写信息：

   • Email：使用你的邮箱地址

   • Master Password：设置主密码（建议12位以上，包含大小写字母、数字、特殊字符）

   • Master Password Hint：设置密码提示（不要直接泄露密码）

4. 完成注册并登录

重要：主密码是加密和解密数据的唯一密钥，服务器端无法恢复。如果遗忘，将无法访问已存储的密码。请务必牢记或妥善保管主密码。

5.2 浏览器插件安装#

以Chrome为例：

1. 访问Chrome应用商店，搜索 “Bitwarden”

2. 安装 “Bitwarden - Free Password Manager” 扩展

3. 点击扩展图标，点击右上角设置图标

4. 在 “Server URL” 中填写你的自建服务器地址： https://vault.example.com

5. 保存设置后，点击 “Register” 创建账号或 “Log In” 登录

Firefox、Edge等浏览器操作类似。

5.3 桌面客户端配置#

1. 下载Bitwarden桌面客户端： https://bitwarden.com/download/

2. 安装后启动应用

3. 点击设置图标，切换到 “Server” 标签

4. 在 “Self-hosted” 栏填写： https://vault.example.com

5. 保存后登录或注册

5.4 移动端App配置#

1. 在App Store（iOS）或Google Play（Android）搜索 “Bitwarden”

2. 安装应用

3. 打开App，点击设置图标

4. 选择 “Account” -> “Add Account”

5. 选择 “Self-hosted”

6. 填写服务器地址： https://vault.example.com

7. 登录或注册账户

5.5 客户端配置验证#

配置完成后，在任意客户端执行以下验证：

1. 在密码库中添加一条测试登录信息

2. 在另一设备登录同一账户

3. 确认数据同步成功

如果同步失败，检查：

• 服务器是否正常运行： docker compose ps

• 客户端配置的服务器地址是否正确

• 网络连接是否正常

6.1 强密码设置#

主密码是保护所有数据的关键，应遵循以下原则：

• 长度：至少12位，推荐16位或更长

• 复杂性：包含大小写字母、数字、特殊字符

• 唯一性：不使用在其他网站用过的密码

• 不可预测性：避免使用字典词汇、生日、电话号码等

可以使用Bitwarden内置的密码生成器创建符合要求的主密码。

6.2 两步登录（2FA）#

两步登录是保护账户安全的重要手段，即使主密码泄露，攻击者也无法登录。

1. 登录Web Vault

2. 进入 “Settings” -> “Two-Step Login”

3. 点击 “Authenticator App (TOTP)”

4. 使用 authenticator App（如Google Authenticator、Authy）扫描显示的二维码

5. 输入App中显示的6位验证码确认绑定

建议：同时配置多个两步登录方式，如 authenticator app + 邮箱，作为备份方案。

6.3 备份策略#

数据备份：

bash

1
# 进入Vaultwarden目录
2
cd ~/vaultwarden
3

4
# 停止服务
5
docker compose stop
6

7
# 备份数据库
8
cp vault/data/vaultwarden.db vault/data/vaultwarden.db.backup.$(date +%Y%m%d)
9

10
# 备份配置文件
11
tar -czf vaultwarden.backup.$(date +%Y%m%d).tar.gz vault/ docker-compose.yml nginx/
12

13
# 重启服务
14
docker compose start

自动备份脚本（添加到crontab）：

bash

1
# 编辑crontab
2
crontab -e
3

4
# 添加每日凌晨3点备份任务
5
0 3 * * * cd ~/vaultwarden && docker compose stop && cp vault/data/vaultwarden.db vault/data/vaultback-$(date +\%Y\%m\%d).db && docker compose start && find ~/vaultwarden/vault/data -name "vaultback-*.db" -mtime +7 -delete

6.4 HTTPS强制#

确保所有客户端都配置使用HTTPS访问服务器。Vaultwarden的Web Vault默认只允许HTTPS连接，如需额外的HTTPS强制，可以在Nginx配置中添加HSTS头。

6.5 登录失败限制#

Vaultwarden内置了登录失败限制功能。可以通过环境变量配置：

yaml

1
environment:
2
  # 失败5次后封禁15分钟
3
  FAILED_LOGIN_ATTEMPTS: 5
4
  # 封禁时间（秒）
5
  FAIL2BAN_TRACKED_HOSTS: 10
6
  FAIL2BAN_UNAUTH_VISIT_TIME: 10
7
  FAIL2BAN_CONSECUTIVE_FAILURES: 5

6.6 关闭公开注册（可选）#

如果服务器仅供个人或团队使用，可以关闭公开注册：

yaml

1
environment:
2
  SIGNUPS_ALLOWED: "false"

关闭后，新用户需要通过管理员面板创建：

1. 访问 https://vault.example.com/admin

2. 使用之前生成的admin token登录

3. 点击 “Users” -> “Add User” 创建新用户

7.1 版本更新步骤#

定期更新Vaultwarden以获取最新功能和安全修复：

bash

1
# 进入Vaultwarden目录
2
cd ~/vaultwarden
3

4
# 拉取最新镜像
5
docker compose pull
6

7
# 停止旧容器并启动新容器
8
docker compose up -d
9

10
# 清理旧镜像
11
docker image prune -f
12

13
# 查看当前版本
14
docker exec vaultwarden vaultwarden --version

建议设置订阅Vaultwarden的GitHub releases，第一时间获取更新通知。

7.2 监控与日志#

查看容器日志：

bash

1
# 实时查看日志
2
docker compose logs -f
3

4
# 查看最近100行日志
5
docker compose logs --tail 100
6

7
# 查看特定容器的日志
8
docker compose logs -f vaultwarden

可以将日志输出到日志管理系统（如ELK）进行集中分析。

7.3 数据库维护#

SQLite数据库长期使用后可能产生碎片，定期执行VACUUM：

bash

1
# 进入容器
2
docker exec -it vaultwarden sh
3

4
# 连接到数据库
5
sqlite3 /data/vaultwarden.db
6

7
# 执行VACUUM
8
VACUUM;
9

10
# 退出
11
.exit

7.4 迁移指南#

将Vaultwarden迁移到新服务器：

1. 在原服务器执行备份（参考7.3节）

2. 在新服务器安装Docker和Docker Compose

3. 复制备份文件到新服务器

4. 在新服务器执行相同目录结构和配置文件

5. 恢复数据库： cp vaultwarden.db.backup vault/data/vaultwarden.db

6. 启动服务： docker compose up -d

7. 更新DNS记录指向新服务器IP

8. 验证所有客户端可正常连接

8.1 容器启动失败#

问题：执行 docker compose up -d 后容器未启动

排查步骤：

bash

1
# 查看详细日志
2
docker compose logs vaultwarden
3

4
# 检查容器状态
5
docker ps -a
6

7
# 检查Docker是否正常运行
8
sudo systemctl status docker
9

10
# 检查端口占用
11
sudo netstat -tlnp | grep 8080

常见原因：

• 端口被占用：修改docker-compose.yml中的端口映射

• 配置文件错误：检查docker-compose.yml语法

• 权限问题：确保目录权限正确

8.2 邮件发送失败#

问题：注册账号或两步登录时无法收到邮件

排查步骤：

1. 检查SMTP配置是否正确

2. 查看Vaultwarden日志中的SMTP错误信息

3. 确认SMTP服务器允许发送邮件

4. 检查邮件是否被误判为垃圾邮件

解决方案：

• 使用可靠的SMTP服务（如SendGrid、Amazon SES、企业邮箱）

• 确认SMTP端口（587或465）正确

• 如果暂时不需要邮件功能，可以在配置中禁用SMTP相关的两步登录方式

8.3 同步问题#

问题：客户端数据无法同步

排查步骤：

1. 确认服务器正常运行

2. 检查客户端配置的服务器地址是否正确

3. 确认网络连接正常

解决方案：

• 重启客户端应用

• 清除客户端缓存后重新登录

• 检查服务器磁盘空间是否充足

• 查看Vaultwarden日志中的同步错误

8.4 性能优化#

内存占用高：

yaml

1
# 在docker-compose.yml中添加内存限制
2
services:
3
  vaultwarden:
4
    mem_limit: 1g
5
    memswap_limit: 1g

启动缓慢：

bash

1
# 使用特定版本的稳定镜像
2
image: vaultwarden/server:1.31.0

大文件上传超时：增加Nginx代理超时时间：

nginx

1
proxy_connect_timeout 300s;
2
proxy_send_timeout 300s;
3
proxy_read_timeout 300s;

8.5 数据恢复#

问题：忘记主密码

说明：由于端到端加密设计，服务器端无法恢复主密码。如果设置了2FA或紧急访问，可以通过其他方式尝试恢复。

解决方案：

• 如果有账户恢复选项（如Yubikey、Security Key），可使用恢复

• 如果设置了紧急访问联系人，联系人可以授予访问权限

• 如果都没有，唯一解决方案是重置账户（数据将丢失）

常用命令速查#

bash

1
# 启动服务
2
docker compose up -d
3

4
# 停止服务
5
docker compose down
6

7
# 重启服务
8
docker compose restart
9

10
# 查看状态
11
docker compose ps
12

13
# 查看日志
14
docker compose logs -f
15

16
# 更新版本
17
docker compose pull && docker compose up -d
18

19
# 进入容器
20
docker exec -it vaultwarden sh

关键目录结构#

plaintext

1
~/vaultwarden/
2
├── docker-compose.yml      # Docker编排配置
3
├── Caddyfile              # Caddy反向代理配置（可选）
4
├── vault/
5
│   ├── data/              # 数据库和配置数据
6
│   │   └── vaultwarden.db # SQLite数据库
7
│   └── logs/              # 日志文件
8
└── nginx/
9
    └── conf.d/            # Nginx配置
10
        └── vaultwarden.conf

环境变量速查表#