ukwa/hapy

hapy Docker镜像文档

镜像概述

hapy Docker镜像是Heritrix3 API操作的Python命令行客户端的Docker化实现。它封装了hapy库，提供与Heritrix 3.x API的完整交互能力，可通过命令行或脚本自动化执行爬虫任务管理，包括作业创建、配置提交、状态监控等操作，简化了Heritrix爬虫的部署与管理流程。

核心功能与特性

• 完整API覆盖：实现Heritrix 3.x API的核心功能，支持作业创建、构建、启动、暂停、终止、复制、检查点等操作。
• 扩展功能支持：提供未公开API的封装，包括系统信息查询、作业详情获取、配置导出及作业删除（需谨慎使用）。
• 命令行工具集成：内置h3cc（Heritrix3 Crawl Controller）脚本，支持直接与Heritrix交互，执行爬虫状态查询、URL队列查看等操作。
• 环境隔离：通过Docker容器化部署，避免Python环境依赖冲突，简化跨平台使用。

使用场景与适用范围

• 爬虫任务自动化：适用于需要通过脚本批量创建、配置和管理Heritrix爬虫作业的场景。
• 爬虫状态监控：可查询作业运行状态、资源使用情况（如堆内存使用）、URL爬取统计等关键指标。
• 命令行快速操作：通过h3cc工具快速执行爬虫控制操作，如查看待爬URL队列、查询特定URL状态。
• 工作流集成：可作为自动化流程的组件，与xmlstarlet等工具配合处理爬虫数据。

使用方法与配置说明

镜像获取

从Docker仓库拉取镜像（假设镜像名为hapy-heritrix）：

bash
docker pull hapy-heritrix

基本使用

交互式Python环境

通过容器内Python环境直接使用hapy库：

bash
docker run -it --rm hapy-heritrix python

在Python交互环境中：

python
import hapy

# 连接Heritrix实例（默认地址https://localhost:8443，用户名/密码admin/admin）
h = hapy.Hapy('https://heritrix-host:8443', username='admin', password='admin')

# 创建作业
h.create_job('example-job')

# 获取作业信息
job_info = h.get_job_info('example-job')
print(f"作业状态: {job_info['job']['status']}")

执行本地脚本

将本地脚本挂载到容器中执行：

bash
docker run -it --rm -v $(pwd):/scripts hapy-heritrix python /scripts/your_script.py

示例脚本（your_script.py）：

python
import hapy

try:
    # 初始化Hapy客户端
    h = hapy.Hapy('https://heritrix-host:8443', username='admin', password='admin')
    
    # 创建作业
    h.create_job('test-job')
    
    # 提交CXML配置
    with open('/scripts/config.cxml', 'r') as f:
        config = f.read()
    h.submit_configuration('test-job', config)
    
    # 构建并启动作业
    h.build_job('test-job')
    h.launch_job('test-job')
    h.unpause_job('test-job')
    
    print("作业启动成功")
except hapy.HapyException as e:
    print(f"操作失败: {e}")

环境变量配置

通过环境变量预设连接参数，避免硬编码：

示例：使用环境变量运行容器

bash
docker run -it --rm \
  -e HERITRIX_URL=https://heritrix-host:8443 \
  -e HERITRIX_USERNAME=myuser \
  -e HERITRIX_PASSWORD=mypass \
  hapy-heritrix python

命令行工具h3cc使用

h3cc是内置的Heritrix3爬虫控制器脚本，支持以下操作：

获取系统信息XML

bash
docker run -it --rm hapy-heritrix python agents/h3cc.py info-xml

结合xmlstarlet提取堆内存使用情况：

bash
docker run -it --rm hapy-heritrix python agents/h3cc.py info-xml | xmlstarlet sel -t -v "//heapReport/usedBytes"

查看待爬URL队列

bash
docker run -it --rm hapy-heritrix python agents/h3cc.py -H heritrix-host -q "http://www.example.com/" -l 5 pending-urls-from

查询特定URL状态

bash
docker run -it --rm hapy-heritrix python agents/h3cc.py -H heritrix-host -q "http://www.example.com/news" url-status

Docker Compose配置示例

创建docker-compose.yml：

yaml
version: '3'
services:
  hapy:
    image: hapy-heritrix
    environment:
      - HERITRIX_URL=https://heritrix:8443
      - HERITRIX_USERNAME=admin
      - HERITRIX_PASSWORD=admin
    volumes:
      - ./scripts:/scripts  # 挂载本地脚本目录
    command: python /scripts/run_crawl.py  # 执行爬虫启动脚本

启动服务：

bash
docker-compose up

API参考

hapy客户端支持的核心API方法：

• create_job(name): 创建新作业
• add_job_directory(path): 添加作业目录
• build_job(name): 构建作业
• launch_job(name): 启动作业
• pause_job(name): 暂停作业
• unpause_job(name): 恢复作业
• terminate_job(name): 终止作业
• teardown_job(name): 清理作业
• copy_job(src_name, dest_name, as_profile): 复制作业
• checkpoint_job(name): 创建作业检查点
• execute_script(name, engine, script): 执行脚本
• submit_configuration(name, cxml): 提交CXML配置

扩展方法：

• get_info(): 获取系统信息（返回dict）
• get_job_info(name): 获取作业信息（返回dict）
• get_job_configuration(name): 获取作业配置（返回字符串）
• delete_job(name): 删除作业（未完全测试，谨慎使用）