업그레이드 절차

이 페이지에서는 Fess 를 이전 버전에서 최신 버전으로 업그레이드하는 절차에 대해 설명합니다.

경고

업그레이드 전 중요한 주의사항

• 업그레이드 전에 반드시 백업을 취득하십시오

• 테스트 환경에서 사전에 업그레이드를 검증할 것을 강력히 권장합니다

• 업그레이드 중에는 서비스가 중지되므로 적절한 유지보수 시간을 설정하십시오

• 버전에 따라 설정 파일 형식이 변경된 경우가 있습니다

대응 버전

이 업그레이드 절차는 다음 버전 간의 업그레이드에 대응합니다:

• Fess 14.x → Fess 15.9

• Fess 15.x → Fess 15.9

중요

Fess 14.x는 OpenSearch 2.x 계열, Fess 15.9은 OpenSearch 3.8.0에 대응합니다. Fess 용 OpenSearch 플러그인은 OpenSearch 버전과 완전히 일치해야 하므로, 14.x에서 업그레이드하는 경우 OpenSearch의 메이저 버전 업그레이드도 필수입니다. 단계 4: OpenSearch 업그레이드 를 참조하십시오.

참고

더 오래된 버전(13.x 이전)에서 업그레이드하는 경우 단계적 업그레이드가 필요할 수 있습니다. 자세한 내용은 릴리스 노트를 확인하십시오.

업그레이드 전 준비

버전 호환성 확인

업그레이드 대상 버전과 현재 버전의 호환성을 확인하십시오.

• 릴리스 노트

• 시스템 요구사항 - Fess 15.9의 동작 환경(Java, OpenSearch 버전)

다운타임 계획

업그레이드 작업에는 시스템 중지가 필요합니다. 다음을 고려하여 다운타임을 계획하십시오:

• 백업 시간: 10분 ~ 수 시간(데이터 양에 따라)

• 업그레이드 시간: 10 ~ 30분

• 동작 확인 시간: 30분 ~ 1시간

• 예비 시간: 30분

권장 유지보수 시간: 총 2 ~ 4시간

단계 1: 데이터 백업

업그레이드 전에 모든 데이터를 백업하십시오.

설정 데이터 백업

1. 관리 화면에서 백업

   관리 화면에 로그인하여 「시스템 정보」→「백업」을 클릭합니다.

   백업 페이지에는 다음 설정 데이터가 항목별로 목록 표시됩니다. 각 행을 클릭하여 다운로드합니다(단일 ZIP 파일이 아니라 항목별 개별 파일입니다. 일괄 다운로드 기능은 없으므로 필요한 항목을 하나씩 다운로드합니다).

   • fess_basic_config.bulk - 설정 인덱스(크롤 설정, 스케줄러, 레이블, 키 매치, 역할, 웹/파일 인증 등 19개 인덱스)

   • fess_config.bulk - 위 19개 인덱스에 더해 크롤 정보, 장애 URL, 작업 로그, 썸네일 큐 등 실행 시 데이터를 포함하는 25개 인덱스

   • fess_user.bulk - 사용자, 역할, 그룹

   • system.properties - 전반 설정을 포함하는 시스템 설정

   • fess.json - 인덱스 설정(샤드 수, index.knn 등)

   • doc.json - 문서 매핑(필드 정의)

   참고

   fess_config.bulk 는 fess_basic_config.bulk 를 포함합니다. 업그레이드 전 설정 백업으로는 fess_basic_config.bulk, fess_user.bulk, system.properties 3개면 충분합니다.

   참고

   검색 로그나 클릭 로그 등의 로그 데이터(search_log.ndjson, click_log.ndjson, favorite_log.ndjson, user_info.ndjson)도 같은 페이지에서 다운로드할 수 있습니다. 설정만 백업하는 경우에는 불필요합니다. 또한 이 *.ndjson 파일들은 백업 페이지에서 업로드하여 복원할 수 없습니다 (「롤백 절차」 참조).

2. 설정 파일 백업

   ZIP 버전:

   $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/
   $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/
   $ cp /path/to/fess/bin/fess.in.sh /backup/
   

   RPM 버전:

   $ sudo cp /etc/fess/system.properties /backup/
   $ sudo cp /etc/fess/fess_config.properties /backup/
   $ sudo cp /etc/sysconfig/fess /backup/
   

   DEB 버전:

   $ sudo cp /etc/fess/system.properties /backup/
   $ sudo cp /etc/fess/fess_config.properties /backup/
   $ sudo cp /etc/default/fess /backup/
   

   참고

   /etc/sysconfig/fess (RPM 버전)와 /etc/default/fess (DEB 버전)는 FESS_PORT, FESS_HEAP_SIZE, SEARCH_ENGINE_HTTP_URL, FESS_DICTIONARY_PATH 등을 지정하는 환경 변수 파일입니다. ZIP 버전에서 이에 해당하는 설정은 bin/fess.in.sh 에 있습니다.

3. 커스터마이징한 설정 파일

   커스터마이징한 설정 파일이 있는 경우 해당 파일도 백업합니다:

   $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/
   

   참고

   app/WEB-INF/classes/log4j2.xml 은 Fess 본체(Web) 프로세스의 로그 설정입니다. 크롤러 등의 자식 프로세스는 별도의 파일 (app/WEB-INF/env/crawler/resources/log4j2.xml 등 crawler, suggest, thumbnail, chunk 총 4개)을 사용하므로, 이를 변경한 경우에는 함께 백업하십시오.

인덱스 데이터 백업

OpenSearch의 인덱스 데이터를 백업합니다.

방법 1: 스냅샷 기능 사용(권장)

OpenSearch의 스냅샷 기능을 사용하여 인덱스를 백업합니다.

참고

파일 시스템 리포지토리(fs)를 등록하려면 사전에 OpenSearch의 opensearch.yml 의 path.repo 에 백업 대상 디렉터리를 지정하고 OpenSearch를 재시작해 두어야 합니다.

1. 리포지토리 설정:

   $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d'
   {
     "type": "fs",
     "settings": {
       "location": "/backup/opensearch/snapshots"
     }
   }'
   

2. 스냅샷 생성:

   $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true"
   

3. 스냅샷 확인:

   $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1"
   

방법 2: 디렉터리별 백업

OpenSearch를 중지한 후 데이터 디렉터리를 백업합니다.

$ sudo systemctl stop opensearch
$ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data
$ sudo systemctl start opensearch

Docker 버전 백업

OpenSearch의 데이터는 Docker 볼륨에 저장됩니다. compose-opensearch3.yaml 에는 인덱스 데이터용 search01_data 와 사전 파일용 search01_dictionary 의 2개 볼륨이 정의되어 있습니다.

참고

실제 볼륨 이름에는 Compose 프로젝트 이름(기본값은 Compose 파일을 배치한 디렉터리 이름)이 접두사로 부여됩니다. 정확한 이름은 다음 명령으로 확인하십시오:

$ docker volume ls

컨테이너를 중지한 후 볼륨을 백업합니다. docker run 의 -v 에는 접두사를 포함한 실제 볼륨 이름을 지정합니다:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml stop
$ PROJECT=$(basename "$(pwd)")
$ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data
$ docker run --rm -v ${PROJECT}_search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data
$ docker compose -f compose.yaml -f compose-opensearch3.yaml start

경고

-v 에 접두사 없이 search01_data 를 지정하면 Docker는 기존 볼륨을 참조하지 않고 같은 이름의 빈 볼륨을 새로 생성합니다. 명령은 오류 없이 실행되고 내용이 빈 아카이브가 생성되므로, 마치 백업이 정상적으로 취득된 것처럼 보일 수 있습니다.

참고

Fess 본체(fess01) 컨테이너에는 전용 볼륨이 없으므로 백업 대상은 위 2개뿐입니다. 다만 관리 화면에서 변경한 전반 설정이나 관리 화면에서 설치한 플러그인은 컨테이너 내부에만 저장되며, 컨테이너를 재생성하면 유실됩니다. 이러한 항목은 Compose 파일의 FESS_JAVA_OPTS 나 FESS_PLUGINS 로 지정하여 영속화하십시오.

단계 2: 현재 버전 중지

Fess와 OpenSearch를 중지합니다.

ZIP 버전에는 중지용 스크립트가 포함되어 있지 않습니다. bin/fess 를 -p 옵션과 함께 실행한 경우에는 PID 파일을 사용하여 중지합니다:

$ kill $(cat /path/to/fess/fess.pid)
$ kill <opensearch_pid>

-p 를 지정하지 않고 실행한 경우에는 프로세스 ID를 확인하여 kill 합니다 (-d 만으로는 PID 파일이 생성되지 않습니다).

RPM/DEB 버전 (systemd):

$ sudo systemctl stop fess.service
$ sudo systemctl stop opensearch.service

Docker 버전:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml down

단계 3: 새 버전 설치

설치 방법에 따라 절차가 다릅니다.

ZIP 버전

1. 새 버전을 다운로드하여 압축을 해제합니다:

   $ wget https://github.com/codelibs/fess/releases/download/fess-15.9.0/fess-15.9.0.zip
   $ unzip fess-15.9.0.zip
   

   참고

   Fess 의 아카이브 버전은 ZIP 형식으로만 배포됩니다(fess-15.9.0.tar.gz 는 제공되지 않습니다).

2. 이전 버전의 설정을 복사합니다:

   $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.9.0/app/WEB-INF/conf/
   $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.9.0/app/WEB-INF/classes/
   $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.9.0/bin/
   

   경고

   fess_config.properties 와 fess.in.sh 를 그대로 복사하면 15.9 에서 기본값이 바뀐 값을 포함해 이전 버전의 값이 그대로 이어집니다. 예를 들어 업그레이드 후에 만든 작업의 기본값이 Groovy 가 됩니다. 마지막 두 명령을 실행하기 전에 각 파일을 fess-15.9.0 의 파일과 비교하고, 직접 변경한 값만 옮기십시오. 확인할 항목은 15.8 에서 이어받은 설정 파일 를 참조하십시오.

3. 커스터마이징한 경우에는 다음도 복사합니다:

   # 로그 설정
   $ cp /path/to/old-fess/app/WEB-INF/classes/log4j2.xml /path/to/fess-15.9.0/app/WEB-INF/classes/
   # 설치된 플러그인
   $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.9.0/app/WEB-INF/plugin/
   # 테마
   $ cp -r /path/to/old-fess/app/themes/. /path/to/fess-15.9.0/app/themes/
   

   경고

   관리 화면 「디자인」에서 편집한 JSP(app/WEB-INF/view/)는 그대로 복사하지 마십시오. 새 버전의 JSP와 구조가 달라진 경우 화면이 올바르게 표시되지 않을 수 있습니다. 새 버전의 JSP에 변경 내용을 다시 적용하십시오.

   참고

   app/WEB-INF/plugin/ 에서 복사한 플러그인은 이전 버전용으로 빌드된 것입니다. 복사한 뒤 fess-15.9.0 에서 bin/fess-setup upgrade plugins 를 실행하여 각 플러그인을 15.9 용으로 빌드된 버전으로 교체하십시오( 플러그인 버전 갱신 참조).

4. 설정 차이를 확인하고 필요에 따라 조정합니다

RPM/DEB 버전

새 버전 패키지를 설치:

# RPM
$ sudo rpm -Uvh fess-15.9.0.rpm

# DEB
$ sudo dpkg -i fess-15.9.0.deb

참고

RPM 버전에서는 /etc/fess/* 의 설정 파일이 %config(noreplace) 로 등록되어 있으므로 업그레이드 시에도 유지됩니다(새 기본 파일은 .rpmnew 로 함께 배치됩니다). 새로운 설정 옵션이 추가된 경우에는 수동으로 조정이 필요합니다. 변경한 /etc/fess/fess_config.properties 는 ZIP 버전 절차에서 복사한 파일과 마찬가지로 15.9 에서도 이전 값이 그대로 사용됩니다. 15.8 에서 이어받은 설정 파일 를 참조하십시오.

경고

DEB 버전에서는 /etc/fess/* 가 conffile로 등록되어 있지 않습니다(conffile은 /etc/default/fess, /etc/init.d/fess, /usr/lib/systemd/system/fess.service 3개뿐입니다). 따라서 dpkg -i 를 실행하면 /etc/fess/fess_config.properties 등이 새 버전의 파일로 덮어써집니다. 확인 없이 덮어쓰며 이전 파일의 사본도 남기지 않으므로 미리 백업하십시오(단계 1). 업그레이드 후에는 이전 파일을 통째로 되돌리지 말고, 새 파일에 변경 내용을 다시 적용하십시오( 15.8 에서 이어받은 설정 파일 참조). 또한 /etc/fess/system.properties 는 패키지에 포함되지 않는 실행 시 생성 파일이므로 덮어써지지 않습니다.

Docker 버전

1. 새 버전의 Compose 파일 가져오기:

   $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.9.0/compose/compose.yaml
   $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.9.0/compose/compose-opensearch3.yaml
   

2. 새 이미지 가져오기:

   $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull
   

단계 4: OpenSearch 업그레이드

Fess 15.9은 OpenSearch 3.8.0에 대응합니다. 연결 대상 OpenSearch가 이보다 오래된 경우 다음 절차에 따라 업그레이드하십시오.

참고

이 절차는 ZIP 버전 및 RPM/DEB 버전에서 OpenSearch를 수동으로 운용하는 경우의 절차입니다. Docker 버전에서는 단계 3에서 새 이미지를 가져오면 OpenSearch와 플러그인도 함께 업데이트되므로 이 단계는 불필요합니다.

중요

Fess 15.9은 청크 벡터 검색(시맨틱 검색) 사용 여부와 관계없이 검색 인덱스 설정에 index.knn 을, 매핑에 content_chunk_vector (knn_vector 타입)를 항상 포함합니다. 따라서 연결 대상 OpenSearch에는 k-NN 플러그인이 필수 입니다.

• 표준 배포판 OpenSearch 및 Docker 버전의 이미지에는 동봉되어 있습니다.

• minimal 배포판에는 포함되어 있지 않으므로 인덱스를 새로 생성하지 못해 |Fess| 가 시작되지 않습니다.

• 인덱스 설정에는 knn.derived_source.enabled 도 항상 전송됩니다. 이를 인식하지 못하는 오래된 OpenSearch에서는 k-NN 플러그인 유무와 관계없이 인덱스 생성에 실패합니다.

자세한 내용은 시맨틱 검색(콘텐츠 청킹 + 벡터 검색) 의 「전제 조건」을 참조하십시오.

경고

OpenSearch의 메이저 버전 업그레이드는 신중하게 수행하십시오. 인덱스 호환성에 문제가 발생할 수 있습니다. Fess 14.x는 OpenSearch 2.x 계열이므로, 14.x에서의 업그레이드는 반드시 이 경우에 해당합니다.

1. 새 버전의 OpenSearch 설치

2. 플러그인 재설치:

   $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0
   

   참고

   이러한 플러그인의 버전은 사용하는 OpenSearch의 버전과 일치시켜야 합니다. Fess 15.9은 OpenSearch 3.8.0에 대응합니다. 버전이 일치하지 않으면 플러그인 설치에 실패합니다.

3. OpenSearch 시작:

   $ sudo systemctl start opensearch.service
   

단계 5: 새 버전 시작

ZIP 버전:

$ cd /path/to/fess-15.9.0
$ ./bin/fess -d -p /path/to/fess-15.9.0/fess.pid

참고

-p 를 지정하면 PID 파일이 생성되며, 다음 중지 시 kill $(cat /path/to/fess-15.9.0/fess.pid) 로 중지할 수 있습니다.

RPM/DEB 버전:

$ sudo systemctl start opensearch.service
$ sudo systemctl start fess.service

Docker 버전:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

단계 6: 동작 확인

1. 로그 확인

   오류가 없는지 확인합니다.

   ZIP 버전:

   $ tail -f /path/to/fess/logs/fess.log
   

   RPM/DEB 버전:

   $ sudo tail -f /var/log/fess/fess.log
   

   Docker 버전:

   $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01
   

   참고

   같은 로그 디렉터리에 크롤 처리의 fess-crawler.log, 인증 및 관리 작업의 audit.log, 검색 요청의 searchlog.log 도 출력됩니다.

2. 웹 인터페이스 액세스

   브라우저에서 http://localhost:8080/ 에 액세스합니다.

3. 관리 화면 로그인

   http://localhost:8080/admin 에 액세스하여 관리자 계정으로 로그인합니다.

4. 버전 확인

   관리 화면에서 「시스템 정보」→「설정 정보」를 클릭하여 「시스템 속성」에 표시되는 fess.version 이 새 버전으로 되어 있는지 확인합니다.

5. 검색 동작 확인

   검색 화면에서 검색을 실행하여 정상적으로 결과가 반환되는지 확인합니다.

단계 7: 인덱스 재작성(권장)

메이저 버전 업그레이드의 경우 인덱스를 재작성할 것을 권장합니다.

참고

아래 단계는 크롤을 다시 실행하는 것으로, 인덱스 매핑(필드 정의)은 업데이트되지 않습니다. 매핑을 업데이트하는 재인덱스가 필요한 경우 — 예를 들어 청크 벡터 검색(시맨틱 검색)을 새로 활성화하려는 경우 등 — 는 관리 화면의 「시스템 정보」→「유지보수」에서 「재인덱싱」을 별도로 실행하세요. 자세한 내용은 15.7 이전 버전에서 업그레이드하는 경우의 마이그레이션(시맨틱 검색(콘텐츠 청킹 + 벡터 검색))을 참조하세요.

1. 기존 크롤 일정 확인

2. 「시스템」→「스케줄러」에서 “Default Crawler” 실행

3. 크롤이 완료될 때까지 대기

4. 검색 결과 확인

경고

재인덱싱에서는 새로운 매핑으로 인덱스가 다시 생성되므로, k-NN 플러그인이 없는 OpenSearch에서는 실패합니다. 단계 4의 주의사항을 확인하십시오.

15.8에서 15.9로 업그레이드

15.8에서 업그레이드하는 경우 다음 변경 사항은 하위 호환되지 않습니다.

내장 OpenSearch 폐지

15.8 까지는 SEARCH_ENGINE_HTTP_URL 을 설정하지 않고 bin/fess 를 실행하면 Fess 가 자체 JVM 안에서 OpenSearch 노드를 시작했습니다. 15.9 에서는 이 구성이 없어지고 검색 엔진은 항상 별도의 서버가 됩니다.

bin/fess.in.sh 는 기본적으로 SEARCH_ENGINE_HTTP_URL=http://localhost:9200 을 설정합니다. 접속할 OpenSearch 가 없으면 Fess 는 시작되지 않습니다. bin/fess-setup install opensearch 로 설치할 수 있습니다(Linux 와 Windows 만 지원. macOS 용 OpenSearch 공식 배포판은 없으므로 Homebrew 또는 Docker 를 사용하십시오).

또한 FESS_DICTIONARY_PATH 를 해당 OpenSearch 의 opensearch.yml 에 있는 configsync.config_path 와 일치시켜야 합니다. 설정되지 않았거나 일치하지 않으면 Fess 는 인덱스를 생성할 수 없습니다. 15.9 의 bin/fess.in.sh (Windows 에서는 bin\fess.in.bat )는 Fess 디렉터리의 opensearch/ 에 bin/fess-setup install opensearch 로 설치한 OpenSearch 가 하나만 있을 때 이를 자동으로 설정합니다. 그 밖의 OpenSearch 를 사용하는 경우에는 Linux 설치 (상세 절차) 또는 Windows 설치 (상세 절차) 에 따라 설정하십시오.

다음도 함께 폐지되었습니다.

• es/ 디렉터리( es/modules , es/plugins , es/data )

• -Dfess.es.dir 와 SEARCH_ENGINE_HOME

• bin/module.xml 과 bin/plugin.xml

• 이전 elasticsearch.* 설정 키에 대한 대체 처리

또한 OpenSearch 3 이전 버전에 접속한 경우 15.8 까지는 오류 로그를 남기고 계속 실행했지만 15.9 에서는 시작에 실패합니다. 해당 버전에는 전체 문서를 순회하는 처리가 사용하는 _shard_doc 정렬이 구현되어 있지 않아, HTTP 를 통해서는 실패하지 않고 응답이 돌아오지 않기 때문입니다.

경고

내장 OpenSearch 로 운영한 경우 인덱스 데이터는 이어받을 수 없습니다. 외부 OpenSearch 서버를 새로 구축하고 관리 화면의 「백업」에서 설정을 옮긴 뒤 다시 크롤링하십시오. 백업에 포함되는 것은 크롤링 설정, 사용자, 로그이며 크롤링한 문서는 포함되지 않습니다.

Playwright 크롤러를 플러그인으로 이동

Playwright 크롤러와 그것이 사용하는 Node.js 실행 파일은 더 이상 배포물에 포함되지 않습니다. fess-15.8.0.zip (457.1 MiB)에서는 Node.js 실행 파일을 담은 Playwright 드라이버 번들이 204.3 MiB 를 차지했습니다.

크롤링 설정의 설정 파라미터에서 client.crawlerClients=playwright:http://.* 와 같이 Playwright 클라이언트를 지정한 경우에는 플러그인과 Node.js 를 모두 설치하십시오. 플러그인은 관리 화면의 「시스템 > 플러그인」 페이지에서도 설치할 수 있습니다. bin/fess.in.sh 가 Node.js 설치 위치를 찾아 PLAYWRIGHT_NODEJS_PATH 를 설정합니다.

$ bin/fess-setup install plugin fess-crawler-playwright
$ bin/fess-setup install nodejs

플러그인이 없어도 이러한 설정은 크롤링되지만 일반 HTTP 클라이언트가 사용되므로, JavaScript 로만 생성되는 텍스트는 인덱싱되지 않습니다. 크롤 작업은 정상적으로 종료되며 장애 URL 도 기록되지 않습니다. 크롤링할 때마다 fess-crawler.log 에는 크롤링 설정마다 1건씩, 플러그인 이름과 위의 두 명령을 알려 주는 경고가 기록됩니다.

Playwright 크롤러를 사용하지 않는 경우에는 대응이 필요 없습니다.

Google Cloud Storage 를 플러그인으로 이동

Google Cloud Storage 의 SDK 는 더 이상 배포물에 포함되지 않으며, gcs:// 크롤링과 gcs 스토리지 타입은 fess-storage-gcs 플러그인에서 제공됩니다. 관리 화면의 「시스템 > 플러그인」 페이지 또는 아래 명령으로 설치하십시오.

$ bin/fess-setup install plugin fess-storage-gcs

crawler.file.protocols 의 기본값에서도 gcs 가 빠져 file,smb,smb1,ftp 가 되었습니다. 플러그인을 설치하면 다시 추가됩니다. 설치 전에는 경로가 gcs: 로 시작하는 파일 크롤링 설정에 대해 경고가 기록될 뿐이며 아무것도 가져오지 않습니다. 업그레이드한 기존 설치는 자체 crawler.file.protocols 를 그대로 유지하므로 경로는 계속 허용되지만 처리할 크롤러 클라이언트가 없고, 새로 설치한 경우에는 gcs: 가 설정된 프로토콜이 아니므로 관리 화면이 경로 저장을 거부하고 이전에 저장된 경로는 로컬 파일 경로로 처리됩니다. 스토리지 화면도 경고를 기록하고 설치해야 하는 플러그인 이름이 포함된 오류를 표시합니다. 이전에는 빈 파일 목록만 표시했습니다.

Google Cloud Storage 를 사용하지 않는 경우에는 대응이 필요 없습니다. Amazon S3 와 MinIO 등 S3 호환 스토리지도 같은 방식으로 플러그인으로 이동했습니다. 다음 절을 참조하십시오.

Amazon S3 를 플러그인으로 이동

AWS SDK 는 더 이상 배포물에 포함되지 않으며, s3:// 크롤링과 s3 및 s3_compat 스토리지 타입은 fess-storage-s3 플러그인에서 제공됩니다. 관리 화면의 「시스템 > 플러그인」 페이지 또는 아래 명령으로 설치하십시오.

$ bin/fess-setup install plugin fess-storage-s3

crawler.file.protocols 의 기본값에서도 s3 가 빠져 file,smb,smb1,ftp 가 되었습니다. 플러그인을 설치하면 다시 추가됩니다. storage.type 의 기본값은 여전히 auto 이며 엔드포인트가 설정되지 않으면 S3 로 해석되므로, s3 를 직접 지정하지 않았더라도 플러그인을 설치할 때까지 관리 화면의 스토리지는 동작하지 않습니다. storage.* 설정값은 WEB-INF/conf/system.properties 에 있으므로 그대로 남고, 기존 crawler.file.protocols 도 업그레이드로 교체되지 않습니다.

Amazon S3 와 MinIO 등 S3 호환 스토리지를 사용하지 않는 경우에는 대응이 필요 없습니다.

SSO 인증을 플러그인으로 이동

네 가지 SSO 인증은 모두 더 이상 배포물에 포함되지 않으며, sso.type 의 값별로 전용 플러그인에서 제공됩니다. 플러그인에는 필요한 인증 라이브러리도 포함됩니다. 대응하는 플러그인은 saml 에는 fess-sso-saml, spnego 에는 fess-sso-spnego, entraid (이전 이름 aad 포함)에는 fess-sso-entraid, oic 에는 fess-sso-oidc 입니다. 마지막 조합에 유의하십시오. 플러그인 이름은 fess-sso-oidc 이지만 sso.type 의 값은 그대로 oic 이며, 둘이 달라지는 곳은 이 한 곳뿐입니다. 사용하는 것을 관리 화면의 「시스템 > 플러그인」 페이지 또는 아래 명령으로 설치하십시오.

$ bin/fess-setup install plugin fess-sso-saml

sso.type 과 saml.*, spnego.*, entraid.*, aad.*, oic.* 각 키는 WEB-INF/conf/system.properties 에 있으므로 설정값은 그대로 남습니다. 관리 화면 「시스템」→「일반」도 네 가지 모두를 선택 항목으로 표시하고 설정란도 그대로 남습니다. 플러그인에서 JSP 를 제공할 수 없기 때문이며, 이 화면은 플러그인이 없다는 것을 알리지 않습니다.

플러그인을 설치하기 전에는 /sso/ 요청이 SSO 로그인 실패를 알리는 로그인 페이지로 리디렉션되며 SSO 로 로그인할 수 없습니다. 15.9 에서는 찾은 컴포넌트 이름과 제공하는 플러그인 이름이 포함된 경고가 fess.log 에 기록됩니다. 15.8 까지는 어느 로그 레벨에서도 아무것도 출력되지 않았습니다.

SSO 를 사용하지 않는 경우, 즉 sso.type 이 none 이거나 설정되지 않은 경우에는 대응이 필요 없습니다.

내장 스크립트 엔진이 Groovy에서 JavaScript로 변경

15.8까지는 내장 스크립트 엔진이 Groovy였고 job.default.script 의 기본값도 groovy 였습니다. 15.9에서는 내장 엔진이 JavaScript이며 기본값은 javascript 입니다. Groovy는 더 이상 기본으로 내장되지 않고 fess-script-groovy 플러그인이 제공합니다. scriptType 에 groovy 를 지정하려면 이 플러그인을 설치해야 합니다.

업그레이드는 각 설정에 저장된 스크립트 엔진을 바꾸지 않으며, 15.9 이전에 저장되어 엔진이 기록되지 않은 설정은 groovy 로 취급됩니다. 플러그인이 없으면 다음이 동작하지 않게 됩니다.

• groovy 로 저장된 스케줄 작업. 15.8 이 직접 등록한 작업도 여기에 해당합니다. Default Crawler, Suggest Indexer, Config Reloader, Log Aggregator, Doc Purger 등 기본 제공 작업은 모두 groovy 로 저장되어 있으며, 15.9 는 시작할 때 아직 존재하지 않는 기본 제공 작업만 추가하므로 이 작업들은 바뀌지 않습니다. 각 작업은 스케줄에 따라 실행될 때마다 실패하고, Default Crawler 에 의한 크롤링도 이루어지지 않습니다. 기본 제공 작업 대부분은 「로깅」이 꺼져 있어 실패가 작업 로그에는 남지 않고 fess.log 에 Failed to execute job 경고로만 기록됩니다.

• 「설정 파라미터」에 필드 스크립트( field.script.<필드 이름> )를 작성한 웹 크롤링 설정과 파일 크롤링 설정. 해당 설정의 문서는 모두 ScriptEngineException 으로 실패하여 장애 URL 로 기록되지만, 크롤 작업 자체는 정상적으로 종료됩니다.

• 「스크립트」를 설정한 데이터스토어 설정. 파라미터 이름 자체가 아닌 값은 평가할 수 없습니다. 데이터스토어 커넥터 개요 를 참조하십시오.

• 문서 부스트 규칙. 해당 규칙은 아무것도 부스트하지 않습니다.

• 「치환」이 groovy: 로 시작하는 경로 매핑. 해당 매핑은 적용되지 않으며 URL 은 바뀌지 않습니다.

처음 시작한 후 fess.log 에서 Settings use the script engine groovy, which is not registered 로 시작하는 경고를 확인하십시오. Fess 는 시작할 때 위의 설정을 한 번 확인하고, 어느 플러그인도 제공하지 않는 엔진을 사용하는 설정의 수를 종류별로 출력합니다. 15.8 에서 이어받은 fess_config.properties 에 job.default.script=groovy 가 남아 있으면 그것도 표시되며, 이 경우 업그레이드 후에 만든 작업도 Groovy 를 사용합니다( 15.8 에서 이어받은 설정 파일 참조). 다음 중 하나로 대응하십시오.

• 플러그인을 설치하고 Fess 를 재시작합니다. 저장된 Groovy 스크립트는 그대로 동작하며 경고도 더 이상 기록되지 않습니다. 플러그인은 관리 화면 「시스템」→「플러그인」에서도 설치할 수 있습니다.

  $ bin/fess-setup install plugin fess-script-groovy
  

• 각 설정을 JavaScript 로 전환합니다. Groovy 만 허용하는 구문을 먼저 다시 작성한 뒤 JavaScript 를 선택합니다.

  • 스케줄 작업: 관리 화면 「시스템」→「스케줄러」에서 「실행 방법」을 javascript 로 바꿉니다. 기본 제공 작업의 스크립트는 다음 두 가지를 제외하면 그대로 유효한 JavaScript 입니다. Thumbnail Purger 는 Groovy 의 long 리터럴 1000L 을 사용하는데 JavaScript 에서는 구문 오류가 됩니다( 1000 으로 작성합니다). Index Exporter 에는 Index Exporter 작업이 삭제된 패키지를 참조 의 변경이 필요합니다. JavaScript의 배열 리터럴은 Java의 String[] 로 자동 변환되므로 Groovy 형식의 as String[] 은 필요하지 않습니다.

    return container.getComponent("crawlJob").logLevel("info").webConfigIds(["1", "2"]).fileConfigIds(["1"]).dataConfigIds([]).execute(executor);
    

  • 웹 크롤링 설정과 파일 크롤링 설정: 「설정 파라미터」에 config.script.type=javascript 를 추가합니다.

  • 데이터스토어 설정: 「파라미터」에 script_type=javascript 를 추가합니다.

  • 문서 부스트 규칙: 「스크립트 종류」를 javascript 로 바꿉니다.

  • 경로 매핑: 「치환」을 groovy: 대신 javascript: 로 시작합니다.

  • job.default.script: 15.8 에서 이어받은 fess_config.properties 에서 javascript 로 설정합니다.

crawler.default.script 삭제

crawler.default.script 는 fess_config.properties 에서 삭제되었습니다. 설정에 남겨 두어도 효과가 없으므로 제거하십시오.

크롤 프로토콜 storage 삭제

crawler.file.protocols 에서 storage 는 더 이상 사용할 수 없으며, 기본 제공 값은 file,smb,smb1,ftp 입니다. 대신 s3 를 사용하고, 경로가 storage: 로 시작하는 파일 크롤 설정은 s3: 경로로 변경하십시오. s3 에는 fess-storage-s3 플러그인이 필요합니다.

Index Exporter 작업이 삭제된 패키지를 참조

15.9 에는 org.opensearch 클래스가 더 이상 포함되지 않으며, 작업 스크립트에서 사용하는 쿼리 빌더는 org.codelibs.fesen.opensearch 아래로 옮겨졌습니다. 15.8 이 Index Exporter 작업에 저장한 스크립트는 org.opensearch.index.query.QueryBuilders 를 참조하며 업그레이드로도 교체되지 않으므로, fess-script-groovy 를 설치해도 이 작업은 실패합니다. 이 작업은 비활성화되고 스케줄이 없는 상태로 제공되므로 실행하는 경우에만 영향이 있습니다. 관리 화면 「시스템」→「스케줄러」에서 작업을 열고 스크립트의 패키지를 15.9 의 것으로 변경하십시오.

return new org.codelibs.fess.job.IndexExportJob().query(org.codelibs.fesen.opensearch.index.query.QueryBuilders.matchAllQuery()).execute()

직접 작성한 스크립트에서 org.opensearch.index.query 를 참조하는 경우에도 같은 방식으로 변경하십시오. 쿼리 예는 인덱스 내보내기 기능 를 참조하십시오.

15.8 에서 이어받은 설정 파일

단계 3의 ZIP 버전 절차에서는 이전 설치의 fess_config.properties 와 bin/fess.in.sh 를 복사합니다. RPM 버전 업그레이드에서는 변경한 /etc/fess/fess_config.properties 가 그대로 남습니다(15.9 의 파일은 fess_config.properties.rpmnew 로 함께 배치됩니다). 어느 경우든 15.9 는 15.8 의 값으로 동작하며, 15.9 에서 기본 제공 값이 바뀐 키도 예외가 아닙니다. 적어도 다음 키를 확인하십시오.

키	15.8.0	15.9	15.8 의 값이 남은 경우의 영향
job.default.script	groovy	javascript	관리 화면 「시스템」→「스케줄러」에서 만드는 작업의 기본값이 groovy 가 되며, fess-script-groovy 플러그인이 없으면 실패합니다.
job.template.script	as String[] 를 포함한 Groovy 형식	JavaScript 형식	크롤링 설정에서 만든 작업의 스크립트가 Groovy 형식이 됩니다.
crawler.file.protocols	file,smb,smb1,ftp,storage,s3,gcs	file,smb,smb1,ftp	s3: 나 gcs: 로 시작하는 경로가 플러그인이 없어도 허용되며, 크롤링할 때 경고를 남기고 처리되지 않습니다. storage 는 더 이상 지원되지 않습니다.
search_engine.http.url	http://localhost:9201	http://localhost:9200	SEARCH_ENGINE_HTTP_URL 이 설정되지 않은 경우에 사용됩니다. 15.8 에서 복사한 bin/fess.in.sh 에서 설정하지 않았다면 여기에 해당하며, Fess 는 15.9 에서 폐지된 내장 OpenSearch 의 포트인 9201 에서 OpenSearch 를 찾습니다.
jvm.crawler.options, jvm.thumbnail.options	-Djcifs.smb.client.*, -Djcifs.smb1.smb.client.*	-Djcifs.client.*	SMB 타임아웃이 jcifs 의 기본값 그대로 남습니다. SMB 타임아웃은 jcifs 3 의 속성 이름을 사용 를 참조하십시오.
crawler.default.script, theme.allowed.archive.extensions, theme.assets.cache.max.age, theme.assets.precompressed, rag.chat.message.max.length, supported.uploaded.js.extentions, supported.uploaded.css.extentions, supported.uploaded.media.extentions, supported.uploaded.files, online.help.name.design	있음	삭제됨	효과가 없습니다. 제거하십시오.

15.8 에서 복사한 bin/fess.in.sh 에는 15.9 의 파일에 있는 다음 두 가지도 없습니다. 15.9 는 SEARCH_ENGINE_HTTP_URL 에 http://localhost:9200 을 설정하지만, 15.8 의 파일은 직접 설정하지 않는 한 설정되지 않은 상태로 둡니다. 또한 bin/fess-setup install nodejs 로 설치한 Node.js 를 찾지 않으므로, PLAYWRIGHT_NODEJS_PATH 를 직접 설정하지 않는 한 Playwright 크롤러는 Node.js 를 찾을 수 없습니다.

어느 파일이든 통째로 복사하지 말고, 15.9 에 포함된 파일을 바탕으로 변경한 값을 다시 적용하십시오. 변경한 값은 diff 로 확인할 수 있습니다:

$ diff /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.9.0/app/WEB-INF/classes/fess_config.properties
$ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.9.0/bin/fess.in.sh

RPM 버전에서는 같은 방식으로 /etc/fess/fess_config.properties 와 /etc/fess/fess_config.properties.rpmnew 를 비교하십시오. DEB 버전 업그레이드에서는 /etc/fess/fess_config.properties 가 덮어써지므로(단계 3 참조) 15.9 의 값에서 시작하며, 다시 적용해야 하는 것은 직접 변경한 값뿐입니다.

SMB 타임아웃은 jcifs 3 의 속성 이름을 사용

Fess 가 SMB 파일 서버를 크롤링할 때 사용하는 jcifs 는 버전 3 에서 속성 이름을 변경했습니다. jcifs.smb.client.* 는 jcifs.client.* 가 되었고, SMB1 용의 jcifs.smb1.smb.client.* 도 같은 속성으로 통합되었습니다. 15.8 까지의 jvm.crawler.options 와 jvm.thumbnail.options 는 이전 이름을 전달했고 jcifs 는 이를 읽지 않으므로, SMB 크롤링은 jcifs 의 기본값으로 동작했습니다. 15.9 는 새 이름을 전달합니다.

-Djcifs.client.responseTimeout=30000
-Djcifs.client.soTimeout=35000
-Djcifs.client.connTimeout=60000
-Djcifs.client.sessionTimeout=60000

따라서 연결 타임아웃과 세션 타임아웃이 처음으로 적용되어 jcifs 의 기본값인 35초에서 60초로 늘어납니다. 응답하지 않는 SMB 서버에 대해 크롤링은 최대 60초 동안 기다리게 됩니다. 응답 타임아웃과 소켓 타임아웃은 jcifs 의 기본값과 같으므로 바뀌지 않습니다.

이 타임아웃들을 변경했다면 두 옵션 모두에서 이름을 바꾸십시오. 이전 이름으로는 15.8 에서도 효과가 없었습니다. 15.8 에서 이어받은 fess_config.properties 에는 이전 이름이 남아 jcifs 의 기본값이 그대로 사용됩니다.

효과가 없던 네 가지 속성 삭제

다음 키는 fess_config.properties 에서 삭제되었습니다. Fess 는 이 파일에서 이 키들을 읽지 않았으므로, 이 이름으로 남겨 둔 값은 이전과 마찬가지로 효과가 없습니다.

• theme.allowed.archive.extensions

• theme.assets.cache.max.age

• theme.assets.precompressed

• rag.chat.message.max.length

rag.chat.message.max.length 가 정하는 상한은 계속 유효하지만 시스템 속성으로 읽힙니다. AI 검색 모드 기능 설정 에 설명된 대로 app/WEB-INF/conf/system.properties 또는 -Dfess.system.rag.chat.message.max.length 로 설정하십시오.

관리 화면의 「페이지 디자인」 삭제

관리 화면의 [시스템 > 페이지 디자인] 을 삭제했습니다. 검색 화면의 JSP, CSS, 이미지를 관리 화면에서 편집할 수 없습니다. 검색 화면의 모양은 정적 테마로 변경하십시오 (테마 개발 가이드 참조).

다음 키도 fess_config.properties 에서 삭제되었습니다. 이 이름으로 남겨 둔 값은 사용되지 않습니다.

• supported.uploaded.js.extentions

• supported.uploaded.css.extentions

• supported.uploaded.media.extentions

• supported.uploaded.files

• online.help.name.design

admin-design 과 admin-design-view 롤은 더 이상 아무 권한도 부여하지 않습니다. 이 롤만 가진 사용자는 로그인하면 관리 화면이 아니라 검색 화면으로 이동합니다.

15.9 전용 마이그레이션 작업

15.7 이전 버전에서 15.9로 업그레이드하는 경우, 사용 중인 기능에 따라 다음 작업이 필요합니다.

시맨틱 검색을 사용하고 있었던 경우

15.7 이전에 시맨틱 검색을 제공하던 fess-webapp-semantic-search 플러그인은 15.9에서 코어로 통합되어 불필요해졌습니다(사용 중단). 플러그인 제거, -Dfess.semantic_search.* 및 -Drank.fusion.searchers=default,semantic 의 제거, 기존 인제스트 파이프라인 분리가 필요합니다. 절차는 15.7 이전 버전에서 업그레이드하는 경우의 마이그레이션 (시맨틱 검색(콘텐츠 청킹 + 벡터 검색))를 참조하십시오.

AI 검색 모드(RAG 채팅)를 사용하고 있었던 경우

15.9부터 AI 검색 모드(RAG 채팅) 기능은 fess-llm-ollama, fess-llm-openai, fess-llm-gemini 등의 플러그인으로 분리되었습니다. 사용 중인 프로바이더에 대응하는 플러그인을 관리 화면 「시스템」→「플러그인」에서 설치하십시오.

SPNEGO(Windows 통합 인증)를 사용하고 있었던 경우

15.9부터 클라이언트 주체의 Kerberos 영역이 서버의 영역과 다르면 SPNEGO 로그인이 거부됩니다. AD 도메인 트리의 하위 도메인이나 신뢰 관계를 맺은 포리스트의 사용자가 로그인하는 구성에서는 관리 화면 「시스템」→「일반」 또는 app/WEB-INF/conf/system.properties 의 spnego.allowed.realms 에 해당 영역을 쉼표로 구분하여 나열하십시오. 나열하지 않으면 15.7까지 로그인할 수 있었던 사용자가 Kerberos realm is not allowed 로 거부됩니다. 자세한 내용은 Windows 통합 인증을 통한 SSO 설정 를 참조하십시오.

또한 15.9에서는 spnego.allow.unsecure.basic 과 spnego.allow.localhost 의 코드상 기본값이 true 에서 false 로 변경되었습니다. 이 키들이 app/WEB-INF/conf/system.properties 에 없는 환경에서는 업그레이드와 함께 더 엄격한 동작이 적용됩니다. 특히 spnego.allow.unsecure.basic=false 인 경우 SPNEGO 라이브러리는 HttpServletRequest#isSecure() 가 true 를 반환하는 요청에만 Basic 인증을 제공하므로, 리버스 프록시에서 TLS를 종료하고 HTTP로 전달하는 구성에서는 지금까지 Basic 인증으로 대체하던 클라이언트가 로그인할 수 없게 됩니다. 이 경우 tomcat_config.properties 에서 tomcat.secure=true 를 설정하십시오. 자세한 내용은 Windows 통합 인증을 통한 SSO 설정 를 참조하십시오.

경고

코드상의 기본값은 키가 없는 경우에만 적용되며, 관리 화면 「시스템」→「일반」은 저장할 때마다 모든 spnego.* 키를 기록합니다. 따라서 15.7에서 이 화면으로 한 번이라도 갱신한 환경에는 spnego.allow.unsecure.basic=true 와 spnego.allow.localhost=true 가 저장된 채로 남아 있으며, 15.9로 업그레이드해도 설정은 강화되지 않습니다. 느슨한 동작이 조용히 유지되고, 15.9은 SPNEGO 초기화 시 fess.log 에 경고를 기록할 뿐입니다. 관리 화면 「시스템」→「일반」 또는 system.properties 에서 두 가지를 모두 명시적으로 비활성화하십시오. 특히 spnego.allow.localhost=true 는 위험합니다. SPNEGO 라이브러리가 동일 호스트에서 온 요청을 Kerberos 검증 없이 서버의 OS 사용자로 인증하므로, 동일 호스트에 리버스 프록시를 두는 구성에서는 안전하지 않습니다.

SAML 인증(SSO)을 사용하고 있었던 경우

15.9부터 Fess 는 전송한 AuthnRequest의 ID와 SAML 응답을 대응시켜 검증하므로 IdP-Initiated(미요청·unsolicited) SSO는 동작하지 않습니다. IdP 포털(Okta 대시보드나 Microsoft Entra ID의 「내 앱」 등)에 배치한 타일에서 시작한 로그인은 대응시킬 AuthnRequest가 없어 거부됩니다. 15.7까지는 Fess 가 대응시키지 못한 응답을 IdP로 되돌려 보내고, IdP가 즉시 SP-Initiated 어서션을 반환했기 때문에 동작했습니다. IdP 측에 타일을 배치하는 경우에는 링크 대상을 Fess 의 /sso/ 로 지정하여 SP-Initiated 로그인이 되도록 하십시오.

또한 IdP는 어서션을 크로스 사이트 POST로 반환하므로 tomcat_config.properties 의 tomcat.sameSiteCookies 를 none 으로 설정해야 합니다. 포함된 기본값 lax 그대로는 세션 쿠키가 이 요청에 전송되지 않아 SAML 로그인을 완료할 수 없습니다. 이 파일은 ZIP 패키지에서는 lib/classes/ , DEB/RPM 패키지에서는 /etc/fess/ 에 있으며, 변경 후에는 Fess 를 재시작해야 합니다. 브라우저는 Secure 속성이 함께 있는 쿠키에 대해서만 none 을 허용하므로 Fess 를 HTTPS로 제공해야 합니다. 15.7까지는 같은 설정 오류가 명확한 오류가 아니라 IdP로의 무한 리다이렉트 루프로 나타났으므로, 동작하는 것처럼 보였던 사이트에서도 설정을 확인하십시오. 15.9에서는 루프에 빠지지 않고 한 번에 실패합니다. 자세한 내용은 SAML 인증을 통한 SSO 설정 을 참조하십시오.

Microsoft Entra ID(Azure AD)를 사용하고 있었던 경우

15.9부터 인가 엔드포인트에 요청하는 응답 모드의 기본값이 form_post 에서 query 로 변경되었습니다. 15.7까지는 콜백이 교차 사이트 POST로 반환되므로, Fess 의 기본값인 tomcat.sameSiteCookies = lax 에서는 세션 쿠키가 전송되지 않아 none 으로 변경해야 했습니다. 이 회피책만을 위해 none 을 설정했다면 기본값으로 되돌릴 수 있습니다. 기존과 같이 form_post 를 사용하려면 entraid.response.mode=form_post 를 지정하고 tomcat.sameSiteCookies = none 을 유지하십시오. 브라우저는 Secure 속성이 함께 있는 쿠키에 대해서만 none 을 허용하므로, 이 경우에도 Fess 를 HTTPS로 제공해야 합니다.

또한 15.9부터 Fess 는 로그인이 완료된 후 백그라운드에서 사용자의 그룹·역할 소속을 해결하며, 로그인이 Microsoft Graph의 응답을 기다리다 멈추는 일은 없어졌습니다. 해결이 완료될 때까지, 또는 해결이 완전히 성공하지 못한 경우 사용자가 보유하는 것은 사용자 본인의 사용자 수준 권한과 entraid.default.groups 및 entraid.default.roles 에 설정한 그룹·역할뿐입니다. 둘 다 설정하지 않은 경우（기본 제공 설정값）, 이 시간대의 검색은 한 건도 결과가 나오지 않습니다. 기본 제공 설정값 그대로 만든 크롤 설정으로 크롤링한 문서에는 {role}guest 가 부여되지만, 로그인한 사용자는 이 역할을 갖고 있지 않기 때문입니다. 해결이 진행되는 동안에는 검색 화면에 그 사실을 알리는 메시지가 표시되며, 완전히 성공하지 못한 경우에는 별도의 메시지가 표시됩니다 （직접 소속 조회와 중첩 그룹 탐색이 모두 성공하지 않는 한 해결은 실패로 처리됩니다）. 액세스 토큰이 갱신될 때마다 해결이 다시 실행되고, 그 후 성공하면 메시지는 사라지므로, 토큰 유효 기간을 넘겨 이어지는 세션에서는 실패가 최종적인 것이 되지는 않습니다. 바로 다시 시도하려면 일단 로그아웃한 후 다시 로그인하십시오. 자세한 내용은 Microsoft Entra ID를 이용한 SSO 설정 를 참조하십시오.

백그라운드에서 해결하기 때문에 생기는 영향으로, 해결이 완료될 때까지는 해결된 역할을 아직 알 수 없습니다. 그래서 관리자는 관리 대시보드가 아니라 검색 화면으로 리다이렉트되며, 그 사이에 관리 화면을 열어도 검색 화면으로 되돌아옵니다. 이 시간대는 최대 약 1초의 스케줄링 지연에 더해 Microsoft Graph 호출 자체（직접 소속 조회 1회, 여기에 중첩 그룹을 따라가기 위해 직접 소속 그룹마다 1회씩 순차 실행. 캐시가 없는 경우）가 걸리므로, 사용자가 소속된 그룹 수에 따라 길어집니다. 이 시간대에 접근이 허용되는 일은 없고 거부될 뿐이며, 이 시간대를 넘기기 위한 설정은 필요하지 않습니다. 인가는 같은 세션의 요청마다 다시 평가되므로, 해결이 완료된 후에 다시 열면 다시 로그인하지 않아도 관리 화면에 정상적으로 접근할 수 있습니다.

경고

이 시간대를 줄이기 위해 Fess 의 관리자 역할을 entraid.default.roles 에 설정해서는 안 됩니다. 이 속성은 단일 전역 설정으로, Fess 는 로그인 시 모든 Entra ID 사용자에게 이를 적용하고 이후의 해결 때마다 다시 적용하므로, 테넌트의 모든 사용자에게 영구적인 Fess 관리자 권한을 부여하게 됩니다.

LDAP / Active Directory 연동을 사용하던 경우

15.9부터 그룹과 롤의 권한 이름은 엔트리의 DN을 텍스트로 잘라낸 값이 아니라 RDN으로 해석한 값이 됩니다. DN 안에서 이스케이프되는 문자(일반적으로 쉼표)를 CN에 포함하는 그룹은 15.7까지와 다른 권한 이름을 갖게 됩니다.

그룹 엔트리의 DN	15.7까지의 권한 이름	15.9의 권한 이름
CN=Sales\, EMEA,CN=Users,...	2Sales	2Sales, EMEA
CN=Sales\, APAC,CN=Users,...	2Sales	2Sales, APAC

15.7까지는 쉼표 앞부분이 일치하는 여러 그룹이 같은 권한 이름으로 합쳐졌기 때문에, Sales, EMEA와 Sales, APAC의 소속자는 서로의 문서와 Sales 그룹의 문서를 읽을 수 있었습니다. 15.9에서는 각각 다른 권한 이름이 되어 이러한 그룹 간 접근은 발생하지 않습니다.

그 대신 기존 권한 이름으로 색인된 문서는 해당 그룹의 사용자에게 보이지 않게 됩니다. 크롤 설정의 「퍼미션」에 기존 권한 이름을 설정했다면 새로운 권한 이름으로 변경한 뒤 다시 크롤 (또는 재색인)하십시오. CN에 쉼표 등을 포함하는 그룹을 사용하지 않는다면 권한 이름은 바뀌지 않습니다.

ldap.role.search.user.enabled 의 동작 변경

15.7까지는 ldap.role.search.user.enabled=false 를 설정해도 사용자 이름에서 유도한 권한 (role.search.user.prefix + 사용자 이름)이 부여되었습니다. 15.9부터는 이 설정이 실제로 반영되어 false 인 경우 부여되지 않습니다.

false 로 설정한 환경에서는 업그레이드 후 사용자가 자신의 권한을 잃게 되므로, 개별 사용자에게 설정한 권한을 가진 문서를 검색할 수 없게 됩니다. 기존 동작을 유지하려면 기본값인 true 로 되돌리십시오.

/api/v2 설정 키를 변경했던 경우

15.8.0부터 네 개의 설정 키에서 api.v2. 접두사가 없어졌습니다. 값과 기본값, 동작은 그대로이지만 하위 호환을 위한 별칭은 제공되지 않습니다. 예전 이름 그대로 남겨 둔 설정은 경고 없이 무시되며, 기본으로 포함된 값이 사용됩니다.

15.7까지	15.8.0 이후	기본값
api.v2.chat.stream.keepalive.interval.ms	api.chat.stream.keepalive.interval.ms	15000
api.v2.param.max.length	api.param.max.length	1000
api.v2.param.max.array.size	api.param.max.array.size	100
api.v2.click.max.rt	api.click.max.timestamp	9999999999999

fess_config.properties 또는 -Dfess.config.<키> JVM 인수로 이 키들을 설정했다면 새 이름으로 변경하십시오. 영향을 받는 것은 명시적으로 설정한 경우뿐이며, 변경한 적이 없는 환경에서는 대응이 필요하지 않습니다.

첫 번째 키는 POST /api/v2/chat/stream 이 모델의 응답을 기다리는 동안 keep-alive 프레임을 보내는 간격을 정하므로, 설정이 사라진 것은 AI 검색 모드에서 드러납니다. 마지막 키는 정확성을 위해서도 이름이 바뀌었습니다. 클릭 로그가 가질 수 있는 rt 값의 상한이며, 응답 시간이 아니라 타임스탬프를 가리킵니다.

플러그인 버전 갱신

app/WEB-INF/plugin/ 에 설치된 플러그인은 Fess 버전에 대응하는 것으로 교체해야 합니다. bin/fess-setup upgrade plugins 는 설치된 모든 플러그인에 대해 이 Fess 용으로 빌드된 버전을 설치하고 이전 버전을 삭제합니다. 그 후 Fess 를 재시작하십시오. bin/fess-setup check 는 OpenSearch 와 그 플러그인, 설치된 Fess 플러그인의 상태를 보고하며, 문제가 있으면 종료 코드 1 로 종료합니다.

$ bin/fess-setup upgrade plugins
$ bin/fess-setup check

upgrade plugins 의 대상은 이미 설치된 플러그인뿐입니다. fess-script-groovy 등 15.9 에서 배포물에서 빠진 부분을 보완하는 플러그인은 앞의 각 절에 설명된 대로 bin/fess-setup install plugin 으로 설치하십시오.

Docker 버전에서 FESS_PLUGINS 를 지정하는 경우에는 fess-ds-wikipedia:15.9.0 처럼 버전 부분을 갱신하십시오.

롤백 절차

업그레이드에 실패한 경우 다음 절차로 롤백할 수 있습니다.

단계 1: 새 버전 중지

$ sudo systemctl stop fess.service
$ sudo systemctl stop opensearch.service

단계 2: 이전 버전 복원

백업에서 설정 파일과 데이터를 복원합니다.

RPM/DEB 버전의 경우:

$ sudo rpm -Uvh --oldpackage fess-<old-version>.rpm

또는:

$ sudo dpkg -i fess-<old-version>.deb

단계 3: 데이터 복원

스냅샷에서 복원:

$ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true"

또는 백업에서 디렉터리 복원:

$ sudo systemctl stop opensearch
$ sudo rm -rf /var/lib/opensearch/data/*
$ sudo tar xzf /backup/opensearch-data-backup.tar.gz -C /
$ sudo systemctl start opensearch

Docker 버전에서는 이전 버전의 Compose 파일로 되돌린 후 볼륨의 내용을 복원합니다:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml down
$ PROJECT=$(basename "$(pwd)")
$ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \
    sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /"
$ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

참고

관리 화면에서 다운로드한 설정 데이터는 Fess 시작 후 「시스템 정보」→「백업」 페이지의 업로드 기능으로 다시 임포트하여 복원할 수 있습니다. 업로드할 수 있는 것은 *.bulk, system 으로 시작하는 *.properties, gsa 로 시작하는 *.xml, fess 로 시작하는 *.json, doc 으로 시작하는 *.json 뿐이며, 한 번의 조작에 파일 1개입니다. 검색 로그 등의 *.ndjson 파일은 받아들여지지 않으며 오류가 됩니다.

경고

fess.json 과 doc.json 의 업로드는 Fess 에 동봉된 인덱스 정의 파일 자체를 덮어씁니다. 업그레이드 후에 이전 버전의 fess.json 이나 doc.json 을 업로드하면 새 버전의 인덱스 설정·매핑이 유실됩니다. 롤백 목적 이외에는 업로드하지 마십시오.

참고

업로드된 system.properties 는 메모리에만 로드되며 파일로는 기록되지 않습니다. 따라서 system.properties 의 내용은 Fess 를 재시작하면 유실됩니다. 확실히 복원하려면 백업한 파일을 정해진 위치(ZIP 버전은 app/WEB-INF/conf/, RPM/DEB 버전은 /etc/fess/)에 직접 배치한 후 시작하십시오.

참고

임포트는 비동기로 실행되며, 화면에는 시작되었다는 내용만 표시됩니다. 실제로 성공했는지는 fess.log 를 확인하십시오.

단계 4: 서비스 시작 및 확인

$ sudo systemctl start opensearch.service
$ sudo systemctl start fess.service

동작을 확인하고 정상적으로 복구되었는지 확인합니다.

자주 묻는 질문

Q: 다운타임 없이 업그레이드할 수 있습니까?

A: Fess의 업그레이드에는 서비스 중지가 필요합니다. 다운타임을 최소화하려면 다음을 고려하십시오:

• 사전에 테스트 환경에서 절차를 확인

• 백업을 사전에 취득

• 유지보수 시간을 충분히 확보

Q: OpenSearch도 업그레이드해야 합니까?

A: Fess 버전마다 대응하는 OpenSearch 버전이 정해져 있습니다. Fess 15.9은 OpenSearch 3.8.0에 대응합니다. opensearch-analysis-fess 등의 Fess 용 OpenSearch 플러그인은 OpenSearch 버전과 완전히 일치해야 하므로, OpenSearch를 업그레이드하는 경우 대응하는 버전(3.8.0)의 플러그인으로 업데이트하십시오.

또한 Fess 15.9은 k-NN 플러그인을 필수로 하며, 인덱스 설정에 knn.derived_source.enabled 를 항상 전송합니다. 오래된 OpenSearch를 그대로 사용하면 새 인덱스 생성에 실패하므로 사실상 OpenSearch의 업그레이드가 필요합니다. 자세한 내용은 단계 4를 참조하십시오.

Q: 인덱스를 재작성해야 합니까?

A: Fess 의 마이너 버전 업그레이드(15.x → 15.9)에서 청크 벡터 검색을 이용하지 않는 경우는 일반적으로 불필요합니다. 기존 인덱스를 그대로 이용할 수 있으며, content_chunker.enabled 등은 기본값이 비활성화이므로 동작은 변하지 않습니다.

다음의 경우에는 재작성·재인덱싱이 필요합니다.

• 새로 청크 벡터 검색(시맨틱 검색)을 활성화하는 경우: 기존 인덱스에는 새 매핑이 반영되지 않으므로 재인덱싱이 필수입니다. 자세한 내용은 15.7 이전 버전에서 업그레이드하는 경우의 마이그레이션 (시맨틱 검색(콘텐츠 청킹 + 벡터 검색))를 참조하십시오.

• 14.x에서 업그레이드하는 경우: OpenSearch가 2.x에서 3.x로 메이저 버전 업그레이드 되므로 인덱스 재작성을 권장합니다.

경고

인덱스를 새로 생성하는 작업(재인덱싱 포함)은 k-NN 플러그인이 없는 OpenSearch에서는 실패합니다. 단계 4의 주의사항을 확인하십시오.

Q: 업그레이드 후 검색 결과가 표시되지 않습니다

A: 다음을 확인하십시오:

1. OpenSearch가 시작되어 있는지 확인

2. 인덱스가 존재하는지 확인(curl http://localhost:9200/_cat/indices)

3. 크롤 재실행

다음 단계

업그레이드가 완료되면:

• 시작, 중지, 초기 설정 - 시작 및 초기 설정 확인

• 보안 설정 - 보안 설정 검토

• 시맨틱 검색(콘텐츠 청킹 + 벡터 검색) - 청크 벡터 검색(시맨틱 검색) 설정 및 마이그레이션 절차

• 릴리스 노트에서 새 기능 확인