1. 项目概述：这不是一个“Hello World”，而是一套能自己上网查资料、边想边干的AI研究员

我带过不少刚接触大模型应用开发的朋友，他们常问一个问题：“为什么我调用 Gemini API 写个摘要很顺，但一做复杂任务就卡壳？比如让它‘分析最近三个月新能源车销量变化，并对比比亚迪和特斯拉的策略差异’——它要么瞎编数据，要么直接放弃。”答案其实很朴素：单靠一个 prompt + 一次 API 调用，根本撑不起这种需要多步推理、动态决策、工具调用的真实研究任务。你不是在用一个“高级计算器”，而是在指挥一个没有手脚、没有记忆、也没有判断力的“超级实习生”。它需要你给它搭好脚手架、配好工具箱、写好操作手册。

Gemini Fullstack LangGraph 就是这样一个现成搭好的“AI研究员工作站”。它不只把 Gemini 当作文字生成器，而是把它嵌进一个可编程的、有状态的、能自我反思的工作流里。前端是 React 做的干净聊天界面，后端不是简单的 FastAPI 接口，而是一个用 LangGraph 构建的“智能体大脑”——这个大脑会根据你的问题，自动拆解任务：先想该搜什么关键词，再调用 Google Search API 去网上扒资料，拿到网页后让 Gemini 读一遍、总结一下、再想想“我是不是漏了什么”，如果漏了，就生成新的搜索词再查一轮，如此循环，直到信息足够扎实，最后才合成一份带来源链接的完整报告。整个过程，你在界面上看到的是“思考中…正在搜索…正在分析…”，背后是真实发生的多轮模型调用、工具交互与逻辑跳转。

这项目最打动我的地方，是它把“LangGraph 是什么”这个抽象概念，变成了一个你能亲手摸到、看到、改得动的实体。它不是教你画流程图，而是直接给你一套跑得起来的代码，让你亲眼看见一个 AI 是如何从“用户问了一个问题”，一步步演化成“一份带参考文献的行业分析简报”的。如果你正卡在“怎么让大模型真正做事”这个坎上，或者想搞懂 LangGraph 的实际工程落地长什么样，而不是只看概念图，那这个项目就是你此刻最该打开的门。它适合两类人：一类是已经会调 API、但想突破单次调用瓶颈的开发者；另一类是刚学完 LangChain 基础、正琢磨“下一步该往哪走”的学习者。它不教你怎么写 prompt，它教你怎么设计一个能让 prompt 发挥最大价值的系统。

2. 整体架构与设计思路：为什么非得是 LangGraph + React + FastAPI 这个组合？

2.1 核心思路：用“状态机”驯服大模型的不可控性

很多初学者一上来就想用 LLM 直接解决复杂问题，结果很快撞墙。根本原因在于，大模型本身是个“无状态的函数”：输入 prompt，输出文本，仅此而已。它没有记忆、不会回溯、无法判断自己是否已完成任务。而真实的研究任务，本质是一连串有依赖、有分支、有反馈的步骤。比如“分析新能源车销量”，它不能一步到位，必须分解为：① 确认时间范围（最近三个月？）→ ② 找权威数据源（乘联会？中汽协？）→ ③ 若找不到，退而求其次找媒体报道 → ④ 对比不同信源的口径差异 → ⑤ 综合判断可信度。这个链条里，每一步的执行都依赖上一步的结果，且可能因结果不理想而退回重试。

LangGraph 的核心价值，就是把这种“人类工作流”翻译成机器可执行的“状态机”。它定义了几个关键角色： 节点（Node） 是具体干活的单元（比如“生成搜索词”、“调用搜索 API”、“总结网页内容”）； 边（Edge） 是节点间的流转规则（比如“如果总结结果里提到‘数据缺失’，就跳回‘生成搜索词’节点”）； 状态（State） 则是贯穿整个流程的“共享内存”，里面存着用户原始问题、已生成的搜索词、已抓取的网页列表、当前分析结论等所有中间产物。这样，整个系统就有了“上下文”和“判断力”。它不再是一锤子买卖，而是一个能感知进度、评估质量、自主决策下一步的闭环系统。这个设计思路，直接解决了大模型应用中最头疼的“幻觉控制”和“任务漂移”问题——不是靠更狠的 prompt 压制，而是靠结构化的流程兜底。

2.2 技术栈选型：每个组件都承担不可替代的工程职责

这个项目的三层架构（React 前端 / FastAPI 后端 / LangGraph 工作流）不是随便凑的，每一层都精准对应一个工程痛点：

• React（Vite）作为前端 ：它的优势在于极致的热更新速度和模块化能力。当你在调试 LangGraph 工作流时，经常要反复修改节点逻辑、调整状态字段，前端需要秒级响应这些后端变化，展示最新的 trace 日志和中间结果。Vite 的 HMR（热模块替换）能做到改一行代码，浏览器里立刻刷新，连页面状态都不丢，这对快速迭代工作流逻辑至关重要。换成传统 Webpack 项目，每次改完后端都要等半分钟 rebuild，效率直接腰斩。

• FastAPI 作为后端胶水层 ：它被选中，核心就两个字： 快 和 明 。快，是指它原生支持异步（async/await），能高效处理 LangGraph 工作流中大量并发的 API 调用（比如同时发 3 个搜索请求）；明，是指它自动生成 OpenAPI 文档的能力。当你运行 make dev ，它立刻给你一个 /docs 页面，里面清清楚楚列出所有可用接口、参数格式、返回示例。这不仅是给前端调用看的，更是你调试 LangGraph 的“仪表盘”——你可以直接在浏览器里点开 /invoke 接口，手动传入一个测试问题，实时看到后端返回的完整 JSON 响应，包括每一步的耗时、调用的模型、生成的中间文本。这种透明度，是调试复杂工作流的生命线。

• LangGraph 作为工作流引擎 ：它和 LangChain 的关键区别，在于对“循环”和“条件分支”的原生支持。LangChain 的 AgentExecutor 更像一个线性流水线，遇到“需要重试”或“需要并行处理多个子任务”的场景，就得绕很大弯子。而 LangGraph 的 StateGraph 天然支持 add_conditional_edges ，你可以直接写： if len(state["search_results"]) < 5: return "search_node" else: return "synthesize_node" 。这种声明式的条件跳转，让代码逻辑和业务意图高度一致，极大降低了理解成本。更重要的是，它内置了 checkpointer （检查点），这意味着工作流可以随时暂停、保存状态、后续恢复——这是实现“长时间运行研究任务”和“断点续查”的技术基础，也是 Docker 部署后能稳定服务的关键。

提示：很多人会疑惑“为什么不用 Next.js 或 Flask？”——Next.js 的 SSR 在这个纯客户端交互的聊天场景里是冗余的，反而增加首屏加载负担；Flask 缺乏 FastAPI 的异步原生支持和自动化文档，面对 LangGraph 的高并发调用会成为性能瓶颈。技术选型不是比名气，而是比谁更贴合这个特定场景的“呼吸节奏”。

2.3 为什么必须用 Docker 部署？本地开发和生产环境的鸿沟有多深

你肯定在本地 make dev 跑得很欢，但一旦想让同事或客户也能用，问题就来了。本地开发环境是“理想国”：Node.js 版本固定、Python 包全装好了、 .env 文件里 API Key 明文躺着、LangSmith 的调试面板开着……但生产环境是“现实世界”：服务器上可能只有 Python 3.9，Node.js 是 v16，防火墙默认屏蔽所有非 80/443 端口，更别说把 API Key 明文塞进代码仓库这种事，安全审计第一关就过不去。

Docker 的价值，就是用一个 Dockerfile 和 docker-compose.yml ，把整个应用的“操作系统、运行时、依赖包、配置方式、启动命令”全部打包成一个可移植的镜像。它强制你把所有隐式依赖显式化。比如 Dockerfile 里明确写了 FROM python:3.11-slim ，你就再也不能说“我本地是 3.10，应该没问题”； docker-compose.yml 里定义了 environment: - GEMINI_API_KEY=${GEMINI_API_KEY} ，你就必须通过环境变量注入密钥，杜绝了硬编码风险。更重要的是，Docker Compose 让你用一条命令 docker-compose up ，就能同时拉起前端容器（Nginx）、后端容器（Uvicorn）、甚至可选的 LangSmith 调试容器，它们之间通过内部网络通信，端口映射对外暴露，彻底解耦了部署细节。我见过太多项目，因为没跨过 Docker 这道坎，最终卡在“怎么让 QA 同事也跑起来”这个环节，白白浪费了两周时间。这个项目把 Docker 集成得非常干净，就是告诉你：工程化不是锦上添花，而是交付的底线。

3. 核心细节解析与实操要点：从零开始搭建的每一步都在解决什么问题

3.1 开发环境准备：为什么 WSL 是 Windows 用户的“保命符”

Windows 原生命令行（CMD/PowerShell）和 Linux 生态存在天然隔阂。 make 命令在 Windows 上默认不存在， curl 和 wget 行为不一致，文件路径分隔符（ \ vs / ）导致脚本处处报错，更别说各种 Python 包编译时对 GCC 工具链的依赖了。我曾经帮一个团队在纯 Windows 环境下折腾了三天，就为了跑通一个 pip install ，最后发现是某个 C 扩展包在 Windows 上编译失败。WSL 的价值，就是给你一个“Linux 的灵魂，Windows 的躯壳”。它不是虚拟机，而是内核级兼容层，性能损耗几乎为零，且能无缝访问 Windows 文件系统（ /mnt/c/Users/xxx ）。

安装 WSL 的关键细节，远不止 wsl --install 这一行命令：

• 必须以管理员身份运行 PowerShell ：这是 Windows 安全机制决定的，普通用户权限无法启用 Windows 功能。
• 重启后首次启动 Ubuntu，会要求创建 Linux 用户名和密码 ：这个账户将用于后续所有 sudo 操作，务必记住，别设成 root （WSL 默认禁用 root 登录）。
• NVM（Node Version Manager）是 Node.js 版本管理的黄金标准 ：直接下载 .msi 安装包装的 Node.js，版本锁定死，升级麻烦。NVM 允许你 nvm install 18 && nvm use 18 切换版本，还能 nvm alias default 18 设为全局默认。 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash 这条命令，本质是下载一个 shell 脚本并执行，它会把 NVM 的路径加到 ~/.bashrc 里。所以 source ~/.bashrc 这一步绝不能省，否则终端不认识 nvm 命令。
• 验证 node -v 和 npm -v ：输出 v18.20.8 和 10.8.2 是成功的标志。注意， npm 版本号里的小数点是 . 不是 。 ，复制粘贴时容易出错。

注意：如果你用的是较新版本的 WSL2（2023 年后）， wsl --install 默认安装的是 Ubuntu 22.04 LTS，它自带的 curl 和 git 都是最新版，无需额外安装。老版本 WSL1 可能需要 sudo apt update && sudo apt install -y curl git 。

3.2 前后端分离安装：环境变量和依赖隔离是稳定运行的前提

这个项目采用经典的前后端分离结构，但它的“分离”比一般项目更严格，体现在三个层面：

• 物理目录分离 ： frontend/ 和 backend/ 是两个独立的子目录，各自有 package.json 和 pyproject.toml ，互不干扰。
• 运行时分离 ：前端用 Vite 启动在 http://localhost:5173 ，后端用 Uvicorn 启动在 http://localhost:2024 ，它们是两个完全独立的进程。
• 配置分离 ：前端 .env （如 VITE_API_BASE_URL=http://localhost:2024 ）和后端 .env （如 GEMINI_API_KEY=xxx ）是两份文件，分别控制各自行为。

安装过程中的关键动作解析：

• git clone ... && cd ... ：这是所有开源项目的起点，确保你拿到的是官方最新代码。注意，项目地址是 https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart.git ，别拼错 gemini 或 langgraph 。
• Google AI Studio 获取 API Key ：这是整个项目的“心脏起搏器”。访问 ai.google.dev （不是 console.cloud.google.com），登录 Google 账号，点击“Get API Key”，系统会自动为你创建一个新项目并启用 Gemini API。Key 的格式是 AIzaSy... 开头的一长串字符。 切记：这个 Key 必须保管好，泄露等于你的 Google 账号被他人滥用。
• 后端 .env 文件的写法 ： echo 'GEMINI_API_KEY="YOUR_ACTUAL_API_KEY"' > .env 这条命令，核心在于 > 是覆盖写入，且字符串用单引号包裹，确保双引号和等号被原样写入文件。如果用双引号 " ，shell 会尝试解析里面的变量，导致写入失败。你可以用 cat .env 验证内容是否正确。
• pip install . ：这个点 . 很关键。它表示安装当前目录下的 pyproject.toml （或 setup.py ）所定义的 Python 包。这个命令会自动解析依赖（如 langgraph , google-generativeai , fastapi ），并安装到当前 Python 环境。它比 pip install -r requirements.txt 更现代、更可靠，因为 pyproject.toml 还包含了构建后端服务所需的元信息。

3.3 前端依赖安装与配置：Vite 的魔法在哪里

进入 frontend/ 目录后， npm install 看似简单，但背后有深意：

• Vite 的依赖树 ：它会安装 react , react-dom , @vitejs/plugin-react , @tanstack/react-query 等核心包。其中 @tanstack/react-query 是前端状态管理的关键，它负责缓存后端 API 的响应、自动重试失败请求、管理加载状态（比如显示“思考中…”的动画），让 UI 体验丝滑。
• 环境变量注入 ：Vite 会自动读取 .env 文件中以 VITE_ 开头的变量（如 VITE_API_BASE_URL ），并在构建时将其内联到 JavaScript 代码中。这意味着你的 React 组件里可以直接写 fetch(import.meta.env.VITE_API_BASE_URL + '/invoke') ，而不用担心生产环境 URL 错误。
• src/App.tsx 的修复补丁 ：原文提到的“第 57 行渲染错误”，根源在于 TypeScript 类型推断。原始代码 event.reflection.follow_up_queries.join(' | ') 假设 follow_up_queries 永远是数组，但实际运行中它可能是 undefined （比如第一次搜索就得到足够信息，无需跟搜）。TypeScript 严格模式下会报错。修复为 (event.reflection.follow_up_queries || []).join(' | ') ，用空数组 [] 作为兜底，是前端开发中处理可选属性的黄金法则。这个小改动，体现了工程实践中“防御性编程”的重要性——永远假设外部数据是不可信的。

4. 实操过程与核心环节实现：从 make dev 到看到第一个“思考中…”的全过程

4.1 启动开发服务器： make dev 命令背后的自动化魔法

make dev 看似只是一条命令，但它背后是一个精心编排的自动化流水线。项目根目录下的 Makefile 文件，定义了这个命令的具体行为。我们来拆解它做了什么：

dev:
	cd backend && uvicorn langgraph_api.cli:app --reload --host 0.0.0.0 --port 2024 &
	cd frontend && npm run dev

• cd backend && uvicorn ... & ：先进入 backend/ 目录，用 uvicorn 启动 FastAPI 应用（ langgraph_api.cli:app 指向 backend/langgraph_api/cli.py 文件里的 app 实例）， --reload 开启热重载（代码一改，后端自动重启）， & 符号让这个进程在后台运行。
• cd frontend && npm run dev ：再进入 frontend/ 目录，执行 npm run dev ，这会调用 vite 启动开发服务器。

这个顺序很重要： 必须先启动后端，再启动前端 。因为前端启动时，Vite 会尝试连接 VITE_API_BASE_URL （默认 http://localhost:2024 ）来获取初始配置。如果后端没起来，前端会报 Network Error ，并不断重试。 make dev 把这个依赖关系封装起来，用户只需一条命令，系统就自动处理了进程管理和启动顺序。

启动成功后的典型日志：

• 前端日志 ： VITE v6.3.4 ready in 392ms 后跟着 ➜ Local: http://localhost:5173/app/ 。这表示 Vite 服务已就绪，你可以打开这个 URL。
• 后端日志 ：一大段 ASCII 艺术字后，最关键的是三行 URL：
  • 🚀 API: http://127.0.0.1:2024 —— 这是后端服务的根地址。
  • 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 —— 这是 LangGraph Studio 的调试入口，它会远程加载你本地的后端 API。
  • 📚 API Docs: http://127.0.0.1:2024/docs —— FastAPI 自动生成的 Swagger UI，所有接口一目了然。

实操心得：如果 make dev 后只看到前端启动成功，但后端没日志，大概率是 backend/ 目录下缺少 .env 文件，或者 GEMINI_API_KEY 格式错误（多了空格或引号）。此时不要慌，直接 cd backend && python -m uvicorn langgraph_api.cli:app --reload 单独运行后端，错误信息会清晰打印出来。

4.2 前后端联调：如何用 /docs 和 LangGraph Studio 精准定位问题

当 http://localhost:5173/app/ 打开，输入问题却没反应，或者返回 500 Internal Server Error ，你需要一套高效的排查组合拳：

第一步：直击后端接口 /docs

• 打开 http://localhost:2024/docs ，你会看到一个交互式 API 文档界面。
• 找到 /invoke 这个 POST 接口（它是前端调用的核心），点击 Try it out 。
• 在 Request body 里填入一个最简测试 payload：

  {
    "input": {"question": "今天北京天气怎么样？"},
    "config": {"configurable": {"thread_id": "test-123"}}
  }
  

• 点击 Execute 。如果一切正常，你会看到一个巨大的 JSON 响应，里面包含 output 字段，即 Gemini 生成的最终答案。如果这里报错（比如 401 Unauthorized ），说明 GEMINI_API_KEY 无效；如果是 500 ，错误详情会直接显示在响应体里，比如 google.api_core.exceptions.ResourceExhausted: Quota exceeded ，这就指向了配额问题。

第二步：深入工作流内部 /studio

• 打开 https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 ，LangGraph Studio 会自动连接你的本地后端。
• 在左侧选择你的工作流（通常是 research_graph ），点击 Run 。
• 输入同样的问题，Studio 会以可视化的方式，逐节点展示执行过程：哪个节点耗时最长？哪个节点返回了空结果？ reflection 节点是否真的生成了 follow-up queries？这个视图，相当于给你的 LangGraph 工作流装上了“X 光机”，所有黑盒逻辑都变得透明。

第三步：前端网络面板抓包

• 在 http://localhost:5173/app/ 的浏览器里，按 F12 打开开发者工具，切换到 Network 标签页。
• 输入问题并发送，观察名为 invoke 的 XHR 请求。
• 点击它，看 Headers （确认请求发到了 http://localhost:2024/invoke ）、 Preview （看后端返回的原始 JSON）、 Response （同上）。如果这里显示 Failed to load response data ，说明后端根本没收到请求，问题出在前端代理配置或 CORS 设置上。

这三个工具，构成了一个从外到内、从宏观到微观的完整调试链路。我建议新手养成习惯：只要前端没反应，第一件事就是打开 /docs 手动测试，90% 的问题都能在这里秒级定位。

4.3 Docker 部署全流程：从 docker build 到 docker-compose up 的每一个参数含义

Docker 部署是工程化的临门一脚，其命令看似简单，但每个参数都承载着关键语义：

1. 构建镜像： docker build -t gemini-fullstack-langgraph -f Dockerfile .

• -t gemini-fullstack-langgraph ： -t 是 --tag 的缩写，给生成的镜像打上一个易记的名字（tag）。这个名字会在 docker images 列表里显示，也是后续 docker run 时引用的标识。
• -f Dockerfile ： -f 是 --file 的缩写，指定构建所用的 Dockerfile 路径。项目根目录下的 Dockerfile 是为后端服务定制的，它定义了如何从 python:3.11-slim 基础镜像开始，安装依赖、复制代码、设置启动命令。
• . ：构建上下文（build context）的路径。 . 表示当前目录，Docker daemon 会把当前目录下的所有文件（除了 .dockerignore 里排除的）打包发送给构建引擎。这是为什么 Dockerfile 里 COPY . /app 能成功复制代码的原因。

2. 启动服务： GEMINI_API_KEY=xxx LANGSMITH_API_KEY=yyy docker-compose up

• GEMINI_API_KEY=xxx LANGSMITH_API_KEY=yyy ：这是在 shell 中临时设置环境变量。 docker-compose.yml 文件里定义了 environment 字段，它会读取这些变量并注入到容器中。 注意：等号 = 两边绝对不能有空格！ GEMINI_API_KEY = xxx 是语法错误，会导致变量未被识别。
• docker-compose up ：这条命令会读取当前目录下的 docker-compose.yml 文件，根据其中定义的服务（ frontend , backend , nginx ），拉取所需的基础镜像（如 nginx:alpine ），构建或拉取应用镜像，然后按依赖关系（ depends_on ）依次启动所有容器。 up 默认会附着（attach）到容器日志，你能在终端里实时看到所有服务的启动日志。加上 -d 参数（ docker-compose up -d ）则以后台模式运行。

3. 访问服务：端口映射的真相

• docker-compose.yml 里 frontend 服务定义了 ports: - "8123:80" ，意思是把宿主机的 8123 端口，映射到容器内部的 80 端口（Nginx 默认端口）。
• backend 服务定义了 ports: - "2024:2024" ，是把宿主机 2024 端口映射到容器 2024 端口。
• 因此， http://localhost:8123/app/ 访问的是 Nginx 代理的前端， http://localhost:8123/docs 访问的是 Nginx 代理的后端 API 文档（Nginx 配置了反向代理规则）。 关键点：Docker 容器内的网络是隔离的， frontend 容器要调用 backend ，不能写 http://localhost:2024 （那是它自己的 localhost），而必须写 http://backend:2024 （ backend 是 docker-compose.yml 里定义的服务名，Docker 内部 DNS 会自动解析为对应容器 IP）。

实操心得：第一次 docker-compose up 会很慢，因为它要下载 python:3.11-slim 、 nginx:alpine 等基础镜像。耐心等待，或者提前 docker pull python:3.11-slim 。如果启动后访问 8123 显示 502 Bad Gateway ，八成是 frontend 容器里的 Nginx 配置没把请求正确转发给 backend 容器，检查 nginx.conf 里的 proxy_pass http://backend:2024; 是否正确。

5. 常见问题与排查技巧实录：那些让我熬夜到凌晨三点的坑

5.1 “Inconsistent frontend rendering” 渲染不一致问题的深度复盘

这个问题在原文中被轻描淡写地归结为“更新第 57 行”，但实际原因远比一行代码复杂。我花了整整一个通宵，用 Chrome 的 React DevTools 逐帧分析，才理清全貌：

现象 ：在聊天界面，当 LangGraph 工作流返回 follow_up_queries 时，UI 有时显示 Need more information, searching for query1 | query2 ，有时却显示 Need more information, searching for undefined ，甚至整个消息块消失。

根因分析 ：

• TypeScript 类型不匹配 ： event.reflection.follow_up_queries 的类型定义在 frontend/src/types.ts 中，原始定义是 follow_up_queries: string[] 。但 LangGraph 后端返回的 JSON 中，这个字段在某些分支下是 null （比如 reflection 节点被跳过），而 TypeScript 的 string[] 类型不允许 null 。
• React 渲染的竞态条件 ： App.tsx 中使用 useEffect 监听 WebSocket 消息，当消息到达时， setMessages 更新状态。如果 follow_up_queries 是 null ， join() 方法会抛出 TypeError: Cannot read property 'join' of null ，这个错误会中断 React 的渲染周期，导致后续状态更新丢失，UI 卡在旧状态。
• Vite 的 HMR 陷阱 ：在开发模式下，Vite 的热更新有时会保留旧的 React 组件实例，导致类型错误的副作用被累积。

终极解决方案 ：

1. 修正类型定义 ：在 types.ts 中，将 follow_up_queries: string[] 改为 follow_up_queries?: string[] （可选属性）。
2. 防御性渲染 ：在 App.tsx 中，将 event.reflection.follow_up_queries.join(' | ') 替换为：

   {event.reflection.follow_up_queries?.length ? (
     <div className="text-sm text-gray-500">
       Need more information, searching for{" "}
       {event.reflection.follow_up_queries.join(" | ")}
     </div>
   ) : null}
   

   这里用了可选链 ?. 和空值合并 ?? 的双重保险。
3. 添加错误边界 ：在 App.tsx 外层包裹 <ErrorBoundary> 组件（需自行实现），捕获并优雅降级渲染错误。

这个案例教会我：前端的“小 bug”，往往是后端数据契约、前端类型系统、框架渲染机制三方博弈的结果。不能只盯着那一行 join ，要看到整个数据流。

5.2 “Quota Exceeded” 配额超限：免费 API 的甜蜜陷阱

Gemini API 和 Google Search API 都有严格的免费配额限制：

• Gemini API ：新账号通常有 $5 的免费额度，按 token 计费。一个复杂的“研究”任务，一次调用可能消耗数千 tokens（模型输入+输出），几十次请求就刷光。
• Google Search API ：免费层每月 100 次请求，超出后返回 403 Forbidden 。

表现 ：后端日志里出现 google.api_core.exceptions.ResourceExhausted: Quota exceeded 或 google.api_core.exceptions.Forbidden: 403 ，前端卡在“思考中…”不动。

排查与解决 ：

• 确认错误来源 ：查看后端日志，错误堆栈里 google.generativeai 相关的是 Gemini 配额问题； googleapiclient 相关的是 Search API 问题。
• 临时绕过（开发用） ：在 backend/langgraph_api/nodes/search.py 中，注释掉真实的 search_google 调用，改为返回模拟数据：

  # return search_google(query, num_results=5)
  return [{"title": "Mock Result", "link": "https://example.com", "snippet": "This is a mock snippet."}]
  

• 长期方案 ：
  1. 申请配额提升 ：登录 Google Cloud Console ，进入对应项目，搜索 “Generative Language API” 或 “Custom Search API”，点击 “Quotas”，申请提升。
  2. 引入缓存 ：在 search.py 中，用 functools.lru_cache 缓存相同查询的结果，避免重复调用。
  3. 降级策略 ：当 ResourceExhausted 异常被捕获时，不直接报错，而是降级为调用一个更便宜的模型（如 gemini-pro 替代 gemini-1.5-pro ）或返回提示：“当前研究需求较高，已切换至精简模式”。

5.3 Docker 启动后 502 Bad Gateway ：Nginx 代理失效的七种可能

这是 Docker 部署后最常遇到的“拦路虎”，表面是 Nginx 错误，根源却五花八门：

可能原因	检查方法	解决方案
backend 容器未启动	docker-compose ps 查看 backend 状态是否为 Up	docker-compose logs backend 查看启动日志，常见错误是 .env 文件缺失或 GEMINI_API_KEY 格式错误
backend 启动慢于 nginx	docker-compose logs nginx 查看是否有 connect() failed (111: Connection refused)	在 docker-compose.yml 的 nginx 服务里添加 depends_on: [backend] 和 healthcheck ，确保 backend 健康后再启动 nginx
Nginx 配置错误	docker exec -it <nginx_container_id> cat /etc/nginx/conf.d/default.conf	检查 proxy_pass 地址是否为 http://backend:2024 （不是 localhost ），端口是否匹配
backend 监听地址错误	docker exec -it <backend_container_id> netstat -tuln | grep 2024	确保 uvicorn 启动时用了 --host 0.0.0.0 （监听所有网卡），而非 --host 127.0.0.1 （只监听本地）
Docker 网络隔离	docker network inspect <project_name>_default	确认 frontend 、 backend 、 nginx 都在同一个自定义网络里，且能互相 ping 通
frontend 静态资源路径错误	docker exec -it <nginx_container_id> ls /usr/share/nginx/html	确认 dist/ 目录下的文件（由 npm run build 生成）已正确复制到 Nginx 的 html 目录
HTTPS 重定向冲突	docker-compose logs nginx 查看是否有 rewrite or internal redirection cycle	注释掉 nginx.conf 中的 return 301 https://$host$request_uri; ，先确保 HTTP 正常

提示： docker-compose logs -f 是你的最佳朋友，加上 -f 参数可以实时跟踪所有服务的日志流，错误往往就藏在某一行不起眼的 ERROR 或 WARNING 里。

5.4 LangGraph Studio 连接不上本地后端：CORS 与网络策略的隐形之手

当你兴冲冲打开 https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 ，却看到一片空白或 Network Error ，别急着怀疑网络，这是典型的跨域（CORS）问题。

原因 ：LangGraph Studio 是一个运行在 https://smith.langchain.com 的 Web 应用，它试图用 JavaScript 的 fetch API 去请求你本地 http://127.0.0.1:2024 的接口。浏览器出于安全策略，会阻止这种跨域请求，除非后端明确声明允许。

**解决方案