Apache Tika 4.1.0 配置参数详解

一、环境信息

项目	值
操作系统	Ubuntu 22.04 LTS（Jammy）
Tika 版本	Apache Tika 4.1.0（官方当前最新稳定版）
Java 版本	OpenJDK 17.0.20.1
安装目录	/opt/tika
启动 jar	tika-server-standard-4.1.0.jar（瘦启动 jar，依赖位于同目录 lib）
配置文件	/opt/tika/tika-config.json（本文示例路径）
服务端口	9998
JVM 堆	-Xms256m -Xmx512m
执行账号	root

二、前置条件

已按《Ubuntu 22.04 安装 Apache Tika 4.1.0 指南》或《CentOS 8 安装 Apache Tika 4.1.0 指南》完成部署，服务单元 /etc/systemd/system/tika.service 处于 active (running) 状态。
拥有 root 权限，本文全部命令以 root 执行。
如需复现文中的接口验证回显，可准备样本文件 /opt/samples/hello.txt 与 /opt/samples/hello.pdf。

三、参数查看与修改方式

查看服务端支持的全部启动参数（不启动服务）：

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

查看运行中进程的实际参数（JVM 参数与启动参数一目了然）：

jps -v

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

Tika 的配置入口共三处，均无需修改任何程序代码：
- systemd 服务单元 /etc/systemd/system/tika.service 的 ExecStart 行：控制 --host、--port、--config、--metricsPort、-i 等启动参数。
- 同一 unit 的 Environment 行：控制 JAVA_OPTS，即 JVM 堆等参数。
- JSON 配置文件：由启动参数 -c 指定路径，控制解析器集合、监听地址端口等深度行为。
修改生效流程：编辑 unit 文件后，必须按顺序执行 systemctl daemon-reload 与 systemctl restart tika；JSON 配置文件在服务启动时读取，修改后重启服务即可。全部修改都用 jps -v 或 ps -ef 复核。

四、参数总览

服务端启动参数（4.1.0 共 6 个）：

参数	说明	默认值
-h, --host	监听主机名，设为 * 表示监听全部网卡	localhost
-p, --port	监听端口	9998
-c, --config	指定 tika-config JSON 配置文件	不加载配置文件
-i, --id	服务实例标识，写入启动日志	未设置时日志输出自动生成的 UUID
--metricsPort	开放 Prometheus 指标端口	未设置时指标功能关闭
-?, --help	打印帮助信息	无

JVM 参数（本文采用 systemd Environment 传递）：

参数	说明	本文取值
-Xms	初始堆大小	256m
-Xmx	最大堆大小	512m
传递方式	unit 文件 Environment 行的 JAVA_OPTS 变量	"JAVA_OPTS=-Xms256m -Xmx512m"

JSON 配置文件顶层合法配置块共 24 个：encoding-detectors、parse-context、emitters、translator、service-loader、metadata-list、engines、content-handler-factory、parsers、presets、server、pipes-iterator、plugin-roots、auto-detect-parser、xml-reader-utils、detectors、text-recognizers、renderers、pipes、inference、pipes-reporters、fetchers、metadata-filters、grpc。其中 server 与 parsers 为服务端最常用的两个块，本文对这两块做了完整实测，其余块未逐一实测，使用前建议先以小端口试启动验证。

五、核心参数分类详解

5.1 服务端启动参数

--help 完整回显（4.1.0）：

 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

逐项说明：

--host：默认仅监听 localhost。生产环境需要被其他主机调用时设为 0.0.0.0（本文实测 unit 即采用 --host 0.0.0.0），并自行做好防火墙与访问控制。
--port：默认 9998。实测改为 19998、29998 均正常启动。
--config：指定 JSON 配置文件，详见 5.2。
--id：实例标识。未设置时启动日志输出自动生成的 UUID，实测日志为 Started Apache Tika server cf16d4f8-f25e-4a8a-9a35-91a980643888。
--metricsPort：4.1.0 新增，3.x 维护线（3.3.2）没有该参数。按惯例使用 9404。

--metricsPort 实测（测试性前台启动，验证后停止）：

cd /opt/tika && java -jar tika-server-standard-4.1.0.jar -p 19998 --metricsPort 9404

启动日志关键行：

INFO  [main] org.apache.tika.server.core.TikaServerProcess Started metrics listener (plain HTTP) on http://localhost:9404/metrics
INFO  [main] org.eclipse.jetty.server.AbstractConnector Started oejs.ServerConnector@2aa7399c{HTTP/1.1, (http/1.1)}{localhost:9404}
INFO  [main] org.eclipse.jetty.server.AbstractConnector Started oejs.ServerConnector@62c6284{HTTP/1.1, (http/1.1, h2c)}{localhost:19998}

拉取 Prometheus 格式指标：

curl -s http://127.0.0.1:9404/metrics | head -10

# HELP jvm_buffer_count_buffers An estimate of the number of buffers in the pool
# TYPE jvm_buffer_count_buffers gauge
jvm_buffer_count_buffers{id="direct"} 1.0
jvm_buffer_count_buffers{id="mapped"} 0.0
jvm_buffer_count_buffers{id="mapped - 'non-volatile memory'"} 0.0
# HELP jvm_buffer_memory_used_bytes An estimate of the memory that the Java virtual machine is using for this buffer pool
# TYPE jvm_buffer_memory_used_bytes gauge
jvm_buffer_memory_used_bytes{id="direct"} 8192.0
jvm_buffer_memory_used_bytes{id="mapped"} 0.0
jvm_buffer_memory_used_bytes{id="mapped - 'non-volatile memory'"} 0.0

确认主服务同步可用：

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

Apache Tika 4.1.0

5.2 JSON 配置文件（4.x 新格式）

4.x 的 tika-config 全面改用 JSON 格式，通过 -c 传入。配置文件建议放在 /opt/tika/tika-config.json，并在 unit 的 ExecStart 行追加 --config /opt/tika/tika-config.json。

实测成功的最小可用配置（监听 29998 端口并显式声明三个解析器）：

{
  "server": { "host": "localhost", "port": 29998 },
  "parsers": ["pdf-parser", "txt-parser", "image-parser"]
}

以该配置启动：

cd /opt/tika && java -jar tika-server-standard-4.1.0.jar -c /tmp/tika-config.json

启动日志关键行：

INFO  [main] org.apache.tika.server.core.TikaServerProcess Using custom config: /tmp/tika-config.json
INFO  [main] org.apache.tika.pipes.core.PipesParser Using per-client server mode with 4 clients
INFO  [main] org.apache.tika.server.core.TikaServerProcess Started Apache Tika server cf16d4f8-f25e-4a8a-9a35-91a980643888 at http://localhost:29998/

验证配置已生效：

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

Apache Tika 4.1.0

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

application/pdf

curl -s -X PUT --data-binary @/opt/samples/hello.txt -H 'Content-Disposition: attachment; filename=hello.txt' http://127.0.0.1:29998/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:29998/meta | grep -o '"tk:parsed-by":\[[^]]*\]'

"tk:parsed-by":["org.apache.tika.parser.CompositeParser","org.apache.tika.parser.pdf.PDFParser"]

可见 kebab-case 写法 pdf-parser 被正确映射为 org.apache.tika.parser.pdf.PDFParser，显式声明 parsers 后解析器集合即为所列组件。

三类非法写法与实测报错对照：

错误一，使用了不存在的顶层 key：

{ "renderer": {} }

org.apache.tika.exception.TikaConfigException: Unknown configuration key(s): [renderer]. Valid keys: [encoding-detectors, parse-context, emitters, translator, service-loader, metadata-list, engines, content-handler-factory, parsers, presets, server, pipes-iterator, plugin-roots, auto-detect-parser, xml-reader-utils, detectors, text-recognizers, renderers, pipes, inference, pipes-reporters, fetchers, metadata-filters, grpc]

报错会列出全部 24 个合法 key（顺序每次可能不同），据此即可核对拼写。

错误二，server 模式缺少 server 块：

{ "parsers": ["pdf-parser"] }

org.apache.tika.exception.TikaConfigException: Couldn't find 'server' element

以 -c 加载配置启动服务端时，配置文件必须包含 server 块。

错误三，parsers 使用全限定类名：

{ "server": { "host": "localhost", "port": 29998 }, "parsers": [{ "class": "org.apache.tika.parser.pdf.PDFParser" }] }

启动阶段不报错，首个请求返回初始化失败（实测响应摘录）：

{"status":"FAILED_TO_INITIALIZE","message":"org.apache.tika.pipes.core.ServerInitializationException: org.apache.tika.exception.TikaConfigException: Unknown component type: 'class'"}

服务端日志中的关键报错行（摘录）：

Component 'class' is not registered. Either the name is misspelled, or the module that provides it is not on the classpath
173 registered component(s): active-mime-parser, adobe-font-metric-parser, apple-single-file-parser, audio-parser
Arbitrary class names are not allowed for security reasons.

即出于安全考虑 4.x 不允许在配置里直接写类名，必须使用注册名，且报错会列出全部 173 个已注册组件名。查询注册名的简便方式是使用 tika-app 命令行工具的 --list-parser-names（与 server 共用同一套组件注册名机制，实测输出 88 行，格式为全限定类名后跟 tab 分隔的注册名）：

cd /opt/tika-cli && java -jar tika-app-4.1.0.jar --list-parser-names 2>/dev/null | head -8

org.apache.tika.parser.apple.AppleSingleFileParser      apple-single-file-parser
org.apache.tika.parser.apple.PListParser        p-list-parser
org.apache.tika.parser.asm.ClassParser  class-parser
org.apache.tika.parser.audio.AudioParser        audio-parser
org.apache.tika.parser.audio.MidiParser midi-parser
org.apache.tika.parser.code.SourceCodeParser    source-code-parser
org.apache.tika.parser.crypto.Pkcs7Parser       pkcs-7-parser
org.apache.tika.parser.crypto.TSDParser tsd-parser

关于其余 22 个顶层配置块（renderers、detectors、pipes 等）：本文仅对 server 与 parsers 做了完整实测，其余块的使用方式未在 4.1.0 环境逐一验证，接入前务必先以临时端口试启动并观察启动日志。

5.3 JVM 参数

JVM 参数在 unit 文件的 Environment 行声明：

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

启动后用 jps -v 验证堆参数已随进程生效（实测回显）：

jps -v

5705 tika-server-standard-4.1.0.jar -Xms256m -Xmx512m
5802 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        5705       1  0 09:31 ?        00:00:11 /usr/bin/java -Xms256m -Xmx512m -jar /opt/tika/tika-server-standard-4.1.0.jar --host 0.0.0.0 --port 9998

调整堆大小的完整流程（以 -Xmx384m 为例）：编辑 unit 中 JAVA_OPTS，依次执行 systemctl daemon-reload 与 systemctl restart tika，再用 jps -v 确认回显已变为新值。

一个实测踩坑：用非引用的 heredoc（EOF 未加引号）写 unit 文件时，$JAVA_OPTS 会被外层 shell 提前展开为空，ExecStart 实际变成 java -jar，JVM 参数静默丢失且服务照常启动。写 unit 必须使用引号 heredoc（即小于号小于号后接带引号的 EOF），或用其他不经过变量展开的方式写入。

5.4 pipes 解析子进程

Tika 4.x 服务端启用 pipes 解析架构：主进程不再直接解析文档，而是按主机核数 fork 若干解析子进程，请求由子进程处理。启动日志关键行（实测）：

Pipes-based parsing enabled for /tika, /rmeta, /unpack, /meta, /detect, and /pipes endpoints
Using per-client server mode with 4 clients
pipes-cpu-sizing: hostCores=12, numClients=4, parentReserved=2, autoCap=slice=2, heap=MaxRAMPercentage=18

要点：

实测主机 12 核时默认 4 个解析子进程，子进程数量由主进程按主机核数自动 sizing，无需手工配置。
实际内存占用为主进程与全部子进程之和。实测 512MB 堆配置下主进程 RSS 约 290MB（systemctl status 显示 Memory 290.7M），子进程按需拉起，估算内存预算时必须把子进程一并计入。
子进程空闲超时后自动退出（日志出现 socket timeout while waiting for task, shutting down），下一个请求会按需重新拉起，这是 4.x 正常行为而非故障。
观察进程树可执行 ps -ef | grep java，主进程与子进程的命令行特征不同，便于区分。

六、生产配置模板

场景与资源建议：

场景	物理内存	磁盘	JVM 堆	说明
小型：日常文档检测	2GB	2GB 起	-Xms256m -Xmx512m	默认 4 个解析子进程，适合个人或小团队调用
中型：批量解析服务	4GB	5GB 起	-Xms256m -Xmx512m	堆保持 512MB 上限，磁盘预留解析临时文件空间，负载由 pipes 子进程分摊

unit 文件模板 /etc/systemd/system/tika.service：

[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 --config /opt/tika/tika-config.json
Restart=on-failure
RestartSec=10
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

JSON 配置模板 /opt/tika/tika-config.json：

{
  "server": { "host": "0.0.0.0", "port": 9998 },
  "parsers": ["pdf-parser", "txt-parser", "image-parser"]
}

模板说明：host 0.0.0.0 供远程调用，仅本机使用可改回 localhost；parsers 按需裁剪，注册名可用 tika-app 的 --list-parser-names 查询（见 5.2）；若需指标上报，在 ExecStart 行追加 --metricsPort 9404。修改任一配置后执行 systemctl daemon-reload 与 systemctl restart tika，并用 jps -v 与 curl http://127.0.0.1:9998/version 复核。

七、常见问题

Q1：启动报 Unknown configuration key(s)，如何处理？ 配置文件里出现了 4.x 不认识的顶层 key，例如旧版习惯写的 renderer。报错信息会列出全部 24 个合法 key，逐一对照修正拼写即可，合法 key 列表见 5.2。

Q2：启动报 Couldn't find 'server' element？ 以 -c 加载配置启动服务端时，配置文件必须包含 server 块。在 JSON 中补上 server 对象（含 host 与 port）后再启动。

Q3：配置了 parsers，服务启动正常，但请求返回 FAILED_TO_INITIALIZE？ parsers 里写了全限定类名或拼错的注册名。4.x 出于安全考虑只接受注册名（kebab-case，如 pdf-parser），且该错误延迟到首个请求才暴露。将写法改为注册名数组即可，全部注册名见启动报错日志（共 173 个）或用 tika-app 的 --list-parser-names 查询。

Q4：修改了 unit 里的 -Xmx 为什么不生效？ systemd 不感知 unit 文件的手工修改。依次执行 systemctl daemon-reload 与 systemctl restart tika，再用 jps -v 确认回显包含新参数值。另注意 heredoc 写入时 $JAVA_OPTS 被提前展开的坑（见 5.3）。

Q5：--metricsPort 开了但远程访问不到指标？ 实测指标监听绑定 localhost（日志显示 Started metrics listener on http://localhost:9404/metrics），远程机器直接访问 9404 不通属预期，可在本机用 curl http://127.0.0.1:9404/metrics 验证，再通过反向代理按需暴露。

Q6：日志出现 socket timeout while waiting for task, shutting down 是否异常？ 不是异常。这是 pipes 解析子进程空闲超时后的自动回收，下一个请求到达时会按需重新拉起子进程。

八、参考链接

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/