用Docker部署自己的JupyterHub

【話在前頭】

用 Docker 部署 JupyterLab 感覺是部署 JupyterLab 最方便的方式了，官方提供了很多可選的鏡像，也可以自己從 jupyter/base-notebook 中繼續打包，鏡像啟動命令加上“--NotebookApp.password”就可以直接用密碼登錄用了。雖然只是自己一個人用，但是如果放在互聯網上訪問的話，總感覺不是那么安全，還是希望能像其他服務一樣，能獨立管理用戶信息，能設置二次驗證（2FA）。不過搜了下網上關於 JupyterHub 的資料比較少，甚至於官方的說明文檔寫的也不是很詳細，有些配置和參數只能去源碼里扒。

 

【文章索引】

1. 打包 JupyterHub 鏡像
2. 配置 JupyterHub 啟動參數
3. 啟動 JupyterHub
4. 隔離 JupyterHub/JupyterLab 網絡

 

【一、打包 JupyterHub 鏡像】

JupyterHub 架構的介紹和原理官方文檔中描述的非常清楚了，這里不再贅述了，簡單說就是 JupyterHub 把 認證 和 單用戶 JupyterLab 的管理 分別拆成了 Authenticator 和 Spawner 模塊，可以根據不同的需要配置不同的認證方式或管理方式。不過官方的 JupyterHub 鏡像只包含了 JupyterHub 項目 本身，只有最基本的認證和管理（如通過 Linux 下 PAM 進行認證、通過本地進程運行 JupyterLab 等）。如果想通過自定義賬號密碼、並且開啟 2FA 的話，JupyterHub 其實也已經實現了一個官方的 NativeAuthenticator 模塊，官方文檔還是比較詳細的，默認用戶信息存儲在 JupyterHub 的 sqlite 數據庫中，可以通過數據源配置改成 Mysql，如果需要連接 Mysql 的話，官方的鏡像也不包含相關模塊，也需要自行安裝。

除此之外，如果 JupyterHub 管理的 JupyterLab 也想在 docker 中運行的話，還需要使用官方提供的 DockerSpawner 進行管理，不過官方文檔不是特別詳細，好在代碼不多，扒扒代碼也能看明白具體應該怎么配置。

所以，如果我們需要實現能獨立管理的用戶信息、支持2FA、使用Mysql數據庫存儲用戶數據，用戶的 JuyterLab 也通過 docker 鏡像進行運行和管理的話，我們可以通過如下的 Dockerfile 在官方鏡像之上打一個更完整的鏡像。

ARG BASE_IMAGE=jupyterhub/jupyterhub:1.2
FROM $BASE_IMAGE

LABEL maintainer="MaysWind <[e-mail]>"

# Install Dependencies
RUN apt-get update \
  && apt-get install -y --no-install-recommends unzip \
  && rm -rf /var/lib/apt/lists/* \
  && rm -rf /tmp/*

# Install Mysql
RUN pip3 --no-cache-dir install mysql-connector \
  && rm -rf /tmp/*

# Install NativeAuthenticator
RUN curl "https://github.com/jupyterhub/nativeauthenticator/archive/master.zip" -L -o /tmp/nativeauthenticator.zip \
  && unzip /tmp/nativeauthenticator.zip -d /tmp \
  && mv /tmp/nativeauthenticator-master /usr/local/bin/nativeauthenticator \
  && pip --no-cache-dir install -e /usr/local/bin/nativeauthenticator \
  && rm -rf /tmp/*

# Install DockerSpawner
RUN pip --no-cache-dir install dockerspawner \
  && rm -rf /tmp/*

注：寫這篇博客的時候，JupyterHub 的最新 Release 版本是 1.1.0，但是 1.1.0 的 docker 鏡像存在問題（靜態資源沒有編譯等），所以這里使用的是還在開發中的鏡像（1.2 tag 目前與 1.2.0dev tag 一致）。

 

【二、配置 JupyterHub 啟動參數】

打完鏡像后后其實就可以啟動了，不過通常還有些配置需要調整下。我通過 docker-compose 啟動 JupyterHub 容器，所有配置參數都通過參數或環境變量進行配置，同時由於 JupyterHub 在 docker 容器中，還需要把宿主機的 docker.sock 掛載到容器內，以便 JupyterHub 能夠管理 JupyterLab 容器。並且為 JupyterHub 和之后的 JupyterLab 建了一個單獨的網絡，方便之后對 JupyterLab 的請求進行隔離，如果沒有需求的話實際上按默認的網絡配置也是可以的，相關的 yml 示例配置如下

version: "2"
networks:
  jupyter-network:
    driver: bridge
    ipam:
      config:
        - subnet: 192.168.254.0/24
          gateway: 192.168.254.1
services:
  jupyterhub:
    image: 你的 JupyterHub 鏡像名稱 
    container_name: jupyterhub
    hostname: "jupyterhub"
    networks:
      - "jupyter-network"
    command:
      - "jupyterhub"
      - "--JupyterHub.hub_bind_url='http://:8081'" # JupyterHub 默認綁定 127.0.0.1，需要改成綁定所有 IP 使 JupyterLab 能跨容器訪問
      - "--JupyterHub.db_url='mysql+mysqlconnector://Mysql用戶名:Mysql密碼@數據庫地址/數據庫名稱'" # 設置 Mysql 數據庫，如果使用默認 Sqlite，可以掛載目錄到 /srv/jupyterhub 實現數據庫持久化
      - "--JupyterHub.authenticator_class='nativeauthenticator.NativeAuthenticator'" # 使用 NativeAuthenticator
      - "--JupyterHub.spawner_class='dockerspawner.DockerSpawner'" # 使用 DockerSpawner
      - "--JupyterHub.admin_access=True" # 啟用管理員功能
      - "--Authenticator.admin_users={'管理員賬戶名稱'}" # 管理員名稱
      - "--Authenticator.allow_2fa=True" # 開啟 2FA 功能
      - "--DockerSpawner.remove_containers=True" # 每次啟動 JuypyterLab 容器時都刪除之前的容器，如果通過 docker-compose 設置的網絡，docker-compose 重新配置網絡后一定要重新創建容器才能啟動
      - "--DockerSpawner.notebook_dir='/home/jovyan/work'" # 設置筆記本默認目錄（默認是 ~）
      - "--DockerSpawner.image='你的 JupyterLab 鏡像名稱'"
      - "--DockerSpawner.network_name='JupyterLab 網絡名稱'" # 如果是通過 docker-compose 設置的網絡，與第3行可能不一致，需要通過 docker network ls 查看
      - "--DockerSpawner.args=['--Application.log_level=WARN']" # 設置日志默認輸出級別
      - "--DockerSpawner.environment={\
             'JUPYTER_ENABLE_LAB': 'yes'\ # 開啟 JupyterLab
           }"
      - "--DockerSpawner.volumes={\
             '/etc/localtime': {'bind': '/etc/localtime', 'mode': 'ro'},\
             '本機 Jupyter 筆記存儲路徑': '/home/jovyan/work'\  # 可以使用 “{username}” 占位，表示用戶名，如 '/mnt/data1/jupyter/{username}/work': '/home/jovyan/work'
           }"
    volumes:
      - "/etc/localtime:/etc/localtime:ro"
      - "/var/run/docker.sock:/var/run/docker.sock"
    restart: on-failure

其中，JupyterHub 配置文件中的配置都可以通過啟動參數的方式進行配置，如上述配置中 command 中的配置項，所有 JupyterHub 配置可以參考官方文檔。對於 NativeAuthenticator，也額外提供了一些其他參數，如自己注冊完賬號，可以設置“Authenticator.open_signup”參數為 False，關閉開放注冊功能，“Authenticator.ask_email_on_signup” 注冊時需要提供郵箱賬號等，這些參數可以如上附到啟動參數中，或者也可寫入到配置文件中，更多參數和用法可以參考官方文檔。對於 DockerSpawner，有些參數是實現了基礎類 Spawner 中定義的，可以查閱 Spawner 的定義文檔 進行配置，也有部分是其本身單獨實現的，可以查閱其源代碼，例如其支持限制內存 “DockerSpawner.mem_limit”、限制CPU “DockerSpawner.cpu_limit”等參數，都是實現基礎類 Spawner 中定義的，Docker 網絡名稱 “DockerSpawner.network_name ”、啟動容器前刪除已有容器的參數 “DockerSpawner.remove_containers” 等都是其本身自己實現的。

如果之前也是通過 docker 部署的 JupyterLab，可能下述幾個參數能遷移大部分之前的個性化配置，

• DockerSpawner.args 可以追加 JupyterLab 容器的啟動參數，默認啟動命令是“start-notebook.sh --ip=0.0.0.0 --port=8888”，可以追加多個參數（如上述設置了配置了日志輸出級別為WARN，JupyterLab 配置文件中的配置都可以使用此方式進行配置，相關配置可以參考官方文檔），參數格式是 python 的 dict。
• DockerSpawner.environment 可以設置 JupyterLab 容器的環境變量，如上述設置了開啟 JupyterLab 功能，容器所有環境變量可以參考官方文檔，參數格式是 python 的 dict。
• DockerSpawner.volumes 可以設置 JupyterLab 容器的掛載配置，提供了兩種配置方式（讀寫模式：'source_path': 'target_path'，或自定義讀寫模式（如只讀）：'source_path': {'bind': 'target_path', 'mode': 'ro'}），格式是 python 的 dict。

 

【三、啟動 JupyterHub】

根據第二步的配置，就可以通過 docker-compose 或者其他方式啟動 JupyterHub 的 docker 鏡像了，只不過很有可能會失敗，主要是由於 NativeAuthenticator 對 Mysql 的兼容性問題，用於管理注冊用戶信息的那張表沒有自動創建成功，不過我們可以幫他完成這個任務，即編寫類似如下的SQL（具體存儲引擎、編碼可以根據自己實際情況調整）。

CREATE TABLE `users_info` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `username` varchar(255) NOT NULL,
  `password` blob NOT NULL,
  `is_authorized` bit(1) DEFAULT NULL,
  `email` varchar(255) DEFAULT NULL,
  `has_2fa` bit(1) DEFAULT NULL,
  `otp_secret` varchar(16) DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4;

創建完 users_info 表后 JupyterHub 應該就能正常啟動了，接下來就可以自己進行注冊賬號了，如果沒有關閉開放注冊功能或者注冊的賬號名在配置中的管理員用戶名中的話，賬號直接就可以登錄，否則需要自行去數據庫中找到自己注冊的記錄，並將 “is_authorized” 字段設置為1。

登錄后應該會默認啟動 JupyterLab，或者也可以自行選擇啟動，啟動成功后會自動跳轉到 JupyterLab，下次訪問時直接就會訪問 JupyterLab，而不會再顯示 JupyterHub 的界面了。如果啟動失敗，也可以通過 docker 查看 JupyterLab 的容器情況。

 

【四、隔離 JupyterHub/JupyterLab 網絡】

JupyterLab 里什么都能干，能執行代碼，能運行腳本，總覺得部署了 JupyterLab 后，直接把內網環境對外打開了，所以還想再對 JupyterHub/JupyterLab 的網絡進行隔離，不允許其訪問內網。這塊通過 iptables 就可以實現，比如上述我定義了 jupyter-network 網絡，IP 是 192.168.254.0/24，我內網 IP 是 192.168.1.0/24，路由（網關）是 192.168.1.1，所以我在宿主機上定義如下 iptables，禁止來自 jupyter-network 的 IP 請求內網 IP（但允許通過路由訪問互聯網）。當然，如果 Mysql 服務器不與 JupyterHub/JupyterLab 在一台宿主機上的話，別忘了允許 JupyterHub 的 IP 地址訪問 Mysql 端口。

iptables -I DOCKER-USER -s 192.168.254.0/24 -d 192.168.1.0/24 -j DROP
iptables -I DOCKER-USER -s 192.168.254.0/24 -d 192.168.1.1 -j ACCEPT

此外，如果宿主機上還有其他服務或 docker 實例，如果需要禁止 JupyterHub/JupyterLab 訪問他們，還需要再定義一條

iptables -I INPUT -s 192.168.254.0/24 -p tcp -j DROP

 

這樣，應該就相對安全了一些吧。