Kyoo视频播放问题排查与解决方案

问题背景

在使用Kyoo视频管理平台(v4.7.1版本)时，用户遇到了无法播放视频的问题，系统显示"Resource not found"错误提示。这是一个典型的媒体服务器资源访问问题，可能由多种配置因素导致。

问题分析

从技术角度来看，这类问题通常涉及以下几个方面：

1. 文件路径映射错误：Docker容器内的路径与宿主机路径映射不正确
2. 权限问题：容器服务对媒体文件缺乏访问权限
3. 服务间通信故障：扫描器服务无法与API服务正常通信
4. 环境配置不当：关键环境变量设置错误

解决方案

经过多次尝试和验证，最终通过以下步骤解决了问题：

1. 完全清理旧有环境

   • 使用docker compose down --volumes命令彻底停止并删除所有容器及关联卷
   • 确保完全清除旧配置可能带来的影响

2. 重新安装Docker环境

   • 按照官方文档重新安装Docker引擎
   • 确保基础运行环境干净可靠

3. 获取最新配置文件

   • 下载全新的docker-compose.yml和.env配置文件
   • 避免旧配置文件中的潜在问题

4. 谨慎修改配置

   • 仅修改必要的路径映射配置
   • 在.env文件中仅更改必要的认证参数
     • API密钥(KYOO_APIKEYS)
     • 公开URL(PUBLIC_URL)
     • Discord认证相关参数

5. 重新启动服务

   • 使用docker compose up -d命令启动服务
   • 观察服务启动日志确认各组件正常运行

技术要点

1. 路径映射原则

   • 在docker-compose.yml中修改volume映射时，确保宿主机路径存在且可访问
   • 推荐使用.env中的LIBRARY_ROOT变量设置媒体库路径，而非直接修改compose文件

2. 权限管理

   • 虽然将权限设置为777可以临时解决问题，但不推荐生产环境使用
   • 应确保Docker容器用户有适当的文件访问权限

3. 服务依赖关系

   • 扫描器服务依赖于API服务
   • 确保服务启动顺序正确，网络配置允许服务间通信

最佳实践建议

1. 配置管理

   • 优先使用.env文件进行配置，而非直接修改docker-compose.yml
   • 对配置变更进行版本控制

2. 故障排查步骤

   • 首先检查docker compose logs获取详细错误信息
   • 验证网络连接和端口映射
   • 检查文件权限和路径映射

3. 维护建议

   • 定期更新Kyoo到最新版本
   • 备份重要配置和数据库
   • 考虑使用docker-compose.override.yml进行自定义配置，而非修改主文件

通过系统性的排查和规范的配置管理，可以有效避免类似Kyoo视频播放问题的发生，确保媒体服务器的稳定运行。