제17회: 플러그인으로 검색 확장하기 – 커스텀 데이터 소스와 Ingest 파이프라인 구현

들어가며

Fess는 기본적으로 많은 데이터 소스를 지원하지만, 기업 고유의 시스템이나 데이터 형식에 대응하려면 플러그인을 통한 확장이 필요할 수 있습니다.

이 글에서는 Fess의 플러그인 아키텍처를 설명하고, 커스텀 데이터 소스 플러그인과 Ingest 플러그인의 구현 방법을 소개합니다.

대상 독자

  • Fess를 독자적인 데이터 소스에 연결하고 싶은 분

  • 플러그인 개발에 관심이 있는 Java 개발자

  • Fess의 내부 아키텍처를 이해하고 싶은 분

플러그인 아키텍처

Fess에는 다음과 같은 종류의 플러그인이 있습니다.

플러그인 종류
종류 역할 예시
데이터 스토어 (fess-ds-*) 외부 데이터 소스에서 데이터 가져오기 Slack, Salesforce, DB
Ingest (fess-ingest-*) 크롤링 데이터의 가공 및 변환 Example
테마 (fess-theme-*) 검색 화면 디자인 Simple, Code Search
스크립트 (fess-script-*) 스크립트 언어 지원 OGNL
웹 앱 (fess-webapp-*) 웹 애플리케이션 확장 MCP Server

플러그인 배치

플러그인은 JAR 파일로 제공되며 Fess의 플러그인 디렉토리에 배치됩니다. 관리 화면의 [시스템] > [플러그인]에서 설치 및 관리할 수 있습니다.

커스텀 데이터 소스 플러그인 개발

사내에 독자적인 문서 관리 시스템이 있는 경우를 가정하여, 데이터 소스 플러그인의 개발 절차를 설명합니다.

프로젝트 구성

기존 데이터 스토어 플러그인(예: fess-ds-git)을 참고하여 Maven 프로젝트를 생성합니다.

fess-ds-custom/
├── pom.xml
└── src/
    └── main/
        └── java/
            └── org/codelibs/fess/ds/custom/
                └── CustomDataStore.java

pom.xml 설정

fess-parent를 부모 POM으로 지정하고 필요한 의존성을 설정합니다.

<parent>
    <groupId>org.codelibs.fess</groupId>
    <artifactId>fess-parent</artifactId>
    <version>15.5.0</version>
</parent>

<artifactId>fess-ds-custom</artifactId>
<packaging>jar</packaging>

<dependencies>
    <dependency>
        <groupId>org.codelibs.fess</groupId>
        <artifactId>fess</artifactId>
        <version>${fess.version}</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

데이터 스토어 클래스 구현

데이터 스토어 플러그인의 핵심은 데이터를 가져와서 Fess에 문서를 등록하는 클래스입니다.

구현의 핵심 포인트는 다음과 같습니다.

  1. 외부 시스템에 대한 연결 및 인증

  2. 데이터 가져오기(API 호출, 파일 읽기 등)

  3. 가져온 데이터를 Fess의 문서 형식으로 변환

  4. 문서 등록

필드 매핑

가져온 데이터를 Fess의 필드에 매핑합니다. 주요 필드는 다음과 같습니다.

  • title: 문서 제목

  • url: 문서 URL(검색 결과의 링크 대상)

  • content: 문서 본문(검색 대상)

  • mimetype: MIME 타입

  • last_modified: 최종 수정 일시

빌드 및 배포

$ mvn clean package

생성된 JAR 파일을 Fess의 플러그인 디렉토리에 배치하고 Fess를 재시작합니다.

Ingest 플러그인 개발

Ingest 플러그인은 크롤링으로 가져온 문서를 인덱스에 등록하기 전에 가공 및 변환하는 메커니즘입니다.

활용 사례

  • 크롤링한 문서에 추가 필드 부여

  • 본문 텍스트 클렌징(불필요한 문자 제거)

  • 외부 API를 사용한 정보 부가(번역, 분류 등)

  • 로그 출력(디버깅용)

구현 포인트

Ingest 플러그인에서는 문서가 인덱스에 등록되기 직전의 데이터에 접근하여 변환 처리를 수행합니다.

예를 들어, 모든 문서에 조직명 메타데이터를 추가하는 처리나 본문에서 특정 패턴을 제거하는 처리 등을 구현할 수 있습니다.

테마 플러그인 개발

검색 화면의 디자인을 완전히 커스터마이즈하고 싶은 경우에는 테마 플러그인을 개발합니다.

테마 구성

테마 플러그인은 JSP 파일, CSS, JavaScript, 이미지 파일로 구성됩니다.

fess-theme-custom/
├── pom.xml
└── src/
    └── main/
        └── resources/
            ├── css/
            ├── js/
            ├── images/
            └── view/
                ├── index.jsp
                ├── search.jsp
                └── header.jsp

기존 테마를 참고하면서 JSP와 CSS를 수정하여 커스텀 디자인을 구현합니다.

개발 모범 사례

기존 플러그인 참고

새로운 플러그인을 개발할 때는 기존 플러그인의 소스 코드를 참고하는 것을 강력히 권장합니다. CodeLibs의 GitHub 리포지토리에서 모든 플러그인의 소스 코드가 공개되어 있습니다.

예를 들어, 데이터 스토어 플러그인 개발에는 fess-ds-git 이나 fess-ds-slack 이 좋은 참고가 됩니다.

테스트

플러그인 테스트는 다음 관점에서 수행합니다.

  • 외부 시스템에 대한 연결 테스트

  • 데이터 변환의 정확성

  • 오류 처리(연결 실패, 데이터 이상 등)

  • 성능(대량 데이터 처리 시간)

버전 호환성

Fess 버전 업그레이드 시 플러그인의 호환성을 확인하십시오. Fess의 메이저 버전 업그레이드 시에는 API 변경이 있을 수 있습니다.

정리

이 글에서는 Fess의 플러그인 개발에 대해 설명했습니다.

  • 플러그인 아키텍처 개요(데이터 스토어, Ingest, 테마, 스크립트)

  • 커스텀 데이터 소스 플러그인의 개발 절차

  • Ingest 플러그인을 통한 문서 가공

  • 테마 플러그인을 통한 UI 커스터마이즈

  • 개발 모범 사례

플러그인을 통해 Fess를 조직 고유의 요구 사항에 맞게 확장할 수 있습니다. 아키텍처 및 스케일링 편은 여기까지입니다. 다음 회부터는 AI 및 차세대 검색 편으로서 시맨틱 검색의 기초를 다룹니다.

참고 자료