AzuraCast升级失败问题分析与解决方案

问题现象

在Docker环境下运行的AzuraCast系统从旧版本升级到最新稳定版时，部分用户遇到了系统无法正常启动的问题。主要报错信息显示PHP类加载失败，具体表现为无法找到AppFactory类文件。错误日志中会看到类似以下内容：

Warning: include(/var/azuracast/www/vendor/composer/../../src/AppFactory.php): Failed to open stream
Fatal error: Uncaught Error: Class "App\AppFactory" not found

问题根源

经过多个用户案例验证，该问题与AzuraCast的"自定义代码插件"功能有关。当系统配置文件中设置了COMPOSER_PLUGIN_MODE=true参数时，在升级过程中会导致依赖关系解析异常，进而引发核心类文件加载失败。

解决方案

临时解决方案

1. 进入AzuraCast安装目录
2. 编辑azuracast.env配置文件
3. 将COMPOSER_PLUGIN_MODE=true改为COMPOSER_PLUGIN_MODE=false
4. 保存后执行标准升级流程：

   ./docker.sh update-self
   ./docker.sh update
   

推荐升级流程

1. 执行升级命令./docker.sh update
2. 当升级程序询问"是否需要自定义配置"时，输入y确认
3. 在出现的配置选项中，确保关闭"自定义代码插件"功能
4. 继续完成升级过程

技术原理

AzuraCast的自定义插件系统通过Composer的插件机制实现。在升级过程中，当插件模式启用时，Composer会尝试优先加载用户自定义的依赖关系，这可能与系统核心依赖产生冲突。特别是在大规模版本升级时，依赖关系的变化可能导致核心类文件无法正确定位。

注意事项

1. 该问题在Ubuntu 22.04系统+Docker环境下较为常见
2. 问题不仅影响稳定版，也出现在滚动更新版中
3. 升级完成后，可以重新启用插件功能，但建议在下次升级前再次禁用

后续建议

对于长期运行的AzuraCast实例，建议：

1. 定期执行系统升级，避免累积过多版本差异
2. 升级前备份重要数据和配置文件
3. 关注官方更新日志，了解可能影响升级的已知问题

该问题的根本修复可能需要等待官方对插件系统的进一步优化。目前通过临时禁用插件功能的方案已被多个用户验证有效，可以作为标准升级流程的一部分。