跳到主要内容
Ed. notes

同源代理:Nitro 转发与 fail-closed

长文 · 2026-11-12 · 合集第 8 / 10 篇

  • Nuxt
  • Nitro
  • SSE
  • 安全边界
第 8 / 10 篇 · 查看全部章节 → 当前:同源代理:Nitro 转发与 fail-closed

结论

浏览器不应该直接访问 FastAPI。前端只请求同源的 /api/assistant/chat,由 Nitro 转发到私有后端;代理把上游 SSE 原样流回浏览器,并在客户端断开时中止上游请求。

生产模式下代理直接返回 404。这个 fail-closed 是当前最重要的安全边界:功能开关可以误开,代理不能。

问题与设计

直接让浏览器请求后端有三个问题:

  • 跨域需要 CORS 配置,开发和部署环境都要维护一份白名单。
  • 后端地址暴露在客户端,增加被扫描和直连的风险。
  • 以后要加身份、配额或审计时,浏览器已经绕过统一入口。

同源代理解决的是“入口收敛”,不是“访问控制”。它不等于登录,也不等于限流;它只是让浏览器只认识一个地址,让后端保持在私有网络里。

请求路径:

浏览器 POST /api/assistant/chat
  → Nitro server route
    → POST http://backend:8000/api/chat
      → SSE 响应
    ← ReadableStream 逐块转发
  ← text/event-stream

代理只做四件事:

  1. 检查功能开关和运行环境,决定是否继续。
  2. 校验 Content-Type 与请求体,避免把明显错误的请求发给后端。
  3. 用 fetch 建立上游连接,保留 AbortSignal。
  4. 把上游响应体包装成 ReadableStream,逐块 enqueue,不调用 response.text()。

业务校验仍然在后端。代理不复制 query 长度、history 条数等规则,避免两份校验逐渐漂移;它只拒绝“不是 JSON 请求”这种传输层错误。

关键代码

代理实现集中在 frontend/server/api/assistant/chat.post.ts。第一道门是 fail-closed:

if (!options.enabled || options.production) {
  throw createError({ statusCode: 404, statusMessage: 'Not Found' })
}

production 来自 process.env.NODE_ENV === 'production',不是前端开关。也就是说,即使误设了 NUXT_ASSISTANT_ENABLED=true,生产构建仍然不会转发。NUXT_PUBLIC_ASSISTANT_ENABLED 只决定是否显示入口,更不是权限。

接下来校验请求并建立上游连接:

const contentType = getRequestHeader(event, 'content-type') || ''
if (!contentType.toLowerCase().includes('application/json')) {
  throw createError({
    statusCode: 415,
    statusMessage: 'Content-Type must be application/json',
  })
}

const body = await readRawBody(event, false)
if (!body) {
  throw createError({
    statusCode: 400,
    statusMessage: 'Request body is required',
  })
}

const endpoint = new URL('/api/chat', options.backendUrl.trim())
const upstream = await fetch(endpoint, {
  method: 'POST',
  headers: { 'content-type': contentType, accept: 'text/event-stream' },
  body: new Uint8Array(body),
  signal: upstreamController.signal,
})

new Uint8Array(body) 复制一份稳定的字节视图,避免把 Node 的 Buffer 生命周期和后续请求处理绑在一起。上游响应必须是流:

setResponseHeader(event, 'Content-Type', 'text/event-stream; charset=utf-8')
setResponseHeader(event, 'Cache-Control', 'no-cache, no-transform')
setResponseHeader(event, 'X-Accel-Buffering', 'no')

return new ReadableStream<Uint8Array>({
  async pull(controller) {
    const { done, value } = await reader.read()
    if (done) {
      controller.close()
      return
    }
    controller.enqueue(value)
  },
  cancel(reason) {
    upstreamController.abort(reason)
  },
})

这里有几个容易写错的地方:

  • 不能 await upstream.text()。 那会等模型把整段回答生成完,SSE 就退化成普通 JSON 请求。
  • 不能忽略客户端断开。 浏览器关闭浮窗或点“停止”时,Nitro 要中止上游请求,否则模型继续消耗额度。
  • 不能把上游错误体原样透传。 代理只返回固定状态和通用文案,详细原因留在服务端日志。
  • X-Accel-Buffering: no 不是万能开关。 部署到 Caddy/Nginx 时仍要确认反向代理没有缓冲响应。

取消路径同时监听请求和响应:

request.once('aborted', abortUpstream)
response.once('close', abortWhenResponseCloses)

abortWhenResponseCloses 只在 response.writableFinished 为 false 时中止,避免正常结束后误触发。流清理时再移除监听、取消 reader、释放锁,防止长连接泄漏。

默认处理器从运行时配置读取服务端参数:

export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event)
  return createAssistantChatProxy({
    enabled: Boolean(config.assistantEnabled),
    backendUrl: String(config.assistantBackendUrl || ''),
    production: process.env.NODE_ENV === 'production',
  })(event)
})

assistantBackendUrl 是私有运行时配置,不会进入客户端 bundle;public.assistantEnabled 才会。这个区分要写进部署文档,否则很容易把后端地址或密钥误放到 public。

验证

代理测试不依赖真实后端,用注入的 fetchImpl 和临时 h3 服务验证四件事:

  • 功能关闭时返回 404,且注入的 fetch 没有被调用。
  • 正常请求返回 text/event-stream,响应体逐块可读,上游路径是 /api/chat。
  • 客户端 abort 后,上游 AbortSignal 变为 aborted。
  • 上游返回 503 时,客户端只拿到通用错误,不包含上游的响应正文。
cd frontend
npm run test -- tests/nuxt/assistant-proxy.spec.ts

端到端测试还会在生产模式下请求 /api/assistant/chat,断言状态是 404。这个断言比“按钮没显示”更重要,因为它验证的是服务端边界,不是 UI 开关。

边界

  • 代理没有身份认证、配额和限流。生产 fail-closed 只是“先不开放”,不是“已经安全”。
  • 代理只支持 Node 运行时;代码直接使用 event.node.req / event.node.res。迁移到 edge worker 时要重写取消和流适配。
  • 请求体在代理层被完整读入内存,没有单独的大小限制;后端有字段约束,但代理层仍应补请求体上限。
  • 没有心跳事件和自动重连。长连接经过反向代理时,要配置足够的读超时,或者在协议层增加 heartbeat。
  • backendUrl 来自受信环境变量,不接受用户输入;如果未来支持多后端路由,必须先做 allowlist,避免 SSRF。

下一篇补可访问性和测试:焦点、live region、键盘路径,以及怎样用假流验证这些行为。