1. Sitemap 引擎
Sitemap 引擎负责资源发现。它抓取、解压、解析并规范化标准 XML sitemap、sitemap 索引层级、.xml.gz 存档和纯文本 URL 列表中的 URL 条目。
技术规格与协议限制
Sitemap 引擎执行 Google Sitemap 协议限制和防御性保护：
| 参数 | 常量 | 值 | 描述 |
|---|---|---|---|
| 最大文档大小 | MAX_UNCOMPRESSED_BYTES |
50 MiB (52,428,800 bytes) | 单个 sitemap 文件允许的最大解压负载。 |
| 最大下载大小 | MAX_DOWNLOAD_BYTES |
52 MiB (54,525,952 bytes) | 最大 HTTP 流式下载大小。 |
| 每文件最大 URL 数 | MAX_URLS_PER_SITEMAP |
50,000 | 每个文档解析的最大 <url> 或 <sitemap> 记录数。 |
| 最大展开上限 | MAX_EXPAND_URLS |
1,000,000 | 递归展开索引时的全局 URL 累积上限。 |
| 最大 Loc 长度 | MAX_URL_LEN |
2,048 bytes | RFC 7230 loc 长度上限，过长 URL 会被丢弃。 |
| 默认最大深度 | max_depth |
3 levels | 嵌套 <sitemapindex> 文件的最大递归深度。 |
核心能力
1. 透明 Gzip 解压炸弹防护
Sitemap 经常使用 .xml.gz 压缩。恶意或损坏的 1 KiB gzip 文件可能在内存中膨胀为数十 GB。IndexFlow 通过受限的 flate2 reader（Take limiter）流式解压，超过 50 MiB 时立即以 SitemapError::DecompressionBomb 中止。
2. 不依赖前缀的 XML 解析
引擎严格按本地字节名称（Tag::from_local）评估标签，因此无论 XML 命名空间别名如何，都能一致提取内容。
3. 容错式 Ampersand 清理
IndexFlow 使用单遍清理器（sanitize_bare_ampersands）重写未转义的 ampersand，同时保留合法 XML 实体和 <![CDATA[...]]> 块。
4. 循环引用与环检测
展开 <sitemapindex> 层级时，IndexFlow 为每个 URL 计算规范身份 key；若当前分支已经访问过该 key，则记录并跳过，不使整个抓取失败。
Google 扩展提取
IndexFlow 将丰富的 Google sitemap 扩展元数据提取为结构化 Rust 模型：
1. 图片（<image:image>）
2. 视频（<video:video>）
3. 新闻（<news:news>）
4. Alternates 与 Hreflang（<xhtml:link>）
URL 区域与路径前缀提取
导入期间，SitemapService 解析 URL 路径和 hreflang 元数据来分类内容：
- 区域提取：识别标准 ISO 639-1 语言前缀或使用声明的
xhtml:link标签。 - 路径前缀：分类根目录（如
/docs、/blog、/products），支持控制台中的本地化筛选。
执行 Sitemap 同步
通过 Web 控制台触发
进入 /sitemap 并点击 Sync Sitemap。
通过 REST API 触发
curl -X POST "https://www.indexflowing.com/docs/api/v1/pipeline/sitemap/start?site_id=1" \
-H "Cookie: if_token=<YOUR_JWT_TOKEN>"
停止正在运行的同步
curl -X POST "https://www.indexflowing.com/docs/api/v1/pipeline/sitemap/stop?site_id=1" \
-H "Cookie: if_token=<YOUR_JWT_TOKEN>"
数据库 Upsert 行为
发现的 URL 以每批 500 条的事务写入数据库。现有 URL 的 sitemap_lastmod、sitemap_synced_at 和 priority 会自动更新，同时保留历史审计日志。