Google Cloud启动User managed notebook卡JupyterLab代理报错排查

页面卡在「Setting up proxy to JupyterLab」加载、日志持续报Error: No such container: proxy-agent，核心原因是GCP用户托管Notebook实例负责和控制台做请求转发的proxy-agent容器没有正常运行。GCP控制台不会直接连接实例上的JupyterLab服务，必须通过这个代理容器完成鉴权和流量转发，容器缺失会导致转发链路中断，前端就会一直卡在加载状态。
常见触发场景：

• 实例启动/创建过程中Docker服务异常退出，代理容器未正常拉起
• 手动清理Docker容器/镜像、修改Docker配置时误删了proxy-agent相关资源
• 实例磁盘空间占满，Docker无法正常启动容器
• 实例内置的代理守护服务配置损坏，无法自动拉起proxy-agent容器
• 本地防火墙、iptables规则拦截了代理容器的通信端口

所有操作都需要先通过GCP控制台提供的SSH入口直连实例操作系统，不要走卡住的JupyterLab页面：

1. 执行systemctl status docker检查Docker服务状态，确认服务处于active (running)状态，如果有启动报错优先定位Docker本身的问题
2. 执行df -h检查磁盘使用率，重点确认根目录/、Docker默认数据目录/var/lib/docker所在分区没有被占满，磁盘使用率100%会导致所有容器都无法启动
3. 执行docker ps -a列出所有容器，确认是否存在名为proxy-agent的容器，如果容器存在但处于Exited状态，记录对应的退出状态码
4. 执行systemctl list-units | grep proxy查找实例上的代理相关systemd服务，不同Deep Learning VM版本的服务名可能是proxy-agent、jupyter-proxy或gcp-notebook-proxy，找到后执行systemctl status 对应服务名查看服务的报错日志
5. 执行journalctl -u docker | grep -i proxy-agent查看Docker日志里和代理容器相关的报错，确认是镜像缺失、端口冲突还是权限问题导致容器启动失败

按操作成本从低到高依次尝试，每步操作完成后等1分钟，刷新控制台页面看是否能正常进入JupyterLab：

• 重启代理服务
  直接强制重启代理守护进程，触发服务自动拉起proxy-agent容器：

  # 依次尝试以下三个重启命令，哪个不报错就说明找对了服务名
  sudo systemctl restart proxy-agent
  sudo systemctl restart jupyter-proxy
  sudo systemctl restart gcp-notebook-proxy
  

  执行完后跑docker ps，如果能看到状态为Up的proxy-agent容器，说明修复成功。
• 补全缺失的代理镜像
  如果重启服务后还是报容器不存在，大概率是代理镜像被误删了，手动拉取官方镜像后再重启服务：

  sudo docker pull gcr.io/deeplearning-platform-release/agent-proxy:latest
  sudo systemctl restart proxy-agent
  

• 修复Docker运行异常
  如果是Docker本身启动失败，对应处理：
  • 磁盘满导致的异常：先执行sudo docker system prune -af清理无用的镜像、停止的容器释放空间（注意该命令会删除所有未运行的容器和未被使用的镜像，执行前确认容器内没有需要留存的未持久化数据），清理完重启Docker：sudo systemctl restart docker
  • 配置损坏导致的异常：如果之前手动修改过/etc/docker/daemon.json配置，先把自定义配置移除恢复默认，再重启Docker
    Docker恢复正常后，再执行第一步的重启代理服务操作。
• 重置Notebook内置配置
  以上操作都无效的话，执行GCP Deep Learning VM内置的重置脚本，重新初始化Jupyter、代理相关的所有配置：

  sudo /opt/deeplearning/bin/reset-notebook
  

  脚本执行完等3-5分钟，等所有服务初始化完成后再刷新页面。
• 兜底方案
  如果所有修复操作都无效，先给实例挂的磁盘做快照备份Notebook里的代码、数据，之后删除故障实例，重新创建同配置的User Managed Notebook，再把备份的磁盘挂载到新实例上即可恢复原有数据，不需要重新配置环境。

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