Jupyter Notebook科研协同与环境容器化：SRE视角的最佳实践 V2024.11.12
TL;DR: 本文面向科研团队，提供Jupyter Notebook在协同开发与环境容器化方面的SRE实践指南。核心在于利用Docker确保环境一致性，并通过Git实现内容版本控制与协同编辑，提升科研项目可复现性和团队效率。
前置条件
确保以下工具已安装并配置完成。
- Docker Engine (Version 24.0.5 或更高)
- Git (Version 2.30.0 或更高)
- Python (Version 3.8 或更高)
Note: 所有操作均在Linux或macOS环境下验证。Windows用户请确保WSL2已正确配置。
1. 环境容器化：Docker镜像构建与管理
为确保Jupyter Notebook运行环境的可复现性，应优先采用Docker容器化。这消除了“在我的机器上可以运行”的问题，简化了团队成员间的环境同步。
1.1 Dockerfile创建
在科研项目根目录下创建Dockerfile，指定基础镜像及所需依赖。
FROM jupyter/scipy-notebook:python-3.9.18
USER root
RUN apt-get update && apt-get install -y --no-install-recommends \
git \
vim \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
USER ${NB_UID}
WORKDIR "/home/${NB_USER}/work"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Expose Jupyter port (default 8888)
EXPOSE 8888
CMD ["jupyter", "notebook", "--port=8888", "--no-browser", "--ip=0.0.0.0", "--allow-root"]
Warning: 避免在Dockerfile中安装非必需的系统级依赖，以减小镜像体积和潜在安全风险。
1.2 `requirements.txt`配置
创建 requirements.txt 文件，记录Python项目依赖。
numpy==1.26.1
pandas==2.1.2
matplotlib==3.8.0
scikit-learn==1.3.2
ipykernel==6.26.0
1.3 Docker镜像构建
在项目根目录执行以下命令，构建Docker镜像。此步骤完成后，本地将有一个名为 research-jupyter:latest 的镜像。
docker build -t research-jupyter:latest .
预期输出:
...
Successfully built [image ID]
Successfully tagged research-jupyter:latest
1.4 Docker容器运行
运行Jupyter Notebook容器，并将本地项目目录挂载到容器内部，以便代码和数据能够持久化。
docker run -p 8888:8888 -v "$(pwd):/home/${NB_USER}/work" research-jupyter:latest
预期输出:
...
[I 2024-11-12 10:00:00.123 NotebookApp] The Jupyter Notebook is running at:
[I 2024-11-12 10:00:00.123 NotebookApp] http://[hostname or IP address]:8888/?token=[your-token]
...
通过浏览器访问上述URL即可进入Jupyter Notebook界面。
2. Git集成与科研协同
利用Git进行版本控制是实现科研代码和笔记协同的基础。解决Jupyter Notebook文件（.ipynb）合并冲突是关键。
2.1 项目初始化与版本控制
在项目根目录初始化Git仓库并添加所有文件。
git init
git add .
git commit -m "Initial commit of research environment and notebooks"
预期输出:
...
[main (root-commit) [commit ID]] Initial commit of research environment and notebooks
...
2.2 `.gitignore` 配置
为避免提交不必要的中间文件或敏感数据，配置.gitignore。
# Jupyter Notebook
.ipynb_checkpoints/
*.pyc
*.log
.DS_Store
# Data
data/
outputs/
Note: 数据文件通常不直接纳入Git仓库，可考虑使用Git LFS进行大文件管理，或通过共享存储挂载。
2.3 解决Jupyter Notebook合并冲突
Jupyter Notebook .ipynb 文件是JSON格式，直接合并可能导致冲突难以解决。推荐使用nbdime工具。
2.3.1 安装 nbdime
在本地环境（非Docker容器）安装nbdime。
pip install nbdime
nbdime config --enable --global
预期输出:
...
Configuring nbdime as the global difftool and mergetool.
...
2.3.2 使用 nbdime 解决冲突
当Git报告.ipynb文件存在合并冲突时，执行：
git mergetool
nbdime将启动一个基于Web的界面，允许逐个单元格地查看差异并选择合并策略。了解nbdime的使用是Jupyter Notebook科研协同的关键，能有效解决“Jupyter Notebook Git冲突怎么解决”这一常见问题。
Warning: 确保团队成员均配置了nbdime，以避免不必要的合并问题。
References
Jupyter Docker Stacks Documentation. (2023). https://jupyter-docker-stacks.readthedocs.io/en/latest/
nbdime Documentation. (2023). https://nbdime.readthedocs.io/en/latest/