Passbolt 5.16.0 配置参数详解

Passbolt 5.16.0 配置参数详解:环境变量与 passbolt.php 双层配置机制、DATASOURCES/APP_FULL_BASE_URL/GPG 密钥环/EMAIL/注册模式逐项实测、healthcheck 全量回显、自注册白名单 API 改动验证与生产配置模板,全部命令与回显实测于 2026-10-19。

Passbolt配置详解2026/10/19

Passbolt 5.16.0 配置参数详解

目标:讲清 Passbolt 5.16.0 服务端的两层配置机制(环境变量与 passbolt.php 文件),逐项实测数据库连接、站点地址、强制 HTTPS、GPG 密钥环、邮件投递、注册模式、角色权限与密码策略等核心参数,并对每一处改动给出验证回显。本文全部命令与回显实测于 2026-10-19,部署过程见《Passbolt 5.16.0 Docker Compose 部署指南》。

一、环境信息

项目值
Passbolt 版本5.16.0(CE,官方最新稳定版,发布于 2026-09-17)
服务器 IP192.168.146.128
服务地址https://192.168.146.128:8113
配置方式环境变量(本部署形态未使用 passbolt.php 文件)
配置目录/etc/passbolt/
运行身份www-data
验证工具bin/cake passbolt healthcheck、send_test_email 及 REST API

一个关键事实先说清楚:本部署形态下 /etc/passbolt/passbolt.php 文件并不存在,全部配置由环境变量承载(实测 ls /etc/passbolt/ 仅有 passbolt.default.php 模板而无 passbolt.php)。healthcheck 输出中「defined in /etc/passbolt/passbolt.php」一类文案属于通用提示语,实际取值来自环境变量。模板文件头部注释原文(实测摘录)说明了这一设计:

By default passbolt tries to use the environment variables or falls back to the default values as defined in default.php. You can use passbolt.default.php as a basis to set your own configuration without using environment variables.

即配置取值优先级为:环境变量 → passbolt.php(可选自定义文件)→ default.php 内置默认值,且模板注释明确警告 Do not modify default.php or you may break your upgrade process(不要修改 default.php,否则可能破坏升级流程)。

二、前置条件

  1. 服务端已部署并可访问:curl -kfs https://192.168.146.128:8113/healthcheck/status.json 返回 "code":200(部署步骤见《Passbolt 5.16.0 Docker Compose 部署指南》)。
  2. 已有至少一个管理员账号(首管理员注册流程见部署指南 4.5 节)。
  3. 能以 www-data 运行身份在 Passbolt 程序根目录执行命令(程序根目录即 bin/cake 所在目录的上级,本文所有 CLI 命令都在该目录下执行)。
  4. 建议先跑一次基线健康检查留档,改配置后对比差异。

三、参数查看与修改方式

3.1 查看:healthcheck 全量体检

su -s /bin/bash -c "bin/cake passbolt healthcheck" www-data

该命令输出按段落分组(Environment、Config files、SSL、SMTP Settings、JWT Authentication、GPG Configuration、Application configuration、Database、Metadata 等),是核对配置生效情况的第一手依据。实测输出节选(本次基线,尾部):

 JWT Authentication

 [PASS] The JWT Authentication plugin is enabled.
 [PASS] The /etc/passbolt/jwt/ directory is not writable.
 [PASS] A valid JWT key pair was found.

 GPG Configuration

 [PASS] PHP GPG Module is installed and loaded.
 [PASS] The environment variable GNUPGHOME is set to /var/lib/passbolt/.gnupg.
 [PASS] The directory /var/lib/passbolt/.gnupg containing the keyring is writable by the webserver user.
 [PASS] The server OpenPGP key is not the default one.
 [PASS] The public key file is defined in /etc/passbolt/passbolt.php and readable.
 [PASS] The private key file is defined in /etc/passbolt/passbolt.php and readable.
 [PASS] The server key fingerprint matches the one defined in /etc/passbolt/passbolt.php.
 [PASS] The server public key defined in the /etc/passbolt/passbolt.php (or environment variables) is in the keyring.
 [PASS] There is a valid email id defined for the server key.
 [PASS] The public key can be used to encrypt a message.
 [PASS] The private key can be used to sign a message.
 [PASS] The public and private keys can be used to encrypt and sign a message.
 [PASS] The private key can be used to decrypt a message.
 [PASS] The private key can be used to decrypt and verify a message.
 [PASS] The public key can be used to verify a signature.
 [PASS] The server public key format is Gopengpg compatible.
 [PASS] The server private key format is Gopengpg compatible.

 Application configuration

 [PASS] Using latest passbolt version (5.16.0).
 [PASS] Passbolt is configured to force SSL use.
 [PASS] App.fullBaseUrl is set to HTTPS.
 [PASS] Selenium API endpoints are disabled.
 [PASS] Search engine robots are told not to index content.
 [INFO] The Self Registration plugin is enabled.
 [INFO] Registration is closed, only administrators can add users.
 [PASS] The deprecated self registration public setting was not found in /etc/passbolt/passbolt.php.
 [WARN] Host availability checking is disabled.
 [HELP] Make sure this instance is not publicly available on the internet.
 [HELP] Or set the PASSBOLT_EMAIL_VALIDATE_MX environment variable to true.
 [HELP] Or set passbolt.email.validate.mx to true in /etc/passbolt/passbolt.php.
 [PASS] Serving the compiled version of the javascript app.
 [WARN] Some email notifications are disabled by the administrator.
 [PASS] The session provider is php.
 [PASS] The database schema is up to date.
 [PASS] The edition served is CE.

 Database

 [PASS] The application is able to connect to the database
 [PASS] 55 tables found.
 [PASS] Some default content is present.
 [PASS] The database version is supported.
 [PASS] The model schema cache shows no discrepancies with the database schema.

 [PASS] No error found. Nice one, sparky!

输出中三类标记要区分:[PASS] 通过;[INFO] 信息提示(如注册关闭);[WARN] 建议关注但非故障(如 MX 校验关闭)。[HELP] 后跟的是处置建议命令。

3.2 修改:环境变量优先

  • 改环境变量后需重启服务进程生效(重启操作见《Passbolt 5.16.0 Docker Compose 部署指南》十、常用运维命令)。
  • 若不愿用环境变量,可复制模板生成自定义文件:cp /etc/passbolt/passbolt.default.php /etc/passbolt/passbolt.php,按模板内注释逐项填写。两种途径不要混用同一参数,避免排查时互相干扰。
  • 查看某参数当前定义:直接查模板与内置默认文件中的 env(...) 行,例如:
grep -n "PASSBOLT_SSL_FORCE" /etc/passbolt/default.php

实测回显:

429:            'force' => filter_var(env('PASSBOLT_SSL_FORCE', false), FILTER_VALIDATE_BOOLEAN)

3.3 CLI 工具一览

配置相关的常用子命令(均以 bin/cake passbolt <子命令> 形式执行):

子命令用途
healthcheck全量配置体检(见 3.1)
send_test_email发送测试邮件并显示调试信息
register_user生成用户注册链接
create_jwt_keys生成 JWT 密钥对
install执行数据库安装/迁移

每个子命令均可加 --help 查看当前版本的参数定义(v5 参数与旧版文档差异较大,务必先查 help,例见 5.5 节 send_test_email 实测)。

四、参数总览

本次实测涉及的核心参数(环境变量名 / 实测值 / 生效验证方式):

参数实测值验证方式
APP_FULL_BASE_URLhttps://192.168.146.128:8113healthcheck App.fullBaseUrl is set to HTTPS
DATASOURCES_DEFAULT_HOST/USERNAME/PASSWORD/DATABASEdb / passbolt / P4ssb0lt / passbolthealthcheck Database 段全 PASS(55 tables found)
PASSBOLT_SSL_FORCEtruehealthcheck Passbolt is configured to force SSL use + 响应头
PASSBOLT_GPG_SERVER_KEY_FINGERPRINT226CD536A314A96C54E0EBCBA5968499BA1A4E66healthcheck GPG 段全 PASS
EMAIL_TRANSPORT_DEFAULT_HOST/PORT/TLS192.168.146.128 / 1025 / falsesend_test_email 发送成功
EMAIL_DEFAULT_FROM / EMAIL_DEFAULT_FROM_NAMEpassbolt@passbolt.local / Passbolt测试邮件发件人回显
PASSBOLT_SECURITY_SMTP_SETTINGS_ENDPOINTS_DISABLEDtruehealthcheck SMTP Settings plugin endpoints are disabled
PASSBOLT_EMAIL_VALIDATE_MXfalse(默认)healthcheck [WARN] Host availability checking is disabled
注册模式(v5 自注册插件)email_domains 白名单 passbolt.localself-registration API PUT/GET 回显

五、核心参数分类详解

5.1 数据库连接(DATASOURCES_DEFAULT_*)

四个变量对应模板文件中的 Datasources.default 段(模板原文含默认值):

'Datasources' => [
    'default' => [
        'host' => env('DATASOURCES_DEFAULT_HOST', 'localhost'),
        'port' => env('DATASOURCES_DEFAULT_PORT', 3306),
        'username' => env('DATASOURCES_DEFAULT_USERNAME', 'user'),
        'password' => env('DATASOURCES_DEFAULT_PASSWORD', 'secret'),
        'database' => env('DATASOURCES_DEFAULT_DATABASE', 'passbolt'),
    ],
],

实测取值 host=db, username=passbolt, password=P4ssb0lt, database=passbolt,healthcheck 数据库段回显 The application is able to connect to the database、55 tables found。注意 DATASOURCES_DEFAULT_PORT 未显式设置时默认 3306。

5.2 APP_FULL_BASE_URL(站点基地址)

该值参与路由生成、注册链接拼接与域校验,必须与实际访问地址逐字符一致(含协议与端口)。实测教训:曾配置为另一网段地址导致请求空响应,改回 https://192.168.146.128:8113 并重启后恢复。验证回显(healthcheck):[PASS] App.fullBaseUrl is set to HTTPS.

5.3 PASSBOLT_SSL_FORCE(强制 HTTPS)

设为 true 后(default.php 第 429 行定义,见 3.2 节回显):

  • healthcheck 回显两行 PASS:Passbolt is configured to force SSL use 与 App.fullBaseUrl is set to HTTPS;
  • 实测响应头出现 HSTS(对任意页面路径均生效):
strict-transport-security: max-age=31536000; includeSubDomains
x-gpgauth-version: 1.3.0
x-gpgauth-login-url: /auth/login
x-gpgauth-logout-url: /auth/logout
x-gpgauth-verify-url: /auth/verify
x-gpgauth-pubkey-url: /auth/verify.json

5.4 GPG 密钥环与服务端密钥

服务端密钥相关的三个变量(模板原文):

'serverKey' => [
    'fingerprint' => env('PASSBOLT_GPG_SERVER_KEY_FINGERPRINT', ''),
    'public' => env('PASSBOLT_GPG_SERVER_KEY_PUBLIC', CONFIG . 'gpg' . DS . 'serverkey.asc'),
    'private' => env('PASSBOLT_GPG_SERVER_KEY_PRIVATE', CONFIG . 'gpg' . DS . 'serverkey_private.asc'),
],
  • 首次启动时自动生成 RSA 3072 服务端密钥,导出到配置目录 gpg/ 子目录(实测文件 serverkey.asc 2456 字节、serverkey_private.asc 5091 字节,属主 www-data)。
  • PASSBOLT_GPG_SERVER_KEY_FINGERPRINT 用于把指纹固定下来。实测指纹核对命令(在服务端密钥环上执行):
gpg --homedir /var/lib/passbolt/.gnupg --fingerprint 226CD536A314A96C54E0EBCBA5968499BA1A4E66
pub   rsa3072 2026-10-19 [SC]
      226C D536 A314 A96C 54E0  EBCB A596 8499 BA1A 4E66
uid           [ unknown] Passbolt default user <passbolt@yourdomain.com>
sub   rsa3072 2026-10-19 [E]

(回显首行的 WARNING: unsafe ownership on homedir 属于以 root 手工查询密钥环的正常提示,healthcheck 以 webserver 用户检查时无此告警。)

  • 核对生效:healthcheck GPG 段 13 项全 PASS(回显见 3.1 节),其中 The server key fingerprint matches the one defined in /etc/passbolt/passbolt.php 即指纹一致性校验。

5.5 邮件投递(EMAIL_*)

v5 的邮件变量是 EMAIL_TRANSPORT_DEFAULT_* 与 EMAIL_DEFAULT_*(模板原文见六、生产配置模板的 EmailTransport/Email 两段)。实测配置 host=192.168.146.128, port=1025, tls=false, from=passbolt@passbolt.local, from_name=Passbolt。

v5 版本重要变更:旧版文档中的 SMTP_HOST/SMTP_PORT 等前缀变量已废弃——实测在 5.16.0 服务端程序内检索不到对这些键的任何引用,配置后完全不生效(healthcheck SMTP 段会显示实际来源:[WARN] The SMTP Settings source is: env variables.)。

发送测试邮件验证(注意 v5 用法是必填参数 -r/--recipient,先用 --help 确认):

su -s /bin/bash -c "bin/cake passbolt send_test_email -r admin@passbolt.local" www-data

实测回显([250] queued 为远端 SMTP 服务器的入队应答):

[250] queued
 QUIT
The message has been successfully sent!

实测在 1025 端口的收信台收到测试邮件,发件人为 Passbolt <passbolt@passbolt.local>,与 EMAIL_DEFAULT_FROM* 一致。

另有一个安全开关:PASSBOLT_SECURITY_SMTP_SETTINGS_ENDPOINTS_DISABLED=true,关闭后 healthcheck 回显 [PASS] The SMTP Settings plugin endpoints are disabled.——禁用了通过 Web 界面改写 SMTP 配置的 API 端点,生产建议保持关闭(理由见《Passbolt 5.16.0 安全加固指南》)。

5.6 注册模式(v5 重要变更,含改动验证实测)

旧变量已废弃:PASSBOLT_REGISTRATION_PUBLIC=true 在 v5 不再生效。证据有二:

  1. healthcheck 明确回显 [PASS] The deprecated self registration public setting was not found in /etc/passbolt/passbolt.php.(deprecated 定性由官方输出给出);
  2. 模板文件的 DEMO 段仍保留 'registration' => ['public' => true] 示例,但 default.php 中该键已由 Self Registration 插件接管。

v5 的正确做法是通过 Self Registration 插件配置,设置存于数据库并由 API 管理。实测全过程(管理员会话):

查询当前设置:

curl -kfs -b <管理员会话Cookie> https://192.168.146.128:8113/self-registration/settings.json
{"body":{"provider":null,"data":null}}

provider: null 即注册关闭(与 healthcheck 的 Registration is closed, only administrators can add users 对应)。

尝试启用白名单时,字段名错误会得到明确的校验回显(实测两次试错,报错信息本身就指明了正确键名):

{"body":{"provider":{"inList":"The provider should be part of the supported list: email_domains."}}}
{"body":{"data":{"allowed_domains":{"_empty":"The list of allowed domains should not be empty."}}}}

按正确字段名提交(允许 passbolt.local 域邮箱自助注册):

curl -kfs -b <管理员会话Cookie> -X PUT -H "Content-Type: application/json" \
  -d '{"provider":"email_domains","data":{"allowed_domains":["passbolt.local"]}}' \
  https://192.168.146.128:8113/self-registration/settings.json

实测回显:

{"body":{"id":"762c718a-d0f9-442f-b010-18b5ecd51595","provider":"email_domains","data":{"allowed_domains":["passbolt.local"]},"created":"2026-10-19T06:39:53+00:00","modified":"2026-10-19T06:39:53+00:00","created_by":"2372c161-abcf-46e3-8d1e-c0fdecaa6a16","modified_by":"2372c161-abcf-46e3-8d1e-c0fdecaa6a16"}}

再次 GET 回读,设置已持久化(改动项验证通过):"provider": "email_domains", "data": {"allowed_domains": ["passbolt.local"]}。白名单域名应写为组织真实邮件域(如公司域名),匹配该域的邮箱才可自助注册。

5.7 角色与权限

Passbolt 内置三种角色,权限自高到低:

角色能力
admin组织管理:用户审批、组管理、全部资源管理与系统设置
user密码业务:创建/编辑/共享自己有权限的资源,参与组协作
guest受限访客态,用于注册/恢复等中间流程

实测验证(管理员会话请求用户列表):

curl -kfs -b <管理员会话Cookie> https://192.168.146.128:8113/users.json
admin@passbolt.local → admin
bob@passbolt.local → user
charlie@passbolt.local → admin

角色在创建用户时指定:bin/cake passbolt register_user ... -r admin(-r 取值 admin/user)。组与共享权限模型(组管理器、共享再加密机制)的实操见《Passbolt 5.16.0 安全加固指南》。

5.8 密码策略

v5 将密码策略交由 Password Policies 插件管理,插件默认启用(内置默认文件中的定义,实测摘录):

'passwordPolicies' => [
    'enabled' => filter_var(env('PASSBOLT_PLUGINS_PASSWORD_POLICIES_ENABLED', true), FILTER_VALIDATE_BOOLEAN),
],

两层策略实测确认:

  • 用户密钥策略:注册时生成 RSA 2048 密钥会被服务端拒绝(实测 HTTP 400 回显 The key size must match security recommendations.),RSA 3072 及以上方可通过——该强校验对全部注册入口生效;
  • 口令生成器与复杂度策略:由管理员在 Web 界面的策略配置中调整并存库,对浏览器扩展生成口令的行为生效。

5.9 其他实用变量

  • PASSBOLT_EMAIL_VALIDATE_MX(默认 false):注册/恢复时校验邮箱域 MX 记录。默认关闭时 healthcheck 有对应 WARN 与 HELP 提示(回显见 3.1 节)。公网实例建议开启,内网实例(邮件域无法公网解析,如本实例的 passbolt.local)保持关闭属合理配置。
  • PASSBOLT_PLUGINS_SELF_REGISTRATION_ENABLED(默认 true):Self Registration 插件总开关,关闭后完全不可配置自注册。
  • GNUPGHOME:服务端密钥环路径,实测 healthcheck 确认为 /var/lib/passbolt/.gnupg 且可被 webserver 用户写入(回显见 3.1 节)。

六、生产配置模板

以下模板基于官方 passbolt.default.php(5.16.0 实测文件)的骨架,填入本实例实测值。使用方式:cp /etc/passbolt/passbolt.default.php /etc/passbolt/passbolt.php 后按需修改,或继续用环境变量(二选一):

<?php
return [
    'App' => [
        'fullBaseUrl' => env('APP_FULL_BASE_URL', 'https://192.168.146.128:8113'),
    ],
    'Datasources' => [
        'default' => [
            'host' => env('DATASOURCES_DEFAULT_HOST', 'db'),
            'port' => env('DATASOURCES_DEFAULT_PORT', 3306),
            'username' => env('DATASOURCES_DEFAULT_USERNAME', 'passbolt'),
            'password' => env('DATASOURCES_DEFAULT_PASSWORD', 'P4ssb0lt'),
            'database' => env('DATASOURCES_DEFAULT_DATABASE', 'passbolt'),
        ],
    ],
    'EmailTransport' => [
        'default' => [
            'host' => env('EMAIL_TRANSPORT_DEFAULT_HOST', '192.168.146.128'),
            'port' => env('EMAIL_TRANSPORT_DEFAULT_PORT', 1025),
            'timeout' => env('EMAIL_TRANSPORT_DEFAULT_TIMEOUT', 30),
            'username' => env('EMAIL_TRANSPORT_DEFAULT_USERNAME', null),
            'password' => env('EMAIL_TRANSPORT_DEFAULT_PASSWORD', null),
            'tls' => env('EMAIL_TRANSPORT_DEFAULT_TLS', false),
        ],
    ],
    'Email' => [
        'default' => [
            'transport' => 'default',
            'from' => [
                env('EMAIL_DEFAULT_FROM', 'passbolt@passbolt.local') => env('EMAIL_DEFAULT_FROM_NAME', 'Passbolt')
            ],
        ],
    ],
    'passbolt' => [
        'ssl' => [
            'force' => true,
        ],
        'gpg' => [
            'serverKey' => [
                'fingerprint' => '226CD536A314A96C54E0EBCBA5968499BA1A4E66',
                'public' => CONFIG . 'gpg' . DS . 'serverkey.asc',
                'private' => CONFIG . 'gpg' . DS . 'serverkey_private.asc',
            ],
        ],
    ],
];

要点:

  • 模板中每个 env('键名', 默认值) 表达式展示了变量名与缺省值,是排查「某个变量到底叫什么」的最权威依据;
  • 'ssl' => ['force' => true] 与环境变量 PASSBOLT_SSL_FORCE=true 等价(本实例走环境变量,文件中此项仅作对照);
  • 服务端密钥的公私钥路径默认即配置目录 gpg/ 子目录下的 serverkey.asc 与 serverkey_private.asc,与实测文件清单一致;
  • 生产替换清单:fullBaseUrl 换成对外域名(如 https://passbolt.example.com,配合反向代理与正式证书,参见《Authelia 4.39 介绍与选型指南》等反代认证组件的组网方式)、数据库口令换成强随机值、邮件服务器换成组织 SMTP(通常 tls=true、端口 587/465)。

七、常见问题

7.1 改了环境变量不生效

环境变量在服务进程启动时读取,修改后必须重启服务进程(重启方式见《Passbolt 5.16.0 Docker Compose 部署指南》十、常用运维命令)。重启后用 healthcheck 对应段落确认。

7.2 SMTP_HOST 等旧变量不生效

v5 已废弃 SMTP_* 前缀,改用 EMAIL_TRANSPORT_DEFAULT_*(详见 5.5 节实测)。判断当前生效来源看 healthcheck SMTP 段的 The SMTP Settings source is: ... 行。

7.3 PASSBOLT_REGISTRATION_PUBLIC 设了没反应

v5 起注册模式由 Self Registration 插件接管,旧变量废弃(healthcheck 会直接点名 deprecated,见 5.6 节证据)。用 5.6 节的 API 流程配置白名单。

7.4 healthcheck 的 WARN 都是故障吗

不是。实测基线中有三类 WARN 均属提示而非错误:SMTP source 为 env variables(来源声明)、Host availability checking is disabled(MX 校验关闭,内网实例合理)、Some email notifications are disabled by the administrator(默认通知策略)。逐条判断标准:有 [HELP] 行的按建议处置,无 HELP 且与实际使用场景相符的保留现状。

7.5 fullBaseUrl 与实际访问不一致

症状从「请求空响应」到「CSRF 校验失败」不等(本实例实测出现过空响应)。检查三处一致性:APP_FULL_BASE_URL、浏览器地址栏、反向代理传给后端的 Host。任何一处改动都要同步。

7.6 用户注册时密钥被拒

回显 The key size must match security recommendations.(HTTP 400):用户 GPG 密钥低于 RSA 3072。让用户在浏览器扩展中选择 RSA 3072 重新生成即可,服务端无需改动。

八、参考链接