Docker 部署与环境变量

部署前的最小准备

部署 Vaultwarden 只需要两样东西：一台能联网的常开主机，以及一个支持容器运行的环境。Docker 是事实上的标准选择，因为它把环境依赖打包在一起，不用在主机上装这一那一。如果你已经按《NAS DIY 指南》装过 Docker，这一步可以直接跳过。

确认两件事就可以动手：Docker 引擎与 compose 插件是否就绪，以及主机上是否预留了 1GB 左右的空闲空间。Vaultwarden 本身吃内存很小，日常运行占用通常在 100MB 以内，这也是它适合小主机的原因。主机的系统选什么发行版并不重要，能用包管理器装上 Docker 就行。

如果你用的是群晖，也可以在套件中心装好容器管理器，然后以图形方式部署，原理与命令行完全一致，可参考《Synology DSM 指南》中的容器章节。无论哪条路，最终跑起来的都是同一个镜像。

compose 文件长什么样

推荐用 compose 文件部署，因为所有的配置都写在一个文件里，升级和迁移都方便。下面是一份可直接使用的最小配置：

services:
  vaultwarden:
    image: vaultwarden/server:1.32.0
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      - DOMAIN=https://vault.example.com
      - ADMIN_TOKEN=请改成你自己的强密码
    volumes:
      - ./vw-data:/data
    ports:
      - 8080:80

把这段内容保存为 docker-compose.yml，然后在同目录下执行 docker compose up -d，容器就会在后台跑起来。整个部署过程通常不超过一分钟。注意这里的镜像标签写的是具体版本号而不是 latest，原因下面会讲。

后期升级、备份、排障都以这份文件为出发点，值得花十分钟认真读每一行的意思。下面把每一项的作用解释一遍：

DOMAIN 这一项要填最终访问用的完整域名，包括 https 前缀。它会影响客户端连接时的行为，填错了会出现各种奇怪的问题，务必在申请好域名后就确定下来。镜像标签固定版本号是为了升级可控：每次升级前看一眼发布说明，确认没有破坏性改动，再改标签拉新镜像。latest 看着省事，但某次自动更新引入兼容问题时你会毫无防备。

数据目录与持久化

挂载 /data 是整个部署里最关键的一行。Vaultwarden 的全部状态都在这个目录里：SQLite 数据库文件、附件、配置文件、RSA 密钥、网站图标缓存。只要这个目录还在，服务就可以在任何机器上重建。

反过来说，如果你忘了挂载，容器被删除的那一刻数据就没了。部署完成后先做一次检查，确认本地目录里出现了 db.sqlite3 这个文件，再继续后面的步骤。这是新手最容易踩的坑，值得我们多花两分钟确认。

理解容器与数据的分离是自建思维的重要一环：容器是一次性的，数据是永久的。抱着「容器可以随便删随便重建」的心态运维，出事的概率会大幅下降。

必须知道的环境变量

Vaultwarden 的配置项很多，但常用的只有一小撮。环境变量改完之后需要重启容器才生效，这一点在调试时容易忘。

关于数据库多说一句。SQLite 对家庭场景完全够用，几百条密码的压力对它不值一提，而且备份极度简单。除非你有几十个用户或者已经有一套现成的数据库基础设施，否则不需要折腾 MySQL 或 PostgreSQL，简单的方案才是能长跑的方案。数据库选型本质上是在为「未来的复杂性」买单，而家庭场景的未来往往并不会真的到来。

注册控制这一条值得单独强调。部署完成之后，任何知道你服务器地址的人都可以注册账号。家用场景下务必把它关掉，只通过管理员邀请的方式加入家庭成员。这既是为了安全，也是为了防止服务被陌生人当免费工具用。

端口与网络模式

默认配置把容器的 80 端口映射到主机的 8080。容器内部还有一个 WebSocket 端口，用于客户端的实时同步，通常与主端口共用，无需额外配置。除非你的网络环境有特殊要求，一般不需要改动端口设计。

绝大多数家庭部署会选第一种：Vaultwarden 只监听本地，由前面的反向代理统一承接 HTTPS 与外部访问。这是下一章的主题。把端口暴露在公网上直接访问是常见的错误做法，既绕过了 HTTPS 的要求，也让攻击面凭空多出一个。

第一次启动与验证

容器跑起来之后，用浏览器打开 http://本机IP:8080 应该能看到登录页面。先别急着注册账号，花两分钟做完这两件事：确认数据目录里的文件已经生成；修改管理后台令牌并关闭公开注册。这两步做完，你的服务才算是处在安全状态。

看到登录页面意味着服务端已经正常工作。此时你可以装一个浏览器插件，在服务器地址里填上这个地址，试着注册一个自己的账号并保存一条密码。如果一切顺利，第一次同步成功的那一刻，整个部署就算完成了。顺手在客户端里确认一下同步状态指示，它会是将来判断服务健康与否的第一窗口。

部署过程中还有几个新手常犯的小错值得提前知道。DOMAIN 环境变量填错了会导致后续 HTTPS 配置混乱，所以上线前一定检查；防火墙忘了放行会让你怀疑是容器的问题，其实是网络层拦住了；在公网直接暴露容器端口而不走反向代理，既过不了 HTTPS 这一关，也不安全。把这些先记住，能少走不少弯路。

后续章节会讲 HTTPS、域名和备份，它们决定了这个服务能不能正式上线给家人用。在那之前，你现在拥有的是一个可用的、只在局域网内有效的密码服务原型。

遇到问题时怎么办

初次部署最常见的几类问题都有固定的排查路径。容器起不来多半是端口冲突或镜像拉取失败，先看 docker logs 的输出；能打开网页但客户端连不上，先怀疑 HTTPS 与域名配置；数据目录没生成文件，检查挂载路径是否写反。记住一条准则：先看日志再改配置，绝大多数线索都在日志的前几行里。

延伸阅读

• NAS DIY 指南：了解部署主机的选型与系统准备
• Synology DSM 指南：群晖用户用图形界面完成同样的部署