超大HTML文档流不能直接进网关，因其缺乏可寻址边界，导致无法流式切片、按需缓存或语义级策略拦截；网关需处理“可调度的HTML片段”，而非完整页面，应通过HTMLHeaderTextSplitter在入口做无状态切片，并安全净化、重写ID与锚点。
超大HTML文档流为什么不能直接进网关
网关不是渲染器，它不解析DOM、不执行JS、不关心语义——只做协议转换、路由分发和流量整形。把一个20MB的HTML文件（含内联CSS/JS/图片base64）直接扔给网关，等于让快递分拣站去读整本《辞海》再决定投递地址。常见现象：HTTP 413 Payload Too Large、connection reset by peer、网关CPU飙升但QPS不涨。
根本问题不在体积本身，而在结构：未拆分的HTML文档缺乏可寻址边界，无法做流式切片、按需缓存、增量校验或语义级策略拦截（比如只过滤含<script></script>的块）。网关层需要的是“可调度的HTML片段”，不是“可浏览器打开的完整页面”。
- 单个
<html>根节点下塞满<div>，没有<section>或<article>作为逻辑锚点 → 无法按语义提取摘要或生成TOC - 所有样式靠
style标签或class硬编码，无data-role或data-section-id→ 无法在网关层做动态样式降级（如移除动画类） - 内联
<script>未标记type="application/json"或data-exec="false"→ 网关无法安全剥离执行逻辑
用HTMLHeaderTextSplitter做网关前置切片
别等HTML到后端才处理。在网关入口处（Nginx/OpenResty或自研网关插件），用HTMLHeaderTextSplitter对原始HTML流做**无状态、零内存拷贝**切片。它不构建DOM树，只扫描文本流中的<h1>~<h3>标签位置，按标题层级物理截断。
关键参数必须显式配置，否则默认行为会漏切：
立即学习“前端免费学习笔记（深入）”；
-
headers_to_split_on=[("h1", "doc"), ("h2", "section"), ("h3", "subsection")]—— 缺一不可，否则<h2>以下内容全归入上一块 -
return_each_element=True—— 保证每个<p>、<ul>都携带其所属标题路径（如["用户指南", "安装步骤", "Linux"]），供后续路由策略使用 -
max_chunk_size=500000（500KB）—— 单块上限，防止单节内容过大导致下游服务OOM；超过则强制在<p>或<div>闭合处截断
切片后输出为JSON数组，每项含content（HTML字符串）、metadata（标题路径、层级、ID）、id（SHA256哈希）。网关可据此做：按metadata.level == "section"分流至缓存集群；对含metadata.title.includes("敏感")的块触发DLP规则；丢弃content.length < 100的空块。
网关层如何安全剥离不可信HTML结构
大型网站常混入第三方脚本、广告iframe、用户提交的富文本——这些在网关层必须隔离，不能放行到后端渲染服务。但简单用正则删<script>会破坏HTML结构，删错标签闭合就导致整个文档解析失败。
正确做法是基于切片后的content字段做白名单净化：
- 只保留语义标签：
<h1>~<h6>、<p>、<ul>、<ol>、<li>、<table>、<tr>、<td>、<th>、<img>（且src必须以/assets/或https://cdn.开头） - 强制移除所有
on*事件属性（onclick、onload等）和javascript:伪协议 - 对
<style>内容用CSSOM解析器校验，仅保留color、font-size、margin等安全属性，丢弃@import、url()、expression()
注意：此步骤必须在切片后执行。若在原始HTML上运行，一次正则替换可能跨多个标题块，导致metadata与content错位——这是生产环境最隐蔽的bug来源之一。
流式重组时DOM ID冲突与锚点失效怎么破
切片再拼接，最大的副作用是id重复和href="#section-3"跳转失效。网关不能依赖客户端JS修复，必须在流式输出前完成锚点重写。
方案是两级ID注入：
- 第一级：网关为每个切片生成唯一前缀（如
chunk_7f3a9b21_），所有原id="section-3"重写为id="chunk_7f3a9b21_section-3" - 第二级：对所有
a[href^="#"]，将href="#section-3"重写为href="#chunk_7f3a9b21_section-3"；若链接指向其他切片，则改用data-external-anchor="section-3"并由前端加载器接管
更关键的是：不要在网关层尝试自动合并<head>或<style>。每个切片应自带最小化<style>（仅作用于本块），避免CSS选择器跨块污染。真正共享的全局样式，应由CDN单独提供，通过<link rel="stylesheet" href="/global.css">引入——网关只负责透传，不参与合成。
