启用 Vaultwarden Admin 管理面板

[!info] related notes [[vaultwarden|Vaultwarden]] 用 NPM 为 Vaultwarden 配置 HTTPS 密钥派生函数（KDF） Debian 部署 Homepage 和 Vaultwarden

目标

开启 Vaultwarden 自带的 /admin 管理面板，用它管理用户、邀请、全局开关（如关闭注册）和诊断信息。成功标准是：访问 https://pass.example.com/admin，用管理令牌登录后看到管理界面。

前置条件

• Vaultwarden 已通过 HTTPS 对外（见 vaultwarden-nginx-proxy-manager-https）。admin 面板尤其敏感，务必在 HTTPS 下访问。
• 能编辑 compose.yaml 并重启容器。

步骤

1. 生成 Argon2 哈希令牌（推荐）

不要直接用明文当 ADMIN_TOKEN。用 Vaultwarden 内置命令生成 Argon2id 哈希（PHC 字符串），即使 compose.yaml 泄露也不暴露原始令牌：

docker exec -it vaultwarden /vaultwarden hash
# 按提示输入你自定义的管理密码，输出形如：
# $argon2id$v=19$m=65540,t=3,p=4$....

原理与 KDF 一致：面板校验时对输入口令做 Argon2 比对，而非存明文。

2. 写入环境变量

把整段哈希填入 ADMIN_TOKEN。注意 compose 中 $ 需转义为 $$，否则会被当作变量插值：

  vaultwarden:
    environment:
      - DOMAIN=https://pass.example.com
      - SIGNUPS_ALLOWED=false
      - ADMIN_TOKEN=$$argon2id$$v=19$$m=65540,t=3,p=4$$....   # 每个 $ 都写成 $$

若用 .env 文件或 shell 传入，转义规则不同；直接写在 compose.yaml 内联时用 $$。

3. 重启并访问

cd /opt/docker && docker compose up -d vaultwarden

浏览器打开 https://pass.example.com/admin，输入你在第 1 步设定的原始管理密码（不是那串哈希）登录。

面板能做什么

• Users：查看/邀请/删除用户、强制启用双因素、重置。
• 关闭注册：在设置中关掉 invitations/signups（等价于 SIGNUPS_ALLOWED=false），只允许邀请制。
• Diagnostics：查看版本、检查是否有新版本（辅助判断 兼容问题）、DNS/时间/WebSocket 自检。
• SMTP：配置并发送测试邮件，用于邀请与找回流程。

验证

• 用管理密码能登录 /admin；错误口令被拒。
• 在 Users 页能看到已注册账户。
• Diagnostics 中各项自检通过。

安全与常见问题

• 不用时关闭面板：把 ADMIN_TOKEN 从环境变量移除并重启，/admin 即整体禁用——长期不需要时这是最安全的状态。
• 务必只经 HTTPS 暴露：admin 面板权限极高，切勿走明文 http://IP。
• $ 未转义导致登录失败：compose.yaml 里哈希的 $ 没写成 $$，令牌被破坏。用 docker exec vaultwarden env | grep ADMIN_TOKEN 核对实际注入值。
• 忘记管理密码：重新执行第 1 步生成新哈希替换即可，不影响用户数据。