跳到主要内容
Ed. notes

全栈联调:Nuxt 代理、SSE 与访问控制

长文 · 2026-11-11 · 合集第 11 / 11 篇

  • SSE
  • Nuxt
  • API设计
  • 安全边界
第 11 / 11 篇 · 查看全部章节 → 当前:全栈联调: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 文本补全,记录在 如何优化。