Ubuntu 22.04 安装 Apache Tika 4.1.0 指南

一、环境信息

项目	值
操作系统	Ubuntu 22.04 LTS（Jammy）
内核	5.15.x x86_64
Tika 版本	Apache Tika 4.1.0（官方当前最新稳定版）
Java 版本	OpenJDK 17.0.20.1（apt 仓库 openjdk-17-jre-headless）
安装目录	/opt/tika
服务端口	9998（Tika Server 默认监听端口）
JVM 堆	-Xms256m -Xmx512m
执行账号	root

二、前置条件

服务器可访问外网（需从 downloads.apache.org 下载发行包）。
拥有 root 权限，本文全部命令以 root 执行。
磁盘剩余空间不低于 2GB（Tika 发行包约 57MB，解压后约 63MB，运行期临时文件与日志另需空间）。
系统时间已同步（Tika 元数据抽取会输出时间戳）。

三、版本选型说明

Apache Tika 官方下载页（tika.apache.org/download.html）当前标注最新发布版为 4.1.0，同时 3.x 维护线（3.3.2）仍在持续修复缺陷。
自 4.x 起，官方不再发布单一可执行 fat jar，tika-server-standard 与 tika-app 均以 zip 发行包交付，包内包含一个瘦启动 jar（thin launcher）与相邻的 lib 依赖目录，使用 java -jar 启动瘦 jar 即可自动加载 lib 下的依赖。
4.1.0 服务端运行要求 Java 11 及以上，实测采用 OpenJDK 17 LTS，兼容性良好。
本文所有命令与回显均在 Ubuntu 22.04 真实环境中按顺序执行并采集，版本号以实测为准。

四、部署步骤

4.1 安装 JDK 与基础工具

apt-get update

apt-get install -y openjdk-17-jre-headless curl wget unzip

回显末尾确认安装完成：

Setting up openjdk-17-jre-headless:amd64 (17.0.20.1+1-1-22.04-Ubuntu)

验证 Java 版本：

java -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)

如需使用 jps 命令验证 JVM 参数，需补装 JDK 套件（jre-headless 不含 jps）：

apt-get install -y openjdk-17-jdk-headless

4.2 下载官方发行包

mkdir -p /opt/tika-dl && cd /opt/tika-dl

curl -sSL -o tika-server-standard-4.1.0.zip https://downloads.apache.org/tika/4.1.0/tika-server-standard-4.1.0.zip -w 'HTTP %{http_code} size=%{size_download}\n'

HTTP 200 size=58810181

可选：校验 sha512（官方同目录提供 tika-server-standard-4.1.0.zip.sha512）：

sha512sum tika-server-standard-4.1.0.zip

4.3 解压部署到 /opt/tika

mkdir -p /opt/tika && unzip -qo /opt/tika-dl/tika-server-standard-4.1.0.zip -d /opt/tika

查看部署结果：

ls -lh /opt/tika

total 57M
-rw-r--r-- 1 root root 116K Sep 26 14:59 LICENSE
-rw-r--r-- 1 root root  182 Sep 26 14:59 NOTICE
drwxr-xr-x 3 root root 4.0K Sep 26 14:59 bin
drwxr-xr-x 2 root root  12K Sep 26 14:59 lib
drwxr-xr-x 3 root root 4.0K Sep 26 14:59 plugins
-rw-rw-r-- 1 root root  49K Sep 26 14:59 tika-server-standard-4.1.0.jar

说明：tika-server-standard-4.1.0.jar 是约 49KB 的瘦启动 jar，实际依赖位于 lib 目录（147 个 jar）。启动器按 jar 同目录加载 lib，因此不要把该 jar 单独拷出目录运行。

确认依赖目录存在：

ls /opt/tika/lib | wc -l

4.4 前台试启动并确认帮助信息

先通过 --help 确认启动参数（不启动服务）：

cd /opt/tika && java -jar tika-server-standard-4.1.0.jar --help

 usage:  tikaserver [-?] [-c <arg>] [-h <arg>] [-i <arg>] [--metricsPort
    <arg>] [-p <arg>]

       Options           Since                    Description
 -h, --host <arg>         --       host name (default = localhost, use * for
                                    all)
 -p, --port <arg>         --       listen port (default = 9998)
 -?, --help               --       this help message
 -c, --config <arg>       --       tika-config file
 -i, --id <arg>           --       id for this server, written to the startup
                                    log
 --metricsPort <arg>      --       serve Prometheus metrics on this port
                                   (9404 by convention); unset means metrics
                                    are off

4.5 编写 systemd 服务单元

创建 /etc/systemd/system/tika.service（注意 JAVA_OPTS 通过 Environment 声明，堆内存限制为 256-512MB）：

[Unit]
Description=Apache Tika Server 4.1.0
After=network.target

[Service]
Type=simple
User=root
Environment="JAVA_OPTS=-Xms256m -Xmx512m"
ExecStart=/usr/bin/java $JAVA_OPTS -jar /opt/tika/tika-server-standard-4.1.0.jar --host 0.0.0.0 --port 9998
Restart=on-failure
RestartSec=10
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

写入后重载并设置开机自启、立即启动：

systemctl daemon-reload

systemctl enable tika

Created symlink /etc/systemd/system/multi-user.target.wants/tika.service → /etc/systemd/system/tika.service.

systemctl start tika

4.6 验证服务状态与 JVM 参数

查看服务状态：

systemctl status tika --no-pager

● tika.service - Apache Tika Server 4.1.0
     Loaded: loaded (/etc/systemd/system/tika.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-12 09:13:03 UTC; 12s ago
   Main PID: 4001 (java)
      Tasks: 39 (limit: 5753)
     Memory: 290.7M
        CPU: 9.393s
     CGroup: /system.slice/tika.service
             └─4001 /usr/bin/java -Xms256m -Xmx512m -jar /opt/tika/tika-server-standard-4.1.0.jar --host 0.0.0.0 --port 9998

用 jps -v 验证堆参数已生效：

jps -v

4001 tika-server-standard-4.1.0.jar -Xms256m -Xmx512m
4120 Jps -Dapplication.home=/usr/lib/jvm/java-17-openjdk-amd64 -Xms8m -Djdk.module.main=jdk.jcmd

用 ps -ef 复核完整命令行：

ps -ef | grep '[t]ika-server-standard'

root        4001       1 31 09:13 ?        00:00:09 /usr/bin/java -Xms256m -Xmx512m -jar /opt/tika/tika-server-standard-4.1.0.jar --host 0.0.0.0 --port 9998

4.7 REST 接口验证

确认服务欢迎信息与版本号：

curl -s http://127.0.0.1:9998/tika

This is Tika Server (Apache Tika 4.1.0). Please PUT

curl -s http://127.0.0.1:9998/version

Apache Tika 4.1.0

准备测试样本文件：

mkdir -p /opt/samples

printf 'Hello Apache Tika!\nThis is a plain text sample file for content detection tests.\n' > /opt/samples/hello.txt

如需 PDF 样本，可执行以下 python3 脚本生成最小合法 PDF：

apt-get install -y python3

# 保存为 /opt/samples/gen_pdf.py 后执行 python3 /opt/samples/gen_pdf.py
from itertools import accumulate
objs = [
    b"<< /Type /Catalog /Pages 2 0 R >>",
    b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
    b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>",
]
stream = b"BT /F1 24 Tf 100 700 Td (Hello Apache Tika PDF sample) Tj ET"
objs.append(b"<< /Length %d >>\nstream\n%s\nendstream" % (len(stream), stream))
objs.append(b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>")
head = b"%PDF-1.4\n"
chunks = [b"%d 0 obj\n%s\nendobj\n" % (i, o) for i, o in enumerate(objs, start=1)]
offsets = [len(head)] + list(accumulate(len(c) for c in chunks))[:-1]
pdf = head + b"".join(chunks)
xref = len(pdf)
pdf += b"xref\n0 %d\n" % (len(objs) + 1) + b"0000000000 65535 f \n"
pdf += b"".join(b"%010d 00000 n \n" % off for off in offsets)
pdf += b"trailer\n<< /Size %d /Root 1 0 R >>\nstartxref\n%d\n%%%%EOF\n" % (len(objs) + 1, xref)
open("/opt/samples/hello.pdf", "wb").write(pdf)

pdf bytes: 604

类型探测（/detect 接口，4.x 已将旧版 /detect/stream 简化为 /detect）：

curl -s -X PUT --data-binary @/opt/samples/hello.txt -H 'Content-Disposition: attachment; filename=hello.txt' http://127.0.0.1:9998/detect

text/plain

curl -s -X PUT --data-binary @/opt/samples/hello.pdf -H 'Content-Disposition: attachment; filename=hello.pdf' http://127.0.0.1:9998/detect

application/pdf

全文抽取（/tika 接口）：

curl -s -X PUT --data-binary @/opt/samples/hello.txt -H 'Content-Disposition: attachment; filename=hello.txt' http://127.0.0.1:9998/tika

Hello Apache Tika! This is a plain text sample file for content detection tests.

curl -s -X PUT --data-binary @/opt/samples/hello.pdf -H 'Content-Disposition: attachment; filename=hello.pdf' http://127.0.0.1:9998/tika


Hello Apache Tika PDF sample

元数据输出（/meta 接口，返回 JSON）：

curl -s -X PUT --data-binary @/opt/samples/hello.pdf -H 'Content-Disposition: attachment; filename=hello.pdf' http://127.0.0.1:9998/meta

{"pdf:incremental-update-count":"0","pdf:has-xfa":"false","pdf:chars-per-page":"28","tk:resource-name":"hello.pdf","dc:format":"application/pdf; version=1.4","access-permission:assemble-document":"true","pdf:num-3d-annotations":"0","pdf:has-collection":"false","pdf:eof-offsets":"604","tk:content-type-magic-detected":"application/pdf","pdf:pdf-version":"1.4","pdf:unmapped-unicode-chars-per-page":"0","access-permission:can-modify":"true","pdf:encrypted":"false","pdf:contains-non-embedded-font":"true","pdf:overall-percentage-unmapped-unicode-chars":"0.0","access-permission:extract-content":"true","Content-Length":"604","Content-Type":"application/pdf","pdf:has-xmp":"false","access-permission:can-print-faithful":"true","access-permission:can-print":"true","pdf:contains-damaged-font":"false","tk:version-count":"0","xmpTPg:NPages":"1","pdf:has-marked-content":"false","pdf:total-unmapped-unicode-chars":"0","tk:parsed-by":["org.apache.tika.parser.DefaultParser","org.apache.tika.parser.pdf.PDFParser"],"access-permission:modify-annotations":"true","access-permission:extract-for-accessibility":"true","access-permission:fill-in-form":"true","tk:parse-time-millis":"9","tk:parsed-by-full-set":["org.apache.tika.parser.DefaultParser","org.apache.tika.parser.pdf.PDFParser"],"tk:embedded-depth":"0","pdf:ocr-page-count":"0"}

4.8 服务停止与重启

systemctl stop tika

systemctl status tika --no-pager | head -3

○ tika.service - Apache Tika Server 4.1.0
     Loaded: loaded (/etc/systemd/system/tika.service; enabled; vendor preset: enabled)
     Active: inactive (dead) since Mon 2026-10-12 09:31:33 UTC; 8ms ago

systemctl restart tika

curl -s http://127.0.0.1:9998/version

Apache Tika 4.1.0

五、配置说明

服务单元文件：/etc/systemd/system/tika.service，JVM 参数在 Environment 行修改。将 -Xmx512m 调整为其他值后需执行 systemctl daemon-reload 再 systemctl restart tika 方可生效。
修改堆内存后用 jps -v 验证，回显应包含新参数值，例如 4001 tika-server-standard-4.1.0.jar -Xms256m -Xmx384m。
监听地址与端口由启动行 --host 与 --port 控制，--host 0.0.0.0 表示监听全部网卡，仅本机访问可改回默认 localhost。
若需启用 Prometheus 指标，在启动行追加 --metricsPort 9404，之后访问 http://127.0.0.1:9404/metrics 获取指标文本。
深度定制（解析器裁剪、临时目录等）通过 -c 参数加载 JSON 配置文件实现，详见本站《Apache Tika 4.1.0 配置参数详解》。
Tika 4.x 采用 pipes 架构：主进程默认 fork 4 个解析子进程（日志出现 Using per-client server mode with 4 clients），实际内存占用为主进程与子进程之和，估算内存时需一并计入。

六、注意事项

Tika 4.x 发行包为 zip 形态（瘦启动 jar 加 lib 目录），不要与 3.x 的单一 fat jar 部署方式混淆。
/detect/stream 是 2.x 与 3.x 的端点，在 4.1.0 中返回 404；4.x 应使用 /detect。
请求 /detect、/tika、/meta 时务必携带 Content-Disposition 请求头并附文件名，否则服务端无法进行基于文件名的类型探测。
默认监听 localhost，若需远程访问必须显式指定 --host 0.0.0.0，并做好防火墙与反向代理等访问控制。
Tika 无内置认证机制，9998 端口不要直接暴露公网。
解析子进程空闲超时后自动退出（日志 socket timeout while waiting for task, shutting down）属于 4.x 正常行为，下一个请求会按需重新拉起。
jre-headless 环境无 jps 命令，验证 JVM 参数需安装 openjdk-17-jdk-headless。

七、常见问题

Q1：服务启动后 curl 返回空或连接拒绝？ 执行 systemctl status tika 确认 Active 状态。若为 active (running) 但端口未监听，查看 journalctl -u tika -n 50 中的启动日志；正常启动完成约需 10 秒，Jetty 输出 Started oejs.ServerConnector 即为就绪。

Q2：访问 /detect/stream 提示 404 Not Found？ 这是 4.x 端点变更所致。4.1.0 的探测端点为 /detect，请求方式与请求头不变，改用 PUT /detect 即可。服务启动日志中会列出全部启用端点：/tika、/rmeta、/unpack、/meta、/detect、/pipes。

Q3：修改了 unit 文件中的 -Xmx 为什么不生效？ systemd 的 ExecStart 支持变量展开，但修改 unit 后必须执行 systemctl daemon-reload，再执行 systemctl restart tika。用 jps -v 或 ps -ef 确认进程命令行中已包含新参数。

Q4：systemd 启动失败提示 ExecStart 相关错误？ 检查 unit 文件中 $JAVA_OPTS 是否在写入时被 shell 提前展开为空（使用引号方式写入 heredoc 可避免），并确认 /opt/tika/tika-server-standard-4.1.0.jar 与 lib 目录同级存在。

Q5：上传大文件报内存不足？ 默认堆 512MB 与 4 个解析子进程的配比适合小中型文档。可适当上调 -Xmx（建议不超过物理内存的 50%），同时在 JSON 配置的 server 块中调整子进程数量。

八、卸载方式

systemctl stop tika

systemctl disable tika

Removed "/etc/systemd/system/multi-user.target.wants/tika.service".

rm -f /etc/systemd/system/tika.service

systemctl daemon-reload

rm -rf /opt/tika /opt/tika-dl /opt/samples

如安装了 jdk-headless 与 python3 且无其他用途，可一并移除：

apt-get purge -y openjdk-17-jdk-headless

apt-get autoremove -y

九、参考链接

Apache Tika 官方下载页：https://tika.apache.org/download.html
Tika 4.1.0 发行包目录：https://downloads.apache.org/tika/4.1.0/
Tika Server 官方文档：https://cwiki.apache.org/confluence/display/TIKA/TikaServer
Tika 官方项目主页：https://tika.apache.org/