配置

关于配置

有三种配置方式:

  1. 通过管理页面 https://vault.yourdomain.com/admin 配置

  2. 通过直接修改管理配置文件 config.json 配置

  3. 通过在启动 Vaultwarden 容器时指定环境变量配置

一般通过管理页面来对 Vaultwarden 进行配置,因为比较直观。

注意:

  • 管理页面的设置会覆盖相应的环境变量值或 config.json 文件中的现有值

  • 管理页面的只读部分只能通过环境变量来设置

  • Vaultwarden 容器只有在启动的时候才会读取 config.json 配置文件,所以,直接修改 config.json 后,需要重启 Vaultwarden 容器才能使更改生效(重启命令:docker restart vaultwarden

管理页面点击 Save 后会自动在 vaultwarden-data 下生成/更新 config.json 文件。注意:只有值不为空的设置项才会出现在 config.json 文件中。

管理页面中各配置项说明

注意:管理页面的设置会覆盖相应的环境变量值或 config.json 文件中的现有值。保存后,建议停止设置环境变量以免造成混淆。这不适用于只读部分,只读部分只能通过环境变量进行设置。

General Settings

  • Domain URL:设置为访问服务器的 URL,包含「http[s]://」。如果没有这个值,一些服务器功能(如附件下载、电子邮件链接和 U2F 等)将无法正常工作。如果使用非默认端口,还需要指定端口号。示例:https://vault.yourdomain.com:28443

  • Allow Sends:控制是否允许用户创建 Bitwarden Send。此设置全局适用于所有用户。要对每个组织的进行控制,请使用「禁用 Send」组织策略。默认值:true

  • HIBP Api KeyHaveIBeenPwned API 密钥。在此处申请(收费服务)。无 HIBP 的话,密码库报告中的「数据泄露报告」无法使用

  • Per-user attachment limit (KB):对每个用户的附件存储空间限制在 xx KB 以内,达到限制后无法上传更多附件

  • Per-organization attachment limit (KB):对每个组织的附件存储空间限制在 xx KB 以内,达到限制后无法上传更多附件

  • Per-user send storage limit (KB):对每个用户的 Send 存储空间限制在 xx KB 以内,达到限制后无法上传更多 Send

  • Trash auto-delete days:在自动删除一个废弃项目之前等待的天数。如果不设置,废弃的项目就不会被自动删除。这是一个全局设置,所以请确保将这个设置的任何更改告知所有用户

  • Incomplete 2FA time limit:在启用了 2FA 的登录被认为不完整之前等待的分钟数,从而导致电子邮件通知。不完整的 2FA 登录是指提供了正确的主密码但未完成所需的 2FA 步骤,这可能表明主密码已泄露。设置为 0 以禁用此检查。此设置全局适用于所有用户。默认值:3

  • Disable icon downloads:设置为 true 将禁用图标下载,这将仍然为 $ICON_CACHE_FOLDER 提供图标服务,但不会产生任何外部网络请求。需要将 $ICON_CACHE_TTL 设置为 0,否则最终会删除图标,并且不会被再次下载。默认值:false

  • Allow new signups:控制新用户是否可以注册。用户可以被 Vaultwarden 管理员邀请,即使此功能被禁用。默认值:true

  • Require email verification on signups. This will prevent logins from succeeding until the address has been verified:注册时要求验证电子邮件。未验证前将无法成功登录。默认值:false

  • If signups require email verification, automatically re-send verification email if it hasn't been sent for a while (in seconds):如果设置了注册时验证电子邮件,设置自动重新发送验证电子邮件的时间间隔(单位秒)。默认值:3600

  • If signups require email verification, limit how many emails are automatically sent when login is attempted (0 means no limit):如果设置了注册时验证电子邮件,限制尝试登录时自动发送电子邮件的次数(0 表示无限制)。默认值:6

  • Email domain whitelist:限制只能某些域的电子邮件地址可以注册,以逗号分隔。将忽略 SIGNUPS_ALLOWED=false。示例:example.com,example.net

  • Org creation users:可以创建新组织的用户电子邮件列表,以英文逗号分隔。值为空或 all 表示所有用户均可以创建组织;none 表示所有用户均不可以

  • Allow invitations:控制组织管理员是否可以邀请用户,将忽略 SIGNUPS_ALLOWED=false。默认值:true

  • Allow emergency access:控制用户是否可以启用对其账户的紧急访问。此设置全局适用于所有用户。默认值:true

  • Allow email change:控制用户是否可以更改电子邮件地址。此设置适用于所有用户。默认值:true

  • Password iterations:服务器端密码散列迭代次数,新用户或当前用户更改密码时才会应用此设置。太高降低性能,太低主密码易被暴力破解,不建议低于 100000。默认值:100000

  • Allow password hints:控制用户是否可以设置密码提示。此设置全局适用于所有用户。默认值:true

  • Show password hints:控制密码提示是否直接显示在网页中。否则,如果电子邮件被禁用,则无法看到密码提示。默认值:true

  • Admin token/Argon2 PHC:定义用于登录管理页面的纯文本 Token 或 Argon2 PHC 字符串并启用管理页面。在这里更改它不会取消当前会话的授权。这里的值可以被在启动 Vaultwarden 容器时指定的环境变量值覆盖

  • Invitation organization name:定义非来自特定组织的邀请电子邮件中显示的名称。示例:Vaultwarden

Advanced Settings

  • Client IP header:客户端 IP 标头,用于标识客户端的 IP。如果为空,则使用远程 IP,设置为 none 将禁用任何标头及仅使用远程 IP。默认值:X-Client-IP

  • Icon redirect code:重定向到外部图标服务的 HTTP 状态代码。支持的代码有 301(传统永久)、302(传统临时)、307(临时)和 308(永久)。临时重定向在测试不同的图标服务时很有用,但一旦确定了一个服务,就应考虑使用永久重定向以利于缓存。目前 Bitwarden 客户端对传统代码的支持更好。

  • Positive icon cache expiry:已成功缓存的图标重新下载的间隔时间(单位秒),此时间后图标将被重新下载。0 表示不重新下载。默认值:2592000

  • Negative icon cache expiry:未成功缓存的图标重新下载的间隔时间(单位秒),此间隔后图标将重新尝试下载。0 表示不重新下载。默认值:259200

  • Icon download timeout:下载图标时的超时时间(单位秒)。默认值:10

  • Icon blacklist Regex:匹配此正则表达式的域名和 IP 的图标将不会被拉取。这对于隐藏本地网络中的其他服务器很有用。查看 wiki 以了解更多细节

  • Icon blacklist non global IPs:任何未被定义为全局 IP 的 IP 都将被列入黑名单。这对确保内部环境安全非常有用。有关它将阻止的 IP 列表,请参阅 Wiki。默认值:true

  • Disable Two-Factor remember:禁用它将强制用户每次登录时使用二次验证。注意复选框虽存在但会被忽略。默认值:false

  • Disable authenticator time drifted codes to be valid:禁用验证器时间漂移。启用此功能后,仅当前 TOTP 码有效,否则当前 TOTP 以及前 30 秒和后 30 秒的 TOTP 均有效。默认值:false

  • Require new device emails:用户登录时,需要发送电子邮件。如果发送电子邮件失败,登录也将失败。默认值:false

  • Reload templates (Dev):将此设置为 true 时,每个请求都会重新加载模板。这会降低服务器速度,仅在开发过程中使用它。默认值:false

  • Log timestamp format:日志的时间戳格式,参考日期和时间语法格式。默认值:%Y-%m-%d %H:%M:%S.%3f

  • (已改为放入 Read-Only Config 中)Bypass admin page security (Know the risks!):禁用管理页面的管理令牌,以便您可以在前端使用自己的认证方式。默认值:false

  • Allowed iframe ancestors (Know the risks!):允许将网页密码库嵌入到 iframe 中的域名列表,这对于嵌入到安全的内部网络中时有用

  • Admin session lifetime:设置管理员会话的生命周期值(单位分钟)

Yubikey Settings

  • Enabled:启用 Yubikey。默认值:true

  • Client ID:在此处申请的您的 YUBICO_CLIENT_ID

  • Secret Key:在此处申请的您的 YUBICO_SECRET_KEY

  • Server:自定义 OTP 服务器地址。值为空表示使用默认的 YubiCloud 服务器地址

Global Duo Settings

注意:用户可以覆盖这部分的设置

SMTP Email Seiings

注意:v1.25.0 版本之前的 Vaultwarden 有一个关于 SSL 和 TLS 的漏洞/错误标记的配置设置项。这已在后续测试版和新发布的版本中得到修复。

旧配置项是 SMTP_SSLSMTP_EXPLICIT_TLS

新配置项是 SMTP_SECURITY,它具有以下选项:starttlsforce_tlsoff

  • SMTP_SECURITY=starttls 等同于 SMTP_SSL=true

  • SMTP_SECURITY=force_tls 等同于 SMTP_EXPLICIT_TLS=true

  • Enabled:启用 SMTP。默认值:true

  • Use Sendmail:是否通过 sendmail 命令发送邮件。默认值:false

  • Sendmail Command:使用哪个 sendmail 命令。如果未指定,则使用在 $PATH 中找到的那个

  • Host:SMTP 服务器地址

  • (v1.25.0 及之后版本已移除)Enable Secure SMTP:(显式)启用此功能后,将默认使用 STARTTLS(一般为 587 或 25 端口)。默认值:true

  • (v1.25.0 及之后版本已移除)Force TLS:(隐式)启用此功能将强制使用 SSL/TLS 连接(一般为 465 端口),而不是使用 STARTTLS 升级的不安全的连接。Enable Secure SMTP 必须设置为 true,此设置才能起作用。默认值:false

  • Secure SMTP:启用安全连接。可用的值:starttls(显式 - 端口 587 或 25)、force_tls(隐式 - 端口 465)、off 不加密。默认值: starttls

  • Port:SMTP 服务器端口。默认值:587

  • From Address:发件人地址

  • From Name:发件人名称。默认值:Vaultwarden

  • Username:用户名

  • Password:密码

  • SMTP Auth mechanism:对于 SSL,默认值应为 PlainLogin;对于非 SSL,默认值应为空。可用的值:PlainLoginXoauth2。使用多个选项时需要用英文逗号「,」分隔

  • SMTP connection timeout:SMTP 连接超时时间(单位秒)。默认值:15

  • Server name sent during HELO:默认情况下,此值是机器的主机名,但可能需要更改以防触发某些反垃圾邮件过滤器

  • (已改为放入 Read-Only Config 中)Enable SMTP debugging (Know the risks!):危险:启用此功能会输出非常详细的 SMTP 信息。这可能包含敏感信息,如密码和用户名!仅在排除故障时才启用此功能。默认值:false

  • Accept Invalid Certs (Know the risks!):危险:允许无效证书。这个选项会带来严重的漏洞,导致中间人攻击!仅当您无法使用有效证书时才将此作为最后的手段。如果证书有效但主机名不匹配,请改用 SMTP_ACCEPT_INVALID_HOSTNAMES(即下面的 Accept Invalid Hostnames (Know the risks!))。默认值:false

  • Accept Invalid Hostnames (Know the risks!):危险:允许无效的主机名。这个选项会带来严重的漏洞,导致中间人攻击!仅当您无法使用有效证书时才将此作为最后的手段。默认值:false

  • Test SMTP:根据以上的设置,发送测试邮件到指定的电子邮件地址,测试 SMTP 功能

Email 2FA Settings

  • Enabled:禁用将阻止用户设置新的电子邮件 2FA 以及使用已配置的电子邮件 2FA。默认值:false

  • Email token size:电子邮件 Token 的位数(最小 6,最大 19)。请注意,无论这里设置为多少,Bitwarden 客户端都将其硬编码为 6 位数。默认值:6

  • Token expiration time:Token 的最大有效时间(单位秒)。用户必须在此时间内打开电子邮件客户端并复制 Token。默认值:600

  • Maximum attempts:重置电子邮件 Token 并发送新邮件之前的最大尝试次数。默认值:3

  • Automatically enforce at login:设置为电子邮件 2FA 提程序,而不考虑任何组织策略。默认值:false

  • Auto-enable 2FA (Know the risks!):在需要时自动将电子邮件 2FA 设置为备用提供程序。默认值:false

Read-Only Config

注意:这些选项无法在编辑器(以及管理页面)中修改,因为它们需要重新启动服务器。要修改它们,需要在启动服务器时设置正确的环境变量。您可以在每个选项的工具提示中检查变量名称。

  • Data folder:主数据文件夹。默认值:data

  • Database URL:数据库 URL。默认值:data/db.sqlite3

  • Icon cache folder:图标缓存文件夹。默认值:data/icon_cache

  • Attachments folder:附件文件夹。默认值:data/attachments

  • Sends folder:Send 文件夹。默认值:data/sends

  • Temp folder:用于存储临时上传的文件。默认值:data/tmp

  • Templates folder:模板数据文件夹,默认情况下使用嵌入式模板。默认值:data/templates

  • Session JWT key:会话 JWT 密钥。默认值:data/rsa_key

  • Web vault folder:网页密码库文件夹。默认值:web-vault/

  • Enable websocket notifications:启用 Websocket 通知。默认值:false

  • (v1.31.0 版本已移除)Websocket address:Websocket 服务器地址。默认值:0.0.0.0

  • (v1.31.0 版本已移除)Websocket port:Websocket 服务器端口。默认值:3012

  • Enable push notifications:启用推送通知。默认值:false

  • Push relay uri:推送中继的 URI

  • Push identity uri:推送身份验证的 URI

  • Installation id:来自 https://bitwarden.com/host 的安装 ID

  • Installation key:来自 https://bitwarden.com/host 的安装密钥

  • Job scheduler poll interval:作业调度线程检查工作运行的频率。如果设置为 0,则全局禁止调度作业。默认值:30000

  • Send purge schedule:检查是否有 Send 超过其删除日期的作业的 Cron 时间表。默认为每小时(每小时的第 5 分钟)。设置为空则禁用此作业。默认值:0 5 * * * *

  • Trash purge schedule:检查要永久删除的废弃项目的作业的 Cron 时间表。默认为每天(午夜后的第 5 分钟)。设置为空则禁用此作业。默认值:0 5 0 * * *

  • Incomplete 2FA login schedule:检查未完成 2FA 登录的作业的 Cron 时间表。默认为每分钟。设置为空则禁用此作业。默认值:30 * * * *

  • Emergency notification reminder schedule:向紧急访问的授予人发送过期提醒作业的 Cron 计划。默认为每小时。设置为空则禁用此作业。默认值:0 5 * * * *

  • Emergency request timeout schedule:授予已达到规定等待时间的紧急访问请求作业的 Cron 时间表。默认为每小时。设置为空则禁用此作业。默认值:0 5 * * * *

  • Event cleanup schedule:从事件表中清除旧事件的作业的 Cron 时间表。默认为每天。设置为空可禁用此作业。默认值:0 10 0 * * *

  • Auth Request cleanup schedule:从验证请求中清除旧的验证请求的作业的 Cron 时间表。默认为每分钟一次。设置为空可禁用此作业。默认值:30 * * * * *

  • Domain Set:表示域名是否由管理员设置,否则将使用默认值。默认值:false

  • Domain origin:域名 URL 源。例如 https://vault.yourdomain.com:8443/admin,其 Domian origin 是 https://vault.yourdomain.com:8443

  • Domain path:域名 URL 路径。例如 https://vault.yourdomain.com:8443/admin,其 Domian path 是 /admin

  • Enable web vault:启用网页密码库。默认值:true

  • Enable event logging:为组织启用事件日志。默认值:false

  • Invitation token expiration time (in hours):组织邀请令牌、紧急访问邀请令牌、电子邮件验证令牌和删除请求令牌的失效小时数(必须至少为 1。单位小时)。默认值:120

  • Events days retain:保存在数据库中的事件的天数。如果不设置,事件将无限期保留

  • Internal IP header property, used to avoid recomputing each time:内部 IP 标头属性,用于避免每次重新计算。默认值:true

  • Icon service:预定义的图标服务,选项包括:internalbitwardenduckduckgogoogle。要指定自定义图标服务,请设置一个带有 {} 实例的 URL 模板,使用域名替换。例如:https://icon.example.com/domain/{}internal 指的是 Vaultwarden 的内置图标获取实现。如果设置了一个外部服务,则对 Vaultwarden 的图标请求将返回 HTTP 重定向到外部服务上的相应图标。默认值:internal

  • _icon_service_url:图标服务 URL

  • _icon_service_csp:图标服务 CSP

  • Customize the enabled feature flags on the clients:这是一个要启用的以逗号分隔的功能标志列表。默认值:fido2-vault-credentials

  • Enable extended logging:启用扩展日志记录,这将在日志中显示时间戳和目标。默认值:true

  • Enable the log to output to Syslog:启用记录到 Syslog。默认值:false

  • Log file path:日志记录文件的路径。默认值:/data/vaultwarden.log

  • Log level:日志记录的级别。可用的值:tracetebuginfowarnerror 以及 off。为了减少日志数量,可以将级别设置为 warnerror。默认值:info

  • Enable DB WAL:启用数据库 WAL。关闭这个设置可能会导致性能变差,但如果在一些不支持 WAL 的外来文件系统上使用 Vaultwarden,可能会有帮助。在改变这个设置之前,请参阅项目 Wiki。默认值:true

  • Max database connection retries:在启动过程中重试数据库连接的次数,每次重试的间隔时间为 1 秒,设置为 0 表示无限制重试。默认值:15

  • Timeout when aquiring database connection:默认值:30

  • Database connection pool size:用于连接数据库的连接池的大小。默认值:10

  • Database connection init:创建新数据库连接时运行的 SQL 语句,主要对连接范围内的 pragmas 有用。如果为空,则使用数据库指定的默认值。默认值:空

  • Bypass admin page security (Know the risks!):禁用管理页面的管理令牌,以便您可以在前端使用自己的验证方式。默认值:false

  • Seconds between login requests:在启动速率限制之前,来自同一 IP 地址的登录和 2FA 请求之间的平均秒数。默认值:60

  • Max burst size for login requests:在保持 login_ratelimit_seconds 指示的平均值的情况下,允许最多此大小的突发请求。注意,这同时适用于登录和 2FA,所以建议至少允许 2 个突发请求。默认值:10

  • Seconds between admin requests:在启动速率限制之前,来自同一 IP 地址的管理请求之间的平均秒数。默认值:300

  • Max burst size for admin requests:在保持 admin_ratelimit_seconds 指示的平均值的情况下,允许最多此大小的突发请求。默认值:3

  • Enable groups (BETA!) (Know the risks!):为组织启用群组支持(目前存在已知问题!)。默认值:false

  • Application Key (generated automatically):Duo 相关的密钥,由系统自动生成(启用 Duo 后)

  • DEPRECATED smtp_ssl:请使用 SMTP_SECURITY

  • DEPRECATED smtp_explicit_tls:请使用 SMTP_SECURITY

  • _smtp_img_src:默认值:cid:

  • Enable SMTP debugging (Know the risks!):启用该选项将输出非常详细的 SMTP 信息。其可能包含敏感信息,如密码和用户名!仅在需要排除故障时才启用此功能!默认值:false

Backup Database

警告:此功能仅创建 SQLite 数据库的备份副本。这不包括完全恢复 Vaultwarden 实例可能需要的任何配置或文件附件数据。有关如何执行完整备份的详细信息,请参阅备份 wiki 页面。

管理页面可读写配置项与环境变量名称的对应

管理页面只读配置项与环境变量名称的对应

[备注]:管理页面的只读部分配置项只能通过环境变量进行设置。

最后更新于