如何配置K8s上JupyterHub单用户Notebook服务器以支持VSCode远程内核连接

要让本地VSCode连接K8s内部的Jupyter单用户Pod内核，需要完成Pod端口暴露、本地端口转发、VSCode内核配置三个核心步骤，以下是具体配置方法：

一、修改JupyterHub单用户Pod配置 #

编辑你的jupyterhub-config.yaml，补充端口暴露和内核相关环境变量，确保Jupyter服务监听可被外部访问的接口：

singleuser:
  # 保留你现有所有配置（extraContainers、lifecycleHooks、storage、image等）
  # 添加以下配置：
  ports:
    - name: notebook
      containerPort: 8888
      protocol: TCP
  extraEnv:
    - name: JUPYTER_ENABLE_LAB
      value: "true"
    - name: JUPYTER_SERVER_PORT
      value: "8888"
    - name: JUPYTER_NOTEBOOK_DIR
      value: /home/jovyan/{username}

配置说明： #

• 暴露8888端口：这是Jupyter服务的默认端口，VSCode远程内核需要通过该端口访问内核API
• JUPYTER_ENABLE_LAB：启用Jupyter Lab（若使用经典Notebook可改为JUPYTER_ENABLE_NOTEBOOK=true）
• 确保你的自定义启动脚本（main.sh）中，Jupyter启动命令包含--ip=0.0.0.0，例如：

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

  这一步保证Pod内部的服务监听所有网络接口，允许K8s端口转发访问。

二、将K8s内部Pod端口转发到本地 #

因为单用户Pod仅在K8s内部网络可见，需要通过kubectl端口转发将Pod的8888端口映射到本地：

1. 先找到目标用户的Notebook Pod名称：

   kubectl get pods -n <你的JupyterHub命名空间>
   

   通常Pod名称格式为jupyter-<用户名>

2. 执行端口转发命令：

   kubectl port-forward jupyter-<用户名> 8888:8888 -n <你的JupyterHub命名空间>
   

   执行后保持终端窗口打开，端口转发会持续生效。

三、配置VSCode连接远程内核 #

1. 登录JupyterHub，进入用户的Notebook服务器，打开终端执行以下命令获取连接Token：

   jupyter server list
   

   输出会包含类似内容：

   Currently running servers:
   http://localhost:8888/?token=<你的-token字符串> :: /home/jovyan/<用户名>
   

   复制<你的-token字符串>部分。

2. 打开本地VSCode，确保已安装Jupyter扩展。

3. 点击左侧Jupyter图标，选择「Connect to Kernel」→「Existing Jupyter Server」。

4. 输入服务器地址：http://localhost:8888，粘贴刚才复制的Token，点击「Connect」。

5. 连接成功后，即可在VSCode中打开Pod内的Notebook文件，使用远程内核运行代码。

四、额外优化建议 #

• 确保你的Jupyter镜像中安装了ipykernel（VSCode默认支持的Python内核），若未安装，可在Dockerfile中添加：

  RUN pip install --no-cache-dir ipykernel
  

• 若需长期访问，可考虑为单用户Pod配置临时的NodePort Service，但注意限制访问权限（不建议直接暴露到公网）；单用户场景优先使用端口转发，安全性更高。

内容的提问来源于stack exchange，提问作者Anushree Sarkar