Passbolt API升级后移动端认证失败问题分析与解决

问题现象

在Passbolt API从旧版本升级到4.9.1-1-ce版本后，用户遇到了移动端应用无法登录的问题。具体表现为：

• Web界面访问正常
• 浏览器插件工作正常
• 但移动应用始终提示登录失败

移动端调试日志显示应用尝试访问/password-expiry/settings.json接口时返回404错误，但实际上系统并未启用密码过期功能。

技术分析

移动端与API的交互机制

Passbolt移动应用在认证过程中会检查服务器功能模块的可用性。当检测到password-expiry模块时，会尝试获取其配置信息。即使该功能未在管理界面启用，移动端仍会进行此检查。

版本兼容性问题

在Passbolt 4.9.1版本中，API对功能模块的检测和处理逻辑有所变化。旧版本中创建的持久化卷可能包含与新版本不兼容的文件结构，导致部分API端点无法正常工作。

容器化部署的特殊性

Docker环境下，/usr/share/php/passbolt目录的持久化卷在早期版本中是必需的，但在新版本中可能成为升级障碍。这个目录如果保留旧版本文件，会导致：

1. 部分新版本文件无法正确部署
2. API路由配置不完整
3. 功能模块检测异常

解决方案

根本解决方法

1. 停止Passbolt容器服务
2. 移除旧的持久化卷：

   docker volume rm [volume_name]
   

3. 重新部署容器，让系统自动创建新的目录结构

注意事项

• 执行此操作前确保有完整的备份
• 新版本可能不再需要手动维护该目录
• 升级后建议全面测试所有客户端连接

经验总结

Passbolt在版本升级过程中，特别是容器化部署时，需要注意：

1. 检查旧版本的特殊目录需求是否在新版本中仍然适用
2. 持久化卷可能需要在主要版本升级时重建
3. 移动端应用与API的兼容性需要特别关注

这个问题提醒我们，在升级开源项目时，不仅要关注新功能的变化，还需要注意部署架构的演进和旧有配置的清理工作。