Kindle Comic Converter (KCC) Docker 镜像依赖问题分析与解决方案

问题背景

Kindle Comic Converter (KCC) 是一款流行的漫画格式转换工具，它提供了 Docker 镜像以便用户快速部署和使用。近期用户反馈在运行最新版 Docker 镜像时遇到了模块缺失错误，提示缺少 natsort 模块。

错误现象

当用户尝试运行 KCC 的 Docker 镜像时，系统抛出以下错误：

Traceback (most recent call last):
  File "/opt/kcc/kcc-c2e.py", line 33, in <module>
    startC2E()
  File "/opt/kcc/kindlecomicconverter/startup.py", line 47, in startC2E
    from .comic2ebook import main
  File "/opt/kcc/kindlecomicconverter/comic2ebook.py", line 37, in <module>
    from natsort import os_sorted
ModuleNotFoundError: No module named 'natsort'

问题分析

经过深入调查，发现问题的根源在于 Docker 基础镜像的构建流程存在以下问题：

1. 依赖安装不完整：虽然 requirements.txt 文件中明确列出了 natsort 作为依赖项，但在构建过程中这些依赖并未被正确安装到最终镜像中。

2. 自动化构建流程失效：Docker 基础镜像的构建工作流已经超过5个月没有自动执行，导致依赖更新未能及时反映在镜像中。

3. 平台兼容性问题：特别是在 ARM/v7 架构平台上，还存在额外的依赖问题，如 psutil、python-slugify 和 Pillow 的版本不兼容。

解决方案

针对这些问题，开发团队采取了以下措施：

1. 手动触发构建流程：重新运行 Docker 基础镜像的构建工作流，确保所有依赖项被正确安装。

2. 依赖项验证：在镜像构建完成后，通过进入容器内部运行 pip list 命令验证所有依赖是否安装完整。

3. 多平台支持修复：针对 ARM/v7 架构的特殊问题，开发团队进行了专门的修复工作，确保跨平台兼容性。

验证结果

修复后，用户可以通过以下步骤验证问题是否解决：

1. 拉取最新版 Docker 镜像
2. 运行容器并检查依赖列表
3. 执行转换命令确认功能正常

经验总结

这个案例揭示了在持续集成/持续部署(CI/CD)流程中需要注意的几个关键点：

1. 定期检查自动化流程：确保构建工作流按预期运行，特别是在依赖更新后。

2. 全面的测试覆盖：不仅测试主要功能，还要验证依赖安装的完整性。

3. 多平台支持验证：对于支持多种架构的 Docker 镜像，需要分别验证各平台的兼容性。

4. 清晰的文档记录：维护详细的构建和部署文档，便于问题排查和团队协作。

后续改进

为了避免类似问题再次发生，建议采取以下长期改进措施：

1. 设置定期自动构建机制
2. 实现构建成功后的自动测试
3. 建立更完善的版本发布检查清单
4. 考虑引入多阶段构建优化 Docker 镜像

通过这次问题的解决，KCC 项目的 Docker 支持得到了显著改善，为用户提供了更稳定可靠的使用体验。