配置Nginx反向代理Docker内JupyterHub的静态资源加载问题

问题背景 #

在Ubuntu虚拟机上配置Nginx作为反向代理，指向Docker内8888端口的JupyterHub，采用子路径/jphub/方案（公司防火墙仅开放80、443端口，无法使用rewrite功能）。当前配置可正常打开页面，但JupyterHub的CSS、图片等静态资源加载路径错误——例如logo请求路径为myservername.com/hub/logo，而非预期的myservername.com/jphub/hub/logo。

解决方案 #

静态资源路径错误的核心原因是JupyterHub不知道自己运行在子路径下，生成的资源URL没有带上/jphub/前缀。需要同时调整Nginx配置和JupyterHub配置来解决：

1. 修改Nginx配置 #

修正原配置中的端口冲突（listen 80却配置SSL证书），优化代理规则，确保请求正确转发：

upstream jupyter {
    server localhost:8888;
    keepalive 32;
}

# 80端口跳转至HTTPS
server {
    listen 80;
    server_name myservername.com;
    return 301 https://$host$request_uri;
}

# HTTPS服务配置
server {
    listen 443 ssl;
    server_name myservername.com;

    ssl_certificate  /etc/ssl/cert-request/cert.pem;
    ssl_certificate_key /etc/ssl/private/cert.key; 
    ssl_prefer_server_ciphers on;

    location /jphub/ {
        proxy_pass http://jupyter/;
        proxy_http_version 1.1;

        # 修正重定向规则，确保JupyterHub返回的URL带上子路径
        proxy_redirect http://jupyter/ https://$host/jphub/;

        # WebSocket支持配置
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 传递正确的请求头，让JupyterHub识别真实请求信息
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https; # 修正为https，匹配实际访问协议
        proxy_set_header X-Nginx-Proxy true;

        proxy_pass_header Set-Cookie;
        proxy_read_timeout 86400;
    }
}

关键修改点：

• 新增80端口跳转至443的server块，解决原配置中SSL证书与80端口冲突的问题
• 简化proxy_redirect规则，避免多规则冲突，确保JupyterHub的重定向URL自动带上/jphub/前缀
• 将X-Forwarded-Proto设为https，匹配实际访问协议
• 移除冗余的proxy_pass_header配置（部分头信息已通过默认规则传递）

2. 配置JupyterHub的子路径 #

让JupyterHub知道自身运行在/jphub/子路径下，生成正确的静态资源URL：

• Docker运行时配置：启动JupyterHub容器时添加环境变量：

  docker run -d -p 8888:8000 \
    -e JUPYTERHUB_BASE_URL='/jphub/' \
    jupyterhub/jupyterhub
  

  （注：JupyterHub默认内部端口为8000，需确保映射到主机的8888端口）

• 配置文件方式：在jupyterhub_config.py中添加以下配置：

  c.JupyterHub.base_url = '/jphub/'
  

  若使用Docker，可将配置文件挂载到容器内的/srv/jupyterhub/jupyterhub_config.py路径。

验证 #

重启Nginx和JupyterHub服务后，访问https://myservername.com/jphub/，检查静态资源的请求路径是否已自动带上/jphub/前缀，确认CSS、图片等资源加载正常。

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