Vaultwarden 私有密码库搭建终极指南

1616 字

8 分钟

Vaultwarden 私有密码库搭建终极指南

2025-11-07

Docker

Vaultwarden

从部署到安全加固：我的 Vaultwarden 私有密码库搭建终极指南#

序言：为何你需要一个私有的密码管理器？#

在当今的数字世界，我们每个人都拥有数十甚至上百个网络账户。如何安全、高效地管理这些密码，成了一个难题。虽然市面上有许多优秀的商业密码管理器，但将我们最核心的数字资产——密码，完全托管在第三方服务器上，总会让人心存一丝顾虑。

自托管（Self-Hosted） 给了我们一个两全其美的选择。Vaultwarden，作为一个与 Bitwarden API 兼容的、用 Rust 编写的轻量级开源项目，让我们可以在自己的服务器上搭建功能完整的私有密码库。

这篇文章，是我在部署和深度配置 Vaultwarden 过程中的全纪录。它不仅包含了从零开始的部署步骤，更涵盖了安全加固、邮件通知、后台禁用等一系列进阶的最佳实践。无论你是新手还是老玩家，相信都能从中有所收获。

准备工作#

一台云服务器 (VPS)，已安装 Docker 和 Docker Compose。
一个域名，用于配置 HTTPS 安全访问。
一个支持 SMTP 的邮箱，用于密码重置和通知。

第一章：基础部署 - Docker Compose#

我们采用 Docker Compose 进行部署，它能让我们用一个 YAML 文件清晰地管理所有配置。

创建项目目录

1
mkdir -p /data/docker/vaultwarden
2
cd /data/docker/vaultwarden

创建 .env 文件管理敏感信息 使用 .env 文件可以有效隔离密码等敏感信息，让 docker-compose.yml 保持干净。
Terminal window

nano .env ``` 在 .env 文件中，我们先定义好管理员后台的令牌。

1
**注意：** 为了安全，`ADMIN_TOKEN` 必须使用 Argon2 哈希值。
2

3
**如何生成哈希值？**
4

5
我们可以使用 `argon2` 命令行工具来生成安全的哈希值。如果你的系统没有安装，可以执行 `sudo apt install argon2` (Debian/Ubuntu) 来安装。
6

7
* **执行以下命令生成哈希**:
8

9
  ```bash
10
  echo -n "MySecretPassword" | argon2 "$(openssl rand -base64 32)" -e -id -k 65540 -t 3 -p 4
11
  ```
12

13
* 请将命令中的 `MySecretPassword` 替换为你自己想设置的、足够复杂的**原始密码**。
14

15
* 执行后，复制终端输出的那一长串以 `$argon2id$...` 开头的哈希字符串。
16

17
将生成的哈希值写入 `.env` 文件：
18
```env
19
# .env 文件内容
20
ADMIN_TOKEN='这里粘贴你生成的$argon2id$哈希字符串'
21
```

3. 编写 docker-compose.yml 文件

1
```bash

nano docker-compose.yml ``` 粘贴以下配置。这份配置经过优化，将端口绑定在 127.0.0.1，强制只能通过反向代理访问，更加安全。

1
```yaml
2
version: '3.7'
3

4
services:
5
  vaultwarden:
6
    image: vaultwarden/server:latest
7
    container_name: vaultwarden
8
    restart: unless-stopped
9
    volumes:
10
      - ./vw-data:/data
11
    ports:
12
      - "127.0.0.1:5555:80"
13
    environment:
14
      DOMAIN: "https://你的域名"
15
      WEBSOCKET_ENABLED: "true"
16
      SIGNUPS_ALLOWED: "true"
17
      ADMIN_TOKEN: ${ADMIN_TOKEN}
18
```
19
**注意：**
20
*   `ports`: `- "127.0.0.1:5555:80"` 中的 `5555` 是宿主机端口，你可以换成任何未被占用的端口。
21
*   `ADMIN_TOKEN: ${ADMIN_TOKEN}`: 这行代码会从 `.env` 文件中读取我们刚才设置的令牌。

4. 启动容器 bash docker-compose up -d

第二章：安全接入 - Nginx 反向代理与 HTTPS#

密码库绝对不能通过 HTTP 暴露在公网上。我们必须配置反向代理和 SSL 证书。

解析域名：将你的域名（如 key.yourdomain.com）A 记录解析到你的 VPS IP。

配置反向代理（以宝塔面板为例）：

新建一个网站，域名填写 key.yourdomain.com。
申请 Let’s Encrypt 证书，并开启强制 HTTPS。
在“反向代理”中，添加代理，目标 URL 填写 http://127.0.0.1:5555 (端口与 yml 中保持一致)。

关键一步：配置文件示例

1
location / {
2
    # 代理到你的 vaultwarden 容器所监听的 本机IP:端口
3
    proxy_pass http://127.0.0.1:5555;
4

5
    # --- WebSocket 支持 (关键！) ---
6
    # 允许协议从 HTTP 升级到 WebSocket
7
    proxy_set_header Upgrade $http_upgrade;
8
    # 设置 Connection 头，完成 WebSocket 握手
9
    proxy_set_header Connection "upgrade";
10

11
    # --- 传递真实信息给后端 ---
12
    # 传递真实的 Host 头，让后端应用知道用户访问的是哪个域名
13
    proxy_set_header Host $host;
14
    # 传递用户的真实 IP 地址
15
    proxy_set_header X-Real-IP $remote_addr;
16
    # 传递完整的代理链 IP
17
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
18
    # 传递协议信息 (http or https)
19
    proxy_set_header X-Forwarded-Proto $scheme;
20
}

配置完成后，你就可以通过 https://key.yourdomain.com 安全地访问你的 Vaultwarden 了。

第三章：功能完善 - 配置 SMTP 邮件服务#

配置邮件服务，可以让你在忘记主密码时进行账户恢复，或接收重要通知。

登录管理员后台：访问 https://key.yourdomain.com/admin。
输入原始密码：在登录框里，输入你生成哈希时使用的那个原始明文密码。
填写 SMTP 信息：
- 进入 Settings -> SMTP Email Settings。
- 根据你的邮箱服务商提供的信息，依次填写 Host, Port, Username, Password 等。
- 注意：Secure SMTP 选项，465 端口通常对应 force_tls，587 端口对应 starttls。
保存与测试：填写完毕后，滚动到页面底部点击 Save，然后再回到顶部点击 Test SMTP 发送测试邮件。

第四章：终极安全 - 按需开关管理员后台#

管理员后台功能强大，但也增加了攻击面。在日常使用中，我们应该将其禁用，只在需要时临时开启。

禁用后台：

停止服务：首先，停止 Vaultwarden 容器，确保数据文件不会被占用。
```
1
docker-compose down
```
注释环境变量：编辑 docker-compose.yml 文件，在 ADMIN_TOKEN: ${ADMIN_TOKEN} 这一行行首加上 # 将其注释掉。
移除持久化令牌：编辑数据目录中的 config.json 文件 (./vw-data/config.json)，找到并完全删除 “admin_token”: ” $argon2id$ …” 这一整行（别忘了处理上一行末尾的逗号）。
重新启动服务：
```
1
docker-compose up -d
```
现在访问 /admin 页面，会明确提示“后台已禁用”。