全栈联调:Nuxt 代理、SSE 与访问控制
结论
浏览器请求同源 /api/assistant/chat,Nitro 再转发到 FastAPI /api/chat;前端要把响应当成一个有事件类型和明确终态的协议,而不是普通 JSON 请求。当前仓库已经有 /chat 页面、全站浮窗和同源代理,但助手默认关闭,生产代理 fail-closed;在鉴权、配额和限流完成前,不能公开暴露。
问题与设计
SSE 响应是长连接文本流,fetch() 不会一次返回完整 JSON。前端必须逐块读取,按空行拆事件,再按 event 分发。网络块边界不保证与事件边界一致,所以不能假设一次 reader.read() 就是一条完整事件。
生成开始后 HTTP 状态通常已经是 200,上游失败只能通过流里的 error 事件通知;前端必须区分“HTTP 建连失败”和“流中途失败”。
同源代理是另一层边界:它解决浏览器跨域、隐藏后端地址和流式转发,但不提供身份、配额或限流。生产模式下代理直接拒绝请求,不能靠前端 feature flag 打开。
关键代码
代理的实现集中在 frontend/server/api/assistant/chat.post.ts:
if (!options.enabled || options.production) {
throw createError({ statusCode: 404, statusMessage: 'Not Found' })
}
const endpoint = new URL('/api/chat', backendBaseUrl)
const upstream = await fetch(endpoint, {
method: 'POST',
headers: { 'content-type': contentType, accept: 'text/event-stream' },
body: new Uint8Array(body),
signal: upstreamController.signal,
})
return new ReadableStream<Uint8Array>({
async pull(controller) {
const { done, value } = await reader.read()
if (done) return controller.close()
controller.enqueue(value)
},
cancel(reason) {
upstreamController.abort(reason)
},
})
createError(404) 是 fail-closed:生产环境即使误设 NUXT_ASSISTANT_ENABLED=true 也不会转发。NUXT_PUBLIC_ASSISTANT_ENABLED 只控制是否渲染浮窗入口,不是安全开关。
前端消费逻辑在 frontend/app/utils/chat-stream.ts 和 useChat.ts。事件契约:
事件契约:
| 事件 | data | 前端动作 |
|---|---|---|
sources |
{ sources: [{ n, title, url, slug, score }] } |
保存引用表,回答前即可展示 |
token |
{ text } |
按顺序追加当前回答 |
done |
{ finishReason: "stop" } |
结束 loading |
error |
{ code, message } |
标记失败,不伪装成完成 |
前端 parser 先缓冲,再按空行边界取完整 block:
buffer += decoder.decode(value, { stream: true })
let boundary = buffer.search(/\r?\n\r?\n/)
while (boundary !== -1) {
const block = buffer.slice(0, boundary)
const delimiter = buffer.slice(boundary).match(/^\r?\n\r?\n/)?.[0] ?? '\n\n'
buffer = buffer.slice(boundary + delimiter.length)
const event = decodeEvent(block)
if (event) yield event
boundary = buffer.search(/\r?\n\r?\n/)
}
decodeEvent() 校验事件名和 payload;useChat() 把 sources 写到消息来源,把 token 追加到回答,用 done / error 收束状态。取消通过 AbortController,服务端检测断开后停止消费 graph。
浏览器请求同源 /api/assistant/chat,由 Nitro 代理转发到私有 FastAPI;模型 Key 只在后端。代理不是访问控制,生产模式下始终拒绝请求。
验证
后端 TestClient 拿到的真实 SSE body:
sources → token → token → token → done
上游失败时:
sources → token → error
不是 done。curl -N 可以检查服务器是否逐事件输出,而不是被代理缓冲:
curl -N -X POST http://127.0.0.1:8000/api/chat \
-H 'content-type: application/json' \
-d '{"query":"多阶段构建解决了什么问题?","history":[],"top_k":5}'
边界
把“已实现”和“上线必需”分开看:
| 能力 | 当前状态 | 上线前需要 |
|---|---|---|
| 身份认证 | 没有 | 登录态或服务间身份 |
| 配额 | 没有 | 用户 / 日预算 |
| 限流 | 没有 | 每 IP 或每用户速率限制 |
| 会话 | 只存在客户端请求里 | 持久化与恢复策略 |
| Schema 演进 | CREATE TABLE IF NOT EXISTS |
migration 工具与回滚 |
| 可观测性 | 日志与 /health |
指标、追踪、成本告警 |
| 部署 | 本地 dev compose | 私有网络、反向代理、fail-closed |
另外几个协议事实:
- HTTP 200 后不能再用状态码表示模型失败,必须消费
error事件。 - SSE 连通只说明传输成功,不说明检索召回、引用正确性或回答质量达标。
X-Accel-Buffering: no不是所有代理的通用开关;部署时仍要确认 Caddy/Nginx 不缓冲。
这个系列到此结束。后续的检索阈值、单篇上下文上限和 embedding 文本补全,记录在 如何优化。