本文整理一套在 Linux 服务器上原生部署 Vaultwarden 的流程:从 Rust 源码编译可执行文件,由 systemd 管理服务进程,使用 SQLite 保存数据,并由 Nginx 提供 HTTPS 反向代理。全程不使用 Docker 或 Docker Compose。
示例以 Ubuntu/Debian、x86_64 或 aarch64、Nginx 和 SQLite 为参考。Vaultwarden、Rust、Web Vault 的版本和构建要求会变化,开始部署前请查看所选版本的 Vaultwarden 官方仓库及其 Wiki。文中
www.example.com、版本标签等均为示例,执行前需要替换为自己的值。原始记录没有保存最终使用的版本号和完整构建日志,因此本文提供的是可复用流程,不代表某台服务器当前状态。
一、部署架构
浏览器 / Bitwarden 客户端 | | HTTPS :443 v Nginx | | HTTP,仅监听本机 127.0.0.1:8000 v Vaultwarden 后端进程 | v SQLite 和附件程序、配置和持久化数据分开放置:
| 目录 | 用途 |
|---|---|
/opt/vaultwarden |
Vaultwarden 可执行文件 |
/etc/vaultwarden |
环境变量配置 |
/var/lib/vaultwarden |
SQLite 数据库、附件、Send 和密钥等数据 |
这种分离方式便于升级程序,也能降低误删数据的风险。Vaultwarden 后端只监听本机,公网请求由 Nginx 接收。
二、部署前检查
1. 确认系统和架构
cat /etc/os-releaseuname -muname -alscpudf -h常见架构对应的 Rust target 如下:
uname -m |
Rust target |
|---|---|
x86_64 |
x86_64-unknown-linux-gnu |
aarch64 |
aarch64-unknown-linux-gnu |
编译产物与系统架构、ABI 有关,不要把另一种架构或不兼容系统编译出的二进制直接复制过来。
2. 准备域名和 HTTPS
将用于访问 Vaultwarden 的域名解析到服务器,并确认公网 TCP 443 可达。使用 HTTP-01 申请证书时,还需要开放 TCP 80。证书可以按照本站的 Certbot 证书申请与自动续期教程先行申请。
三、创建专用用户和目录
创建不允许交互登录的系统用户,并准备程序、配置和数据目录:
sudo useradd --system \ --home /var/lib/vaultwarden \ --shell /usr/sbin/nologin \ vaultwarden
sudo install -d -o root -g root -m 755 /opt/vaultwardensudo install -d -o root -g vaultwarden -m 750 /etc/vaultwardensudo install -d -o vaultwarden -g vaultwarden -m 750 /var/lib/vaultwarden专用用户可避免服务长期以 root 身份运行。若用户或目录已经存在,先检查状态,不要重复创建或覆盖:
id vaultwardenls -ld /opt/vaultwarden /etc/vaultwarden /var/lib/vaultwarden四、安装 Rust 并编译 Vaultwarden
1. 安装构建工具
Ubuntu/Debian 示例:
sudo apt updatesudo apt install -y build-essential pkg-config curl git libssl-dev libsqlite3-dev不同 Vaultwarden 版本的系统依赖和编译特性可能不同。如官方构建说明要求其他依赖或选项,应以目标版本的说明为准。
2. 安装 Rust 工具链
以准备编译的普通用户执行 rustup 安装:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh按提示完成后加载 Cargo 环境,并确认版本:
source "$HOME/.cargo/env"rustc --versioncargo --version记录 Rust 版本,后续升级或重编译时便于复现构建环境。
3. 获取并固定源码版本
git clone https://github.com/dani-garcia/vaultwarden.gitcd vaultwardengit tag --sort=-v:refname | headgit checkout <确认过的版本标签>把占位文本替换为计划部署的正式版本标签。生产环境建议固定版本,而不是长期直接跟随不断变化的主分支。进入该版本后,先阅读仓库中的构建说明。
4. 编译并安装可执行文件
常见的 Rust release 构建命令如下,实际命令和 feature 选项要以所选版本官方说明为准:
cargo build --releasefile target/release/vaultwardenls -lh target/release/vaultwarden确认编译成功且架构符合服务器后,将程序安装到固定目录:
sudo install -o root -g root -m 755 \ target/release/vaultwarden \ /opt/vaultwarden/vaultwarden
/opt/vaultwarden/vaultwarden --help后端编译完成不一定代表 Web Vault 前端资源也已就绪。部署前要确认该版本的 Web Vault 准备方式、兼容版本、资源目录,以及由 Vaultwarden 还是 Nginx 提供静态文件。不要把其他版本的前端文件随意覆盖进来。
五、配置 Vaultwarden
创建环境变量文件:
sudo nano /etc/vaultwarden/vaultwarden.env示例配置:
ROCKET_ADDRESS=127.0.0.1ROCKET_PORT=8000
DOMAIN=https://www.example.comDATA_FOLDER=/var/lib/vaultwarden
# 生成强随机值后再填写,不要使用示例或弱口令ADMIN_TOKEN=替换为强随机令牌
# 仅在需要邮件功能时配置,并使用实际 SMTP 参数# SIGNUPS_ALLOWED=false# SMTP_HOST=# SMTP_FROM=# SMTP_FROM_NAME=# SMTP_USERNAME=# SMTP_PASSWORD=生成随机管理令牌的示例:
openssl rand -base64 48将输出填入 ADMIN_TOKEN,再将域名换成实际 HTTPS 地址。环境变量名称和支持情况以当前 Vaultwarden 版本文档为准。保护配置文件权限:
sudo chown root:vaultwarden /etc/vaultwarden/vaultwarden.envsudo chmod 640 /etc/vaultwarden/vaultwarden.env管理令牌、邮件密码等属于敏感信息,不要提交到 Git 或贴到公开日志中。
六、创建 systemd 服务
创建 unit 文件:
sudo nano /etc/systemd/system/vaultwarden.service写入:
[Unit]Description=Vaultwarden ServerAfter=network.target
[Service]Type=simpleUser=vaultwardenGroup=vaultwardenWorkingDirectory=/opt/vaultwardenEnvironmentFile=/etc/vaultwarden/vaultwarden.envExecStart=/opt/vaultwarden/vaultwardenRestart=on-failureRestartSec=5NoNewPrivileges=truePrivateTmp=true
[Install]WantedBy=multi-user.target通知 systemd 重新读取 unit,设置开机启动并立即启动服务:
sudo systemctl daemon-reloadsudo systemctl enable --now vaultwardensudo systemctl status vaultwarden查看启动日志:
sudo journalctl -u vaultwarden -n 100 --no-pager确认进程正常运行且监听在 127.0.0.1:8000 后再配置 Nginx。常用管理命令:
sudo systemctl start vaultwardensudo systemctl stop vaultwardensudo systemctl restart vaultwardensudo systemctl status vaultwardensudo journalctl -u vaultwarden -f七、配置 Nginx HTTPS 反向代理
下面配置展示 HTTP 跳转和 HTTPS 反向代理的基本结构。证书路径应替换成 Certbot 实际签发的路径,域名也应换成自己的域名。
server { listen 80; server_name www.example.com;
location ^~ /.well-known/acme-challenge/ { root /var/www/letsencrypt; default_type "text/plain"; try_files $uri =404; }
location / { return 301 https://$host$request_uri; }}
server { listen 443 ssl; server_name www.example.com;
ssl_certificate /etc/letsencrypt/live/www.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/www.example.com/privkey.pem;
location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; }}检查 Nginx 配置并平滑重载:
sudo nginx -tsudo systemctl reload nginxVaultwarden 的通知或 WebSocket 功能可能需要额外的 Upgrade/Connection 代理头,应按目标版本的官方反向代理配置补全。如果 Web Vault 静态资源由 Nginx 单独提供,还需要配置其静态目录。
八、验证部署
先在服务器本机检查后端是否响应:
curl -i http://127.0.0.1:8000/再从浏览器访问 https://www.example.com,确认 HTTPS 页面、静态资源、登录和 API 请求正常。若本机后端正常而公网返回 502,检查 Nginx 的 proxy_pass、Vaultwarden 监听地址和端口。
九、备份数据
至少要备份以下内容:
/var/lib/vaultwarden/:数据库、附件、Send 文件和生成的密钥。/etc/vaultwarden/:环境变量配置,备份时保护管理令牌和邮件密码。/etc/systemd/system/vaultwarden.service和 Nginx 站点配置。- 独立存放的 Web Vault 静态资源(如有)。
/etc/letsencrypt/:证书和私钥,备份时严格限制访问。
使用 SQLite 时,可在维护窗口停止服务后归档数据目录,避免复制时数据库仍在写入:
sudo systemctl stop vaultwardensudo tar -czf /root/vaultwarden-data-$(date +%F-%H%M%S).tar.gz \ -C /var/lib vaultwardensudo systemctl start vaultwarden备份完成后还应确认归档文件存在,并定期验证备份可恢复。仅把备份留在同一块磁盘上不能防止磁盘故障。
十、升级 Vaultwarden
升级前固定目标版本并阅读该版本的变更说明。建议按以下顺序操作:
- 记录当前程序版本和 Rust 工具链版本。
- 备份数据目录、环境变量、systemd、Nginx 配置和 Web Vault 资源。
- 获取目标版本源码,并按该版本说明完成编译。
- 停止服务并保存旧二进制。
- 安装新二进制及匹配的 Web Vault 资源。
- 启动服务并检查 systemd 日志、网页、登录、附件和通知。
- 若出现异常,结合版本的数据库迁移说明决定回滚方式。
二进制替换示例(在目标版本已成功编译后执行):
sudo systemctl stop vaultwardensudo cp -a /opt/vaultwarden/vaultwarden /opt/vaultwarden/vaultwarden.baksudo install -o root -g root -m 755 \ target/release/vaultwarden \ /opt/vaultwarden/vaultwardensudo systemctl start vaultwardensudo systemctl status vaultwardensudo journalctl -u vaultwarden -n 100 --no-pager如果新版本已迁移数据库,不能只回滚二进制就假设数据兼容;应按该版本说明恢复匹配的数据备份。
十一、常见问题
| 现象 | 排查方向 |
|---|---|
| systemd 启动失败 | 检查 systemctl status、journalctl、程序路径、执行权限和环境变量文件 |
Exec format error |
二进制架构与服务器架构不匹配 |
| Nginx 返回 502 | 检查 Vaultwarden 服务、监听地址、端口和 proxy_pass |
| HTTPS 无法访问 | 检查 DNS、80/443、防火墙、Nginx 语法和证书路径 |
| 页面打开但登录异常 | 检查 DOMAIN、代理头、后端日志及前后端版本匹配 |
| 静态资源加载失败 | 检查 Web Vault 是否部署、Nginx 静态目录和浏览器缓存 |
| 附件或 Send 异常 | 检查数据目录权限、磁盘空间和 DATA_FOLDER |
| 重启后数据丢失 | 确认数据使用持久化目录,而不是临时目录 |
常用排查命令:
sudo systemctl status vaultwarden --no-pagersudo journalctl -u vaultwarden -n 100 --no-pagerss -lntp | grep 8000sudo nginx -tsudo nginx -Tcurl -i http://127.0.0.1:8000/分享日志或配置前,删除管理令牌、密码和其他敏感值。

DISCUSSION
留言与交流
欢迎分享你的想法、经验,或提出与本文相关的问题。