Jupyter Lab 无法启动 Kernel 问题排查与解决总结

📄 Jupyter Lab 无法启动 Kernel 问题排查与解决总结
一、问题概述
🚨 现象描述：
用户通过浏览器访问远程服务器的 Jupyter Lab 页面（http://xx.xx.xx.xx:8891/lab）后，.ipynb 文件可以打开，但无法正常启动内核 (Kernel)，并持续报错：

“Error Starting Kernel”
“Failed to fetch”
浏览器开发者工具 (F12) 中观察到多个错误：
WebSocket connection to ‘ws://xx.xx.xx.xx:8891/api/kernels/…/channels?..’ failed:
W
WebSocket connection to ‘ws://xx.xx.xx.xx:8891/api/events/subscribe’ failed:

二、原因分析
🧠 核心问题：
WebSocket 协议连接失败，导致内核无法启动或通信中断。
🔍 根本原因：
用户启动了 HTTP（非加密）版本的 Jupyter Lab。
但在远程访问时，浏览器出于安全策略，默认拒绝 ws:// 协议。
同时没有使用反向代理或 HTTPS 证书保护，导致浏览器无法建立 WebSocket 通道。
⚠️ 后续进一步排查发现：
使用 curl 可以正常访问 HTTP 接口，说明端口已开放，HTTP 通信无问题。
WebSocket 协议握手失败，浏览器未能收到 101 Switching Protocols 响应。
后台日志提示 [SSL: HTTP_REQUEST]、wrong version number，说明客户端发起了 HTTP 请求，但服务端运行的是 HTTPS 模式。

三、调查过程
时间点
调查内容
结论
🕵️ 初始
验证 Jupyter 服务是否正常运行
✅ 正常，端口 8891 已开放
🕵️ 继续
使用 curl 测试 API 通信
✅ HTTP 接口 /api/kernelspecs 可访问
🕵️ 核心
检查 WebSocket 握手失败原因
❌ 浏览器使用 ws://，服务器未响应升级接口
🕵️ 关键
检查服务器 SSL 状态
✅ 实际已使用 HTTPS 证书启动 Jupyter
🕵️ 修正
切换访问方式为 https://
✅ 一切恢复正常，内核可启动，WebSocket 正常通信

四、解决方案
✅ 最终解决步骤如下：
生成自签名 HTTPS 证书：
mkdir -p ~/certs
o
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \

-keyout ~/certs/jupyter.key \

-out ~/certs/jupyter.pem \

-subj “/CN=xx.xx.xx.xx”

以 HTTPS 模式启动 Jupyter Lab：
jupyter lab \

–ip=0.0.0.0 \

–port=8891 \

–no-browser \

–ServerApp.allow_remote_access=True \

–ServerApp.allow_origin=“*” \

–ServerApp.disable_check_xsrf=True \

–ServerApp.token=‘’ \

–certfile=~/certs/jupyter.pem \

–keyfile=~/certs/jupyter.key

浏览器访问地址更新为：
https://xx.xx.xx.xx:8891/lab

确认 WebSocket 已升级为 wss://，内核可正常启动。

五、经验教训与建议
✅ 技术建议：
避免使用 http:// + ws:// 组合方式部署 Jupyter Lab，特别是在远程或跨域访问场景。
建议统一采用 https:// + wss:// 方式部署，确保浏览器信任并兼容。
如果为局域网使用，可生成自签名证书临时使用；如部署到公网，建议使用 Let’s Encrypt 免费证书或正式 CA 证书。
📁 工具建议：
借助浏览器 F12 工具中的 Network + Console 是定位 Jupyter Kernel 问题的关键。
使用 curl，telnet，或 Python websocket-client 库可以本地模拟 WebSocket 握手行为，帮助分析服务端响应状态。

六、附录（常用命令）
🔹 查看端口是否开放：
curl http://:/api/kernelspecs
t
telnet

🔹 检查防火墙（iptables）：
sudo iptables -L -n