Passbolt 5.16.0 配置参数详解
Passbolt 5.16.0 配置参数详解:环境变量与 passbolt.php 双层配置机制、DATASOURCES/APP_FULL_BASE_URL/GPG 密钥环/EMAIL/注册模式逐项实测、healthcheck 全量回显、自注册白名单 API 改动验证与生产配置模板,全部命令与回显实测于 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) |
| 服务器 IP | 192.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,否则可能破坏升级流程)。
二、前置条件
- 服务端已部署并可访问:
curl -kfs https://192.168.146.128:8113/healthcheck/status.json返回"code":200(部署步骤见《Passbolt 5.16.0 Docker Compose 部署指南》)。 - 已有至少一个管理员账号(首管理员注册流程见部署指南 4.5 节)。
- 能以 www-data 运行身份在 Passbolt 程序根目录执行命令(程序根目录即
bin/cake所在目录的上级,本文所有 CLI 命令都在该目录下执行)。 - 建议先跑一次基线健康检查留档,改配置后对比差异。
三、参数查看与修改方式
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_URL | https://192.168.146.128:8113 | healthcheck App.fullBaseUrl is set to HTTPS |
| DATASOURCES_DEFAULT_HOST/USERNAME/PASSWORD/DATABASE | db / passbolt / P4ssb0lt / passbolt | healthcheck Database 段全 PASS(55 tables found) |
| PASSBOLT_SSL_FORCE | true | healthcheck Passbolt is configured to force SSL use + 响应头 |
| PASSBOLT_GPG_SERVER_KEY_FINGERPRINT | 226CD536A314A96C54E0EBCBA5968499BA1A4E66 | healthcheck GPG 段全 PASS |
| EMAIL_TRANSPORT_DEFAULT_HOST/PORT/TLS | 192.168.146.128 / 1025 / false | send_test_email 发送成功 |
| EMAIL_DEFAULT_FROM / EMAIL_DEFAULT_FROM_NAME | passbolt@passbolt.local / Passbolt | 测试邮件发件人回显 |
| PASSBOLT_SECURITY_SMTP_SETTINGS_ENDPOINTS_DISABLED | true | healthcheck SMTP Settings plugin endpoints are disabled |
| PASSBOLT_EMAIL_VALIDATE_MX | false(默认) | healthcheck [WARN] Host availability checking is disabled |
| 注册模式(v5 自注册插件) | email_domains 白名单 passbolt.local | self-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
- 登录页响应头同时暴露 GPGAuth 协议端点声明(认证体系见《Passbolt 5.16.0 安全加固指南》):
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.asc2456 字节、serverkey_private.asc5091 字节,属主 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 不再生效。证据有二:
- healthcheck 明确回显
[PASS] The deprecated self registration public setting was not found in /etc/passbolt/passbolt.php.(deprecated 定性由官方输出给出); - 模板文件的 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 重新生成即可,服务端无需改动。
八、参考链接
- Passbolt 官方文档(配置与托管):
https://help.passbolt.com - Passbolt API 源码(config 目录含全部配置模板):
https://github.com/passbolt/passbolt_api - healthcheck 官方说明:
https://help.passbolt.com/faq/hosting/update#workaround-health-check - 《Passbolt 5.16.0 Docker Compose 部署指南》(部署形态与重启操作)
- 《Passbolt 5.16.0 安全加固指南》(GPG 密钥保护、审计日志与备份恢复)
- 《Passbolt 5.16.0 介绍与选型指南》(架构与选型背景)