SSE流式传输实战：Next.js+FastAPI+OpenWebUI搭建聊天应用

前阵子完整跑通了一套前后端分离的聊天产品，前端用 Next.js 负责页面和交互，后端用 FastAPI 做业务逻辑与流式转发，模型层直接对接 OpenWebUI 暴露的 API。整套链路从浏览器里的一个回车，到最终模型逐字吐出内容，中间要经过三层服务，每一层都涉及流式传输、用户鉴权和会话状态管理。这篇文章不是架构设计文档，而是把我在实际搭建过程中踩过的坑、验证过的方案、以及可以直接抄走的代码切片完整梳理一遍，适合那些想基于现成模型网关快速做聊天类产品，又希望前端体验自己掌控的团队参考。

这套方案最大的价值在于分工非常干净：Next.js 管界面和流式渲染，FastAPI 管用户、权限和转发，OpenWebUI 管模型路由和历史会话。你不需要自己维护模型调度，也不需要把模型服务商的密钥直接暴露在浏览器里，业务系统的边界会清晰很多。接下来我从设计思路开始讲，然后逐步拆到代码和部署层面。

1. 项目背景与整体设计思路

1.1 这个项目到底解决什么问题

聊天产品在早期原型阶段通常有两种做法。一种是在前端页面里直接调用模型服务商的接口，浏览器发请求、拿结果、渲染。这种做法开发速度最快，但问题也很明显：接口密钥一旦放进前端代码，就等于公开了；跨域策略、请求鉴权、用户体系全部需要另外处理；多模型切换或者接企业内部知识库时，根本没有统一入口。

另一种做法是用传统后端模板渲染页面，服务端把聊天内容生成好再返回 HTML。这种方案安全边界好控制，但页面交互体验很难做到现代聊天应用那种流畅的流式输出，前端团队和后端团队耦合在一起，迭代效率也不高。

这个项目采用的就是第三种路径：前后端分离，中间加一层业务后端，模型侧接 OpenWebUI。前端不用关心模型从哪来、怎么鉴权，后端不用关心按钮状态和 DOM 渲染，OpenWebUI 不用关心你是谁、有没有权限。每一层的职责单一，出了问题也能快速定位是界面、转发还是模型网关的故障。

1.2 选型逻辑：为什么是 Next.js + FastAPI + OpenWebUI

三个组件不是随便凑在一起的，每一个都是对比过替代品之后定下来的。

Next.js 选它的核心原因是它对流式渲染支持得非常好。聊天产品最重要的体验就是“一个字一个字往外蹦”，Next.js 的 App Router 可以直接在服务端组件里读流、客户端组件里渲染增量内容，配合 React 的并发特性，UI 更新非常丝滑。它还自带路由、SSR、静态导出，前端部署方案很灵活。相比纯 Vite + React 的 SPA，Next.js 在 SSR 场景下对首屏加载和 SEO 更友好；相比纯 Django 模板渲染，它的交互体验又明显高一个档次。

FastAPI 则是 Python 生态里最适合做流式网关的框架。它基于 ASGI，异步能力是原生的，配合 httpx 的异步流式请求，可以在不占用线程池的情况下把上游模型的 token 流一个字节一个字节转发到前端。再加上 Pydantic 做请求参数校验，写接口的体验非常顺。如果换成 Flask 的同步模型，长连接一多，线程池很快被打满，服务和数据库都会被拖垮。

OpenWebUI 的价值在于它把“模型网关”这件事做好了。它对外提供的是业界通用的 /v1/chat/completions 风格接口，可以对接多家模型服务商、内部模型、甚至本地方案；同时自带会话管理、多用户支持、历史记录等能力。如果你不想在业务后端里重复造“模型路由”和“会话存储”这两个轮子，选它作为模型入口是很务实的决定。我的观点是：能用成熟开源组件解决的事情，尽量不要自己写，把精力留给你真正有业务差异化的地方。

2. 分层架构与数据流拆解

2.1 三层分工的边界在哪里

我最终落地的架构是三段式：浏览器 -> Next.js -> FastAPI -> OpenWebUI -> 模型。很多初学者会困惑：Next.js 和 FastAPI 都有 API 能力，边界到底怎么划。我的划分标准很简单：

这个边界确保了每一层都能独立替换。比如前端不喜欢 Next.js 可以换成纯 React 或者 Vue，只要协议不变；后端想从 FastAPI 改成 Node.js 也可以，只要继续对接 OpenWebUI 的接口。我在实际项目中就见过前端换框架、后端换语言的案例，因为边界清晰，切换成本比预想低很多。

2.2 一次聊天消息的完整流转

完整链路我建议你在写代码之前先画清楚，因为后来所有调试都是围绕这条链路展开的。以用户输入“帮我写一段 Python 冒泡排序”为例：

用户在输入框按下回车，Next.js 页面先把这条消息本地渲染出来，同时把对话历史拼接成请求体，通过 fetch 发送到 FastAPI 的 /api/chat/stream 接口。FastAPI 第一步是校验用户的 JWT，确认会话归属，接着把请求体转发给 OpenWebUI 的聊天补全接口，并附上服务端持有的 API Key。OpenWebUI 拿到请求后，根据模型配置调用具体的模型服务商接口，模型开始流式生成内容。OpenWebUI 把模型的输出 token 流逐步返回给 FastAPI，FastAPI 在返回流中透传事件，Next.js 端通过 ReadableStream 读取，增量更新 UI，把 delta 内容不断追加到气泡里，直到收到结束标记。

这个链路里最容易出问题的是协议格式在每一层都略有不同。浏览器和 FastAPI 之间是我自定义的 SSE 事件格式；FastAPI 和 OpenWebUI 之间是业界通用的聊天补全格式；OpenWebUI 和模型服务商之间又是它内部自己定义的格式。所以调试的时候要一层一层验证，我在后文会专门展开排查方法。

2.3 为什么用 SSE 而不是 WebSocket 或轮询

聊天补全场景是一个典型的“下行为主”的数据流：用户发一次请求，模型长时间持续返回内容，用户在这段时间内基本不需要向服务器发送额外数据。用 WebSocket 做当然可以，但它带来了不必要的复杂度：需要处理连接建立、心跳、消息帧格式、粘包问题，还需要考虑后端服务的连接状态同步。SSE（Server-Sent Events）是纯 HTTP 协议，浏览器原生支持 EventSource，自动重连机制也内置了，配合 fetch 的流式读取，体验上和 WebSocket 几乎没有差别。

轮询则是最不推荐的做法。每隔几百毫秒问一次“有没有新内容”，请求量大、响应延迟高，而且对于聊天这种高频交互场景，浪费的服务器资源非常明显。当然，如果你未来要做的产品是实时协同编辑、在线白板这种双向高频互动场景，再考虑 WebSocket 也不迟。

3. 核心模块实现实录

3.1 前端：Next.js 流式接收与渲染状态机

前端最关键的一段代码是从 fetch 响应体里读流。直接使用浏览器接口的时候，最容易忽略的就是：响应体不是一次性到达的，需要持续读取 ReadableStream，并且注意解码器要用 stream: true，否则多字节字符（尤其是中文）在跨 chunk 边界时会被截断，出现乱码。

// app/api/chat/stream 的前端调用封装 async function sendChatRequest(messages, onDelta, signal) { const response = await fetch('/api/chat/stream', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ messages }), signal, }); if (!response.ok) { throw new Error(`请求失败: ${response.status}`); } const reader = response.body.getReader(); const decoder = new TextDecoder('utf-8'); let buffer = ''; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const lines = buffer.split('\n'); // 最后一行可能是不完整的，需要留在 buffer 里继续拼接 buffer = lines.pop() || ''; for (const line of lines) { if (!line.startsWith('data:')) continue; const payload = JSON.parse(line.slice(5).trim()); if (payload.type === 'delta') { onDelta(payload.content); } else if (payload.type === 'done') { // 流结束 } else if (payload.type === 'error') { throw new Error(payload.message); } } } }

对应的 UI 状态机建议用四个状态来管理：idle 表示等待用户输入，loading 表示请求已发出但还没有任何返回内容，streaming 表示正在逐字接收内容，error 表示出错需要展示错误信息。很多聊天页面出现“内容已经生成完了但界面还在转圈”的问题，就是因为没有把 loading 和 streaming 分开，导致关闭 loading 动画的时机不对。

另外强烈建议在 React 组件里把 AbortController 和请求生命周期绑定。聊天页面常见的崩溃场景是用户切换会话、刷新页面或者发起新请求时，旧请求还在继续写状态，导致 UI 出现幻觉内容。用 AbortController 在每次请求开始前记录，在组件卸载或请求失效时主动中断，能省掉大量现场排查的麻烦。

3.2 后端：FastAPI 的 SSE 落地与转发实现

后端接口我采用 sse-starlette 库来实现 SSE 响应，它的 EventSourceResponse 处理了 HTTP 响应头、空行分隔、断线重连等底层细节，比自己直接拼字符串要稳得多。核心逻辑是启动一个异步生成器，内部再用 httpx.AsyncClient 的 stream 方法去请求 OpenWebUI。

# fastapi_app.py 关键部分 from fastapi import FastAPI, Request, Depends, HTTPException from fastapi.middleware.cors import CORSMiddleware from sse_starlette.sse import EventSourceResponse import httpx import json app = FastAPI() app.add_middleware( CORSMiddleware, allow_origins=["http://localhost:3000"], allow_methods=["*"], allow_headers=["*"], ) OPENWEBUI_BASE_URL = "http://openwebui:8080" OPENWEBUI_API_KEY = "sk-xxxx" # 服务端持有，绝不下发前端 async def verify_user(request: Request): # 这里校验 JWT，返回当前用户 ID # 省略具体实现 ... return "user_123" @app.post("/api/chat/stream") async def chat_stream(request: Request, user_id: str = Depends(verify_user)): body = await request.json() messages = body.get("messages", []) # 业务侧可在这里做消息过滤、长度限制等 async def event_generator(): async with httpx.AsyncClient(timeout=None) as client: payload = { "model": "default", "messages": messages, "stream": True, } headers = {"Authorization": f"Bearer {OPENWEBUI_API_KEY}"} async with client.stream( "POST", f"{OPENWEBUI_BASE_URL}/api/chat/completions", json=payload, headers=headers, ) as resp: if resp.status_code != 200: error_text = await resp.aread() yield { "event": "error", "data": json.dumps({"message": f"上游错误: {error_text.decode('utf-8', 'ignore')}"}) } return async for line in resp.aiter_lines(): if not line.startswith("data:"): continue data = line[5:].strip() if data == "[DONE]": yield {"event": "done", "data": "{}"} break yield {"event": "message", "data": data} return EventSourceResponse(event_generator())

这里有一个非常关键的决策：后端使用系统级 API Key 去请求 OpenWebUI，而不是把每个用户的 JWT 直接透传。这样做的原因是，模型网关和业务系统的用户体系不同，JWT 到 OpenWebUI 那边根本无法识别，强行透传只会得到 401。正确做法是保持“业务用户”和“模型调用凭证”隔离：浏览器只持有自己的 JWT，FastAPI 根据 JWT 判断用户身份和会话权限，再用服务端保存的 OpenWebUI Key 发起模型调用。

3.3 对接 OpenWebUI API 时容易踩的接口差异

OpenWebUI 不同版本的 API 路径和字段会有差异。在我接触的一些版本里，对外暴露的兼容端点通常遵循业界通用的聊天补全格式：POST 到 /api/chat/completions，请求体包含 model、messages、stream 三个字段，响应流中每行是 data: {"choices": [{"delta": {"content": "..."}}]}。

建议你在写业务代码之前，先用 curl 验证你部署的那一版 OpenWebUI 具体路径是什么，不要死记硬背：

curl -N -X POST http://localhost:3001/api/chat/completions \ -H "Authorization: Bearer sk-xxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "default", "messages": [{"role": "user", "content": "你好"}], "stream": true }'

看到形如data: {"choices":[{"delta":{"content":"你"}}]}的连续输出，再开始对接。这个验证步骤能避免你在业务代码里写错路径或者字段名之后，花费大量时间排查到底是哪一层出了问题。

另外 OpenWebUI 返回的 choices 数组在最开始时可能是空的，不要假设第一行就一定包含 content。实现解析逻辑时要把 delta 可能缺失的情况处理好，宁可漏掉一个空包，也不要让前端解析 JSON 直接报错。

4. 会话管理、多用户隔离与安全设计

4.1 会话记录应该由谁保存

聊天产品必然涉及历史会话。常见的错误是把会话和消息记录全部交给 OpenWebUI 管理，业务后端完全不落库。这样做短期能用，但长期会出现严重问题：OpenWebUI 的会话是跟着模型网关的用户走的，当业务用户注销、权限变更或者你需要根据业务数据库关联分析聊天记录时，数据根本对不上。

我推荐的方案是业务后端保存“会话元数据”和“消息本体”。前端创建新会话时，先调 FastAPI 创建一个会话记录，拿到会话 ID；之后所有聊天请求都带上这个会话 ID。FastAPI 在转发给 OpenWebUI 之前，把自己的把对数据库插入一条消息记录，记录内容包含会话 ID、角色、内容、时间戳。模型返回之后，再把完整的回复写入数据库。这样你既有 OpenWebUI 里的实时对话流，也有业务数据库里的权威历史记录，两边数据完全可控。

4.2 双层鉴权模型与 Token 存储

整个系统里存在两种凭据：用户的身份凭证（JWT）和系统的模型调用凭证（OpenWebUI API Key）。用户 JWT 由 FastAPI 签发，可以放在 httpOnly Cookie 里，这样浏览器里的 JavaScript 脚本无法读取，能有效降低 XSS 攻击导致 token 泄露的风险。OpenWebUI API Key 永远只存在于后端环境变量中，绝不进前端代码或接口响应。

很多人在做前后端分离登录时，喜欢把 JWT 放在 localStorage 里，图的是调用方便。但在聊天类产品里，用户消息里可能粘贴各种来源的文本，前端渲染时很容易引入不可信 HTML，一旦 XSS 攻击拿到 localStorage，用户身份直接被盗。用 httpOnly Cookie 至少能把这个风险窗口缩小很多。如果你担心 CSRF，配合 SameSite 属性和请求来源校验已经足够大部分场景使用。

4.3 输入校验、限流与内容安全

聊天接口是公开暴露的，如果不加限制，很容易被脚本刷爆，产生高额模型调用费用。FastAPI 层必须做三件事：长度校验、频率限制、内容过滤。

长度校验很简单，用 Pydantic 控制 messages 数组长度和 message.content 的最大长度，比如限制单条消息不超过 8000 字符，单次对话上下文不超过 20 条。频率限制可以用简单的内存限流器，以用户 ID 为维度，每 10 秒最多请求一次。生产环境建议用分布式限流组件，但开发阶段内存版完全够用。内容过滤方面，至少要有一个敏感词列表和基础的 HTML 标签剥离逻辑，防止恶意内容进入模型上下文。

5. 部署与运行配置实录

5.1 本地开发环境启动流程

本地开发我建议用 Docker 启动 OpenWebUI，其他两个服务直接用命令行跑，这样迭代最快。流程是：

1. 先启动 OpenWebUI 容器，映射端口 3001；
2. 在 OpenWebUI 界面里创建管理员账号，进入后台生成 API Key；
3. 启动 FastAPI，环境变量里填 OPENWEBUI_BASE_URL 和 OPENWEBUI_API_KEY；
4. 启动 Next.js 开发服务器，通过代理或 CORS 访问 FastAPI。

docker run -d --name openwebui -p 3001:8080 \ -v openwebui_data:/app/backend/data \ ghcr.io/open-webui/open-webui:main export OPENWEBUI_BASE_URL=http://localhost:3001 export OPENWEBUI_API_KEY=sk-xxxx uvicorn fastapi_app:app --reload --port 8000 cd frontend npm run dev

前端开发服务器默认端口 3000，访问 http://localhost:3000 即可。开发阶段我会在 next.config.js 里配置 rewrite，把 /api 下的请求转发到 localhost:8000，这样浏览器就不会遇到跨域问题，代码里所有请求都走相对路径。

5.2 生产部署的容器编排

生产环境我用 Docker Compose 把三个服务编排在一个网络里。前端容器跑 npm run start，后端容器跑 uvicorn，OpenWebUI 单独挂一个数据卷。前端对外访问时通过 Nginx 反代，需要注意 SSE 相关的两个关键参数：proxy_buffering 必须关掉，否则 Nginx 会缓冲整个响应流，导致前端迟迟收不到数据；proxy_read_timeout 要调大，比如 300 秒，否则模型推理时间稍长就被 Nginx 掐断。

version: "3.8" services: openwebui: image: ghcr.io/open-webui/open-webui:main restart: unless-stopped ports: - "3001:8080" volumes: - openwebui_data:/app/backend/data environment: - ANONYMIZED_TELEMETRY=false backend: build: ./backend restart: unless-stopped ports: - "8000:8000" depends_on: - openwebui environment: - OPENWEBUI_BASE_URL=http://openwebui:8080 - OPENWEBUI_API_KEY=${OPENWEBUI_API_KEY} - DATABASE_URL=sqlite:///./data/chat.db frontend: build: ./frontend restart: unless-stopped ports: - "3000:3000" environment: - NODE_ENV=production volumes: openwebui_data:

这里要注意一个坑：Next.js 的 NEXT_PUBLIC_ 前缀变量会在构建时被编译进 JS 包，所以不要在生产环境里用 NEXT_PUBLIC_API_BASE_URL 这种方式指定后端地址。正确做法是让前端容器只跑页面，所有 API 请求走同一个域名，由 Nginx 按路径分发到对应后端，这样既避免跨域，也避免了构建时环境变量不一致的坑。

5.3 关键配置清单与参数说明

这套配置的核心思路是：前端能接触到的只有业务接口和错误信息，所有凭据和内部地址都在后端环境变量里。

6. 常见问题与排查技巧实录

6.1 流式响应像挤牙膏一样，半天不出字

表现：接口最终能返回完整内容，但前端等待很久之后才一次性显示，完全感受不到流式效果。

我遇到过的原因有四种。第一种是 Nginx 的 proxy_buffering 没有关闭，响应被缓冲在 Nginx 层，必须加proxy_buffering off;。第二种是响应头缺少Cache-Control: no-cache或者X-Accel-Buffering: no，某些反代组件默认会缓冲。第三种是上游模型服务本身就不是流式返回，OpenWebUI 的 stream 参数没有生效，需要单独用 curl 验证上游是否真的逐行输出。第四种是前端解码逻辑的问题，buffer 处理不对，导致所有内容等到最后才被消费，这个排查方法很简单：打开浏览器开发者工具看响应预览，如果请求体里的网络标签页显示内容是连续增加的，那问题就在前端解析层。

6.2 Next.js 开发模式下请求被发两次

表现：每次发送聊天请求，后端日志里出现两条相同记录，前端展示时出现重复消息。

这是 React StrictMode 的典型行为。开发模式下 React 会故意执行两次 effect，暴露异步操作没有清理的问题。解决方案是在发起请求的 effect 里正确使用 AbortController，在清理函数中中断上一次请求；或者在事件处理函数里手动触发请求，而不是依赖 effect。注意不要因为“请求发了两次”就简单屏蔽 StrictMode，那会掩盖其他并发问题。

6.3 上游返回 500，前端却拿到 200

表现：模型网关已经报错，但前端页面还处于正常状态，用户看到的是一片空白。

原因是 FastAPI 作为 SSE 代理层，即使上游出错，它依然返回了 200 状态码，需要等前端自己解析错误事件才知道出问题了。改进方式是在 event_generator 里捕获上游的非 200 状态，转为 error 事件发出；或者在 HTTP 层拦截特定错误场景直接返回非 200。我的经验是：SSE 场景下，不要把错误状态寄托在 HTTP 状态码上，必须设计一套应用层错误事件协议，前端要解析并渲染错误信息。表格里可以这样对应：

6.4 SSE 中文出现乱码或 JSON 半截

表现：英文内容正常，中文内容偶尔出现“�”符号，或者个别消息解析失败。

绝大多数情况是因为在前端读取流时，没有使用 TextDecoder 的 stream 模式。当一段中文 UTF-8 字符被拆到两个 chunk 里时，第一个 chunk 末尾是不完整的字节序列，如果立刻按字符串处理就会乱码。解决办法在前文 3.1 节已经给出：decoder.decode(value, { stream: true })，每次解码后把 buffer 最后一行留下，等下一个 chunk 到达再拼接。另外后端转发时不要用 resp.text() 一次性读取再转发，必须用 aiter_lines 逐行转发，否则流式效果丢失。

6.5 会话历史被重复追加

表现：打开历史会话时，消息列表出现重复，或者一轮对话结束后气泡数量翻倍。

这个问题的根源通常是前端把“本地乐观渲染的消息”和服务端返回的“完整历史记录”混用了。我推荐的数据流策略是：前端展示的消息以服务端接口返回为准。本地提前渲染只是为了用户感知，但收到服务端权威数据后要替换整个消息数组，而不是追加。后端在每次 SSE 流结束后，把保存的完整消息记录返回给前端，前端直接用这份记录刷新列表。这个策略简单且不会出现重复。

做这个项目过程中我最深的几点体会

第一，流式聊天项目的调试难度远比普通接口高，因为数据是持续不断的，任何一环的状态码、缓冲策略、解码方式出错，表现都很隐蔽。我每次排查都坚持从最上游开始验证：先 curl OpenWebUI，再写最小测试用例调 FastAPI，最后才看前端页面。这个顺序帮我省了大量时间。

第二，OpenWebUI 版本升级带来的接口兼容性问题，是我在这类项目里遇到最多的事故来源。建议生产环境锁定镜像版本，不要追 latest，升级之前先在测试环境跑一遍 curl 回归脚本。

第三，这套架构的扩展空间非常大。如果你后续需要做企业内部知识库问答，可以在 FastAPI 层加入文档检索模块，把检索结果拼接进上下文；如果需要多模型路由，可以在 FastAPI 层根据业务规则把请求分发到 OpenWebUI 不同的模型配置上；甚至可以做消息审计和情感分析，因为这些数据都在自己的数据库里，完全可控。最后分享一个实用小技巧：给 SSE 请求统一加上X-Accel-Buffering: no和Cache-Control: no-cache两个响应头，能规避很多反代环境下的流式响应问题。