Vaultwarden 1.37.4 配置参数详解
Vaultwarden 1.37.4 全量配置参数详解：配置加载优先级、核心访问、注册与邀请控制、管理员认证、账户安全、SMTP 邮件、两步验证与 WebSocket 参数，标注真实默认值并附关键项实测回显。
Vaultwarden 1.37.4 配置参数详解
> 目标：读完本文后，你可以按需查找 Vaultwarden 1.37.4 各配置参数的默认值、作用与注意事项，并通过实测回显验证关键参数（注册开关、管理员令牌、DOMAIN、KDF 轮数）是否按预期生效。
一、环境信息
本文的默认值与回显均在下表环境实测核对，参数默认值同时对照了源码配置定义（config.rs）与官方 .env.template 模板。
| 项目 | 实测值 |
|---|---|
| 操作系统 | Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic） |
| Vaultwarden 版本 | 1.37.4（启动日志横幅 Version 1.37.4） |
| Web Vault 版本 | 2026.7.0 |
| 数据库 | SQLite 3.53.2（诊断页实测） |
| 数据目录 | /opt/data/vaultwarden |
| 服务端口 | 监听 80，对外 8222 |
| 部署形态 | 通过部署形态提供的环境变量注入配置（管理台 config.json 为另一途径） |
二、配置机制概览
2.1 参数从哪里来
Vaultwarden 的配置有三个来源，优先级从高到低：
- 数据目录中的 config.json：通过
/admin管理台修改保存时生成，运行时立即生效，不需要重启； - 环境变量：部署形态启动时注入，每个 config.json 中保存的驼峰式参数（如
signupsAllowed）都对应一个大写环境变量名（如SIGNUPS_ALLOWED）； - 内置默认值：两者都未设置时使用，本文表格中的「默认值」列即来自源码定义。
两个易踩的坑：其一，管理台改过的参数会被 config.json 固化，之后改环境变量不再生效，必须先在管理台删除该参数的覆盖；其二，敏感参数（ADMIN_TOKEN、SMTP_PASSWORD、YUBICO_SECRET_KEY 等）在 config.json 与诊断接口中都只显示遮罩值，不回显明文。
2.2 配置类型约定
- 布尔参数接受
true/false； - 未设置即为默认值的参数在表格中标注「可选」，表示可以留空不配；
- 带星号章节的示例命令均可直接执行验证。
三、核心访问参数
3.1 DOMAIN
| 参数 | 默认值 | 说明 |
|---|---|---|
| DOMAIN | http://localhost | 对外服务的完整地址（含协议与端口），影响邮件链接、附件下载令牌签发、管理台会话令牌签发、WebSocket 地址等 |
| DOMAIN_SET | false | 是否强制锁定域名（设为 true 后以 DOMAIN 为准，忽略请求头） |
| DOMAIN_ORIGIN | 自动取 DOMAIN 的协议+主机+端口 | 跨域场景单独指定 Origin |
| DOMAIN_PATH | 自动取 DOMAIN 的路径 | 反代挂在子路径时使用 |
默认值实测：未设置 DOMAIN 时，附件下载令牌的签发方标识为 http://localhost|file_download（解码实测下载链接中的 JWT 载荷）：
# echo 'eyJuYmYiOjE3OTIyMjQ2MzAsImV4cCI6MTc5MjIyNDY5MCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdHxmaWxlX2Rvd25sb2FkIiwic3ViIjoiZjhhZmEwNmMtN2FhYi00NDRmLTkyYTItNTczY2M5ZmNmMjJiIiwiZmlsZV9pZCI6ImQwMWU5Nzk5ZjYyNDU2OWU3ODRkIn0' | base64 -d
{"nbf":1792224630,"exp":1792224690,"iss":"http://localhost|file_download","sub":"f8afa06c-7aab-444f-92a2-573cc9fcf22b","file_id":"d01e9799f624569e784d"}
设置 DOMAIN=https://vault.example.com 后，管理台会话令牌的签发方变为 https://vault.example.com|admin：
# echo 'eyJuYmYiOjE3OTIyMjU4OTksImV4cCI6MTc5MjIyNzA5OSwiaXNzIjoiaHR0cHM6Ly92YXVsdC5leGFtcGxlLmNvbXxhZG1pbiIsInN1YiI6ImFkbWluX3BhbmVsIn0' | base64 -d
{"nbf":1792225899,"exp":1792227099,"iss":"https://vault.example.com|admin","sub":"admin_panel"}
要点：DOMAIN 必须写成用户浏览器实际访问的地址。写成内网地址或协议不一致，会导致邮件中的链接打不开、客户端 WebSocket 连接失败等问题；挂在反向代理子路径下时用 DOMAIN_PATH 指定路径部分。
四、注册与邀请控制
4.1 SIGNUPS_ALLOWED
| 参数 | 默认值 | 说明 |
|---|---|---|
| SIGNUPS_ALLOWED | true | 是否允许任何访客自行注册账户 |
这是公网部署必须关闭的第一项。实测关闭后（SIGNUPS_ALLOWED=false 并重建服务生效），两步注册流程的第一步即被拒绝：
# curl -s -w "\nHTTP %{http_code}\n" -X POST http://127.0.0.1:8222/identity/accounts/register/send-verification-email \
-H "Content-Type: application/json" -d '{"email":"user1@vaultwarden.local","name":"user1"}'
{"message":"Registration not allowed or user already exists","validationErrors":{"":["Registration not allowed or user already exists"]},"errorModel":{"message":"Registration not allowed or user already exists","object":"error"},"error":"","error_description":"","exceptionMessage":null,"exceptionStackTrace":null,"innerExceptionMessage":null,"object":"error"}
HTTP 400
日志同步记录（回显自实测）：
[2026-10-17 08:14:27.652][vaultwarden::api::identity][ERROR] Registration not allowed or user already exists
[2026-10-17 08:14:27.652][response][INFO] (register_verification_email) POST /identity/accounts/register/send-verification-email => 400 Bad Request
注意回显文案是「Registration not allowed or user already exists」，把「不允许注册」与「用户已存在」合并为同一提示，这是刻意的模糊处理，避免攻击者探测哪些邮箱已注册。
4.2 注册验证与域白名单
| 参数 | 默认值 | 说明 |
|---|---|---|
| SIGNUPS_VERIFY_EMAIL | false | 注册后是否强制邮箱验证（验证前不能登录） |
| SIGNUPS_VERIFY_RESEND_TIME | 3600 | 验证邮件重发间隔（秒） |
| SIGNUPS_VERIFY_RESEND_LIMIT | 6 | 验证邮件最大重发次数 |
| SIGNUPS_DOMAINS_WHITELIST | 空字符串 | 允许注册的邮箱域白名单，逗号分隔；为空不限制 |
组合建议：公网完全关闭注册用 SIGNUPS_ALLOWED=false；内部有限开放用 SIGNUPS_ALLOWED=true + SIGNUPS_DOMAINS_WHITELIST=corp.example.com；再叠加 SIGNUPS_VERIFY_EMAIL=true 确保邮箱真实存在。
4.3 INVITATIONS_ALLOWED 与邀请参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| INVITATIONS_ALLOWED | true | 管理员能否邀请外部邮箱加入组织 |
| INVITATION_ORG_NAME | Vaultwarden | 邀请邮件中的组织署名 |
| INVITATION_EXPIRATION_HOURS | 120 | 邀请令牌有效期（小时） |
| ORG_CREATION_USERS | 空（不限制） | 允许创建组织的用户邮箱白名单，逗号分隔；空表示所有用户都可创建 |
关闭开放注册后，团队新成员走「管理员邀请 → 受邀者设置主密码」路径，因此 INVITATIONS_ALLOWED 通常保持 true；如果组织成员完全由管理员在管理台手动建立，可将其设为 false。实测部署中两项均显式配置为 false/true（见部署指南中的 compose.yml）。
4.4 PASSWORD_ITERATIONS（KDF 轮数）
| 参数 | 默认值 | 说明 |
|---|---|---|
| PASSWORD_ITERATIONS | 600000 | 新注册用户的 PBKDF2-SHA256 迭代轮数；仅影响新用户，老用户保持注册时固化的值 |
三个实测锚点：
- 注册下限：1.37.4 拒绝 PBKDF2 轮数低于 100000 的注册请求，实测提交 5000 轮返回：
{"message":"Password iteration minimum is 100000","validationErrors":{"kdfIterations":["Password iteration minimum is 100000"]},"errorModel":{"message":"Password iteration minimum is 100000","object":"error"},"error":"","error_description":"","exceptionMessage":null,"exceptionStackTrace":null,"innerExceptionMessage":null,"object":"error"}
- 已注册用户查询 KDF 参数（prelogin 接口）返回注册时固化的 600000：
# curl -s -X POST http://127.0.0.1:8222/identity/accounts/prelogin -H "Content-Type: application/json" -d '{"email":"admin@vaultwarden.local"}'
{"kdf":0,"kdfIterations":600000,"kdfMemory":null,"kdfParallelism":null,"kdfSettings":{"iterations":600000,"kdfType":0,"memory":null,"parallelism":null},"salt":null}
- 未注册邮箱返回占位参数，且占位值随注册策略变化（实测：默认配置下 5000，关闭注册后 100000）：
# curl -s -X POST http://127.0.0.1:8222/identity/accounts/prelogin -H "Content-Type: application/json" -d '{"email":"nobody@vaultwarden.local"}'
{"kdf":0,"kdfIterations":100000,"kdfMemory":null,"kdfParallelism":null,"kdfSettings":{"iterations":100000,"kdfType":0,"memory":null,"parallelism":null},"salt":null}
客户端同时支持 Argon2id 作为 KDF（kdfType=1），由客户端在注册时选择；服务端参数 PASSWORD_ITERATIONS 只约束 PBKDF2 路径。
五、管理员与管理台参数
5.1 ADMIN_TOKEN
| 参数 | 默认值 | 说明 |
|---|---|---|
| ADMIN_TOKEN | 未设置（可选） | 管理台访问口令；支持两种形态：明文口令或 argon2id PHC 字符串（以 $argon2id$ 开头） |
| DISABLE_ADMIN_TOKEN | false | 设为 true 时完全关闭管理台（公网部署的保守选项） |
| ADMIN_SESSION_LIFETIME | 1200（秒） | 管理台会话有效期（20 分钟） |
实测部署采用 argon2id 形态（生成命令与完整回显见部署指南 2.2 节）：
$argon2id$v=19$m=65540,t=3,p=4$NXJIcE1kMURMRGZ3OTBYZDgrdlRSWFIwWXVsNElFdlU3V0ZtakZuWUF4ST0$jXhsLhviXX2rEyQmARrfcXrT3H75bs+0D0EPbqgVBnM
登录行为实测三连：
# 正确口令（生成哈希时用的明文）→ 200 + 会话 Cookie VW_ADMIN
HTTP/1.1 200 OK
# 错误口令 → 401，页面文案
Invalid admin token, please try again.
# 连续错误 → 429 限流（窗口 300 秒、突发 3 次）
HTTP/1.1 429 Too Many Requests
Too many requests, try again later.
安全提示：argon2 形态下数据库或配置泄露不会直接暴露口令；若用明文形态，任何读到配置的人即可进管理台。同时 DISABLE_ADMIN_TOKEN=true 是最保守的做法（彻底禁用管理台，配置全部走环境变量）。
5.2 IP_HEADER（真实客户端 IP）
| 参数 | 默认值 | 说明 |
|---|---|---|
| IP_HEADER | X-Real-IP | 从反向代理传递的头中取真实客户端 IP，用于日志与限流 |
| IP_HEADER_TRUSTED_PROXIES | local | 信任哪些代理来源（默认仅本机/内网） |
实测部署中反代显式设置 X-Real-IP，与服务端默认头一致。若不设置该头，日志中的 IP 是代理地址，fail2ban 封禁会误伤代理（《Vaultwarden 安全加固指南》第七章依赖此参数）。
六、账户安全与数据参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| SHOW_PASSWORD_HINT | false | 登录失败时是否向客户端回显主密码提示（公网建议保持 false，防枚举） |
| REQUIRE_DEVICE_EMAIL | false | 新设备登录是否要求邮箱确认 |
| SENDS_ALLOWED | true | 是否启用 Sends（临时文本/文件分享） |
| EMERGENCY_ACCESS_ALLOWED | true | 是否启用应急访问 |
| TRASH_AUTO_DELETE_DAYS | 未设置（可选） | 回收站条目超过该天数自动清除；未设置时使用默认清理周期 |
| USER_ATTACHMENT_LIMIT | 未设置（可选，字节） | 单用户附件总配额；不设置即不限 |
| ORG_ATTACHMENT_LIMIT | 未设置（可选，字节） | 单组织附件总配额 |
| ATTACHMENTS_FOLDER | 自动为数据目录下 attachments | 附件存储目录 |
| DATABASE_URL | 自动为数据目录下 db.sqlite3 | 数据库连接串，可切换 MySQL/PostgreSQL |
| ICON_CACHE_FOLDER | 自动为数据目录下 icon_cache | 网站图标缓存目录 |
| ICON_CACHE_TTL | 2592000（30 天） | 图标缓存有效期（秒） |
| ICON_CACHE_NEGTTL | 259200（3 天） | 抓取失败负缓存时间（秒） |
| ICON_DOWNLOAD_TIMEOUT | 10 | 图标抓取超时（秒） |
| DISABLE_ICON_DOWNLOAD | false | 是否禁用图标抓取（内网无出口时建议 true） |
实测数据目录与上述默认值吻合（ls -la 实测）：db.sqlite3（290816 字节）与 db.sqlite3-wal/db.sqlite3-shm（WAL 模式伴生文件）、attachments/（内含条目 UUID 子目录）、tmp/、rsa_key.pem（1675 字节，JWT 签名密钥）、compose.yml。icon_cache 目录在首次触发图标抓取前不存在。
附件实测：上传 48 字节文件后，落盘路径为 attachments/<条目UUID>/<附件ID>（实测 attachments/f8afa06c-7aab-444f-92a2-573cc9fcf22b/d01e9799f624569e784d），文件内容为客户端加密后的字节流；接口列表返回 size=48（48.00 bytes）。附件下载地址由服务签发带令牌的 URL，实测形如：
http://127.0.0.1:8222/attachments/f8afa06c-7aab-444f-92a2-573cc9fcf22b/d01e9799f624569e784d?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
七、SMTP 邮件参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| SMTP_HOST | 未设置（可选） | SMTP 服务器地址；不设置则邮件功能整体停用 |
| SMTP_SECURITY | starttls | 加密方式：starttls / force_tls / off；旧参数 SMTP_SSL 与 SMTP_EXPLICIT_TLS 已废弃 |
| SMTP_PORT | 按加密方式自动（force_tls=465，starttls=587，off=25） | 端口 |
| SMTP_FROM | 空字符串 | 发件地址（必填才能发信，如 vaultwarden@example.com） |
| SMTP_FROM_NAME | Vaultwarden | 发件人显示名 |
| SMTP_USERNAME / SMTP_PASSWORD | 未设置（可选） | SMTP 认证凭据 |
| SMTP_AUTH_MECHANISM | 未设置（可选） | 认证机制：Plain/Login/Xoauth2；默认自动协商 |
| SMTP_TIMEOUT | 15 | 发信超时（秒） |
| SMTP_EMBED_IMAGES | true | 邮件内嵌 Logo 图片 |
| SMTP_ACCEPT_INVALID_CERTS | false | 是否接受无效证书（仅测试环境，生产禁用） |
| SMTP_ACCEPT_INVALID_HOSTNAMES | false | 是否接受证书域名不匹配 |
| SMTP_DEBUG | false | 打印 SMTP 会话调试日志 |
邮件功能覆盖：邀请、注册邮箱验证、主密码提示回发、两步验证邮箱码、应急访问通知等。排错方法：发信失败时先看日志中的 SMTP 关键字错误行，再用 SMTP_DEBUG=true 观察完整会话。公网部署建议全部显式配置；仅内网使用且无需邮件时保持未设置即可（相关按钮会被客户端隐藏）。
八、两步验证参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| YUBICO_CLIENT_ID | 未设置（可选） | YubiKey 验证服务的 Client ID |
| YUBICO_SECRET_KEY | 未设置（可选） | YubiKey 验证服务的 Secret Key |
| YUBICO_SERVER | 未设置（可选） | 自建 YubiKey 验证服务地址；不设置用官方服务 |
| DUO_IKEY | 未设置（可选） | Duo Security Integration Key |
| DUO_SKEY | 未设置（可选） | Duo Security Secret Key |
| DUO_HOST | 未设置（可选） | Duo Security API Host |
配置说明：YubiKey 与 Duo 的开关由对应参数组是否完整填写决定（诊断页会显示启用状态，实测诊断页包含两步验证相关检查行）；TOTP（认证器）与邮箱验证码不需要服务端参数，开箱可用。YUBICO_SECRET_KEY 与 DUO_SKEY 属于敏感参数，管理台中仅显示遮罩值。
九、WebSocket 与通知参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| WEBSOCKET_ENABLED | true | WebSocket 实时通知开关；1.34.0 起通知功能内置常开，该参数保留用于兼容旧版本配置文件 |
实测诊断页包含 WebSocket 检查行。反向代理必须放行连接升级（Upgrade/Connection 头，见部署指南第五章），否则客户端退化为轮询同步。
十、关键项实测回显汇总
把本文最常被问到的「改了到底生效没有」汇总为一组可复制命令：
# 1) 注册开关生效验证（期望 HTTP 400 + Registration not allowed）
# curl -s -w "\nHTTP %{http_code}\n" -X POST http://127.0.0.1:8222/identity/accounts/register/send-verification-email \
-H "Content-Type: application/json" -d '{"email":"probe@vaultwarden.local","name":"probe"}'
{"message":"Registration not allowed or user already exists",...}
HTTP 400
# 2) 管理台口令验证（期望 401 或 429 为拒绝，200 + VW_ADMIN Cookie 为通过）
# curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:8222/admin \
-H "Content-Type: application/x-www-form-urlencoded" --data-urlencode 'token=<你的口令>'
200
# 3) KDF 参数验证（期望返回注册时固化的轮数）
# curl -s -X POST http://127.0.0.1:8222/identity/accounts/prelogin \
-H "Content-Type: application/json" -d '{"email":"<已注册邮箱>"}'
{"kdf":0,"kdfIterations":600000,...,"salt":null}
# 4) 服务能力开关与版本验证
# curl -s http://127.0.0.1:8222/api/config | head -c 200
{"version":"1.37.4",...
诊断页 /admin/diagnostics 一次能看到数据库版本（实测 SQLite 3.53.2）、运行形态、反向代理检测（实测「Uses a reverse proxy: No」为直连状态，接入反代后变化）、DNS、服务器时间与 HTTPS 状态，是核对配置生效的最快入口。
十一、参考链接
- Vaultwarden 官方 Wiki（Configuration 全量参数表）：https://github.com/dani-garcia/vaultwarden/wiki/Configuration-Overview
- 官方 .env.template 模板（逐参数注释）：https://github.com/dani-garcia/vaultwarden/blob/main/.env.template
- 官方 Wiki（管理台说明）：https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page
- Vaultwarden 源码仓库：https://github.com/dani-garcia/vaultwarden
- Have I Been Pwned（HIBP_API_KEY 申请）：https://haveibeenpwned.com/API/Key
- Yubico 验证服务（YUBICO_* 参数）：https://developers.yubico.com/OTP/
- Duo Security（DUO_* 参数）：https://duo.com/
- 本专栏相关：《Vaultwarden 介绍与选型指南》、部署指南、《Vaultwarden 安全加固指南》《Vaultwarden 运维手册》
- 相关文档：《Keycloak 配置参数详解》《OpenBao Docker Compose 部署指南》