同源代理: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
代理只做四件事:
- 检查功能开关和运行环境,决定是否继续。
- 校验
Content-Type与请求体,避免把明显错误的请求发给后端。 - 用
fetch建立上游连接,保留AbortSignal。 - 把上游响应体包装成
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、键盘路径,以及怎样用假流验证这些行为。