十分钟跑起 Vaultwarden:最简部署

前面两章我们把选型做完了：你决定把密码库交给自己的一台设备来跑。这一篇要解决的问题非常具体——怎么用最少的步骤，把 Vaultwarden 在你的设备上真正跑起来，并且跑稳。不需要你懂编程，也不需要你读源码，整个过程就是装环境、建目录、写一个配置文件、敲一条命令。跟着走一遍，十分钟之后，你会在浏览器里看到属于自己的密码库登录页，知道这台设备从此是你家最保险的保险箱。

准备：先确认设备上有 Docker

Vaultwarden 官方推荐的运行方式就是 Docker 容器。它本身是一个用 Rust 写的轻量服务，内存占用只有几十 MB,CPU 也几乎不挑，但要跑得稳，必须放在一台长期在线的设备上：一台家用 NAS、一台低功耗小主机、一只树莓派，甚至旁路由上那点空闲的 Docker 环境都行。选什么样的设备做常年开机的家用服务器，可以参考《家用 NAS 选购与上手指南》和《家用 NAS 家庭服务器搭建指南》里的讨论，家庭网络拓扑怎么规划也可以翻一翻《软路由实战手册》,这里我们只假设你的设备已经能开机、能联网，并且你能在上面敲终端命令。

安装 Docker 不用背参数：Ubuntu、Debian 这类系统可以用官方提供的一键安装脚本，跑一次就把引擎装上；装完顺手确认一下 compose 插件也在。之后所有操作都通过 compose 文件完成，不再需要手敲那一长串 docker run。验证环境是否就绪的方法很简单，在终端依次执行 docker version 和 docker compose version，两条命令都能打印出版本号，就说明环境没问题。如果其中一条报命令不存在，先把这个问题解决再往下走，后面所有命令都依赖这两个东西。

为什么官方坚持用 Docker 而不是让你直接装服务？原因有三个：版本固定，镜像标签写死，不会被系统包管理器悄悄升级；环境干净，服务依赖都封在镜像里，不污染你的系统；迁移容易，换一台设备只要把 compose 文件和数据目录搬过去，两分钟复原。对密码这种要求长期稳定运行的服务，这三点比什么都实在。

在设备上建一个专属目录

容器是一次性的，删了就没了，但数据必须留在宿主机上，所以动手前先挑一个目录。推荐放在你以后做备份时会顺手带上的位置，例如在用户家目录下建一个 vaultwarden 文件夹，里面再建一个 vw-data 子目录：

mkdir -p ~/vaultwarden/vw-data
cd ~/vaultwarden

这个 vw-data 目录是整个密码库的命根子：你的账号注册信息、保存的每一条密码、附件、服务端配置，全都会落在这里。以后谈备份，本质上就是把这个目录整体打包复制走；以后谈灾难恢复，本质上也是把这个目录还原到新设备上。目录名字你可以自己起，但路径里不要带中文和空格，省得以后写配置文件时被转义问题坑一次。建好之后用 ls 确认一下位置，把它记在你常用的备忘里，后面每一步都围绕这个目录展开。

如果你手上不止一台设备，这一步也要顺便想好：数据目录在哪台设备上，就意味着密码库的家在哪台设备上。选那台开机时间最长、硬盘最稳、备份最方便的，别选那台你三天两头要重装系统的。

编写 docker-compose.yml

在 vaultwarden 目录里新建一个名叫 docker-compose.yml 的文件，内容可以整段照抄，一行都不用改：

services:
  vaultwarden:
    image: vaultwarden/server:1.37.4
    container_name: vaultwarden
    restart: unless-stopped
    volumes:
      - ./vw-data:/data
    ports:
      - "8080:80"

逐行解释一下，以后你自己改起来心里有数。各字段的含义对照如下表：

image 这一行固定用 vaultwarden/server:1.37.4，这是当前稳定版，和官方 Bitwarden 客户端完全兼容，不要随手改成 latest，以免哪天不知不觉升级出意料之外的变化。restart: unless-stopped 的意思是设备重启后服务自动拉起，除非你手动把它停掉——密码库这种服务，就该这样躺着自己醒过来，而不是等你出差在外才想起来它没开机。

再补一个新手常踩的坑：目录权限。如果 vw-data 目录是用 root 身份建的，容器内进程可能写不进去，启动直接报权限错误。解决办法很简单，把目录属主改成你平时操作的那个用户，或者干脆在 mkdir 之后顺手调一下权限。第一次启动失败别慌，先 logs，再看权限，八成能找到答案，这三板斧就是后面排障的全部套路。

常见问题：第一次没跑起来怎么办

第一次部署翻车是常态，几个最常见的问题先告诉你答案。docker compose up -d 之后页面打不开，先 docker compose ps 看容器是不是真在 running;如果状态是 restarting，说明它在反复崩溃，用 docker compose logs 看具体报错，报错里写得很直白。端口被占用是最常见的一类，换一个宿主机端口，比如把映射改成别的空闲端口，记得后面浏览器访问时也跟着改。镜像拉不下来，多半是网络问题，换个网络环境或者先手动 docker pull 一次镜像，再回到 compose 启动。

数据目录里生成了一堆文件，但页面返回 500，一般是挂载路径写错了，检查 compose 里 volumes 那一行的相对路径，确认它指向的就是你建的 vw-data。还有一种情况，是你在错误的目录里执行了 docker compose up,compose 文件没被读到，终端会提示找不到配置文件——回到 docker-compose.yml 所在目录再执行一遍就好。这些问题的共同点是：不用重装系统，也不用重建镜像，改配置、看日志、重启动，三板斧基本能解决。把 docker compose logs 和 docker compose ps 这两条命令记牢，以后容器出任何问题，都是它们打头阵。

一条命令启动，浏览器验证

文件存好后，在同一个目录里执行启动命令：

docker compose up -d

第一次运行会从镜像仓库拉取镜像，耐心等进度条跑完。结束后执行 docker compose ps，看到这一行服务的状态是 running，容器就算活着了。这时候打开浏览器，访问「内网 IP 冒号 8080」这样的地址，协议是 http，例如设备内网地址是 192.168.1.10，就访问那个地址加 8080 端口，能看到 Vaultwarden 的网页登录界面，部署就算成功。

验证清单一共三条：网页能正常打开、docker compose ps 显示 running、服务日志里没有红色报错。三条都过才算跑通。如果页面打不开，先用 docker compose logs -f 看日志，绝大多数情况是 8080 端口被别的服务占了，或者 vw-data 目录权限不对，照着报错改即可。改完再 docker compose up -d，服务会自动重新加载配置。记住这个 logs 命令，以后排查任何容器问题都是它打头阵。

到这一步，你已经完成了三件事：跑起来了一个长期在线的服务、把数据和容器分开存、并且让服务在重启后自动恢复。这三件事看似平常，但它们正是「自建服务能不能用一年」和「能不能用一天」的分水岭。后面所有的 HTTPS、主密码、客户端，都是在这个稳定底座上往上叠，底座不晃，楼才盖得高。

部署完成后先别急着注册

内网裸跑只是万里长征第一步。此时网页走的是明文 http，你输入的任何信息在网络上都是裸奔的，手机用流量连过来尤其危险，所以正式启用之前，下一篇要先把 HTTPS 和反向代理配好。另外，首次注册会创建你的主账号，主密码到底怎么设才算安全、浏览器里攒了几年的旧密码怎么迁进来，后面三篇会逐一展开。你现在只需要确认两件事：服务能起来，数据目录里已经能看到生成的文件。确认之后，这台设备就正式成为你的私人密码服务器了，接下来的每一篇都是在这台服务器上添砖加瓦。

这一篇还有一个隐性收益：你顺便熟悉了 Docker 的基本节奏——建目录、写 compose、up、ps、logs。以后在这台设备上跑任何其他服务，都是这个套路，学会一次，终身受用。密码库只是你在这台设备上跑的第一个服务，不是最后一个。

等你跑顺了，后面加新服务时，你会发现整个过程几乎不用再学：还是那台设备，还是那个 Docker，还是那份 compose 文件，只是换个镜像名、换个端口。这就是把环境跑通之后的复利。

延伸阅读

• 常年开机的设备怎么选：家用 NAS 选购与上手指南
• 把服务装进家庭服务器：家用 NAS 家庭服务器搭建指南
• 下一步：给密码库配上加密通道，见下一篇《配置 HTTPS 与反向代理：让密码库走加密通道》。