Mercury项目Docker部署问题排查与解决方案

背景介绍

Mercury是一个基于Python的交互式笔记本工具，允许用户将Jupyter Notebook转换为Web应用程序。在实际部署过程中，用户可能会遇到各种环境配置问题。本文将重点分析在Ubuntu系统上使用Docker部署Mercury时遇到的典型问题及其解决方案。

问题现象

在Ubuntu 22.04.5虚拟机上通过docker-compose部署Mercury时，主要遇到两个关键问题：

1. Mamba安装依赖失败：执行docker-compose build时，mamba无法正确解析requirements.txt文件中的特定包版本要求，特别是channels[daphne]和dj-rest-auth[with_social]这两个依赖项。

2. IPython兼容性问题：成功构建镜像后，运行演示脚本时出现IPython与execnb之间的兼容性问题，具体表现为InteractiveShell.run_cell()方法收到了意外的关键字参数cell_id。

问题分析

Mamba依赖解析问题

Mamba作为Conda的替代品，虽然提供了更快的依赖解析速度，但在处理某些特殊格式的依赖声明时可能存在限制。错误信息表明：

• 无法识别channels[daphne]的可选依赖格式
• 无法找到dj-rest-auth[with_social]的指定版本

这可能是由于conda-forge仓库中这些包的特定版本不可用，或者mamba对这些特殊语法支持不完善。

IPython兼容性问题

该问题源于IPython版本与execnb之间的API不兼容。较新版本的IPython修改了run_cell()方法的签名，不再支持cell_id参数，而execnb仍尝试传递此参数。

解决方案

修改Dockerfile

建议采用以下优化方案：

1. 升级基础镜像到Ubuntu 22.04以获得更好的Python 3.10支持
2. 使用pip替代mamba安装Python依赖
3. 保留mamba仅用于安装核心组件

示例Dockerfile关键修改：

FROM ubuntu:22.04

# 安装系统依赖
RUN apt-get update && apt-get install -y python3.10 python3-pip git 及其他必要依赖...

# 安装Miniconda
RUN wget -qO /tmp/miniconda.sh 下载地址 && \
    bash /tmp/miniconda.sh -b -p /opt/conda

# 使用conda安装核心组件
RUN conda install --yes python=3.10 mamba -c conda-forge
RUN mamba install --yes gunicorn psycopg2 daphne mercury -c conda-forge

# 使用pip安装其余依赖
RUN python3.10 -m pip install -r mercury/requirements.txt

调整requirements.txt

针对依赖问题，建议：

1. 移除可能导致问题的特殊语法依赖
2. 明确指定关键组件的版本

示例修改：

celery>=5.3.4
ipython>=7.31.1,<8.0.0  # 限制IPython大版本
ipywidgets==8.0.3  # 固定版本
dj-rest-auth==3.0.0  # 简化依赖声明
channels>=4.0.0  # 简化可选依赖

部署建议

1. 测试环境验证：先在本地venv环境中测试所有功能，确认无兼容性问题后再进行Docker化。

2. 版本控制：严格锁定关键依赖的版本，特别是IPython这类核心组件。

3. 日志监控：部署后密切监控容器日志，及时发现运行时问题。

4. 渐进式升级：对于生产环境，建议采用渐进式升级策略，先在小范围测试新版本。

总结