本地 AI API 适配器代码复盘：真实流式、重试与安全边界

这篇文章来自一个本地 Node.js API 适配器原型的代码审阅和定向安全回归测试。只保留可公开的工程经验，不描述上游平台、地址、账号、浏览器资料或内部标识；没有对真实上游做集成测试，也不代表身份认证或可用性背书。

先说结论：接口兼容不等于传输兼容

兼容某种聊天 API，不只是让请求字段和 JSON 响应长得相似。客户端通常还依赖流式首包、增量事件、取消行为、错误终态和 usage 统计。若服务端先把完整 SSE 响应读进字符串、解析完毕后再一次性写给客户端，即使最终响应使用了 text/event-stream，用户仍要等生成结束才看到内容。这是“事件格式像流，传输却被缓冲”的假流式。

审阅时还要把三层分开验证：

协议层：字段、状态码、事件类型、结束标记是否符合明确声明的兼容范围。
传输层：首事件是否及时到达，后续事件是否增量送达，慢客户端是否触发背压。
生命周期层：客户端断开后，上游请求、浏览器会话、定时器和锁是否都能释放。

本地访问限制是边界，不是身份认证

将管理型或个人使用的 API 绑定到 loopback，并拒绝不匹配的 Host/Origin，可以减少意外暴露和部分跨站请求风险。它不能证明调用者是谁：同一台机器上的其他进程、命令行工具或恶意本地软件仍可能访问该端口。若服务需要共享给其他设备，应补上明确的身份认证、最小权限、TLS、限流和网络访问策略，而不是只把监听地址改成 0.0.0.0。

同理，CORS 是浏览器的读取策略，不是服务端访问控制。每个 API 路由仍需检查认证、请求大小、速率和可执行能力；使用浏览器自动化时，调试端口应被视为高权限控制面，不能因应用 API 只监听本机就忽略它。

本地原型的后续复核还把 TCP 对端地址纳入了检查：即使请求伪造 Host: localhost 且不发送 Origin，非 loopback 或缺失的对端地址也会被拒绝。定向测试覆盖 IPv4、IPv6、IPv4-mapped IPv6、非本机地址和缺失地址，8 项 Node.js 测试通过。它只是网络边界的纵深防御；同一台机器上的其他进程仍可访问，不能替代认证。服务当前默认绑定本机回环接口，若将来改为对外监听，仍应增加身份认证、TLS、限流和网络访问策略，并重新审查代理拓扑。

让字节真的逐步到达客户端

若上游已提供 SSE 且代理不需要改写事件，优先以字节流直通，避免不必要的全量缓存与二次解析。Node 的 pipeline 能把可读流接到 HTTP 响应，并协调背压与错误清理；以下是结构示意，路由仍需在发出响应头前完成鉴权、输入校验和上游状态检查：

import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

async function relayEventStream(req, res, upstream, controller) {
  req.once('aborted', () => controller.abort());
  res.once('close', () => {
    if (!res.writableEnded) controller.abort();
  });

  res.writeHead(upstream.status, {
    'content-type': 'text/event-stream; charset=utf-8',
    'cache-control': 'no-cache, no-transform',
    'x-accel-buffering': 'no',
  });

  if (!upstream.body) {
    res.end();
    return;
  }

  try {
    await pipeline(Readable.fromWeb(upstream.body), res, {
      signal: controller.signal,
    });
  } catch (error) {
    if (!controller.signal.aborted) throw error;
  }
}

这段代码只展示传输骨架。controller 应在发起上游 fetch 前创建，并传入 signal；只转发经过审核的响应头，不能盲目复制 hop-by-hop、长度或压缩相关头。上游错误应在下游提交响应头之前映射成稳定、有限的公开错误，不能把上游原始正文直接吐给用户。

如果要转换事件格式而不是透传，解析器必须跨网络 chunk 保留未完成的数据，正确处理 UTF-8 多字节字符被拆开、CRLF、多个 data: 行、空行分帧和供应商结束标记。SSE 事件以 UTF-8 文本传输，事件块以空行分隔；按“每个 chunk 就是一条消息”来解析会在真实网络边界上出错。

取消、背压与重试必须一起设计

客户端关闭页面或停止生成后，应中止上游请求并释放订阅、浏览器页、锁和计时器。若共享任务还有其他订阅者，取消策略需按任务归属或引用计数决定，不能一个读者离开就杀掉其他人的工作。

Node 的可写响应在 write() 返回 false 时表示缓冲区需要等待；继续高速写入会把慢客户端变成不断增长的内存队列。使用 pipeline 或正确等待 drain，并对连接数、单请求时长、输入/输出字节数及并发任务设置上限。

重试也要有清晰的上限语义：把 maxAttempts 定义为包含首次请求在内的总请求次数，用测试断言最终调用次数；不要在循环耗尽后又另发一次请求。只有在请求尚未被上游接受、错误可重试且重复执行不会造成副作用时才自动重试。上游可能已经生成内容但响应丢失时，重发可能重复计费或创建第二个会话；优先使用上游支持的幂等键，无法判断执行状态时返回可诊断的失败，而不是静默再跑一遍。

一旦下游已经收到响应头或部分内容，就无法再把这条 HTTP 响应改成新的 JSON 状态码。此时应按公开协议发送一个安全的错误终态，或者结束连接并允许客户端查询任务状态，不要悄悄切换到第二次生成。

日志留下线索，不留下对话

模型提示词、完整生成内容、工具参数、Cookie、访问令牌和浏览器会话都可能包含个人或业务敏感信息。日志宜采用字段白名单，记录 request ID、路由模板、HTTP 状态、耗时、首事件延迟、事件数、重试次数、结束原因和有限错误码；不要通过截取正文前几十个字符来“方便排障”。

错误详情也要分层：受控日志可以保留经过清洗的异常类别和内部关联 ID，客户端只收到稳定错误码与可理解的重试建议。对日志字段做长度限制和 CR/LF 清洗，防止内容注入伪造日志行；为日志设置访问控制和保留期限。

兼容声明要诚实

解析出一个形似 tool_call 的 JSON 对象，不代表服务端真的执行了工具。若要执行，必须做工具名白名单、参数 schema 校验、授权检查、超时和审计。
如果没有真实计算 token 数，不要把固定的零值包装成准确 usage；可以省略、返回 null，或明确说明统计不可用。
明确支持哪些角色、内容块、流事件和结束原因；未知字段要有稳定策略，不能把用户内容拼进指令后就默认认为保持了原协议语义。
记录兼容层自己的版本与能力清单，客户端升级时用契约测试比较，而不是仅凭一条成功请求认定兼容。

当前代码样本的边界核对

以下是截至 2026-10-20 对本机个人原型的静态源码核对：没有登录上游、请求真实模型、读取 .env，也不在文章中保留上游地址、内部接口、账号标识、Cookie 名或专有模型清单。它描述的是这个样本当前的实现，不是推荐的生产方案。

浏览器会话桥接：Node 服务通过 Puppeteer 使用本机浏览器页面上下文发出带会话的请求。这不是官方模型 SDK，也不是独立的服务端 API 凭据；浏览器用户资料和调试端口都应按高权限凭据管理。服务仅允许 loopback 监听并校验 TCP 对端、Host 和 Origin，但这不等于认证，也挡不住同机其他进程。
浏览器进程启动参数（2026-10-20 修复）：旧实现把可配置的浏览器可执行路径与用户资料目录插入单条命令字符串，再通过 shell 启动。路径中的引号或 shell 元字符可能改变命令解释；即使它们来自本机配置，也没有理由增加 shell 解析层。现在直接把可执行路径和参数数组交给 spawn，资料目录作为单一参数传递，并只记录受限的启动错误类别。隔离测试注入假进程验证特殊字符不会被拆成命令；测试没有启动真实浏览器。这是缩小本机命令解释面，不代表 loopback 调试端口变成了安全或低权限接口。
stream: true 仍不是实时流：浏览器侧先完整读取响应文本，再交给 SSE 解析器聚合为一段完整回复；兼容接口等上游结束后才开始写事件，正文只作为一个完整内容增量发出。大回复会增加首字延迟和内存占用，停止生成也无法及时中止已经完成或仍在等待的上游请求。
工具调用只是格式转换：工具定义被转换成提示文本，回复中符合约定格式的 JSON 块会被解析并包装成 tool_calls。这个适配层本身不执行工具，也没有完成工具名白名单、参数 schema 校验或授权；调用方必须自行验证，不能因为响应字段兼容就把它当成安全的工具运行时。
日志正文泄漏（审阅基线，已于 2026-10-18 修复）：旧版调试日志会记录上游 SSE 正文的前 200 个字符；解析异常时还可能记录原始片段、错误消息、完整请求地址和会话 ID。现在请求/解析路径及进程级异常处理只记录长度、错误类别/代码、状态和尝试次数，不记录正文、错误消息、URL 或会话 ID。新增回归将敏感标记放入流响应、格式错误事件、上游错误、请求地址和会话 ID，确认日志中不出现标记；另检查本机 README 不含认证请求头或内部标识。日志仍应设置访问控制与保留期限，并持续审查新增日志调用。
日志文件权限（2026-10-20 修复）：本机旧日志目录和文件此前允许同机其他账号读取。已在不读取日志内容的前提下，将现有目录/文件限制为所有者访问；写入代码也会在创建与追加时持续确保目录为 0700、日志为 0600，避免新日期文件回到宽松默认权限。临时目录回归会把既有宽松权限模拟出来，并验证写入后权限被收紧、历史字节原样保留。权限收紧不会替代日志清理周期、磁盘配额或访问审计。
重试预算为零会多发请求（审阅基线，已于 2026-10-18 修复）：首次复核时，唯一调用点省略预算参数并使用默认值 3；正常路径里的每次循环尝试都会返回或继续，所以循环后的备用请求不可达。但函数参数允许传入 0：循环一次都不执行，尾部备用逻辑却会额外发送一次上游请求。现在入口拒绝非正整数预算，循环外的备用请求也已替换为防御性错误；隔离回归验证非法预算零请求、三次预算最多三次请求。修复只在本机完成，未连接上游或部署。
空响应仍会触发请求重放（待修复/验证）：当前源码把“没有解析错误标记、但正文为空”的结果当作可重试，并会再次 POST 聊天请求。代码没有证明上游尚未接受第一次请求，也没有看到幂等键或可查询的执行状态；如果空正文来自响应丢失、解析差异或上游已完成但未返回正文，重试可能重复执行并带来重复资源消耗。应先区分明确可重试的拒绝/失败状态；无法证明请求未被接受时，不要自动重放非幂等 POST，或使用上游提供的幂等键与任务状态查询。此项来自本地静态源码核对，尚未做上游验证。
进程级致命异常处理只记录日志（待修复）：当前 uncaughtException 处理器仅输出一条省略详情的日志后返回，没有进入受控退出流程；unhandledRejection 处理器也只记录日志。为避免服务在不可保证状态下继续接流量，应执行最小同步清理后以非零状态退出，并由 PM2 等外部进程管理器重启；不要把全局异常监听器当作恢复机制。Node.js 官方文档明确指出安装该监听器会覆盖默认退出行为，且不应在未捕获异常后恢复正常运行。这里只审阅了本地处理器，没有验证其实际部署方式或监督进程配置。

现有 npm test 共运行 17 项：8 项网络边界测试、6 项隔离重试/日志/README 检查，以及 2 项浏览器启动参数和 1 项日志权限回归。动态测试使用假依赖与临时目录，不启动真实浏览器或请求上游。它们不覆盖上游登录、模型协议、真实增量流、工具执行或端到端取消行为。此次没有连接上游做集成测试；“测试通过”不能被解读为整个适配器安全或可用。

回归测试清单

使用可控的假上游分两次延迟发送事件，断言客户端在上游结束前已经收到首事件，并观察首事件延迟而非只检查最终正文。
客户端收到部分事件后主动断开，断言上游 AbortSignal 已触发，且连接、锁和任务计数归零。
模拟慢客户端与大响应，确认背压生效、队列有界，内存不会随流长度持续增长。
对 401、429、超时、空流、畸形事件和上游断连分别断言公开状态、事件终态与精确上游调用次数。
上游在接受请求后断连时，验证不会无幂等保障地重复创建任务。
用日志捕获器检查提示词、响应正文、令牌和 Cookie 不会出现在日志中。
从非 loopback Host/Origin、不同本机端口和无认证请求测试访问策略；确认 CORS 规则没有被当成授权规则。