容器内的默认工作目录是 /workspace，这也是 Jupyter 实例的根目录。/workspace 目录旨在用于存储所有重要的工作成果。服务器其他目录中的数据（例如 /root）可能会在容器重启时丢失。

基于 Jupyter 的令牌身份验证（推荐）

通过 AUTHENTICATE_VIA_JUPYTER 变量激活基于 Jupyter 身份验证实现的令牌身份验证：

docker run -p 8080:8080 --env AUTHENTICATE_VIA_JUPYTER="mytoken" mltooling/ml-workspace:0.13.2

您还可以使用 <generated> 让 Jupyter 生成一个随机令牌，并将其打印到容器日志中。如果设置为 true，则不会设置任何令牌，但会确保对工作区中任何工具的请求都会通过 Jupyter 实例检查用户是否已身份验证。这通常用于 JupyterHub 等工具，这些工具会配置自己的身份验证方式。

基于 Nginx 的基本身份验证

通过 WORKSPACE_AUTH_USER 和 WORKSPACE_AUTH_PASSWORD 变量激活基本身份验证：

docker run -p 8080:8080 --env WORKSPACE_AUTH_USER="user" --env WORKSPACE_AUTH_PASSWORD="pwd" mltooling/ml-workspace:0.13.2

基本身份验证是通过 Nginx 代理配置的，与另一种方式相比可能性能更好。因为在使用 AUTHENTICATE_VIA_JUPYTER 时，每次对工作区中任何工具的请求都需要通过 Jupyter 实例检查用户（基于请求的 Cookie）是否已身份验证。

当设置为 true 时，必须将 cert.crt 和 cert.key 文件挂载到 /resources/ssl 目录；或者，如果证书文件不存在，则容器会生成自签名证书。例如，如果本地系统的 /path/with/certificate/files 目录下包含主机域名的有效证书文件（cert.crt 和 cert.key），则可以在工作区中按如下方式使用：

docker run \
    -p 8080:8080 \
    --env WORKSPACE_SSL_ENABLED="true" \
    -v /path/with/certificate/files:/resources/ssl:ro \
    mltooling/ml-workspace:0.13.2

如果您希望在公共域名上托管工作区，我们建议使用 Let's Encrypt 为您的域名获取受信任的证书。要将生成的证书（例如通过 certbot 工具）用于工作区，privkey.pem 对应于 cert.key 文件，而 fullchain.pem 则对应于 cert.crt 文件。

启用 SSL 支持后，您必须通过 https:// 访问工作区，而不是普通的 http://。

例如，以下命令将工作区的资源限制为最多 8 个 CPU、16GB 内存和 1GB 共享内存（参见已知问题)：

docker run -p 8080:8080 --cpus=8 --memory=16g --shm-size=1G mltooling/ml-workspace:0.13.2

📖 有关更多选项和资源限制的文档，请参阅Docker 官方指南。

极简版镜像（mltooling/ml-workspace-minimal）是我们最小的镜像，包含了功能部分中描述的大多数工具和特性，但去除了主镜像中预装的大部分 Python 库。任何被排除的 Python 库或工具都可以在运行时由用户手动安装。

docker run -p 8080:8080 mltooling/ml-workspace-minimal:0.13.2

R 版镜像（mltooling/ml-workspace-r）基于我们的默认工作区镜像，并在此基础上添加了 R 解释器、R Jupyter 内核、RStudio 服务器（可通过“打开工具 -> RStudio”访问），以及 R 生态系统中的多种流行包。

docker run -p 8080:8080 mltooling/ml-workspace-r:0.12.1

Spark 版镜像（mltooling/ml-workspace-spark）基于我们的 R 版工作区镜像，并在此基础上添加了 Spark 运行时、Spark Jupyter 内核、Zeppelin Notebook（可通过“打开工具 -> Zeppelin”访问）、PySpark、Hadoop、Java 内核，以及一些额外的库和 Jupyter 扩展。

docker run -p 8080:8080 mltooling/ml-workspace-spark:0.12.1

目前，GPU 版仅支持 CUDA 11.2。未来可能会增加对其他 CUDA 版本的支持。

GPU 版镜像（mltooling/ml-workspace-gpu）基于我们的默认工作区镜像，并在此基础上添加了 CUDA 10.1 以及适用于 GPU 的各种机器学习库（如 TensorFlow、PyTorch、CNTK、JAX 等）。此 GPU 镜像对系统有以下额外要求：

• 显卡的 NVIDIA 驱动程序。驱动程序需兼容 CUDA 11.2，版本为 >=460.32.03（📖 说明）。
• （Docker ≥ 19.03）NVIDIA 容器工具包（📖 说明）。

docker run -p 8080:8080 --gpus all mltooling/ml-workspace-gpu:0.13.2

• （Docker < 19.03）NVIDIA Docker 2.0（📖 说明）。

docker run -p 8080:8080 --runtime nvidia --env NVIDIA_VISIBLE_DEVICES="all" mltooling/ml-workspace-gpu:0.13.2

GPU 版还提供了一些额外的配置选项，如下所述：

ML Hub 可以轻松地在单个服务器上（通过 Docker）或集群上（通过 Kubernetes）搭建多用户环境，并支持多种使用场景和身份验证提供商。您可以通过以下方式试用 ML Hub：

docker run -p 8080:8080 -v /var/run/docker.sock:/var/run/docker.sock mltooling/ml-hub:latest

有关 ML Hub 的更多信息和文档，请查看 GitHub 网站。

1. 在工作区的终端中运行以下命令，在端口 1234 上启动一个 HTTP 服务器：python -m http.server 1234
2. 选择 Open Tool -> Access Port，输入端口 1234，并选择“获取可共享链接”选项。
3. 单击“Access”，您将看到 Python 的 http.server 提供的内容。
4. 打开的链接也可以分享给其他人，或从外部应用程序中调用（例如，尝试在 Chrome 的无痕模式下访问）。

通过 SSH 连接，可以实现从远程机器到本地机器，或反之的端口隧道转发。例如，您可以将工作空间内部的 5901 端口（VNC 服务器）暴露到本地机器的 5000 端口，方法是执行以下命令：

ssh -nNT -L 5000:localhost:5901 my-workspace

若要将本地机器上的应用端口暴露到工作空间，请使用 -R 选项（而非 -L）。

隧道建立后，您可以在本地机器上使用自己喜欢的 VNC 查看器，连接到 vnc://localhost:5000（默认密码：vncpassword）。为了使隧道连接更加稳定可靠，我们建议使用 autossh 自动重启 SSH 隧道，以防连接中断：

autossh -M 0 -f -nNT -L 5000:localhost:5901 my-workspace

端口隧道在您于工作空间内启动了基于服务器的工具，并希望将其对外部机器开放时非常有用。默认情况下，工作空间已在不同端口上运行多种工具，例如：

• 8080：主工作空间端口，可访问所有集成工具。
• 8090：Jupyter 服务器。
• 8054：VS Code 服务器。
• 5901：VNC 服务器。
• 22：SSH 服务器。

有关所有工具的端口信息，请参阅 supervisor 配置文件。

📖 如需了解更多关于端口隧道/转发的信息，建议参考这篇指南。

SCP 允许通过 SSH 连接，在不同机器之间安全地复制文件和目录。例如，要将本地文件（./local-file.txt）复制到工作空间内的 /workspace 目录中，可执行以下命令：

scp ./local-file.txt my-workspace:/workspace

若要将 my-workspace 中的 /workspace 目录复制到本地机器的工作目录中，则可执行：

scp -r my-workspace:/workspace .

📖 如需了解更多关于 scp 的信息，建议参考这篇指南。

Rsync 是一种用于在不同机器之间高效传输和同步文件的工具（例如通过 SSH 连接），它通过比较文件的修改时间和大小来确定需要更新的内容。每次运行 rsync 命令时，它都会自动识别哪些文件需要更新，相比使用 scp 或 sftp 等工具更为高效便捷。例如，要将本地文件夹（./local-project-folder/）中的所有内容同步到工作空间内的 /workspace/remote-project-folder/ 文件夹中，可执行以下命令：

rsync -rlptzvP --delete --exclude=".git" "./local-project-folder/" "my-workspace:/workspace/remote-project-folder/"

如果工作空间内的文件夹中有更改，您也可以通过交换源和目标参数，将这些更改同步回本地文件夹：

rsync -rlptzvP --delete --exclude=".git" "my-workspace:/workspace/remote-project-folder/" "./local-project-folder/"

每当您需要同步最新版本的文件时，都可以重新运行这些命令。Rsync 只会传输那些确实需要更新的文件。

📖 更多关于 rsync 的信息，请参阅此 man 页面。

除了复制和同步数据外，SSH 连接还可用于通过 SSHFS 将远程机器上的目录挂载到本地文件系统中。例如，要将 my-workspace 的 /workspace 目录挂载到本地路径（如 /local/folder/path），可执行以下命令：

sshfs -o reconnect my-workspace:/workspace /local/folder/path

远程目录挂载完成后，您可以像操作本地目录和文件一样与远程文件系统进行交互。

📖 如需了解更多关于 sshfs 的信息，建议参考这篇指南。

工作区可以通过 remote_ikernel 工具添加到 Jupyter 实例中作为远程内核。如果您已在本地机器上安装了 remote_ikernel（pip install remote_ikernel），工作区的 SSH 设置脚本会自动为您提供设置远程内核连接的选项。

在远程机器上运行内核时，笔记本本身会保存在本地文件系统上，但内核仅能访问运行该内核的远程机器的文件系统。如果需要同步数据，可以使用 rsync、scp 或 sshfs，具体方法请参阅 SSH 访问 部分。

如果您希望手动设置和管理远程内核，可以使用 remote_ikernel 命令行工具，如下所示：

# 将 my-workspace 替换为工作区 SSH 连接的名称
remote_ikernel manage --add \
    --interface=ssh \
    --kernel_cmd="ipython kernel -f {connection_file}" \
    --name="ml-server (Python)" \
    --host="my-workspace"

您可以使用 remote_ikernel 命令行功能列出（remote_ikernel manage --show）或删除（remote_ikernel manage --delete <REMOTE_KERNEL_NAME>）远程内核连接。

Visual Studio Code 的 Remote - SSH 扩展允许您打开任何可通过 SSH 访问的远程机器上的远程文件夹，并像处理本地文件夹一样进行操作。连接到远程机器后，您可以与远程文件系统中的任何文件和文件夹交互，并充分利用 VS Code 的各项功能（IntelliSense、调试和支持扩展）。该扩展能够自动发现并开箱即用支持由工作区 SSH 设置脚本配置的无密码 SSH 连接。要使您的本地 VS Code 应用程序连接到工作区：

1. 在本地 VS Code 中安装 Remote - SSH 扩展。
2. 按照 SSH 访问 部分的说明运行所选工作区的 SSH 设置脚本。
3. 打开本地 VS Code 中的 Remote-SSH 面板。所有已配置的 SSH 连接都应自动被发现。只需选择您想要连接的任意已配置的工作区连接，如下所示：

📖 有关 Remote SSH 扩展的更多功能和信息，请参阅此指南。

要将 Python 代码作为作业运行，您需要通过 EXECUTE_CODE 提供一个代码目录（或脚本）的路径或 URL。该代码可以已经挂载到工作区容器中，也可以从版本控制系统（例如 git 或 svn）下载，具体方法如下文所述。所选代码路径必须是可执行的 Python 文件。如果所选代码是一个目录（例如从 VCS 下载代码时），则需要在该目录的根目录下放置一个 __main__.py 文件。__main__.py 文件应包含启动作业的代码。

从版本控制系统运行代码

您可以使用 pip-vcs 格式直接从 Git、Mercurial、Subversion 或 Bazaar 执行代码，如 此指南 中所述。例如，要从一个 git 仓库的子目录执行代码，只需运行：

docker run --env EXECUTE_CODE="git+https://github.com/ml-tooling/ml-workspace.git#subdirectory=resources/tests/ml-job" mltooling/ml-workspace:0.13.2

📖 有关如何指定分支、提交或标签的更多信息，请参阅 此指南。

运行挂载到工作区的代码

在下面的示例中，我们将当前工作目录（预计包含我们的代码）挂载到工作区的 /workspace/ml-job/ 目录中并执行：

docker run -v "${PWD}:/workspace/ml-job/" --env EXECUTE_CODE="/workspace/ml-job/" mltooling/ml-workspace:0.13.2

安装依赖项

如果预装的工作区库与您的代码不兼容，可以通过将以下一个或多个文件添加到您的代码目录来安装或更改依赖项：

• requirements.txt: pip 要求格式用于 pip 可安装的依赖项。
• environment.yml: conda 环境文件用于创建独立的 Python 环境。
• setup.sh: 通过 /bin/bash 执行的 Shell 脚本。

执行顺序为：1. environment.yml -> 2. setup.sh -> 3. requirements.txt

在交互模式下测试作业

您可以在工作区中（以正常方式启动并带有交互式工具）测试您的作业代码，方法是执行以下 Python 脚本：

python /resources/scripts/execute_code.py /path/to/your/job

构建自定义作业镜像

您也可以将代码直接嵌入到自定义作业镜像中，如下所示：

FROM mltooling/ml-workspace:0.13.2

# 将作业代码添加到镜像
COPY ml-job /workspace/ml-job
ENV EXECUTE_CODE=/workspace/ml-job

# 仅安装依赖项
RUN python /resources/scripts/execute_code.py --requirements-only

# 在容器启动时仅执行代码
CMD ["python", "/resources/docker-entrypoint.py", "--code-only"]

例如，要安装 Apache Zeppelin 笔记本服务器，只需执行：

/resources/tools/zeppelin.sh --port=1234

安装完成后，刷新 Jupyter 网站，Zeppelin 工具将出现在 Open Tool -> Zeppelin 下。其他工具可能仅在 Desktop VNC 中可用（例如 atom 或 pycharm），或者根本不提供 UI（例如 starspace、docker-client）。

工作空间在运行时可以通过多种方式扩展，具体说明请参见此处。然而，如果您希望使用自己的软件或配置来定制工作空间镜像，可以按照以下示例通过 Dockerfile 实现：

# 从任意一个工作空间版本/风味继承
FROM mltooling/ml-workspace:0.13.2

# 执行自定义操作，例如：
RUN \
    # 使用提供的安装脚本安装 r-runtime、r-kernel 和 r-studio Web 服务器
    /bin/bash $RESOURCES_PATH/tools/r-runtime.sh --install && \
    /bin/bash $RESOURCES_PATH/tools/r-studio-server.sh --install && \
    # 清理层 - 移除不必要的缓存文件
    clean-layer.sh

最后，使用 docker build 构建您自定义的 Docker 镜像。

📖 如需更全面的 Dockerfile 示例，请参阅 R 版本的 Dockerfile。

要将正在运行的工作空间实例更新到最新版本，需要将当前的 Docker 容器替换为基于更新后工作空间镜像的新容器。

在此更新过程中，工作空间内未挂载卷持久化的所有数据都将丢失。正如 持久化数据 部分所述，通常会将卷挂载到 /workspace 文件夹。工作空间内的所有工具都配置为将 /workspace 文件夹作为所有源代码和数据工件的根目录。在更新期间，其他目录中的数据将被移除，包括已安装或更新的库以及某些机器配置。我们集成了备份与恢复功能（CONFIG_BACKUP_ENABLED），用于备份和恢复一些选定的配置文件/文件夹，例如用户的 Jupyter/VS-Code 配置、~/.gitconfig 和 ~/.ssh。

docker run -d \
    -p 8080:8080 \
    --name "ml-workspace" \
    -v "/path/on/host:/workspace" \
    --env AUTHENTICATE_VIA_JUPYTER="mytoken" \
    --restart always \
    mltooling/ml-workspace:0.8.7

如果您希望通过 VNC 客户端直接连接到工作空间（而不是使用 noVNC Web 应用程序），可能需要更改某些 VNC 服务器配置。要配置 VNC 服务器，可以在容器启动时通过 docker run 的 --env 选项提供或覆盖以下环境变量：

很遗憾，目前我们尚不支持在工作空间中使用非 root 用户。我们计划实现这一功能，并已开始进行一些重构以支持该配置。然而，这仍需要我们投入大量额外的工作、重构和测试。

通常不建议在容器中使用 root 用户（或具有 sudo 权限的用户），因为一旦系统或内核出现漏洞，用户可能会突破容器限制并访问宿主机系统。尽管此类严重的内核漏洞并不常见，因此发生严重攻击的风险极低。正如 Docker 官方文档 所述，即使使用 root 用户，容器通常也能很好地防止突破到宿主机。而且与其他许多容器应用场景相比，我们实际上希望为用户提供灵活性，使其能够在工作空间容器内拥有控制权和系统级安装权限。

工作空间预装了多种常用的工具，可用于创建隔离的 Python 虚拟环境。以下部分将简要介绍如何在工作空间中使用这些工具。关于何时使用哪种工具的信息，请参阅 此处。更多使用信息请参考相应工具的官方文档。

venv（推荐）：

要通过 venv 创建虚拟环境，请执行以下命令：

# 在工作目录中创建环境
python -m venv my-venv
# 在 shell 中激活环境
source ./my-venv/bin/activate
# 可选：为该环境创建 Jupyter 内核
pip install ipykernel
python -m ipykernel install --user --name=my-venv --display-name="my-venv ($(python --version))"
# 可选：退出环境会话
deactivate

pipenv（推荐）：

要通过 pipenv 创建虚拟环境，请执行以下命令：

# 在工作目录中创建环境
pipenv install
# 在 shell 中激活环境会话
pipenv shell

# 可选：为该环境创建 Jupyter 内核
pipenv install ipykernel
python -m ipykernel install --user --name=my-pipenv --display-name="my-pipenv ($(python --version))"
# 可选：关闭环境会话
exit

virtualenv:

要通过 virtualenv 创建虚拟环境，请执行以下命令：

# 在工作目录中创建环境
virtualenv my-virtualenv
# 在 shell 中激活环境会话
source ./my-virtualenv/bin/activate
# 可选：为该环境创建 Jupyter 内核
pip install ipykernel
python -m ipykernel install --user --name=my-virtualenv --display-name="my-virtualenv ($(python --version))"
# 可选：关闭环境会话
deactivate

conda:

要通过 conda 创建虚拟环境，请执行以下命令：

# 创建环境（全局）
conda create -n my-conda-env
# 在 shell 中激活环境会话
conda activate my-conda-env
# 可选：为该环境创建 Jupyter 内核
python -m ipykernel install --user --name=my-conda-env --display-name="my-conda-env ($(python --version))"
# 可选：关闭环境会话
conda deactivate

提示：Jupyter 笔记本中的 Shell 命令：

如果您通过专用的 Jupyter 内核安装并使用虚拟环境，并在 Jupyter 中使用 shell 命令（例如 !pip install matplotlib），则可能会使用错误的 Python 或 pip 版本。要使用所选内核的 Python 和 pip 版本，请改用以下方法：

import sys
!{sys.executable} -m pip install matplotlib

工作区提供了三种简便的方法来在主 Python 实例之外安装不同的 Python 版本：pyenv、pipenv（推荐）、conda。

pipenv（推荐）：

要在工作区内通过 pipenv 安装不同的 Python 版本（例如 3.7.8），请执行以下命令：

# 安装指定版本的 Python
pipenv install --python=3.7.8
# 在 shell 中激活环境会话
pipenv shell
# 检查 Python 安装情况
python --version
# 可选：为该环境创建 Jupyter 内核
pipenv install ipykernel
python -m ipykernel install --user --name=my-pipenv --display-name="my-pipenv ($(python --version))"
# 可选：关闭环境会话
exit

pyenv：

要在工作区内通过 pyenv 安装不同的 Python 版本（例如 3.7.8），请执行以下命令：

# 安装指定版本的 Python
pyenv install 3.7.8
# 使其全局可用
pyenv global 3.7.8
# 在 shell 中激活该版本的 Python
pyenv shell 3.7.8
# 检查 Python 安装情况
python3.7 --version
# 可选：为该 Python 版本创建 Jupyter 内核
python3.7 -m pip install ipykernel
python3.7 -m ipykernel install --user --name=my-pyenv-3.7.8 --display-name="my-pyenv (Python 3.7.8)"

conda：

要在工作区内通过 conda 安装不同的 Python 版本（例如 3.7.8），请执行以下命令：

# 创建包含指定 Python 版本的环境
conda create -n my-conda-3.7 python=3.7.8
# 在 shell 中激活环境会话
conda activate my-conda-3.7
# 检查 Python 安装情况
python --version
# 可选：为该 Python 版本创建 Jupyter 内核
pip install ipykernel
python -m ipykernel install --user --name=my-conda-3.7 --display-name="my-conda ($(python --version))"
# 可选：关闭环境会话
conda deactivate

提示：Jupyter 笔记本中的 Shell 命令：

如果您通过专用的 Jupyter 内核安装并使用其他 Python 版本，同时在 Jupyter 中使用 shell 命令（例如 !pip install matplotlib），则可能会使用错误的 Python 或 pip 版本。要使用所选内核的 Python 和 pip 版本，请改用以下方法：

import sys
!{sys.executable} -m pip install matplotlib

某些桌面工具（例如，最新版本的 Firefox）或库（例如，PyTorch - 参见问题：1、2）在共享内存大小（/dev/shm）过小时可能会崩溃。Docker 的默认共享内存大小为 64MB，这可能对一些工具来说不够。您可以通过 shm-size docker run 选项提供更大的共享内存大小：

docker run --shm-size=2G mltooling/ml-workspace:0.13.2

一般来说，在 Docker 中运行代码的性能与直接在主机上运行几乎相同。然而，如果您限制了容器的 CPU 配额（如 此部分 所述），容器仍然会看到主机上可用的全部 CPU 核心数，且没有技术手段可以阻止这一点。许多库和工具会使用全部 CPU 核心数（例如通过 os.cpu_count()）来设置用于多进程或多线程处理的线程数。这可能导致程序启动的线程或进程数量超过其在现有 CPU 配额下能够高效处理的能力，从而极大地降低整体性能。因此，重要的是将可用的 CPU 数量或最大线程数显式地设置为配置的 CPU 配额。该工作空间提供了自动检测可用 CPU 数量的功能，并通过环境变量（如 OMP_NUM_THREADS 或 MKL_NUM_THREADS）来配置各种常用库。此外，也可以在容器启动时通过 MAX_NUM_THREADS 环境变量显式设置可用 CPU 数量（参见 配置部分）。同一环境变量也可用于在运行时获取可用 CPU 数量。

尽管工作空间的自动配置功能可以解决多种效率低下的问题，我们仍建议为所有库显式配置可用的 CPU 数量。例如：

import os
MAX_NUM_THREADS = int(os.getenv("MAX_NUM_THREADS"))

# 在 PyTorch 中设置
import torch
torch.set_num_threads(MAX_NUM_THREADS)

# 在 TensorFlow 中设置
import tensorflow as tf
config = tf.ConfigProto(
    device_count={"CPU": MAX_NUM_THREADS},
    inter_op_parallelism_threads=MAX_NUM_THREADS,
    intra_op_parallelism_threads=MAX_NUM_THREADS,
)
tf_session = tf.Session(config=config)

# 为 Keras 设置会话
import keras.backend as K
K.set_session(tf_session)

# 在 sklearn 的估计器中设置
from sklearn.linear_model import LogisticRegression
LogisticRegression(n_jobs=MAX_NUM_THREADS).fit(X, y)

# 为 multiprocessing 池设置
from multiprocessing import Pool

with Pool(MAX_NUM_THREADS) as pool:
    results = pool.map(lst)

如果您在启动工作空间时，容器日志中出现以下错误，则很可能无法在您的硬件上运行该工作空间：

exited: nginx (terminated by SIGILL (core dumped); not expected)

工作空间中使用的 OpenResty/Nginx 二进制包需要在支持 SSE4.2 的 CPU 上运行（参见 此问题）。不幸的是，一些较旧的 CPU 不支持 SSE4.2，因此无法运行该工作空间容器。在 Linux 系统中，您可以通过查看 /proc/cpuinfo 文件中的 flags 部分来确认您的 CPU 是否支持 SSE4.2。如果遇到此类问题，请随时通过评论告知我们：#30。