Passbolt 界面反复卡死——一个缺失的配置文件引发的三种故障模式
我在 Synology NAS 上用 Docker 跑 Passbolt——一个开源的团队密码管理器，前面
挂着一层 nginx 反向代理。连着几周的某个坏习惯让我头疼：Web 界面动不动就
卡死，返回 504 Gateway Timeout，偏偏在正需要密码的时候拒绝交出任何凭据。
这是追查那个卡死毛病到根因的记录——以及我自己那个”修复”又引出一个全新故障
模式的转折。
为什么这件事值得写
密码管理器是唯一一个不能掉链子的应用。当我正和客户谈到一半、需要服务器凭据 的时候，转圈的加载动画是绝对不能接受的。症状看起来毫无规律——有时正常、有时 504——但真正的根源只是一个缺失的文件，外加叠在上面的两个错误。如果你也在 Docker 里自托管 Passbolt，这三个坑里大概有一个正在前面等你。
症状：cron 卡住，界面跟着遭殃
Passbolt 每分钟跑一个 cron 任务处理它的邮件队列——找回链接、分享通知、测试 邮件。正常情况下一秒以内跑完。我这边每次要花 30–60 秒。
这为什么要紧？Passbolt 靠一组 PHP-FPM worker 提供 Web 界面。当 cron 任务在 发邮件时卡住，就会占住一个 worker。卡住的 cron 攒多了，worker 池就被耗尽—— 普通页面请求开始排队，nginx 超时，于是你看到 504。
日志把话说得很明白：
not starting: job is still running since ... (1m elapsed)根源一：GPG 指纹为 null
Passbolt 用服务器 GPG 密钥加密存储 SMTP 设置。要用这些设置，它必须知道用哪把
密钥解密——这个值来自 passbolt.gpg.serverFingerprint，由配置文件
/etc/passbolt/passbolt.php 提供。
这个文件不存在。
于是指纹解析成 null，SMTP 设置的 GPG 解密失败，每个想发邮件的 cron 迭代都
卡在这个失败上。健康检查把它摊开来给你看：
SMTP Setting errors: ... setDecryptKeyFromFingerprint():
Argument #1 ($fingerprint) must be of type string, null given队列里还有一封名副其实的死邮件——一条几个月前就耗尽重试次数、永远发不出去的
SMTP timeout 记录。它每一分钟都被重新扫描一遍，雪上加霜。
DELETE FROM email_queue WHERE sent = 0 AND send_tries >= 4;根源二：没活下来的修复（复发）
这里才是真正扎心的地方。这个 bug 我此前其实修过一次——通过在容器内部创建
/etc/passbolt/passbolt.php。两个星期后卡死回来了，文件也消失了。
原因：维护时我重建过容器，而 Docker 容器的可写层天生就是临时的。写进容器 文件系统（而不是挂载卷）的任何东西，都会在重建时消失。我的修复有效期和容器 一样长，而不是和部署一样长。
真正持久的三件套，全部活在容器之外：
- 一个位于宿主机上的配置文件，通过 bind mount 挂进镜像的
/etc/passbolt/passbolt.php：
<?php
return [
'App' => [
'fullBaseUrl' => env('APP_FULL_BASE_URL', 'https://pass.example.com'),
],
'passbolt' => [
'gpg' => [
'serverFingerprint' => 'A3DD9B762D48722C10CF88DDB5372E46A54E1419',
],
],
];- compose 里的 bind mount——让它在重建后存活的关键：
volumes:
- /volume1/docker/passbolt/session-config/passbolt.php:/etc/passbolt/passbolt.php:ro- 正确的环境变量名。我之前一直用
PASSBOLT_GPG_SERVER_FINGERPRINT，而 Passbolt 会静默忽略它。真正的变量是PASSBOLT_GPG_SERVER_KEY_FINGERPRINT——而且它要的是完整的 40 位指纹，不是截短的：
PASSBOLT_GPG_SERVER_KEY_FINGERPRINT: "A3DD9B762D48722C10CF88DDB5372E46A54E1419"根源三：我自己造成的重定向循环
卡死修好之后，我把 Passbolt 从 5.14.3 升到 5.15.0。然后，打开
https://pass.example.com/，浏览器直接报：
ERR_TOO_MANY_REDIRECTS我以为是升级弄坏了什么。其实没有。罪魁祸首是我留在配置文件里的 ssl.force：
'passbolt' => [
'ssl' => [
'force' => true,
],
],Passbolt 的 SSL 强制中间件会检查请求的 scheme，而在 TLS 终止型反向代理后面，
这个 scheme 永远是 http——因为代理（nginx）终结 TLS 连接后，把纯 HTTP
转发给容器。中间件看到 http，尽职尽责地重定向到 https://同一条URL，nginx
再把它当 http 转回来，循环往复，永无止境。
解法在于想清楚到底谁负责 SSL。如果反向代理已经在边缘强制 HTTPS，应用就不该
再强制一遍。把 ssl.force 从配置里删掉（把 TLS 交给 nginx），循环立刻消失。
这条通用规则不止适用于 Passbolt，所有挂在反向代理后面的应用都一样：要么代理
终结 TLS，要么应用自己终结——两者永不兼得。代理已经在处理的时候，千万别在
应用里再开 ssl.force。
换了我现在会怎么做
- 配置放进卷，不放容器。 我一旦用
docker exec写文件，就等于答应了下一次 重建时重做一遍。正确反应应当是：这东西需要扛过docker compose up吗？需要 就进 bind mount，而不是可写层。 - 先查真实的变量名。 那个指纹环境变量让我多走了弯路，因为我信了一个 Passbolt 根本不认的名字，而它不认的时候也不吭声。当某个配置值”不起作用”时，先去上游 文档核对准确的 key，再怀疑别的。
- 测公网 URL，别只信健康检查。 健康检查每次通过，却完全没发现重定向循环——
因为它从不走真实的公网代理路径。一条两秒的
curl -I就能立刻暴露问题。
结果
卡死消失了：cron 从 30–60 秒降到 1 秒以内跑完，邮件队列清空，Web 界面毫秒级 响应而不是 504。Passbolt 现在跑着最新的 5.15.0，所有 GPG 和 SMTP 健康检查全绿 ——而且这个修复是写成能扛过下一次容器重建的。
值得带走的经验：一个”偶尔卡死”的自托管服务，很少是真正的谜团。通常就是一个 缺失的配置值，只是以三种不同的方式浮出水面。修配置，不要修症状。
想要稳定的自托管基础设施？
如果你跑着 Passbolt、密码管理器、邮箱或仪表盘之类的服务，而且它们时不时抽风——界面 卡死、504、重启就消失的灵异问题——这正是我诊断和修复的范围。我熟悉 Docker、 反向代理和各种自托管技术栈，交付时会把一切整理成文档，让下一个人（或未来的你） 不用靠猜。
联系我：[email protected] 或 WhatsApp +60 12-797 2969，也可以看看我在 hoelee.com 做的事情。
