Apache PyLucene 配置与构建参数详解

目标：逐项讲清并实测 PyLucene 构建体系的三个配置层面——Makefile 变量、JCC 代码生成器参数、initVM 运行期 JVM 参数；并完整实测"启用可选模块 smartcn"的全程与排障。所有命令与回显均来自 PyLucene 9.12.0 在 Ubuntu 22.04 的真实构建。

一、环境信息

本章配置均在以下实测环境验证，安装过程见《Ubuntu 22.04 安装 Apache PyLucene 指南》。

python3 --version && java -version 2>&1 | head -1 && ant -version | head -1
python3 -c "import setuptools; print('setuptools', setuptools.__version__)"
python3 -c "from jcc import config; print('JCC', config.VERSION)"
python3 -c "import lucene; print('PyLucene', lucene.VERSION)"

实测输出（Ubuntu 22.04 服务器）：

Python 3.10.12
openjdk version "17.0.20.1" 2026-08-18
Apache Ant(TM) version 1.10.12 compiled on January 17 1970
setuptools 59.6.0
JCC 3.14
PyLucene 9.12.0

• 操作系统：Ubuntu 22.04（x86_64）；JDK：OpenJDK 17（/usr/lib/jvm/java-17-openjdk-amd64）
• 实测对象：PyLucene 9.12.0 源码树（/root/build/pylucene-9.12.0）、JCC 3.14
• 构建产物：lucene-9.12.0-cp310-cp310-linux_x86_64.whl，官方测试 127 用例全部通过

二、配置体系总览

PyLucene 没有统一的配置文件，配置分三层，各管一段：

三层的耦合关系（实测确认）：Makefile 把变量拼成一条 JCC 命令（可用 make -n 或构建日志看到），JCC 的 --vmarg 决定生成期 JVM 行为，而 initVM 的 vmargs 是独立的运行期 JVM 参数——两者不会互相传递，smartcn 词库属性需要两处都配（第六章实测）。

三、Makefile 关键变量逐项实测

3.1 变量全景

源码包 Makefile 针对不同平台预置了多组示例段，按注释行 # Linux (Ubuntu 22.04 ...) 格式复制一份并取消注释即可。本文实测使用的 Ubuntu 22.04 配置段：

cd /root/build/pylucene-9.12.0
grep -n -A7 "Ubuntu 22.04" Makefile

实测输出：

# Linux     (Ubuntu 22.04 64-bit, Python 3.10.12, OpenJDK 17)
PREFIX_PYTHON=/usr
ANT=/usr/bin/ant
PYTHON=$(PREFIX_PYTHON)/bin/python3
JCC=$(PYTHON) -m jcc --shared
NUM_FILES=16
MODERN_PACKAGING=true

3.2 路径类变量：PREFIX_PYTHON / PYTHON / ANT

• PREFIX_PYTHON：Python 安装前缀。Ubuntu 系统自带 Python 位于 /usr，实测 PREFIX_PYTHON=/usr 后，lucene 模块与 JCC 都装入 /usr/local/lib/python3.10/dist-packages/（prefix 派生路径）：

ls /usr/local/lib/python3.10/dist-packages/ | grep -iE "lucene|JCC"

实测输出：

JCC-3.14-py3.10-linux-x86_64.egg
lucene
lucene-9.12.0.dist-info

• PYTHON：构建用的解释器，决定生成的扩展针对哪个 Python 版本（cp310）。换 venv 时把它指到 venv 的 python3 即可，注意 PREFIX_PYTHON 与之配套。
• ANT：ant 可执行文件路径。9.x 构建链实际走 Gradle wrapper（./gradlew collectRuntimeJars），ANT 变量仅旧版本（Lucene 7/8 时代 ant jar）构建需要，当前保留只为兼容 Makefile 的历史目标，实测填 /usr/bin/ant 不参与编译。

3.3 JCC 与 NUM_FILES

• JCC：JCC 的调用方式，$(PYTHON) -m jcc --shared。--shared 要求 JCC 以共享模式安装（Linux 上 setuptools ≥ 58.3 自动启用，实测验证方法见《Ubuntu 22.04 安装 Apache PyLucene 指南》4.3 节：from jcc import config; print(config.SHARED) 输出 True）。
• NUM_FILES：JCC 把全部 Java 包装拆成多少个 C++ 源文件。Lucene 9.12 的类数量巨大，单文件编译会耗尽内存或超时，默认建议 Linux 用 16。实测 make all 日志中可见拆分结果（16 个 __wrap*.cpp 分片并行编译）：

ls build/temp.linux-x86_64-3.10/build/_lucene/ | head -6

实测输出：

__wrap01__.o  __wrap02__.o  __wrap03__.o  __wrap04__.o  __wrap05__.o  __wrap06__.o

• MODERN_PACKAGING：setuptools ≥ 58.3.0 必须设为 true。实测影响：开启后 compile 目标改为 $(PYTHON) -m build -nw 产出 wheel、install 目标改为 $(PYTHON) -m pip install dist/lucene-9.12.0-*.whl --force-reinstall（现代 PEP-517 流程）；不开则走旧的 setup.py install 分支，在新 setuptools 上会失败。

3.4 JARS：打包模块清单（最重要的一组变量）

JARS 变量决定把哪些 Lucene 运行时 jar 交给 JCC 包装。源码包默认启用 23 行（含 core），smartcn 与 phonetic 默认被注释。实测查看：

grep -n "JARS" Makefile | head -8
sed -n '106,131p' Makefile

实测输出（节选）：

JARS = $(LUCENE_JAR)
JARS+=$(ANALYSIS_JAR)           # multilingual analyzer module
JARS+=$(BACKWARD_CODECS_JAR)
JARS+=$(CLASSIFICATION_JAR)
JARS+=$(CODECS_JAR)
...
JARS+=$(SMARTCN_JAR)            # smart chinese analyzer（本文实测已启用）
#JARS+=$(PHONETIC_JAR)          # phonetic analyzer module（默认注释）

每个 jar 变量对应源码树里的 Gradle 产物路径，例如：

grep -n "SMARTCN_JAR=\|SPATIAL_EXTRAS_JAR=" Makefile

实测输出：

SMARTCN_JAR=$(LUCENE)/analysis/smartcn/build/runtimeJars/lucene-analysis-smartcn-$(LUCENE_VER)-SNAPSHOT.jar
SPATIAL_EXTRAS_JAR=$(LUCENE)/spatial-extras/build/runtimeJars/lucene-spatial-extras-$(LUCENE_VER)-SNAPSHOT.jar

启用/停用模块就是增删这些 JARS+= 行，改完 make all 重新生成安装。默认清单里 24 个 --jar（core + 23 个模块）外加 ANTLR/ASM 3 个 --include，可通过构建日志核对：

grep -m1 "python3 -m jcc --shared" /root/make_all.log | grep -o "\-\-jar " | wc -l

实测输出：

24

💡 技术拓展：为什么 JCC 需要 --include 与 --jar 两种参数——

参数	语义	典型用法
--jar	把 jar 里的类包装成 Python 类	Lucene 各模块 jar
--include	jar 只进 classpath/发行物，不包装类	依赖库（ANTLR、ASM、spatial4j）

Makefile 的 GENERATE 变量里 --include $(ANTLR_JAR) $(ASM_JAR) $(ASM_COMMONS) 就是让查询解析依赖进 classpath 但不暴露给 Python。

3.5 JCCFLAGS：给 JCC 的 JVM 传参

Makefile 预留了 JCCFLAGS 变量（GENERATE=$(JCC) $(foreach jar,$(JARS),--jar $(jar)) $(JCCFLAGS) ...），可以在不改 Makefile 的情况下给生成期 JVM 附加参数。实测最典型的用途就是 smartcn 词库属性（第六章），命令形如：

make all JCCFLAGS="--vmarg -Danalysis.data.dir=/root/analysis-data"

3.6 其他实用变量

• ICUSBIN / ICU：可选 ICU 分析器支持。Makefile 中有条件块，未设置时输出 ICU not installed 并跳过（实测默认构建日志含此行，属正常现象）。
• DEBUG：设为 true 时 C++ 编译带 -g 调试符号，排查 JCC 段错误时使用。
• VERSION / LUCENE_VER：PyLucene 与 Lucene 版本号，均为 9.12.0，生成物命名 lucene-9.12.0 与其一致。

四、JCC 参数逐项实测

4.1 参数全景

JCC 的参数体系可用 help 查看，本文把构建 PyLucene 用到的参数按功能分组逐一实测（完整 help 见《Apache PyLucene 常用 CLI 命令与工具详解》）：

python3 -m jcc --help | grep -E "^  --jar|^  --include|^  --python|^  --version|^  --shared|^  --files|^  --use_full_names|^  --vmarg" | head -10

实测输出：

  --jar PATH: add PATH to the classpath and wrap all classes in the jar
  --include PATH: add PATH to the classpath and include all contents in the extension
  --python PYTHON: python package name for the extension (module name)
  --version VERSION: version of the extension (module version)
  --shared: build the extension in shared mode
  --files N: number of modules to split the generated C++ sources into
  --use_full_names: preserve java packages as-is in python package hierarchy
  --vmarg JAVAARG: java vm argument (used at build time only)

4.2 输入类参数：--jar / --include / --package / --classpath

• --jar PATH：包装指定 jar 的全部类。可重复出现，PyLucene 构建实际传了 24 个（见 3.4 节统计）。jar 内的 public 类默认全部暴露。
• --include PATH：依赖进 classpath 与发行物但不包装。实测构建中用于 ANTLR/ASM。
• --exclude CLASS：显式不包装指定类（help 原文 "explicitly don't wrap CLASS"）。官方构建实测传了 5 个：module-info（Lucene 9 jar 是 JPMS 模块化 jar，模块描述符不是普通类，不排除则 JCC 装载报 NoClassDefFoundError: module-info is not a class because access_flag ACC_MODULE is set）与 4 个 Windows 专有类。
• --package PACKAGE：把 PACKAGE 加入"自动包装依赖类"的包列表（补充默认的 java.lang，help 原文 "add PACKAGE to the list of packages from which dependencies are automatically wrapped"），不是包重命名。
• --classpath：追加纯 classpath 条目（不进入发行物），实测构建未使用。

4.3 生成物类参数：--python / --version / --files / --use_full_names

--python lucene 决定 import 名，--version 9.12.0 决定模块版本与 wheel 文件名，--files 16 决定 C++ 分片数，--shared 生成共享 libjcc 运行时。官方构建实际命令行（取自构建日志）还携带三组协议/模块参数，逐一实测核实：

grep -m1 "python3 -m jcc --shared" /root/make_all_smartcn3.log | grep -oE -- "--(mapping|sequence|module|use_full_names) [^ ]*"

实测输出：

--mapping org.apache.lucene.document.Document
--mapping java.util.Properties
--sequence java.util.AbstractCollection
--sequence java.util.AbstractList
--module python/collections.py
--module python/ICUNormalizer2Filter.py
--module python/ICUFoldingFilter.py
--module python/ICUTransformFilter.py
--use_full_names

• --mapping CLASS SIG1 SIG2：为指定类生成 Python 映射（dict 风格）协议包装，官方用于 Document 与 Properties；
• --sequence CLASS SIG：生成 Python 序列协议包装，官方用于 AbstractCollection/AbstractList（这就是 for hit in hits.scoreDocs 能直接迭代的来源）；
• --module MODULE：把源码包 python/ 下的补充模块（collections.py 与 ICU 三个）打进发行物；
• --use_full_names：保留 Java 完整类名层级；实测发现它还承担化解跨 jar 同名类冲突的作用——去掉该参数用手动 jcc 包装 smartcn 相关 jar 时，org.apache.lucene.analysis.id.IndonesianStemmer 与 org.tartarus.snowball.ext.IndonesianStemmer 会报 ValueError: python class name already in use, use --rename（完整失败实录见《Apache PyLucene 常用 CLI 命令与工具详解》§2.7）。

实测产物可核对：

ls -la /root/build/pylucene-9.12.0/dist/

实测输出：

-rw-r--r-- 1 root root 45941427 Oct 16 04:53 lucene-9.12.0-cp310-cp310-linux_x86_64.whl

文件名四段信息与参数一一对应：lucene（--python）9.12.0（--version）cp310（PYTHON 指向的解释器）linux_x86_64（构建平台）。

4.4 动作类参数：--generate / --build / --compile / --install / --bdist

JCC 支持分阶段执行：--generate 只生成源码、--build 生成+编译、--compile 等价 build、--install 编译并安装、--bdist 生成 distutils 二进制发行包。Makefile 正是利用 --generate 先产出 setup.py，再用 python3 -m build -nw 打包。手动分阶段实测（以 smartcn + core + analysis-common 三 jar 为例，完整命令与逐步排障实录见《Apache PyLucene 常用 CLI 命令与工具详解》§2.2/§2.7）：

cd /tmp && python3 -m jcc --vmarg -Danalysis.data.dir=/root/analysis-data \
  --jar $L/analysis/smartcn/build/runtimeJars/lucene-analysis-smartcn-9.12.0-SNAPSHOT.jar \
  --jar $L/core/build/runtimeJars/lucene-core-9.12.0-SNAPSHOT.jar \
  --jar $L/analysis/common/build/runtimeJars/lucene-analysis-common-9.12.0-SNAPSHOT.jar \
  --exclude module-info --use_full_names --python cnlib --version 1.0 --generate
ls

实测输出：

build
setup.py

注意实测教训：只传 smartcn 单个 jar 时 --generate 必然失败（NoClassDefFoundError: org.apache.lucene.analysis.Analyzer，缺 core 依赖），跨 jar 依赖必须完整传入。

4.5 JVM 类参数：--vmarg / --maxheap

--vmarg JAVAARG 给 JCC 自身启动的 JVM 传系统属性/参数（仅生成期生效，不带入运行期），--maxheap N 设生成期 JVM 堆上限。实测 smartcn 词库属性传入后包装成功（对比不传时失败，见第六章）：

python3 -m jcc --vmarg -Danalysis.data.dir=/root/analysis-data --jar .../lucene-analysis-smartcn-9.12.0-SNAPSHOT.jar --python lucenetest --version 9.12.0 --generate

实测输出（节选，不再报词库异常，仅剩预期中的缺 core 依赖）：

While loading org.apache.lucene.analysis.cn.smart.SmartChineseAnalyzer:
  java.lang.NoClassDefFoundError: org/apache/lucene/analysis/Analyzer

4.6 JCC 安装后的固化配置：jcc/config.py

JCC 安装时把 JDK 路径、shared 开关等固化进 config.py，运行 jcc 命令时读取：

python3 -c "from jcc import config; print('VERSION:', config.VERSION); print('SHARED:', config.SHARED); print('LFLAGS:', config.LFLAGS)"

实测输出：

VERSION: 3.14
SHARED: True
LFLAGS: ['-L/usr/lib/jvm/java-17-openjdk-amd64/lib', '-ljava', '-L/usr/lib/jvm/java-17-openjdk-amd64/lib/server', '-ljvm', '-Wl,-rpath=/usr/lib/jvm/java-17-openjdk-amd64/lib:/usr/lib/jvm/java-17-openjdk-amd64/lib/server']

换 JDK 时除了重编 PyLucene，JCC 本身也要按新 JDK 重新安装（config.py 的 LFLAGS/rpath 会更新），否则运行期加载 libjvm.so 失败。

五、initVM 运行期 JVM 参数实测

5.1 堆内存：-Xmx

JVM 与 Python 进程同住，堆内存用 initVM 的 vmargs 控制，实测 256MB 参数生效：

python3 -c "
import lucene
lucene.initVM(vmargs=['-Xmx256m'])
from java.lang import Runtime
print('maxMemory(MB):', int(Runtime.getRuntime().maxMemory()/1024/1024))
"

实测输出（默认构建环境）：

maxMemory(MB): 256

生产建议：嵌入式场景 JVM 堆不必给大（索引 I/O 大多走堆外内存映射），256-512MB 起步按索引规模调；JVM 只能初始化一次，vmargs 只有第一次 initVM 生效。

5.2 系统属性：-D（smartcn 词库）

initVM 的 vmargs 可传任意 JVM 系统属性。实测 smartcn 场景必须传词库属性，否则任何触发类解析的操作都会抛 ExceptionInInitializerError（含读取 lucene.CLASSPATH 这种看似无关的操作——JCC 生成的模块在解析类引用时就会触发 AnalyzerProfile 静态初始化，真实堆栈见第六章）：

python3 -c "
import lucene
lucene.initVM(vmargs=['-Xmx256m', '-Danalysis.data.dir=/root/analysis-data'])
cp = lucene.CLASSPATH
entries = cp.split(':')
print('CLASSPATH entries:', len(entries))
print('entry0:', entries[0].split('/')[-1])
print('entry-1:', entries[-1].split('/')[-1])
"

实测输出（smartcn 构建环境）：

CLASSPATH entries: 26
entry0: lucene-core-9.12.0-SNAPSHOT.jar
entry-1: asm-commons-7.2.jar

26 个 classpath 条目 = 24 个 Lucene jar + ANTLR + ASM 两个 --include 依赖，与构建参数完全对应。

5.3 运行期扩展 classpath 的真实结论：不可行

老版本 PyLucene 文档曾提供 lucene.addClasspath() 运行期扩展 classpath 的用法，在新版 JCC（3.14）生成的模块中已不存在，实测调用直接报 AttributeError：

python3 -c "
import lucene
lucene.initVM(vmargs=['-Xmx256m', '-Danalysis.data.dir=/root/analysis-data'])
lucene.addClasspath('/root/build/pylucene-9.12.0/lucene-java-9.12.0/lucene/test-framework/build/runtimeJars/lucene-test-framework-9.12.0-SNAPSHOT.jar')
"

实测输出：

Traceback (most recent call last):
  File "<string>", line 4, in <module>
AttributeError: module 'lucene' has no attribute 'addClasspath'

尝试绕过 JCC 机制、直接在 vmargs 里传 -Djava.class.path 更危险——实测直接触发 JVM 段错误崩溃（JCC 生成模块用自身机制构造 classpath，与该系统属性冲突）：

python3 -c "
import lucene
lucene.initVM(vmargs=['-Xmx256m', '-Djava.class.path=/root/build/pylucene-9.12.0/lucene-java-9.12.0/lucene/test-framework/build/runtimeJars/lucene-test-framework-9.12.0-SNAPSHOT.jar'])
print('initVM with -Djava.class.path OK')
"

实测输出（进程崩溃，无任何 Python 输出）：

# A fatal error has been detected by the Java Runtime Environment:
#
#  SIGSEGV (0xb) at pc=0x000073e1da923b94, pid=10002, tid=10002
#
# JRE version: OpenJDK Runtime Environment (17.0.20.1+1) (build 17.0.20.1+1-1-22.04-Ubuntu)
# Java VM: OpenJDK 64-Bit Server VM (17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing, tiered, compressed oops, compressed class ptrs, g1 gc, linux-amd64)
# Problematic frame:
# V  [libjvm.so+0x28cb94]  AccessInternal::PostRuntimeDispatch<...>::oop_access_barrier(void*)+0x4

实测结论：未包装的 Java 类在运行期无法导入（模块顶层可用 API 仅 JArray 与 initVM 系列，实测 dir(lucene) 无 JClass/JPackage/addClasspath）；要使用非默认模块，唯一正确途径是构建期把模块加进 Makefile 的 JARS 后 make all 重建（见第六章）。运行期 vmargs 只用于堆内存与普通系统属性（如 5.2 节词库属性），不要传 classpath 类参数。

六、可选模块启用实测：smartcn 全程记录

smartcn（中文分词）默认未打包。从启用到跑通共踩三个真实坑，全程实录如下，可作为其它可选模块的启用模板。

第一步：取消 Makefile 注释并重建（失败 A：误启用多行）

cd /root/build/pylucene-9.12.0
sed -i 's|^#JARS+=|JARS+=|' Makefile   # ⚠️ 危险写法：会把所有注释的 JARS 行全部启用
make all

实测报错（关键行）：

jcc.cpp.JavaError: java.lang.NoClassDefFoundError: org/locationtech/spatial4j/shape/ShapeFactory
Caused by: java.lang.ClassNotFoundException: org.locationtech.spatial4j.shape.ShapeFactory
    While loading org.apache.lucene.spatial.prefix.tree.S2ShapeFactory
make: *** [Makefile:284: setup.py] Error 1

原因：一并启用的 SPATIAL_EXTRAS_JAR 依赖外部库 spatial4j-0.8.jar，它只进了发行物没进 JCC 的包装 classpath，装载 spatial-extras 的类时找不到（官方默认注释该行）。实测结论：只启用需要的模块行，不要批量取消注释。

第二步：精确启用 smartcn 后重建（失败 B：词库目录缺失）

sed -i 's|^JARS+=\$(SPATIAL_EXTRAS_JAR)|#JARS+=$(SPATIAL_EXTRAS_JAR)|' Makefile
make all

实测报错（关键行）：

jcc.cpp.JavaError: java.lang.ExceptionInInitializerError
Caused by: java.lang.RuntimeException: WARNING: Can not find lexical dictionary directory! ...
        at org.apache.lucene.analysis.cn.smart.AnalyzerProfile.init(AnalyzerProfile.java:71)
        at org.apache.lucene.analysis.cn.smart.AnalyzerProfile.<clinit>(AnalyzerProfile.java:40)
make: *** [Makefile:284: setup.py] Error 1

原因：JCC 包装阶段装载 AnalyzerProfile，其静态初始化在当前目录找不到 analysis-data 目录就抛异常。词库主数据其实已内嵌在 smartcn jar 里（classpath 加载 coredict.mem/bigramdict.mem），只需让属性检查通过。

第三步：JCCFLAGS 传词库属性（成功）

mkdir -p /root/analysis-data
make all JCCFLAGS="--vmarg -Danalysis.data.dir=/root/analysis-data"

实测输出（结尾）：

build of pylucene 9.12.0 complete

第四步：运行期同样传属性（必配）

运行期不传属性时，initVM/读 CLASSPATH 都会触发同样的 AnalyzerProfile 异常（真实堆栈与 5.2 节 CLASSPATH 实测同源）。运行期配置后一切正常：

python3 -c "
import lucene
lucene.initVM(vmargs=['-Xmx256m', '-Danalysis.data.dir=/root/analysis-data'])
from org.apache.lucene.analysis.cn.smart import SmartChineseAnalyzer
from org.apache.lucene.analysis.tokenattributes import CharTermAttribute
a = SmartChineseAnalyzer()
ts = a.tokenStream('body', 'PyLucene 让 Python 直接调用 Lucene 的全文检索能力')
ts.reset()
words = []
while ts.incrementToken():
    words.append(ts.getAttribute(CharTermAttribute.class_).toString())
print('分词结果:', words)
"

实测输出：

分词结果: ['pylucen', '让', 'python', '直接', '调用', 'lucen', '的', '全文', '检索', '能力']

💡 说明：pylucene→pylucen、lucene→lucen 是 smartcn 内置英文词干化规则的真实行为，非异常。其它可选模块（kuromoji/nori/stempel 等已默认启用）无此词库检查问题，phonetic 启用方法与 smartcn 第一步相同（取消注释后 make all），实测无附加要求。

七、常见问题（FAQ）

Q1：改了 Makefile 变量后 make 没有生效？ JARS 增删、NUM_FILES 变更都影响生成物，直接 make all 会触发 setup.py 目标重新生成；但产物目录里残留旧文件时建议 rm -rf build dist 后再构建（实测该顺序最干净）。

Q2：怎么确认我启用的模块真的进了包装？ 构建日志里数 --jar（grep -m1 'python3 -m jcc' build 日志 | grep -o -- '--jar ' | wc -l），或安装后直接 from org.apache.lucene.analysis.cn.smart import SmartChineseAnalyzer——能 import 即已包装。

Q3：PREFIX_PYTHON 指到 venv 后 make 报找不到模块？ venv 里要装齐 setuptools/wheel/build，且 PYTHON=$(VENV)/bin/python3 必须与 PREFIX_PYTHON 配套；JCC 是按解释器版本编译的，换 venv 后 JCC 与 PyLucene 都要重建。

Q4：initVM 传了 -Danalysis.data.dir 但仍报 ExceptionInInitializerError？ JVM 只初始化一次：同一进程里若有代码先 initVM 且未带该属性，后补无效。确保进程内第一次 initVM 就带上；多线程场景用 with lucene.attachThread():，属性在主线程初始化时确定。

Q5：ICU not installed 是报错吗？ 不是。ICU 分析器属可选增强，未设置 ICUSBIN 时 Makefile 输出该提示并跳过其资源处理，构建不受影响（实测默认构建日志含此行且最终 build complete）。

八、参考链接

• PyLucene 官方构建文档：https://lucene.apache.org/pylucene/install.html
• JCC 项目主页与参数说明：https://lucene.apache.org/pylucene/jcc/
• JCC 源码内 INSTALL 文档（shared 模式说明）
• 安装主线流程：《Ubuntu 22.04 安装 Apache PyLucene 指南》
• jcc 命令与检索实操：《Apache PyLucene 常用 CLI 命令与工具详解》