Ubuntu 22.04 安装 Apache StormCrawler 3.6.0 指南
Ubuntu 22.04 安装 Apache StormCrawler 3.6.0 指南：JDK 17 与 Maven 环境准备、2.x 与 3.x 版本选型对照、官方 Maven archetype 生成 crawler 工程与手工依赖引入两种方案、Apache Storm 2.8.8 运行时安装、uberjar 构建验证与卸载，全程实测。
Ubuntu 22.04 安装 Apache StormCrawler 3.6.0 指南
目标：在 Ubuntu 22.04 服务器上完成 Apache StormCrawler 3.6.0（基于 Apache Storm 的低延迟网络爬虫框架，以 Maven 工程形态引入）的安装与验证。本文给出 JDK 17 环境准备、2.x/3.x 版本选型对照、官方 archetype 生成工程与手工 Maven 依赖引入两种方案、Apache Storm 2.8.8 运行时安装，以及 uberjar 构建验证与卸载方式。所有命令与回显均在 Ubuntu 22.04.5 + OpenJDK 17 + Maven 3.6.3 环境实测通过。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（VERSION_CODENAME=jammy）
- 架构：x86_64（内核 6.8.0-138-generic）
- Java：OpenJDK 17.0.20.1（
openjdk-17-jdk-headless，Ubuntu 官方源） - 构建工具：Apache Maven 3.6.3（Ubuntu 官方源）
- StormCrawler 版本：3.6.0（当前最新稳定版，groupId 为
org.apache.stormcrawler，class 版本 61.0，需 JDK 17） - 依赖的 Storm 运行时：Apache Storm 2.8.8（archetype 生成的 pom 中
storm.version=2.8.8） - 演示账号：root
- 工程目录：
/root/build/crawler-demo/ - Storm 安装目录：
/opt/apache-storm-2.8.8/
💡 说明：Apache StormCrawler 是一组以 jar 库发布的爬虫组件（spout/bolt/资源文件），本身不是独立服务；「安装」的本质是准备 JDK/Maven 构建环境、用官方 Maven archetype 生成一个 crawler 工程，并准备好用于运行的 Apache Storm 二进制发行版。
二、前置条件
2.1 更新软件源
sudo apt-get update
2.2 安装 JDK 17 与 Maven
StormCrawler 3.x 的 class 文件版本为 61.0（父 pom 中 maven.compiler.source/target/release 均为 17），必须使用 JDK 17（Ubuntu 22.04 官方源已内置）：
sudo apt-get install -y openjdk-17-jdk-headless maven wget
验证 JDK 与 Maven：
java -version
mvn -version
实测回显：
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)
Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"
2.3 固化 JAVA_HOME（持久化）
为保证 Maven 与后续 Storm 命令始终使用 JDK 17，将环境变量写入 /etc/profile.d/：
echo "export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64" > /etc/profile.d/jdk17.sh
echo "export PATH=\$JAVA_HOME/bin:\$PATH" >> /etc/profile.d/jdk17.sh
source /etc/profile.d/jdk17.sh
三、版本选型说明
通过 Maven Central 查询当前版本（org.apache.stormcrawler:stormcrawler-core）：
wget -qO- "https://search.maven.org/solrsearch/select?q=g:org.apache.stormcrawler+AND+a:stormcrawler-core&rows=5&wt=json"
实测返回（节选）：
"a": "stormcrawler-core",
"latestVersion": "3.6.0",
StormCrawler 存在两条版本线，对照如下：
| 版本线 | 最新版本 | Maven groupId | class 版本 | 所需 JDK | 配套 Storm | 结论 |
|---|---|---|---|---|---|---|
| 3.x | 3.6.0 | org.apache.stormcrawler | 61.0 | JDK 17 | Storm 2.8.x（archetype 生成 2.8.8） | 新项目用 3.x |
| 2.x | 2.11 | com.digitalpebble.stormcrawler | 55.0 | JDK 11 | Storm 2.4.x | 仅维护旧项目时用 |
💡 版本选择建议：3.x 线的 groupId 已从
com.digitalpebble.stormcrawler迁移为org.apache.stormcrawler（Apache 官方孵化归属），且模块全面更新（Elasticsearch 模块演化为 OpenSearch 模块等）。新安装一律选 3.x 当前版 3.6.0。本指南全程按 JDK 17 + StormCrawler 3.6.0 + Storm 2.8.8 实测。
四、方案 A：官方 Maven archetype 生成 crawler 工程（官方推荐）
StormCrawler 官方推荐用 Maven archetype 一键生成一个开箱可用的 crawler 工程（含完整拓扑定义 crawler.flux、默认配置 crawler-conf.yaml 与过滤器资源文件）。
4.1 创建构建目录并执行 archetype
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
mkdir -p /root/build && cd /root/build
mvn archetype:generate -B \
-DarchetypeGroupId=org.apache.stormcrawler \
-DarchetypeArtifactId=stormcrawler-archetype \
-DarchetypeVersion=3.6.0 \
-DgroupId=com.demo.crawl -DartifactId=crawler-demo -Dversion=1.0-SNAPSHOT -Dpackage=com.demo.crawl \
-Dhttp-agent-name="DemoCrawler" -Dhttp-agent-version="1.0" \
-Dhttp-agent-description="Demo crawler for local test" \
-Dhttp-agent-url="http://www.example.com" -Dhttp-agent-email="root@example.com"
实测结果：命令正常退出（退出码 0），生成工程目录。
⚠️ 注意：archetype 要求必须提供
http-agent-name、http-agent-version、http-agent-description、http-agent-url、http-agent-email五个属性，缺省会报错Property http-agent-name is missing.。爬虫代理名需符合 RFC 9309 规范（仅字母、数字、下划线、连字符）。
4.2 生成的工程结构
find /root/build/crawler-demo -type f | sort
实测回显：
/root/build/crawler-demo/README.md
/root/build/crawler-demo/crawler-conf.yaml
/root/build/crawler-demo/crawler.flux
/root/build/crawler-demo/pom.xml
/root/build/crawler-demo/src/main/resources/default-regex-filters.txt
/root/build/crawler-demo/src/main/resources/default-regex-normalizers.xml
/root/build/crawler-demo/src/main/resources/jsoupfilters.json
/root/build/crawler-demo/src/main/resources/parsefilters.json
/root/build/crawler-demo/src/main/resources/urlfilters.json
| 文件 | 作用 |
|---|---|
| pom.xml | 构建定义（锁定 StormCrawler 3.6.0、Storm 2.8.8、编译目标 17、shade 打 uberjar） |
| crawler.flux | 生产拓扑定义（URLFrontier 状态后端 + StdOutIndexer） |
| crawler-conf.yaml | 爬虫自定义配置（覆盖 crawler-default.xml 默认值） |
| urlfilters.json | URL 过滤链（BasicURLFilter、HostURLFilter、RegexURLFilter 等） |
| default-regex-filters.txt | URL 正则过滤规则（默认拒绝 file/ftp/mailto、图片后缀、localhost 与私网地址） |
| default-regex-normalizers.xml | URL 正则正规化规则 |
| parsefilters.json / jsoupfilters.json | 解析过滤器链 |
4.3 生成 pom 的关键参数
生成工程 pom.xml 中的核心版本锁定（实测值）：
| 配置项 | 值 | 说明 |
|---|---|---|
| stormcrawler.version | 3.6.0 | StormCrawler 版本 |
| storm.version | 2.8.8 | 配套 Apache Storm 版本 |
| urlfrontier.version | 2.4 | URLFrontier 客户端版本 |
| maven-compiler-plugin source/target | 17 | Java 编译目标 |
| maven-shade-plugin mainClass | org.apache.storm.flux.Flux | uberjar 主类（Flux 拓扑启动器） |
| 核心依赖 | stormcrawler-core、stormcrawler-tika、stormcrawler-urlfrontier、storm-client（provided）、flux-core | 默认模块组合 |
五、方案 B：手工创建 Maven 工程引入依赖（自定义模块组合）
不需要 archetype 默认模块组合（如只需 core，或要接入 OpenSearch/Solr/SQL 后端）时，可手工创建 pom.xml 自选依赖。最小依赖组合示例：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.demo.crawl</groupId>
<artifactId>crawler-minimal</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.stormcrawler</groupId>
<artifactId>stormcrawler-core</artifactId>
<version>3.6.0</version>
</dependency>
<dependency>
<groupId>org.apache.storm</groupId>
<artifactId>storm-client</artifactId>
<version>2.8.8</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.apache.storm</groupId>
<artifactId>flux-core</artifactId>
<version>2.8.8</version>
</dependency>
</dependencies>
</project>
可选后端模块（按需加入，版本同为 3.6.0）：
| Artifact | 用途 |
|---|---|
| stormcrawler-opensearch | OpenSearch/Elasticsearch 状态与索引后端 |
| stormcrawler-solr | Solr 后端 |
| stormcrawler-sql | 关系数据库后端（状态/索引） |
| stormcrawler-tika | 非 HTML 文档解析（PDF/Office 等） |
| stormcrawler-urlfrontier | URLFrontier 分布式抓取队列后端 |
| stormcrawler-aws | AWS（CloudWatch 指标等）集成 |
| stormcrawler-playwright / stormcrawler-selenium | 浏览器渲染抓取 |
| stormcrawler-langid / stormcrawler-ai / stormcrawler-warc | 语言识别 / AI 能力 / WARC 归档 |
💡 说明：
storm-client官方声明为provided——构建 uberjar 时不打入 Storm 本体，运行时由 Storm 发行版提供，避免包冲突。
六、构建 uberjar 与验证
进入工程目录执行构建（方案 A 生成的工程，首次构建需联网下载依赖）：
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
cd /root/build/crawler-demo
mvn -B clean package
实测回显（尾部，依赖已缓存时）：
[INFO] BUILD SUCCESS
[INFO] Total time: 20.001 s
构建产物：
ls -lh target/*.jar
实测回显：
-rw-r--r-- 1 root root 106M Oct 12 13:32 target/crawler-demo-1.0-SNAPSHOT.jar
-rw-r--r-- 1 root root 6.1K Oct 12 13:32 target/original-crawler-demo-1.0-SNAPSHOT.jar
💡 说明：
crawler-demo-1.0-SNAPSHOT.jar为 shade 合并后的 uberjar（约 106MB，mainClass 已设为org.apache.storm.flux.Flux），可直接交给storm命令运行；original-*.jar是 shade 前的原始 jar。构建期出现 gson 与 urlfrontier-client 的重叠类 WARNING 属正常提示。
七、配置说明
7.1 运行时：安装 Apache Storm 2.8.8 二进制发行版
StormCrawler 工程构建出的 uberjar 需要交给 Apache Storm 运行（本地模式或分布式模式均通过 Storm 发行版的 bin/storm 命令启动）。Storm 2.8.8 与 archetype 生成的 storm.version 一致：
cd /opt
wget "https://archive.apache.org/dist/storm/apache-storm-2.8.8/apache-storm-2.8.8.tar.gz"
echo "075a165ac6f5f7d3284ff1fd46cfb0e30b63ed70b65ef59723c8c9c0d6107026ad25f5f86f45531837ceed22499f97fed81abf7018b02658e5d4c405e178a68a apache-storm-2.8.8.tar.gz" | sha512sum -c -
实测回显：
apache-storm-2.8.8.tar.gz: OK
解压（得到 /opt/apache-storm-2.8.8/）：
tar xzf apache-storm-2.8.8.tar.gz
验证 Storm 可用：
/opt/apache-storm-2.8.8/bin/storm version
实测回显：
Running: /usr/lib/jvm/java-17-openjdk-amd64/bin/java -client -Ddaemon.name= -Dstorm.options= -Dstorm.home=/opt/apache-storm-2.8.8 -Dstorm.log.dir=/opt/apache-storm-2.8.8/logs -Djava.library.path=/usr/local/lib:/opt/local/lib:/usr/lib:/usr/lib64 -Dstorm.conf.file= -cp /opt/apache-storm-2.8.8/*:/opt/apache-storm-2.8.8/lib/*:/opt/apache-storm-2.8.8/extlib/*:/opt/apache-storm-2.8.8/extlib-daemon/*:/opt/apache-storm-2.8.8/conf org.apache.storm.utils.VersionInfo
Storm 2.8.8
Branch v2.8.8
From source with checksum dd8ab586a06db2ced58135f6be47980
⚠️ 注意：
archive.apache.org下载较慢时可改用镜像站（如https://mirrors.huaweicloud.com/apache/storm/apache-storm-2.8.8/apache-storm-2.8.8.tar.gz，与官方 sha512 校验一致）。Apache 官方当前归档保留的 Storm 2.x 最新版本以https://archive.apache.org/dist/storm/目录列表为准。
7.2 爬虫基础配置：http.agent 与后端
- 代理标识：
crawler-conf.yaml中的http.agent.name（必填，用于 robots.txt 指令匹配）与http.agent.version、http.agent.description、http.agent.url、http.agent.email组成完整 User-Agent； - 状态后端：archetype 默认拓扑（crawler.flux）使用 URLFrontier 后端（gRPC 服务，默认端口 7071），配置项
urlfrontier.host、urlfrontier.port；本地演示可改用 StormCrawler 自带的内存后端组件（见《构建并运行示例抓取应用指南》篇）； - 过滤配置：
urlfilters.config.file、parsefilters.config.file、jsoup.filters.config.file指向 classpath 内的 JSON 过滤链文件。
各配置项的完整含义、默认值与生产模板见《Apache StormCrawler 3.6.0 配置参数详解》篇。
八、注意事项
⚠️ 注意：
- StormCrawler 3.x 必须 JDK 17+（class 版本 61.0）。JDK 11 下即使空工程能构建（无 Java 源码时编译器不会真正执行），运行期加载 StormCrawler 类会抛
UnsupportedClassVersionError。- archetype 缺少
http-agent-*属性会直接报错退出，五个属性一个都不能少。crawler-conf.yaml引用了parse.tika.config.file: "tika-config.xml"，但 archetype 不生成该文件；需在工程根目录自建最小tika-config.xml（<properties></properties>），避免 Tika 解析 bolt 初始化失败。- archetype 自带的
default-regex-filters.txt默认拒绝 localhost/127.x/私网地址的 URL（防 SSRF 泄漏），抓取本机测试站点前需按需注释对应规则。- 生产环境运行 worker 需关注 JVM 堆：Storm 默认 worker 堆较大，可通过
topology.worker.childopts或STORM_JAR_JVM_OPTS限制到 256-512MB（本地模式验证方法见下节）。
九、常见问题
Q1：mvn 编译报 invalid target release: 17 或运行时报 UnsupportedClassVersionError ... class file version 61.0？
原因：使用了低于 17 的 JDK。StormCrawler 3.6.0 与其依赖的 Storm 2.8.8 组件均按 Java 17 编译。解决：安装 openjdk-17-jdk-headless 并按第 2.3 节固化 JAVA_HOME，再执行 mvn -version 确认 Java version 为 17。
Q2：archetype:generate 报 Property http-agent-name is missing.？
archetype 元数据把代理信息定义为必填属性。补齐 -Dhttp-agent-name/-Dhttp-agent-version/-Dhttp-agent-description/-Dhttp-agent-url/-Dhttp-agent-email 后重新执行（见第四节命令）。
Q3：mvn clean package 慢或超时？
首次构建需从 Maven Central 下载全部依赖（实测约 4 分半）。依赖缓存后二次构建约 20 秒。内网环境可配置公司 Nexus/Artifactory 镜像。
Q4：storm version 报 JAVA_HOME 未设置？
Storm 脚本依赖 JAVA_HOME 定位 java 可执行文件。按第 2.3 节固化后再执行，或临时 export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64。
Q5：本地模式运行时如何限制 JVM 堆在 256-512MB？
storm local 命令读取环境变量 STORM_JAR_JVM_OPTS 注入 JVM 参数，例如 STORM_JAR_JVM_OPTS="-Xms256m -Xmx512m"；启动后回显的 Running: 行会包含该参数，可用 jps -v 核对生效值（实测 Running: 行含 -Xms256m -Xmx512m）。
十、卸载方式
删除工程与本地 Maven 仓库中的 StormCrawler 依赖：
rm -rf /root/build/crawler-demo
rm -rf ~/.m2/repository/org/apache/stormcrawler
删除 Storm 运行时：
rm -rf /opt/apache-storm-2.8.8 /opt/apache-storm-2.8.8.tar.gz
如同时移除 JDK 17 与 Maven：
sudo apt-get remove -y openjdk-17-jdk-headless maven
sudo apt-get autoremove -y
十一、参考链接
- StormCrawler 官网与文档：
https://stormcrawler.net/ - StormCrawler 源码仓库：
https://github.com/apache/stormcrawler - Maven Central 版本目录：
https://repo1.maven.org/maven2/org/apache/stormcrawler/ - Apache Storm 下载归档：
https://archive.apache.org/dist/storm/ - Storm 官方文档：
https://storm.apache.org/