Open Notebook 容器启动慢或依赖下载超时（国内/慢网络）怎么解决？

用 Docker 部署 Open Notebook 时，如果你的容器启动非常缓慢、启动过程中崩溃、worker 进入 FATAL 状态，或者 pip/uv 下载依赖失败，多半是网络原因：网络本身慢，或者对 Python 包仓库（PyPI）的访问受限。官方排障文档把这个场景列为常见问题 #11（Slow Startup or Download Timeouts），给出了明确的解决路径：在 docker-compose.yml 中加大下载超时，国内网络再叠加 PyPI 镜像源。本文按"识别现象 → 看日志 → 改配置 → 重启 → 验证"的顺序走一遍。

确认是这类问题：对照症状与原因

quick-fixes.md 中该条目的原始描述是：

• Symptom: Container crashes on startup, worker enters FATAL state, or pip/uv downloads fail
• Cause: Slow network or restricted access to Python package repositories

如果你观察到的现象属于上述三类之一（比如 docker compose up 后容器反复重启、日志里出现 uv/pip 拉包失败），就适用本文的操作路径；如果只是端口冲突或"Cannot connect to server"，应转到对应的 快速修复条目。

第一步：看日志，确认卡在哪一段

先确认容器当前状态和报错位置：

docker compose logs

两个值得留意的地方：

• 容器内 entrypoint（scripts/docker-entrypoint.sh）在安装可选的重型运行时时会打日志，例如 Installing Docling (first start; this pulls a large ML stack ...)，安装失败时会打 WARNING: Docling install FAILED. Booting without it ...。这类日志说明慢和失败都发生在依赖下载阶段。
• 如果 worker 进程进入 FATAL，docker compose logs 里能看到 supervisord 的进程状态变化，配合上面的下载类报错可以判断是网络问题而不是代码问题。

第二步：在 docker-compose.yml 中加大下载超时

官方给出的第一个方案是把下载超时从默认值提到 10 分钟。编辑你部署目录下的 docker-compose.yml（参考仓库中的 docker-compose.yml），在 open_notebook 服务的 environment 段加入：

environment:
  - UV_HTTP_TIMEOUT=600  # 10 minutes (default is 30s)

文档注释写明默认值为 30 秒。另外说明一个文档间的事实差异：构建镜像的 Dockerfile 中已写入 ENV UV_HTTP_TIMEOUT=120（作用于镜像构建阶段），而 quick-fixes.md 给出的运行时建议值是 600，两者并不矛盾，按排障文档的 600 在 compose 中覆盖即可。

第三步（可选，国内网络）：配置 PyPI 镜像源

如果你在中国大陆、访问 PyPI 官方源受限，文档建议同时设置 uv 和 pip 的索引地址，同样加到 open_notebook 服务的 environment 中：

environment:
  - UV_HTTP_TIMEOUT=600
  - UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
  - PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

文档给出的备选镜像：

• Tsinghua: https://pypi.tuna.tsinghua.edu.cn/simple
• Aliyun: https://mirrors.aliyun.com/pypi/simple/
• Huawei: https://repo.huaweicloud.com/repository/pypi/simple

如果你能直连官方 PyPI 且只是单纯慢，只保留 UV_HTTP_TIMEOUT=600 即可，不必换源。

第四步：重启使配置生效

配置改完后重启服务（quick-fixes.md 中该场景给出的重启命令）：

docker compose restart

验证结果

文档给出的预期是：首次启动可能需要几分钟，因为依赖在下载；之后的启动会快很多（First startup may take several minutes while dependencies download. Subsequent starts will be faster.）。按下面两步核对：

# 看启动日志，确认依赖安装完成、没有 FAILED/WARNING 下载报错
docker compose logs

# 确认 API 已经就绪
curl http://localhost:5055/health

健康检查的正常输出为 {"status":"ok"}（这是 quick-fixes.md 中给出的预期输出示例）。如果你还观察到首次启动特别久且日志里有 Docling/Crawl4AI 的安装过程，见下一节的说明。

相关限制：可选重型运行时的首次下载

除了 PyPI 依赖，docker-compose.yml 注释和 environment-reference.md 说明还有两个默认关闭的可选运行时，开启后会在首次启动时额外下载大体积依赖：

• OPEN_NOTEBOOK_ENABLE_DOCLING=true：Docling 引擎 + OCR + 图片源，文档描述为"several hundred MB to a few GB"级别的大型 ML 依赖栈；
• OPEN_NOTEBOOK_ENABLE_CRAWL4AI=true：本地 Crawl4AI 运行时，还会下载约 150MB 的 Chromium 浏览器。

两者的下载缓存都在挂载的数据卷上（docker-compose.yml 中 ./notebook_data:/app/data），所以只有第一次启动慢，后续启动走缓存。安装失败时不会阻断启动：entrypoint 会打明显的 WARNING，应用照常启动，对应引擎通过 GET /api/capabilities 报告不可用。content-processing-engines.md 还特别提醒：离线/内网部署如果连不上 PyPI，应直接保持这两个开关关闭（"If you can't reach PyPI, leave these disabled"）。

如果你的慢就来自这两个可选运行时，处理方式和上文相同：给 open_notebook 服务加上 UV_HTTP_TIMEOUT=600 和镜像源，等首次安装跑完并落盘到缓存卷即可。

还解决不了时

按 troubleshooting 索引 的诊断清单继续：docker ps 看容器状态、docker compose logs | head -50 抓最近日志、curl http://localhost:5055/health 验证连通性。资源不足类问题（磁盘、内存）也在 quick-fixes.md 的条目 #9 中有对应检查项（df -h 检查至少 5GB 空闲空间等）。