ukwa/heritrix-worker

UKWA Heritrix

镜像概述和主要用途

本镜像基于https://github.com/internetarchive/heritrix3%E6%9E%84%E5%BB%BA%EF%BC%8C%E6%B7%BB%E5%8A%A0%E4%BA%86UK%E7%BD%91%E7%BB%9C%E6%A1%A3%E6%A1%88%E9%A6%86(UKWA)%E7%89%B9%E5%AE%9A%E7%9A%84%E4%BB%A3%E7%A0%81%E5%92%8C%E9%85%8D%E7%BD%AE%EF%BC%8C%E7%94%A8%E4%BA%8E%E5%88%9B%E5%BB%BADocker%E9%95%9C%E5%83%8F%E4%BB%A5%E8%BF%90%E8%A1%8C%E7%BD%91%E7%BB%9C%E7%88%AC%E8%99%AB%E4%BB%BB%E5%8A%A1%E3%80%82%E8%AF%A5%E9%95%9C%E5%83%8F%E6%94%AF%E6%8C%81%E6%9C%AC%E5%9C%B0%E5%BC%80%E5%8F%91%E3%80%81%E9%9B%86%E6%88%90%E6%B5%8B%E8%AF%95%E5%92%8C%E7%94%9F%E4%BA%A7%E7%8E%AF%E5%A2%83%E9%83%A8%E7%BD%B2%EF%BC%8C%E6%8F%90%E4%BE%9B%E5%AE%8C%E6%95%B4%E7%9A%84%E7%88%AC%E8%99%AB%E7%94%9F%E6%80%81%E7%B3%BB%E7%BB%9F%EF%BC%8C%E5%8C%85%E6%8B%AC%E7%97%85%E6%AF%92%E6%89%AB%E6%8F%8F%E3%80%81%E6%B5%8F%E8%A7%88%E5%99%A8%E6%B8%B2%E6%9F%93%E3%80%81URL%E5%8E%BB%E9%87%8D%E5%92%8C%E7%BB%93%E6%9E%9C%E5%AD%98%E5%82%A8%E7%AD%89%E5%8A%9F%E8%83%BD%E3%80%82

核心功能和特性

• 多组件集成：包含ClamD病毒扫描、WebRender API、Warcprox浏览器爬虫集成、OutbackCDX URL去重服务、Kafka消息队列等
• 测试支持：提供本地测试网站和Wayback服务，便于验证爬虫结果
• 可配置性：通过环境变量和配置文件调整爬虫行为，支持代理设置
• 监控能力：集成Prometheus指标、JMX监控和Kafka UI，便于系统监控
• 自动化测试：使用Robot Framework执行集成测试，确保爬虫功能稳定性

使用场景和适用范围

• 大规模网络内容归档和爬取
• 网络爬虫开发与测试
• 网络资源定期抓取与去重
• 网络内容历史版本记录与回放

使用方法和配置说明

本地开发

修改Java代码后，可通过Maven编译并运行单元测试：

bash
$ mvn clean install

由于爬虫是多组件系统，建议同时运行集成测试以验证功能完整性。

持续集成测试

主仓库ukwa-heritrix的所有标签、推送和拉取请求都会触发集成测试，通过后推送更新的Docker镜像。工作流配置见此处。建议先在本地运行集成测试。

本地集成测试

使用提供的Docker Compose文件进行本地测试，该文件启动多个服务（含测试专用服务）：

核心服务组件

• 爬虫主服务及关联组件：
  • ClamD：病毒扫描
  • WebRender API和Warcprox：浏览器爬虫集成
  • OutbackCDX服务器：记录已爬URL的时间戳和校验和，用于去重
  • Apache Kafka和Zookeeper：消息队列服务
• 测试网站：
  • 模拟http://acid.matkelly.com/的容器
  • 托管爬虫测试站点http://crawl-test-site.webarchive.org.uk的容器（非公开URL）
• 结果查看服务：
  • Wayback服务：查看爬取结果
  • warc-server容器：提供WARC文件访问

环境配置

docker-compose.yml依赖.env文件获取共享变量，包括运行服务的用户UID，需覆盖为当前开发用户的UID：

bash
$ export CRAWL_UID=$(id -u)

或使用 helper 脚本：

bash
$ source source-setup-crawl-uid.sh

构建和运行测试

构建镜像：

bash
$ docker-compose build

此命令构建heritix和robot镜像。Compose文件会传递HTTP_PROXY和HTTPS_PROXY环境变量至构建环境，支持代理环境构建。

运行集成测试：

bash
$ docker-compose up

如需手动测试爬虫，可指定服务查看日志：

bash
$ docker-compose up heritrix warcprox webrender

ukwa-heritrix配置为启动后几秒自动运行frequent爬取任务。测试后建议清理环境：

bash
$ docker-compose rm -f
$ mvn clean

服务端点

运行后，以下服务可用于爬虫实验：

其他调试服务：

手动测试

使用https://github.com/ukwa/crawl-streams%E5%B7%A5%E5%85%B7%E4%B8%8E%E7%88%AC%E8%99%AB%E4%BA%A4%E4%BA%92%EF%BC%8C%E6%8F%90%E4%BA%A4%E6%B5%8B%E8%AF%95%E7%AB%99%E7%82%B9%E7%A7%8D%E5%AD%90URL%EF%BC%9A

bash
$ docker run --net host ukwa/crawl-streams submit -k localhost:9092 fc.tocrawl -S http://acid.matkelly.com/
$ docker run --net host ukwa/crawl-streams submit -k localhost:9092 fc.tocrawl -S http://crawl-test-site.webarchive.org.uk/

• --net host：使容器可通过localhost访问本地Kafka实例
• -S：标记URL为种子，爬虫会将其SURT前缀范围内的URL纳入爬取范围；无此标志时，仅当前爬取范围内的URL会被处理

爬虫会自动获取HTML页面所需的资源（如图像、CSS、JavaScript），即使这些资源超出主爬取范围。

直接与Kafka交互

可使用Kafka工具直接操作主题（不推荐，仅作参考）：

bash
# 发送种子URL
cat testdata/seed.json | kafka-console-producer --broker-list kafka:9092 --topic fc.tocrawl
# 消费待爬URL
kafka-console-consumer --bootstrap-server kafka:9092 --topic fc.tocrawl --from-beginning
# 消费已爬URL
kafka-console-consumer --bootstrap-server kafka:9092 --topic fc.crawled --from-beginning

自动化测试

robot容器通过Robot Framework运行测试，测试用例位于integration-test/robot/tests/crawl-test-site.robot，对两个测试站点执行爬取验证。

Heritrix3爬取任务

TBA - 本节将重点介绍ukwa-heritrix的配置选项和环境变量

TBA - 设计细节和原理将移至整体文档站点

使用Heritrix3 Sheets作为配置机制，允许根据URL的SURT前缀调整爬虫行为。

Heritrix3模块摘要

适用于Heritrix 3.4.+的模块：

• AnnotationMatchesListRegexDecideRule：基于注解检查的决策规则
• AsynchronousMQExtractor：向外部队列发布消息用于处理
• ClamdScanner：通过外部ClamAv守护进程处理内容
• CompressibilityDecideRule：拒绝高压缩或低压缩率的URI
• ConsecutiveFailureDecideRule：当URI及其引用者的HTTP状态码均≥400时拒绝该URI
• CountryCodeAnnotator：为URI添加国家代码注解
• ExternalGeoLookup：结合MaxMind GeoLite2数据库实现地理定位决策规则
• ExtractorJson：从JSON数据中提取URI
• ExtractorPattern：基于正则表达式提取URI（为特定站点编写，未广泛使用）
• HashingCrawlMapper：使用哈希库的简化版HashCrawlMapper
• IpAnnotator：为URI添加IP注解
• ViralContentProcessor：将输入URI提交给ClamAv扫描
• WARCViralWriterProcessor, XorInputStream：基于原始数据异或版本强制写入"转换"记录的工具
• RobotsTxtSitemapExtractor：从robots.txt提取并加入站点地图链接
• WrenderProcessor：通过Web渲染服务处理页面，替代默认H3处理

发布流程

仅需标记构建，执行以下命令即可标记版本并触发Docker镜像构建：

bash
mvn release:clean release:prepare

SCM/git标签格式应为X.Y.Z。

变更记录

• 2.7.11：
  • 基于Heritrix 3.4.0-20210621
• 2.7.0-BETA：
  • 将Heritrix3更新至基于BDB-JE 7的版本
  • 移除已从H3中删除的addPersistentDataMapKey使用
• 2.6.10：
  • 允许通过环境变量切换至布隆过滤器唯一URI方案
  • 将OutbackCDX客户端POST切换为使用HttpClient
  • 默认不检查OutbackCDX HttpClient构建器的系统属性
  • 确保HTTPClient响应实体被消费
  • 添加OutbackCDX客户端请求的Prometheus指标
• 2.6.9：
  • 确保配额重置传播至前置条件和重定向（#50）
• 2.6.8：
  • 恢复使用服务器配额作为默认值
• 2.6.7：
  • 避免收集源统计信息（解决#49引发的问题）
• 2.6.6：
  • 确保RobotsTxtSitemapExtractor中的SourceTag不设为null（#49）
  • 修改日志器以允许缓冲而非每行刷新
• 2.6.5：
  • 修复关键数据字段（如launchTimestamp）未标记为持久化导致的爬虫负载下失败问题
• 2.6.4：
  • 添加可选refreshDepth字段，标记launchTimestamp作为继承字段的跳数
• 2.6.3：
  • 处理无来源的范围内URI时使用自身作为来源
• 2.6.2：
  • 依赖Crawler Commons处理不同格式的站点地图
  • 全项目更新至commons-io 2.4（确保Crawler Commons兼容性）
  • 不假设robots.txt中的站点地图一定有效（可能存在重定向，#44）
  • 修复非种子URI因日志构建器假设存在源CrawlURI导致的日志问题
  • 允许每个CrawlURI最多50,000个外链（应对大型站点地图）
• 2.6.1：
  • 修改处置处理器，避免因robots.txt在前置条件外被发现并判定为范围外而导致缓存失效
  • 更新至OutbackCDX 0.5.1，移除处理含* URL的临时解决方案
• 2.6.0：
  • 站点地图提取及与重爬机制的简单集成
• 2.5.2：
  • 恢复跳过整个处置链（因-5000响应导致robots.txt缓存失效）
• 2.5.1：
  • 允许配置WARC写入器数量（原5个在数据中心环境下成为瓶颈）
• 2.5.0：
  • 简化关闭逻辑，避免锁文件残留
  • 允许超额队列退役后重新激活，而非全部释放
  • 跳至处置处理器而非整个链，确保重爬延迟设置正确
• 2.4.15：
  • 修复Spring语法问题
• 2.4.14：
  • Docker关闭期间尝试 checkpoint
  • 允许配置WebRender最大重试次数
• 2.4.13：
  • 配置WebRender超时，使用WEBRENDER作为默认前缀
  • 将范围内URL输出至单独Kafka主题
• 2.4.12：
  • 仅在修改配置表时重置，支持简单"刷新"请求
• 2.4.11：
  • 复制配置表以确保修改targetSheet后保持生效
• 2.4.10：
  • 未指定时保持配置表不变
• 2.4.9：
  • 重构并简化RecentlySeen代码，默认忽略forceFetch；可覆盖obeyForceFetch，但期望行为是即使URI已存在于前沿队列也强制接受（便于重新排序），而非覆盖RecentlySeen
• 2.4.8：
  • 重置配置表定义以解决重爬延迟问题，launchTimestamp解决此问题
• 2.4.7：
  • 更新至Heritrix 3.4.0-20190418（避免永久缓存DNS失败）
  • 支持启动模式：none、new-crawl和resume-latest
• 2.4.6：
  • 确保关键任务在跳过处置链前完成
  • 允许基于URL覆盖配置表中的launchTimestamp，命名一致
• 2.4.5：
  • 切换至通用每启动配置表设置（"目标配置表"，可设置任何属性）
  • 为每个目标创建配置表，通过此方式设置launchTimestamp
  • 切换至hostMaxSuccessKb而非serverMaxSuccessKb（解决HTTP/HTTPS间配额清除问题）
• 2.4.4：
  • 添加跳过处置链的能力（针对近期已见且超出范围的URI）
  • 提高WebRender耐心
  • 重命名Metrics Bean以明确其与Prometheus的关联
• 2.4.3：
  • 允许通过Prometheus监控告警计数
  • 记录OutbackCDX 0.5.1前版本处理含* URL的已知问题
• 2.4.2：
  • 恢复使用Heritrix 3.4.0-20190207（放弃3.4.0-SNAPSHOT测试）
• 2.4.1：
  • 切换至清除主机配额而非服务器配额
  • 添加DOI.org作为已知URL缩短服务（始终解析）
  • 恢复URL缩短服务列表
• 2.4.0：
  • 允许使用launch timestamp控制重爬
  • 处理错误外链（WebRender返回-5002错误码），明确标记WebRendered项
  • 确保关键前置条件不被配额阻止（配额仅在种子处理时清除）
• 2.3.6：
  • 恢复使用服务器配额，避免修改前沿组
• 2.3.5：
  • 使用并清除主机配额，解决http/https问题
• 2.3.4：
  • 支持正确不通过Kafka路由
  • 简化配置表逻辑布局
• 2.3.3：
  • 明确配额重置操作
  • 给予H3启动时间
• 2.3.2：
  • 使用一致的Web Render配置环境变量
  • docker-compose文件中使用新版webrender-api服务
  • 移除warcprox的WARC前缀中的斜杠
  • Travis更新至Java 8
• 2.3.1：
  • WebRender WARC与普通WARC存储在同一位置（未生效，见2.3.2）
  • Maven构建更新至Java 8
  • 更新发送前范围逻辑以匹配候选处理器
  • 减少URL遗忘日志
• 2.3.0：
  • 切换至"遗忘型"URI过滤器（BdbUriUniqFilter+ForgettingFrontierProcessor）
  • 使用注解进行配额重置
  • 支持Puppeteer作为替代渲染器
  • 将配额重置移至处理器
  • 确保后置过滤时应用配置表
  • 始终获取嵌入资源
• 2.2.20：
  • 缩短重爬周期以避免爬取跳过问题
  • 确保配额重置避免潜在竞争条件
• 2.2.19：
  • Docker构建依赖Maven处理H3版本等
  • 允许OSSRH快照
  • 从Maven组装Heritrix
  • 尝试快照构建和仅核心仓库
• 2.2.18：
  • 修复WebRender numTries检查中的NPW
• 2.2.17：
  • 更新至3.4.0-20190207 H3构建
  • 允许禁用输出日志
  • 迁移至3.4 H3版本
• 2.2.16：
  • 使用IA SNAPSHOT二进制版本
  • 正确更新WebRenderCount注解
• 2.2.15：
  • 统一使用WebRender术语（替代Wrender）
  • 简化Web渲染器以允许H3正确处理重试
  • 为Kafka客户端添加显式client id
  • 统一Prometheus指标命名
• 2.2.14：
  • 对HTTPS和HTTP应用配置表
• 2.2.13：
  • 尝试替代配额重置逻辑
  • 确保Kafka偏移量正确提交
  • 默认保留所有checkpoint以避免日志文件问题
• 2.2.12：
  • 确保每个消费者使用唯一groupId（Kafka手动分区要求）
• 2.2.11：