企业官网建设流程全解析

• 示例工程
• 教育

Practical_RL 是一套面向实战的强化学习课程（"A course in reinforcement learning in the wild"），课程内容覆盖从基础 Gymnasium 环境交互、值函数方法到 PPO、TRPO、MCTS 等十余周内容，大量练习以 Jupyter Notebook 形式交付，并依赖 gym、atari、TensorFlow/PyTorch、OpenGL 渲染等众多组件。为简化安装过程，仓库在 docker/README.md 中提供了完整的容器化部署方案：你可以直接拉取预构建镜像（几行命令即可启动带全部依赖的 Jupyter 环境），也可以基于仓库自带的 Dockerfile 手动构建 CPU/GPU 版本。读完本文，你将掌握本课程 Docker 环境的两种启动路径、GPU 透传配置、镜像构建参数与依赖清单的内部机制，从而在任何平台上快速复现课程实验环境。

为什么用 Docker 部署课程环境

强化学习课程实验对运行环境有特殊要求：既有 Python 科学计算栈（numpy、scipy、matplotlib），也有老牌深度学习框架（TensorFlow 1.13、PyTorch），还有仿真环境与渲染库（gym、atari-py、pyglet、OpenGL、ffmpeg、xvfb 虚拟显示器）。手工在本地逐个安装很容易因版本冲突或图形依赖缺失而卡住。Docker 容器相当于一台预装好所有依赖的虚拟机，一次拉取即可获得与课程一致的运行环境，这正是 docker/README.md 开篇所强调的定位——"To simplify installation process, you can deploy a container (~virtual machine) with all dependencies pre-installed"。

部署方式分为两条主线：

1. 使用预构建镜像（推荐）：直接拉取 Docker Hub 上的dmittov/practical_rl镜像，通过 Kitematic 图形界面或命令行docker run启动，仓库根目录挂载进容器作为/notebooks；
2. 手动构建（Manual）：在本仓库根目录执行docker build，通过--build-arg device=cpu|gpu选择基础镜像与深度学习框架版本，构建出完全由本地代码衍生的镜像。

两条路线的最终体验一致：容器启动后运行 Jupyter Notebook，监听 8888 端口，通过浏览器输入 token 访问。

准备工作：安装 Docker 与 GPU 运行时

安装 Docker 客户端

docker/README.md 推荐了两种客户端形态：

• Kitematic：Docker 官方提供的图形化界面，支持所有平台，适合不熟悉命令行的用户；
• 原生 Docker（Native）：Linux 上推荐直接使用原生 CLI；Windows / macOS 分别参考 Docker 官方提供的 Docker Desktop 安装指引。

安装完成后，终端执行docker --version可确认 CLI 可用。

GPU 支持的前置条件（可选）

docker/README.md 明确指出：若希望用 GPU 加速训练（课程中的 DQN、A2C、PPO 等深度 RL 实验均可受益），需要提前在宿主机安装：

• NVIDIA 驱动（Unix 版本）；
• nvidia-container-toolkit（让 Docker 能透传 GPU 给容器）；
• CUDA 10.2（对应预构建镜像spring2020-cuda-10.2标签的依赖版本）。

注意：仓库当前 Dockerfile 的 GPU 基础镜像已升级为nvidia/cuda:12.9.1-base-ubuntu24.04，与预构建镜像spring2020-cuda-10.2分属不同代际。若使用预构建的spring2020-*标签，请以 README 标注的 CUDA 10.2 为准；若手动构建，则以 Dockerfile 内 CUDA 12.9.1 基础镜像为准，宿主机驱动需与之匹配。

方式一：使用预构建镜像（Kitematic 图形界面）

如果你偏好图形化操作：

1. 打开 Kitematic，在搜索框中查找dmittov/practical_rl；
2. 下载并启动该容器；
3. 访问 Jupyter 有两种途径：
   • 点击右上角的"web preview"屏幕预览；
   • 或进入 Settings → Ports，查看 Jupyter 实际映射的宿主机端口（通常形如32***），用浏览器访问对应地址。

Kitematic 会自动完成端口映射与目录挂载，适合 Windows 用户作为入门选择。

方式二：使用预构建镜像（命令行原生方式）

在终端执行：

docker run --rm -it -v /path/to/your/repo:/notebooks -p <local_port>:8888 dmittov/practical_rl:spring2020-cpu

参数逐项说明：

docker/README.md 给出一个完整示例（将本机/home/myuser/Documents/practical_rl挂载并映射 8888 端口）：

docker run --rm -it -v /home/myuser/Documents/practical_rl:/notebooks -p 8888:8888 dmittov/practical_rl:spring2020-cpu

启动后，容器日志中会打印一串 Jupyter token。在浏览器中访问：

http://localhost:<local_port>/?token=<token_you_see_in_container_logs>

例如 docker/README.md 中的实际形态：localhost:8888/?token=ad1a5a0aab43efb47a9a805388fcf508d0b5f84a16e4542b。token 保证了 Notebook 服务的安全性，首次访问后建议按提示设置密码。

使用 GPU 版预构建镜像

若宿主机已安装 NVIDIA 驱动与 nvidia-container-toolkit，执行：

docker run --rm -it -v /path/to/your/repo:/notebooks -p <local_port>:8888 --gpus all dmittov/practical_rl:spring2020-cuda-10.2

与 CPU 版相比仅多了两点差异：镜像标签改为spring2020-cuda-10.2，并追加--gpus all将宿主机全部 GPU 透传给容器。

方式三：手动构建镜像（Manual）

如果你希望基于当前仓库代码自行构建（例如跟随课程仓库的最新改动，或想复现 Dockerfile 的构建流程），在克隆本仓库后进入仓库根目录执行：

docker build -t practical_rl --build-arg device=cpu .

构建 GPU 版本：

docker build -t practical_rl --build-arg device=gpu .

--build-arg device=cpu|gpu是镜像定制的核心开关，它决定两件事：选用哪个基础镜像，以及深度学习框架（TensorFlow / PyTorch）安装哪套预编译包。构建完成后启动容器：

docker run --rm -it -v <local_dir>:/notebooks -p <local_port>:8888 practical_rl

GPU 版启动需追加--gpus all：

docker run --rm -it -v <local_dir>:/notebooks -p <local_port>:8888 --gpus all practical_rl

docker/README.md 推荐在仓库目录下直接挂载当前路径，Linux 下可用反引号命令替换：

docker run --rm -it -v `pwd`:/notebooks -p 8888:8888 practical_rl

启动后同样从控制台复制 token，访问http://localhost:8888/?token=<token>。

深入解析 Dockerfile：多阶段构建与 device 参数

手动构建背后是仓库 docker/Dockerfile 的精巧设计，理解它有助于排查构建问题、按需定制环境。

多阶段构建：CPU 与 GPU 共享一份构建逻辑

Dockerfile 使用了两组基础镜像并通过ARG device动态选择：

• base-cpu：基于ubuntu:24.04；
• base-gpu：基于nvidia/cuda:12.9.1-base-ubuntu24.04（包含 CUDA 运行环境）。

随后FROM base-$device AS base依据构建参数选中其一，FROM stage-$device as final再按相同机制选择最终阶段。这意味着 CPU 与 GPU 镜像共享除基础镜像和框架包之外的全部构建步骤，避免重复维护。

系统层：图形渲染与仿真所需组件

基础层通过 apt 安装：wget unzip git cmake xvfb sudo freeglut3-dev ffmpeg。其中xvfb（虚拟 X 帧缓冲）与freeglut3-dev（OpenGL 工具库）服务于课程中带渲染的 Gym 环境，ffmpeg用于视频录制——这与仓库根目录的 xvfb 脚本（封装了Xvfb :1 -screen 0 1024x768x24 -ac +extension GLX +render -noreset的 start/stop/restart 逻辑）一脉相承，保证无显示器环境下 RL 环境也能完成渲染。

用户与目录：非 root 运行 + 可写 Notebook 目录

Dockerfile 创建了默认用户jovyan（可用ARG username覆盖），将其加入 sudo 组并配置免密 sudo（%sudo ALL=(ALL) NOPASSWD:ALL），随后创建/notebooks目录并授权给该用户。后续所有 conda 安装都以普通用户身份执行，保证容器安全性的同时，让挂载进/notebooks的宿主目录可写。

Python 层：Anaconda + 条件化依赖模板

Dockerfile 下载并静默安装Anaconda3-2025.06至/opt/conda，并配置 conda 环境初始化。随后通过ADD deeplearning.yaml /tmp/deeplearning-template.yaml把依赖清单拷入镜像，再根据 device 参数用 sed 做模板替换：

• CPU 阶段：s/{tensorflow}/tensorflow/g、s/{pytorch}/pytorch/g
• GPU 阶段：s/{tensorflow}/tensorflow-gpu/g、s/{pytorch}/pytorch-gpu/g

最后conda env create -f /tmp/deeplearning.yaml创建名为deeplearning的 conda 环境，并执行python -m ipykernel install --user --name python3 --display-name "Python 3"，把该环境注册为 Jupyter 内核。构建结束后清理模板文件，避免污染镜像。

运行入口：固定端口与挂载点

Dockerfile 尾部声明：

• EXPOSE 8888：暴露 Jupyter 端口；
• VOLUME /notebooks+WORKDIR /notebooks：声明挂载卷并设为工作目录；
• COPY run_jupyter.sh /+CMD ["/run_jupyter.sh"]：容器启动时执行 run_jupyter.sh。

启动脚本内容极简但关键：

#!/usr/bin/env bash jupyter notebook --no-browser --ip 0.0.0.0

--ip 0.0.0.0让 Jupyter 监听容器内所有网络接口，配合-p端口映射后宿主机才能通过localhost访问；--no-browser则避免在无浏览器环境中报错，这也是每次启动必须从日志复制 token 的原因。

deeplearning.yaml：课程依赖清单全解

deeplearning.yaml 是 conda 环境的完整规格文件（{tensorflow}、{pytorch}为构建期占位符），其依赖覆盖了课程各周的实验需求：

conda 通道（channels: defaults）依赖：

pip 依赖：

• 仿真与 RL 生态：gym、gym[box2d]（经典控制/Box2D 环境）、gym[atari]、atari-py（Atari ROM 接口）；
• 可视化与数据处理：matplotlib、seaborn、scikit-image、imageio（GIF/视频导出）；
• 渲染与运行时：pyglet（OpenGL 窗口）、psutil（进程监控）；
• 文本处理：requests（下载）、editdistance（序列编辑距离，用于 week07_seq2seq 的翻译/文本任务）。

环境最终安装在prefix: /opt/conda/envs/deeplearning。对照课程仓库 week04_approx_rl/requirements.txt 可以看到，新版课程环境已迁移到gymnasium、ale_py、torch等现代依赖；而容器镜像保持了课程春季学期的经典依赖栈（TensorFlow 1.13 + atari-py），两者版本语义不同，选用镜像方案时建议沿用镜像内置版本以保证与旧版 Notebook 兼容。

常见问题与验证

• token 找不到：每次docker run后查看容器日志，token 在 Jupyter 启动输出中；若已设置密码，可直接用密码登录。
• Notebook 打不开：确认-p的宿主机端口未被占用，且访问地址为http://localhost:<local_port>/?token=<token>（容器内--ip 0.0.0.0已保证端口可达）。
• GPU 版本无法使用：先验证宿主机nvidia-smi正常，再确认 nvidia-container-toolkit 已安装；预构建spring2020-cuda-10.2镜像需 CUDA 10.2 配套驱动，手动构建镜像则要求 CUDA 12.9.1 基础镜像对应驱动。
• 渲染类环境报错（如 gym 的 OpenGL 环境）：镜像已内置 xvfb、freeglut3-dev 与 xvfb 管理脚本，可参考仓库 setup_colab.sh 的思路在容器内先启动虚拟显示器再运行渲染环境。
• 验证环境就绪：进入容器后执行conda activate deeplearning，再依次python -c "import gym, torch, tensorflow"检查三大核心依赖；随后在 Jupyter 中新建 Notebook，内核选择 "Python 3"，运行一个简单的 Gym 环境交互（如gym.make('CartPole-v0')）即可确认仿真链路正常。

总结

docker/README.md 为本课程提供了"零安装"的容器化方案：预构建镜像的 Kitematic / 命令行两种启动方式覆盖了不同平台与熟练度的用户，GPU 透传则解决了深度 RL 训练的算力需求；仓库源码层的 Dockerfile 通过device构建参数与 sed 模板替换，将 CPU/GPU 两套镜像统一到同一份构建逻辑，deeplearning.yaml 则完整固化了课程实验所需的 conda + pip 依赖栈。无论选择哪种方式，最终都能在浏览器中通过 token 进入与课程完全一致、开箱即用的 Jupyter 强化学习工作台。

• 示例工程
• 教育