Jupyter Notebook科研环境构建与可复现性实践：SRE视角下的版本控制与容器化 V2024.08.20

Roxi 加速器 — 稳定·快速·安全

全球节点覆盖，支持所有主流平台，一键连接无需配置。新用户免费试用。

立即体验 →

Version: 2024.08.20

1. 前置条件 (Prerequisites)

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux (Ubuntu 22.04 LTS), macOS, 或 Windows 10/11 (WSL2)
• Python 3.8+
• Git 2.30+
• Docker Desktop 4.20+ (或 Docker Engine)

2. Jupyter Notebook环境初始化与依赖管理

2.1 创建项目目录与虚拟环境

为每个科研项目创建独立的目录和Python虚拟环境，以避免依赖冲突。这是确保Jupyter Notebook科研笔记隔离性的基础。

mkdir -p ~/research_projects/my_project_alpha
cd ~/research_projects/my_project_alpha
python3 -m venv .venv
source .venv/bin/activate

Expected Output: (命令行前缀变为(.venv)，表示虚拟环境已激活)

(.venv) user@host:~/research_projects/my_project_alpha$

2.2 安装Jupyter Lab与核心依赖

安装Jupyter Lab以及项目所需的基础库。我们将使用pip install。请注意，requirements.txt是确保Jupyter Notebook依赖管理可复现的关键。

pip install jupyterlab matplotlib numpy pandas scikit-learn
pip freeze > requirements.txt

Expected Output: (部分输出)

Successfully installed ...
(.venv) user@host:~/research_projects/my_project_alpha$ cat requirements.txt
Jinja2==3.1.2
...

Note: requirements.txt应定期更新，尤其是在添加或移除依赖后。此文件将用于重建环境。

3. 版本控制与可复现研究实践

3.1 初始化Git仓库并配置忽略文件

使用Git对整个项目目录进行版本控制，包括Jupyter Notebook文件、数据和代码。.gitignore是必不可少的，用于忽略虚拟环境、大型数据集和敏感信息。

git init
echo ".venv/" >> .gitignore
echo "*.ipynb_checkpoints/" >> .gitignore
echo "data/*.csv" >> .gitignore # 示例：忽略原始大型数据集
git add .
git commit -m "Initial project setup with Jupyter and basic dependencies"

Expected Output: (部分输出)

Initialized empty Git repository in ...
[main (root-commit) 3a1b2c3] Initial project setup with Jupyter and basic dependencies
 4 files changed, 20 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 requirements.txt

3.2 运行Jupyter Lab并提交更改

启动Jupyter Lab进行科研工作。完成阶段性工作或重要更改后，务必提交到Git仓库。

jupyter lab --no-browser --port=8888

Expected Output:

[I ...] JupyterLab is running at: http://localhost:8888/lab?token=...
    Or copy and paste one of these URLs:
        http://localhost:8888/lab?token=...
        http://127.0.0.1:8888/lab?token=...
Press Ctrl-C to stop and shut down all kernels (and save this notebook to disk).

在Jupyter Lab中创建或修改analysis.ipynb后：

git add analysis.ipynb
git commit -m "Implemented initial data loading and visualization in analysis.ipynb"

Warning: 避免在Git中存储大型二进制文件。对于大型数据集，应通过版本控制的脚本下载，或使用Git LFS。关于Jupyter Notebook怎么用进行版本控制，关键在于频繁提交和清晰的提交信息。

4. 容器化Jupyter环境：Docker实现可复现性

4.1 创建Dockerfile

使用Docker封装Jupyter环境，确保在任何机器上都能复现相同的运行环境。这将解决“我的机器上可以运行”的问题，是实现可复现研究的最终手段。

# Dockerfile
FROM python:3.9-slim-buster

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8888

CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root"]

4.2 构建与运行Docker镜像

构建Docker镜像并运行容器。这样，您的Jupyter环境及其所有依赖都被封装在一个可移植的单元中。

docker build -t my_research_jupyter:v1.0.0 .
docker run -p 8888:8888 -v $(pwd):/app my_research_jupyter:v1.0.0

Expected Output: (部分输出)

[+] Building 0.5s (10/10) FINISHED
 ...
Successfully tagged my_research_jupyter:v1.0.0
[I ...] JupyterLab is running at: http://0.0.0.0:8888/lab?token=...

Note: -v $(pwd):/app 将当前宿主机目录挂载到容器的/app目录，使得容器内的Jupyter Lab可以直接访问并保存宿主机上的项目文件。

References

• Jupyter Project Official Website
• Git Official Website
• Docker Documentation