2026-07-03 本文总阅读量: 次 | 文章总字数: 2,249 字

用网页快照、静态 HTML 和 PDF 转换接口构建网页归档 Agent

摘要：网页内容会变化，重要页面需要保留可复核的归档记录。本文演示如何把站点基础检查、网页快照、URL 转 HTML、HTML 转 PDF、HTML 转 Word、DNS、SSL 和 WHOIS 接口组合起来，构建一个网页证据归档 Agent。

关键词：网页归档 Agent、网页快照 API、URL 转 HTML API、HTML 转 PDF API、DNS 查询 API、SSL 证书 API

问题背景

运营活动页、新闻报道、竞品页面、采购公告和合规材料都可能在发布后发生变化。只保存一个 URL 并不够，因为页面可能下线、改版、跳转或被 robots 策略影响。归档系统需要同时保存页面内容、截图、基础站点信息和生成时间。

Agent 可以把归档流程标准化：先检查站点基础信息，再保存网页快照和静态 HTML，最后按需要导出 PDF 或 Word。这样后续无论是内容复盘、合规留档还是竞品研究，都能回到当时的页面状态。

Agent 工作流

Agent 工作流示意图

接口编排

步骤	接口	请求方式	用途
标题图标	`获取任意站点标题与图标`	GET	保存页面标题、站点图标等基础信息
DNS 查询	`域名 DNS 信息查询`	GET	保存域名解析信息
SSL 证书	`域名 SSL 证书信息解析`	GET	保存证书主体、有效期等信息
WHOIS	`域名 Whois 查询`	GET	保存域名注册信息
网页快照	`网站截图与 HTML 快照`	POST	同时保存截图和 HTML 快照
静态 HTML	`URL 转静态 HTML 文件`	POST	生成可归档的静态 HTML
PDF 导出	`HTML/URL 转 PDF`	POST	将页面导出成 PDF
Word 导出	`HTML 转 Word`	POST	将页面内容导出成 Word

调用示例

保存网页快照：

curl -X POST "https://api.gugudata.com/websitetools/url2snapshot?appkey=YOUR_APPKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/campaign/page",
    "responseFormat": "base64",
    "fullPage": true,
    "width": 1920,
    "height": 1080,
    "deviceScaleFactor": 1,
    "isMobile": false
  }'

生成静态 HTML：

curl -X POST "https://api.gugudata.com/websitetools/url2html?appkey=YOUR_APPKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/campaign/page"
  }'

查询域名 SSL 信息：

curl -G "https://api.gugudata.com/v2/websitetools/sslcertinfo" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "domain=example.com"

Agent 可以用归档任务记录每次执行：

def build_archive_record(url: str, snapshot_id: str, status: str) -> dict:
    """Build a webpage archive record."""
    return {
        "source_url": url,
        "snapshot_id": snapshot_id,
        "status": status,
        "artifacts": ["snapshot", "html", "pdf"],
    }

归档记录怎么设计

网页归档建议保存以下字段：

字段	说明
source_url	原始 URL
normalized_url	规范化后的 URL
captured_at	归档时间
page_title	页面标题
domain_info	DNS、SSL、WHOIS 摘要
snapshot_file	截图或快照文件
html_file	静态 HTML 文件
pdf_file	PDF 文件
status	成功、部分成功、失败、待重试

对于需要长期保存的页面，应保留多个版本，而不是覆盖旧文件。版本差异可以用于活动复盘、竞品监控或内容审计。

标准架构拆解

网页归档系统可以拆成以下模块：

模块	责任
任务创建	接收 URL、归档原因、输出格式和优先级
站点检查	查询标题图标、DNS、SSL 和 WHOIS
内容捕获	生成截图、HTML 快照和静态 HTML
文档导出	按需要导出 PDF 或 Word
归档索引	保存文件位置、时间、状态和来源

Agent 应关注归档完整性。比如截图成功但 HTML 失败时，任务不应该简单标记为成功，而应标记为“部分成功”，并允许补跑失败步骤。

数据流与接口边界

推荐流程如下：

用户提交需要归档的 URL 和用途。
Agent 规范化 URL，并提取域名。
查询站点标题、图标、DNS、SSL 和 WHOIS。
调用网页快照接口保存页面状态。
调用 URL 转静态 HTML 接口保存可读内容。
按业务需要导出 PDF 或 Word。
生成归档记录，并保存所有文件引用。

接口边界上，站点基础检查提供上下文，快照和 HTML 保存页面内容，PDF 和 Word 提供可交付格式。不要只保留最终 PDF，否则后续很难重新处理原始页面。

错误处理

如果页面需要登录、被防爬或加载超时，Agent 应记录失败原因，而不是生成空白归档。若 DNS 或 SSL 查询失败，但页面快照成功，可以标记为部分成功。对于动态页面，建议同时保存全页截图和 HTML 快照。

归档任务应支持重试，但重试生成的是新版本，不应覆盖第一次归档时间。

可靠性与观测

建议记录以下指标：

指标	用途
archive_success_rate	完整归档成功率
partial_archive_count	部分成功数量
snapshot_latency_ms	快照生成耗时
html_export_success_rate	静态 HTML 生成成功率
document_export_success_rate	PDF 或 Word 导出成功率

当部分成功数量升高时，要区分是页面访问问题、转换问题还是文档导出问题。归档系统需要按步骤定位，而不是只返回一个失败状态。

落地清单

每次归档都生成独立版本。
同时保存截图、HTML 和文档产物。
归档记录中保留站点基础信息。
部分成功要可见，不能被最终文件掩盖。
对需要登录的页面建立人工归档流程。

可扩展方向

这个 Agent 可以继续接入网页性能与 SEO 评分接口，把归档记录和性能快照一起保存；也可以接入网页 URL 链接提取接口，自动归档同一专题下的重要链接。