用 Nginx Proxy Manager 为 Vaultwarden 配置 HTTPS

[!info] related notes [[vaultwarden|Vaultwarden]] Debian 部署 Homepage 和 Vaultwarden Nginx Proxy Manager MOC Vaultwarden prelogin 404 故障

目标

让 Vaultwarden 通过一个域名以 HTTPS 对外提供服务（如 https://pass.example.com），成功标准是：Bitwarden 客户端能注册/登录、保险库能实时同步、浏览器地址栏显示有效证书。

为什么必须做这一步：Vaultwarden 出于安全强制要求 HTTPS 才能创建账号等；直接用 http://IP:8080 会缺功能。见 [[vaultwarden]]。

前置条件

• 已按 debian-docker-deploy-homepage-vaultwarden 跑起 Vaultwarden 容器（容器名 vaultwarden，内部监听 80）。
• Nginx Proxy Manager（NPM）已部署并占用宿主 80/443，管理后台在 :81。见 nginx-proxy-manager-moc。
• 一个域名，其 A 记录已指向该主机公网 IP；主机 80/443 端口对外开放（Let’s Encrypt HTTP-01 校验需要 80）。
• NPM 与 Vaultwarden 在同一个 Docker 网络（同一 compose.yaml 默认满足），这样 NPM 能用容器名访问。

步骤

1. 确认 Vaultwarden 无需再对外暴露端口

交给 NPM 反代后，Vaultwarden 不必再把 8080:80 映射到宿主。可在 compose.yaml 中移除其 ports，只保留内部网络访问（更安全）：

  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    volumes:
      - ./vaultwarden/data:/data
    environment:
      - DOMAIN=https://pass.example.com   # 关键：改成你的实际 HTTPS 域名
      - SIGNUPS_ALLOWED=false             # 注册完务必关闭

2. 在 NPM 添加 Proxy Host

后台 Hosts → Proxy Hosts → Add Proxy Host：

• Domain Names：pass.example.com
• Scheme：http
• Forward Hostname / IP：vaultwarden（容器名，不是宿主 IP）
• Forward Port：80（Vaultwarden 容器内部端口，不是 8080）
• Advanced/选项：勾选 Block Common Exploits；勾选 Websockets Support（见下）

3. 开启 WebSocket 支持

Vaultwarden 用 WebSocket 推送保险库变更的实时同步（/notifications/hub）。必须在该 Proxy Host 勾选 Websockets Support，否则功能可用但多端同步会退化为轮询/不及时。

现代 Vaultwarden 把 WebSocket 与 HTTP 合并在同一端口 80，无需再单独暴露旧版的 3012 端口或设 WEBSOCKET_ENABLED。

4. 申请并强制 SSL

切到 SSL 选项卡：

• SSL Certificate：Request a new SSL Certificate
• 勾选 Force SSL、HTTP/2 Support、HSTS Enabled
• 同意 Let’s Encrypt 条款并填邮箱 → Save

5. 让 DOMAIN 生效

确认第 1 步的 DOMAIN 已是最终 HTTPS 地址后重启容器：

cd /opt/docker
docker compose up -d vaultwarden

验证

1. 浏览器访问 https://pass.example.com，证书有效、能打开 Web Vault。
2. Bitwarden 扩展/App 中「自托管环境」填该域名，能登录并同步。
3. 看日志确认无 404、握手正常：

docker logs -f vaultwarden
# 期望看到：POST /identity/connect/token => 200 / GET /api/sync => 200

常见问题

• 证书申请失败：多为 80/443 未从外部可达。检查云安全组、宿主 ufw/firewalld、80 端口未被占用。
• 502 Bad Gateway：NPM 与 Vaultwarden 不在同一网络，或 Forward 写成了宿主 IP:8080。改用容器名 vaultwarden:80 并确认同网络。
• 能登录但多端不同步/通知不动：忘勾 Websockets Support。
• 客户端报 prelogin/password => 404：与反代无关，是版本兼容问题，见 vaultwarden-prelogin-404。
• 改了 DOMAIN 后旧会话失效：iss 变化导致旧 token 作废，重新登录即可。