Linux安装配置Passbolt团队密码管理详解

本文深入剖析了在CentOS 7/8上成功部署Passbolt团队密码管理系统的三大核心难点与实战避坑指南：必须提前严格满足gpgme-devel安装、SELinux设为permissive、firewalld启用并放行HTTP/HTTPS这三项硬性环境条件；数据库必须全程使用utf8mb4字符集及对应配置，否则注册和导入将因字符串错误静默失败；SMTP邮件功能绝非可选，需精准匹配端口（465+SSL或587+TLS）、完整邮箱地址作为用户名，并用第三方邮箱授权码替代登录密码——任何一处配置偏差都会导致GPG初始化卡死、数据库连接中断或验证邮件无法发送，且系统往往只显示“灰按钮”或空白页而无明确报错，掌握日志排查技巧（如实时追踪PHP-FPM和MariaDB日志）才是高效排障的关键。

Passbolt 在 CentOS 7/8 上能跑起来，但默认脚本安装容易卡在 PHP 扩展、SELinux 或 firewalld 配置上——不是环境没调好，而是官方 install.sh 对系统状态假设太强。直接按文档顺序执行，90% 的失败都出在 GPG 初始化或数据库权限环节。

CentOS 7 安装前必须手动处理的三个硬性条件

Passbolt 不接受“差不多可以”的环境。以下三项不提前确认，后续所有配置都会在 Web 安装器第 2 步（GPG 密钥生成）或第 4 步（数据库连接测试）报错退出：

• gpgme-devel 必须已安装，否则 GpgKeyGenerateController.php 会静默失败，页面只显示“密钥生成中…”无限转圈
• SELinux 必须设为 permissive（不是 disabled），否则 PHP-FPM 进程无法读取 /var/www/passbolt/config/app.php 中的 GPG 密钥路径
• firewalld 必须运行且已放行 http 和 https 服务，passbolt install 脚本内部会调用 firewall-cmd --permanent --add-service=http，若服务未运行则直接退出并报错 Failed to connect to bus

MySQL/MariaDB 创建数据库时的字符集陷阱

Passbolt 要求数据库使用 utf8mb4 字符集和 utf8mb4_unicode_ci 排序规则，否则用户注册或密码导入时会触发 SQLSTATE[HY000]: General error: 1366 Incorrect string value 错误。不能只靠 CREATE DATABASE passbolt; 简单建库：

CREATE DATABASE passbolt CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON passbolt.* TO 'passbolt'@'localhost' IDENTIFIED BY 'P4ssb0lt';
FLUSH PRIVILEGES;

同时需在 /etc/my.cnf.d/server.cnf 中追加：

[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
innodb_file_format = Barracuda
innodb_file_per_table = 1
innodb_large_prefix = 1

改完必须重启 mariadb，否则 Web 安装器仍会检测失败。

Web 安装器里填 SMTP 配置却收不到验证邮件？检查这三点

邮件功能在 Passbolt 中不是可选模块，管理员账户创建、用户邀请、密码共享全部依赖它。常见失效原因：

• SMTP 端口填了 465 却没选 “SSL/TLS” 加密方式（Web 安装器下拉菜单里叫 encryption），实际应选 ssl；若填 587 则必须选 tls
• EMAIL_TRANSPORT_DEFAULT_USERNAME 必须是完整邮箱地址（如 wbsu2003@88.com），不能只填用户名 wbsu2003
• 第三方邮箱（如 QQ、163、88）需开启“SMTP 服务”并使用“授权码”而非登录密码，这个授权码要填进 EMAIL_TRANSPORT_DEFAULT_PASSWORD 字段

Docker 部署时 /gpg 目录权限错误导致 GPG 初始化失败

用 Docker 快速启动 Passbolt 很方便，但官方镜像对 GPG 目录权限极其敏感。如果看到容器日志反复输出 gpg: can't open '/var/www/passbolt/config/gpg/serverkey.asc': Permission denied，问题不在挂载路径本身，而在宿主机目录权限：

必须确保宿主机上的 /volume2/docker/passbolt/gpg 目录对 UID 33（www-data 用户）可写。执行：

chmod 755 /volume2/docker/passbolt/gpg
chown 33:33 /volume2/docker/passbolt/gpg

注意：不能用 chmod 777，Passbolt 启动时会主动拒绝 world-writable 的 GPG 目录，直接退出并报错 Security check failed: gpg home directory is world writable。

Passbolt 的 GPG 密钥初始化、数据库字符集、邮件加密协议这三处，任一环节出错都不会给出明确提示，而是表现为“下一步按钮灰掉”或“页面空白”。遇到卡住，先查日志：tail -f /var/log/php-fpm/www-error.log 和 journalctl -u mariadb -n 50，比重装快得多。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。