Files

HaHafeng 5c5fec52c1 fix(aia,ssa,asl,infra): harden SSE transport and stabilize attachment context

Deliver SSE protocol hardening for SAE/HTTP2 paths, add graceful shutdown health behavior, and improve SSA retry UX for transient stream failures. For AIA, persist attachment extraction results in database with cache read-through fallback, plus production cache safety guard to prevent memory-cache drift in multi-instance deployments; also restore ASL SR page scrolling behavior.

Made-with: Cursor

2026-03-09 18:45:12 +08:00

6.2 KiB

Raw Permalink Blame History

SAE 生产环境 SSE 协议故障诊断与终极防御指南

故障现象： SAE 部署后，前端偶发 net::ERR_HTTP2_PROTOCOL_ERROR，后端日志显示请求已接收甚至已完成。第二次请求恢复正常。

故障定性： 云原生环境下的经典长连接断裂与 HTTP/2 协议翻译冲突。

核心认知： 在 Serverless 容器中，不要试图“防止连接断开”（做不到），必须通过“前端智能重连”和“后端优雅停机”来容错。

一、为什么你们的修复“治标不治本”？

你们已经做了非常出色的网络层修复：

去除了 Connection: keep-alive：防止 HTTP/2 严格模式下因为禁用的连接专有头部（Connection-Specific Headers）导致强制 RST_STREAM。
条件化了 Connection: Upgrade：防止 Nginx 把普通的 SSE 长轮询当成 WebSocket 升级，导致协议错乱。

为什么还是会偶发失败？

因为当 SAE 进行滚动更新（Rolling Update）时，旧的 Node.js Pod 会收到 SIGTERM 信号准备退出。此时，阿里云 CLB（负载均衡）的连接池中可能还有几十条保持活跃的 HTTP/2 物理连接。

如果浏览器复用了这条即将被回收的 HTTP/2 通道来发起新的 SSE 请求，或者旧 Pod 直接被底层硬杀（Kill -9），Nginx 往后端转发时会遭遇 Connection Refused 或 Broken Pipe。Nginx 无法优雅地把这个错误包装成 HTTP 状态码，只能粗暴地向客户端发送一个 HTTP/2 GOAWAY 帧，浏览器收到后就会报出 ERR_HTTP2_PROTOCOL_ERROR。

二、终极防御三板斧（Cloud-Native Resilience）

要 100% 消除用户的报错感知，必须在前端、Nginx 和后端落地以下三个机制：

🪓 第一斧：前端 SSE 智能断线重连 (Intelligent Retry)

这是解决问题的绝对核心！对于大模型对话（Chat）和分析执行（Execute），前端绝不能因为一次底层网络闪断就把红色错误拍在用户脸上。

改造方案： 在 useSSAChat.ts 或底层 SSE 请求库中（推荐使用微软的 @microsoft/fetch-event-source 库，它自带强大的重试机制），拦截网络层错误并静默重试。

import { fetchEventSource } from '@microsoft/fetch-event-source';

async function startSseStream(url: string, payload: any) {
let retryCount = 0;
const MAX_RETRIES = 3;

await fetchEventSource(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),

// 关键：拦截底层 HTTP/2 协议错误并决定是否重试  
async onopen(response) {  
  if (response.ok) retryCount \= 0; // 连接成功，重置计数器  
},  
  
onerror(err) {  
  retryCount++;  
  if (retryCount \> MAX\_RETRIES) {  
    throw err; // 超过重试次数，才真正向用户报错  
  }  
  // 记录日志，但不抛出异常  
  console.warn(\`\[SSE\] 网络闪断，正在进行第 ${retryCount} 次重连...\`, err);  
  // 返回一个延迟时间 (指数退避) 告诉底层库多久后重连  
  return Math.min(1000 \* (2 \*\* retryCount), 5000);   
},  
  
onmessage(msg) {  
  // 处理正常的 SSE 事件  
}

});
}

效果：即便 SAE 正在滚动部署，CLB 断开了连接，浏览器会在 1 秒内静默发起第二次请求，此时 CLB 已经指向了新 Pod，用户毫无感知，只会觉得“这次思考慢了一秒”。

🪓 第二斧：Nginx 层彻底关闭缓存 (Disable Buffering)

如果你们的 Ingress 或前置 Nginx 开启了代理缓冲（Proxy Buffering），它是 SSE 流式输出的绝对天敌，也是加剧协议错误的元凶。

改造方案： 必须为 /api/v1/ssa/*/chat 等 SSE 接口单独关闭 Nginx 缓冲。

location ~ ^/api/v1/ssa/.*(?:chat|stream)$ {
proxy_pass http://backend_upstream;

\# 以下三行是 SSE 救命神药  
proxy\_http\_version 1.1;  
proxy\_buffering off;      \# 严禁 Nginx 缓存 Chunk 数据  
proxy\_cache off;          \# 严禁缓存  
chunked\_transfer\_encoding on;  
  
\# 彻底清理可能导致 H2 冲突的 Headers  
proxy\_set\_header Connection '';  
  
\# 延长超时时间（应对大模型深度思考）  
proxy\_read\_timeout 120s;

}

🪓 第三斧：Node.js 后端优雅停机 (Graceful Shutdown)

为什么部署期间连接断裂那么惨烈？因为 Node.js 默认在收到 SAE 的部署停止信号（SIGTERM）时会立刻自杀。

改造方案： 在 main.ts 或 app.module.ts 中实现 Graceful Shutdown。当收到退出信号时，拒绝新的请求，但给已经建立的 SSE 长连接留出 30 秒的执行时间。

// Node.js Express/NestJS 优雅停机示例
let isShuttingDown = false;

// 1. 探针接口：一旦开始停机，立刻告诉 SAE/CLB "我不健康了"，不要再给我派发新请求
app.get('/health', (req, res) => {
if (isShuttingDown) {
return res.status(503).send('Shutting down');
}
res.status(200).send('OK');
});

// 2. 捕获系统终止信号
process.on('SIGTERM', () => {
console.log('[System] 收到 SIGTERM 信号，准备优雅停机...');
isShuttingDown = true;

// 停止接收新连接
server.close(() => {
console.log('[System] 所有现有连接已处理完毕，安全退出。');
process.exit(0);
});

// 强制超时机制：如果过了 30 秒还有 SSE 流没跑完（比如陷入死循环），强制退出
setTimeout(() => {
console.error('[System] 优雅停机超时 (30s)，强制退出。');
process.exit(1);
}, 30000);
});

三、架构师总结

你们在本地开发环境（HTTP/1.1 直连，无负载均衡，无 Pod 销毁）永远无法复现这个问题。

这不单纯是网络配置问题，这是 Serverless 架构下的“状态保持”冲突。 请优先让前端团队加上 @microsoft/fetch-event-source 的静默重连机制，这不仅能解决 SAE 部署期间的报错，还能解决未来医院网络环境不稳定、用户切网（WIFI 换 5G）导致的所有诡异长连接断开问题。这是投入产出比（ROI）最高的一记绝杀。

6.2 KiB Raw Permalink Blame History Unescape Escape