Open Notebook 浏览器提示 “Cannot connect to server“ 怎么排查？-编程实验室

Open Notebook 浏览器提示 "Cannot connect to server" 怎么排查？

【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook

用 Docker Compose 部署的 Open Notebook 打开http://localhost:8502时，浏览器弹出错误页提示 "Cannot connect to server" 或 "Unable to reach API"，页面能加载但无法创建 Notebook、无法操作界面。项目文档把这种情况归因为前端（Next.js，8502 端口）连不上 API（FastAPI，5055 端口），这是 Open Notebook 最常见的连接类故障（见 Connection Issues）。本文按文档给出的诊断命令和修复分支，给出一条从“服务是否在跑”到“API_URL 是否匹配”的连续排查路径，适用于标准的docker compose单容器部署，以及配置了反向代理或从其他机器远程访问的部署。

确认你看到的是同一类故障

connection-issues.md 列出的 "Cannot connect to server" 典型现象是：

浏览器显示错误页；
提示 "Unable to reach API" 或 "Cannot connect to server"；
UI 能加载，但无法创建 Notebook 等需要调用 API 的操作。

如果你的现象是浏览器控制台里的 CORS 报错（Cross-Origin Request Blocked、Access-Control-Allow-Origin）或502 Bad Gateway，那属于同一文档中的独立分支（分别由前端与 API 的 URL 不匹配、反向代理连不到 API 引起），修复动作不一样，本文最后会给出指向。先按下面这条主线走。

第一步：在服务端确认服务和端口

文档给出的最短诊断路径是（摘自 Quick Fixes 第 1 条）：

# 1. 确认 API 是否在运行 docker ps | grep api # 2. 确认 5055 端口能响应 curl http://localhost:5055/health # 3. 不通过就重启所有服务 docker compose restart # 4. 重新打开浏览器访问 # http://localhost:8502

执行时要注意两点：

服务名取决于你的 compose 布局。仓库根目录的 docker-compose.yml 只定义surrealdb和open_notebook两个服务，标准部署下docker ps | grep api是匹配不到东西的，应改用docker compose ps确认所有服务显示为 "Up"。docker ps | grep api适用于 reverse-proxy.md 中 frontend/api 拆分的多容器布局，那种布局里才存在名为api的服务。
health 接口的返回内容。文档对curl http://localhost:5055/health的期望输出写得不一致：connection-issues.md 和 quick-fixes.md 写的是{"status":"ok"}，而 docker-compose 安装文档写的是{"status": "healthy"}，与源码中实际返回一致——见 api/main.py 中的 health 端点：

@app.get("/health") async def health(): return {"status": "healthy"}

因此判断标准是：命令返回一个包含status字段的 JSON 就算 API 可达；如果 curl 直接连接失败（拒绝连接、超时），说明 5055 端口根本没暴露或 API 没在运行，进入下面的分支。

第二步：按检查结果走对应修复分支

分支 A：API 没在运行或刚启动还没就绪

Quick Fixes 的解法就是docker compose restart，然后重新打开http://localhost:8502。docker-compose 安装文档的 Troubleshooting 部分还提示：首次运行时服务可能需要 20–30 秒才能起来，刚执行完docker compose up -d就访问报这个错时，先等一等再查。用日志确认 API 是否真正启动、有没有报错：

# 标准两服务布局（surrealdb + open_notebook） docker compose logs open_notebook | tail -30 # 文档中对多容器布局给出的等价命令 docker compose logs api | tail -30

如果docker compose ps显示服务压根不在运行，直接启动：

docker compose up -d

分支 B：端口没有暴露

docker compose ps的端口列应能看到0.0.0.0:5055->5055/tcp（以及 8502 的映射）。如果看不到，检查 compose 文件里open_notebook服务的ports是否包含"5055:5055"，仓库默认文件里是有的：

ports: - "8502:8502" # Web UI - "5055:5055" # REST API

缺失时补上"5055:5055"，然后重启。注意docker compose down会停止并移除容器（不带-v时./notebook_data、./surreal_data数据卷内容不受影响，只有docker compose down -v才会删除数据）：

docker compose down docker compose up -d

分支 C：API_URL 与前端地址不匹配

connection-issues.md 给出的对应命令：

# 查看当前 .env 里的 API_URL cat .env | grep API_URL

文档中的匹配示例：前端地址是http://localhost:8502时，API_URL应为http://localhost:5055。改错时修正.env中的API_URL并重启。另外可以用容器内视角确认运行时实际生效的值：

docker exec open-notebook env | grep API_URL

关于API_URL的选取，reverse-proxy.md 说明前端按三级优先级确定 API 地址：运行时环境变量API_URL（最高优先级）> 构建期NEXT_PUBLIC_API_URL> 从请求头自动推断（用host头构造{protocol}://{hostname}:5055，并遵循X-Forwarded-Proto）。自动推断在反向代理等复杂拓扑下可能失败，所以文档建议：

配置了反向代理时，显式设置API_URL为公网 URL，且用https://；
API_URL末尾不要带/api，系统会自动补上；
前端是 HTTPS 时API_URL不能是http://，否则会出现混合内容/CORS 报错。

分支 D：从其他机器访问时被防火墙挡住

如果你是在局域网或远程机器上访问，文档的 "Different Machine / Remote Access" 一节给出流程：

# 1. 在服务器上查 IP hostname -I # 或 ifconfig | grep "inet " # 2. .env 或 compose 中把 API_URL 指向服务器 IP # API_URL=http://192.168.1.100:5055 # 修改后 docker compose restart # 3. 客户端浏览器访问 http://192.168.1.100:8502

验证端口与防火墙时，需要在服务器和客户端分别执行；ufw命令需要 root 权限：

# 服务器上确认端口在监听 netstat -tlnp | grep 5055 # 客户端确认能连通 telnet 192.168.1.100 5055 # 服务器防火墙放行（需要 sudo） sudo ufw allow 8502 sudo ufw allow 5055

第三步：用浏览器控制台看前端实际请求的地址

修复API_URL类问题时，最直接的证据在浏览器里。按 reverse-proxy.md 的 "How to Debug Configuration Issues"：

打开 F12 控制台，找以🔧 [Config]开头的日志，它会显示前端最终使用哪个 API URL；
文档示例（原文示例输出，不是固定预期）：

# 正常： ✅ [Config] Runtime API URL from server: https://your-domain.com # 异常： ❌ [Config] Failed to fetch runtime config ⚠️ [Config] Using auto-detected URL: http://localhost:5055

第二条异常输出的含义是：运行时配置没取到，前端回退到自动推断。如果你是通过 IP 或域名访问、而推断结果落到了localhost:5055，浏览器自然连不上——显式设置API_URL就是解法。

前端错误页本身（ConnectionGuard 触发）也会显示它尝试访问的 URL（{当前页面 origin}/api/config），可以和服务端检查结果互相印证。

验证修复结果

按文档的 "Testing Connection" 清单逐项过一遍即可：

# 1. 服务都在跑 docker compose ps # 2. 端口在监听 netstat -tlnp | grep -E "8502|5055" # 3. API 有响应（返回含 status 字段的 JSON，见上文两种文档示例） curl http://localhost:5055/health # 4. 前端页面可达 curl http://localhost:8502 | head

全部通过后，重新打开http://localhost:8502：界面正常显示、可以创建 Notebook，即视为修复完成。前端错误页上也有 Retry 按钮（按R键同样触发重新检测），重启服务后可以先点它而不必刷新整页。