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.js8502 端口连不上 APIFastAPI5055 端口这是 Open Notebook 最常见的连接类故障见 Connection Issues。本文按文档给出的诊断命令和修复分支给出一条从“服务是否在跑”到“API_URL 是否匹配”的连续排查路径适用于标准的docker compose单容器部署以及配置了反向代理或从其他机器远程访问的部署。确认你看到的是同一类故障connection-issues.md 列出的 Cannot connect to server 典型现象是浏览器显示错误页提示 Unable to reach API 或 Cannot connect to serverUI 能加载但无法创建 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 没在运行进入下面的分支。第二步按检查结果走对应修复分支分支 AAPI 没在运行或刚启动还没就绪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分支 CAPI_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_URLhttp://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键同样触发重新检测重启服务后可以先点它而不必刷新整页。相关但不同的现象别混进本流程connection-issues.md 里以下故障与 Cannot connect to server 相邻但处理路径不同遇到时转到对应分支Connection refused/ECONNREFUSED/socket hang upAPI 端口没开、API 崩溃或 IP 写错。按文档顺序查docker ps、查端口lsof -i :5055、查日志docker compose logs api | tail -30找 error、重启 API。502 Bad Gateway反向代理代理连不到后端。在代理所在机器curl http://localhost:5055/health验证后端并核对 nginx 配置——常见错误是proxy_pass漏掉/api路径HTTPS 场景记得设API_URLhttps://yourdomain.com。CORS 报错前端与 API 的 URL 或协议不匹配核对API_URL的协议http/https与前端实际访问地址一致后docker compose restart frontend多容器布局。间歇性断开文档建议开启重试SURREAL_COMMANDS_RETRY_ENABLEDtrue等.env变量并降低并发SURREAL_COMMANDS_MAX_TASKS2这类调整会改变整体行为不属于本次连接失败的默认动作。排查完仍无法定位时docker compose logs的完整输出、docker compose restart后的表现以及你当前的部署方式单容器/多容器/反向代理是 Troubleshooting Index 建议的下一步求助材料。【免费下载链接】open-notebookAn Open Source implementation of Notebook LM with more flexibility and features项目地址: https://gitcode.com/GitHub_Trending/op/open-notebook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
