Hibernate Search 6.x：Lucene索引目录只读配置及JIB权限设置

需求背景 #

需要在构建阶段生成Lucene索引，通过Hibernate Search提供自动补全API，无需动态生成或更新索引，仅基于预先生成并复制的索引提供查询服务。

当前配置问题 #

使用Hibernate Search 6.x及以上版本，目前没有直接将Lucene索引目录设为只读的官方配置。当前persistence.xml中的Hibernate Search配置如下：

<property name="hibernate.search.backend.directory.type" value="local-filesystem"/>
<property name="hibernate.search.backend.directory.root" value="${LUCENE_INDEX_DIR}"/>
<property name="hibernate.search.mapping.build_missing_discovered_jandex_indexes" value="false"/>
<property name="hibernate.search.backend.lucene_version" value="8.11.2"/>
<property name="hibernate.search.schema_management.strategy" value="none"/>
<property name="hibernate.search.backend.directory.locking.strategy" value="none"/>

原本设置locking.strategy为none期望实现只读目录运行，但未生效。

索引生成流程 #

已通过批量索引生成索引，并在构建流水线中将整个索引目录发布到Maven：

SearchSession searchSession = Search.session(
        HibernateUtil.getEntityManagerFactory().createEntityManager());
MassIndexer indexer = searchSession.massIndexer().purgeAllOnStart(true);

部署时会下载索引并作为Docker镜像的一部分复制到容器文件系统，目前需将该目录设为可写才能正常运行。现切换到Quarkus+JIB构建Docker镜像，需要以下任一解决方案：

解决方案1：让Lucene后端适配只读索引目录 #

通过组合配置实现只读模式：

• 保持schema_management.strategy为none，避免Hibernate Search尝试修改索引结构
• 添加配置hibernate.search.automatic_indexing.enabled=false，彻底关闭自动索引更新逻辑
• 自定义目录提供者，使用Lucene的SimpleFSDirectory（无需写入权限）：
  创建自定义目录提供者类：

  public class ReadOnlyLocalDirectoryProvider implements DirectoryProvider {
      @Override
      public Directory createDirectory(DirectoryInitializationContext context) {
          Path root = context.root();
          try {
              return SimpleFSDirectory.open(root);
          } catch (IOException e) {
              throw new RuntimeException("Failed to open read-only Lucene directory", e);
          }
      }
  }
  

  在persistence.xml中配置使用自定义提供者：

  <property name="hibernate.search.backend.directory.type" value="custom"/>
  <property name="hibernate.search.backend.directory.custom.type" value="com.yourpackage.ReadOnlyLocalDirectoryProvider"/>
  

• 保留locking.strategy为none，避免Lucene尝试创建锁文件

解决方案2：通过JIB设置容器文件夹权限 #

如果需要控制容器内索引目录的权限，可在JIB配置中指定：

Maven JIB插件配置 #

在pom.xml的JIB插件中添加目录权限配置：

<plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>jib-maven-plugin</artifactId>
    <version>3.4.0</version>
    <configuration>
        <from>
            <image>quay.io/quarkus/quarkus-jvm:2.16.6.Final</image>
        </from>
        <to>
            <image>your-image-name</image>
        </to>
        <extraDirectories>
            <paths>
                <path>
                    <from>path/to/your/lucene-index</from>
                    <into>/path/in/container</into>
                    <permissions>
                        <directory>0555</directory> <!-- 目录只读，所有者可读可执行 -->
                        <file>0444</file> <!-- 文件只读 -->
                    </permissions>
                </path>
            </paths>
        </extraDirectories>
    </configuration>
</plugin>

Gradle JIB插件配置 #

在build.gradle中配置：

jib {
    from {
        image = 'quay.io/quarkus/quarkus-jvm:2.16.6.Final'
    }
    to {
        image = 'your-image-name'
    }
    extraDirectories {
        paths {
            path {
                from = file('path/to/your/lucene-index')
                into = '/path/in/container'
                permissions {
                    directory = '0555'
                    file = '0444'
                }
            }
        }
    }
}

Quarkus JIB扩展配置 #

在application.properties中配置：

quarkus.jib.extra-directories.paths[0].from=path/to/your/lucene-index
quarkus.jib.extra-directories.paths[0].into=/path/in/container
quarkus.jib.extra-directories.paths[0].permissions.directory=0555
quarkus.jib.extra-directories.paths[0].permissions.file=0444

内容的提问来源于stack exchange，提问作者Rahul sivasankaran