문제 해결

이 페이지에서는 Fess 의 설치, 시작, 운용 시 자주 발생하는 문제와 해결 방법에 대해 설명합니다.

설치 시 문제

Java가 인식되지 않음

증상:

-bash: java: command not found

또는:

'java' is not recognized as an internal or external command

원인:

Java가 설치되어 있지 않거나 PATH 환경 변수가 올바르게 설정되어 있지 않음.

해결 방법:

  1. Java가 설치되어 있는지 확인:

    $ which java
$ java -version

  2. 설치되어 있지 않은 경우 Java 21 설치:

    # Ubuntu/Debian
$ sudo apt-get update
$ sudo apt-get install openjdk-21-jdk

# RHEL/CentOS
$ sudo yum install java-21-openjdk

    Debian 12 의 표준 리포지토리에는 openjdk-21-jdk 패키지가 없습니다. Debian 12 에서는 대신 Adoptium의 Linux 설치 안내 의 Debian 용 절차에 따라 Eclipse Temurin 21 을 설치하십시오.

  3. JAVA_HOME 환경 변수 설정:

    $ export JAVA_HOME=/path/to/java
$ export PATH=$JAVA_HOME/bin:$PATH

    영구적으로 설정하는 경우 ~/.bashrc 또는 /etc/profile 에 추가합니다.

플러그인 설치 실패

증상:

ERROR: Plugin installation failed

원인:

  • 네트워크 연결 문제

  • 플러그인 버전이 OpenSearch 버전과 일치하지 않음

  • 권한 문제

해결 방법:

  1. OpenSearch 버전 확인:

    $ /path/to/opensearch/bin/opensearch --version

  2. 플러그인 버전을 OpenSearch 버전에 맞춤:

    $ /path/to/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip

  3. 권한 확인:

    $ sudo /path/to/opensearch/bin/opensearch-plugin install ...

  4. 프록시를 통해 설치하는 경우:

    $ export ES_JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080"
$ /path/to/opensearch/bin/opensearch-plugin install ...

시작 시 문제

Fess가 시작되지 않음

증상:

Fess 시작 명령을 실행해도 오류가 발생하거나 즉시 종료됨.

확인 항목:

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

    $ curl http://localhost:9200/

    정상인 경우 JSON 응답이 반환됩니다.

    OpenSearch 가 응답하지 않으면 Fess 는 1분 정도 재시도한 후 시작을 중단하고, 콘솔과 logs/fess.log 에 다음 메시지를 출력합니다:

    The search engine at http://localhost:9200 did not become available within 60221ms. Check that OpenSearch is running and reachable. If there is none yet, run bin/fess-setup install opensearch to set one up.

    OpenSearch 를 시작하거나 SEARCH_ENGINE_HTTP_URL 을 확인하십시오. 새로 설치한 ZIP 버전에는 bin/fess-setup install opensearch 로 설치하기 전까지 OpenSearch 가 없습니다. Linux 설치 (상세 절차) 를 참조하십시오.

  2. 포트 번호 충돌 확인:

    $ sudo ss -tuln | grep 8080

    포트 8080이 이미 사용되고 있는 경우 설정 파일에서 포트 번호를 변경하십시오.

  3. 로그 파일 확인:

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

    오류 메시지에서 원인을 특정합니다.

  4. Java 버전 확인:

    $ java -version

    Java 21 이상이 설치되어 있는지 확인하십시오.

  5. 메모리 부족 확인:

    $ free -h

    메모리가 부족한 경우 힙 크기를 조정하거나 시스템 메모리를 증설하십시오.

OpenSearch가 시작되지 않음

증상:

ERROR: bootstrap checks failed

원인:

시스템 설정이 OpenSearch 요구사항을 충족하지 못함.

해결 방법:

  1. vm.max_map_count 설정:

    $ sudo sysctl -w vm.max_map_count=262144

    영구적으로 설정:

    $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
$ sudo sysctl -p

  2. 파일 디스크립터 상한 증가:

    $ sudo vi /etc/security/limits.conf

    다음을 추가:

    opensearch  -  nofile  65535
opensearch  -  nproc   4096

  3. 메모리 잠금 설정:

    $ sudo vi /etc/security/limits.conf

    다음을 추가:

    opensearch  -  memlock  unlimited

  4. OpenSearch 재시작:

    $ sudo systemctl restart opensearch

인덱스를 생성할 수 없음(사전 파일 경로)

증상:

Fess 에 액세스하면 HTTP 404 가 반환되고 fess.log 에 다음 오류가 출력됩니다:

Failed to create index: index=fess, path=fess_indices/fess.json
... reason=Resource path must be inside config directory: /var/lib/opensearch/data/config/ja/mapping.txt

원인:

OpenSearch 3.8.0 이상에서는 사전 파일이 OpenSearch 설정 디렉터리 밖에 있으면 인덱스 생성을 거부합니다. configsync.config_path 와 FESS_DICTIONARY_PATH 가 설정 디렉터리 밖(data/config/ 등)을 가리키고 있습니다.

해결 방법:

  1. configsync.config_path 와 FESS_DICTIONARY_PATH 를 OpenSearch 설정 디렉터리 아래의 디렉터리로 변경합니다.

    • RPM/DEB 버전: /etc/opensearch/dictionary/

    • ZIP 버전: /path/to/opensearch-3.9.0/config/dictionary/

  2. 기존 사전 파일이 있는 경우 새 디렉터리로 복사합니다.

  3. OpenSearch, Fess 순서로 재시작합니다.

자세한 내용은 Linux 설치 (상세 절차) 를 참조하십시오.

포트 번호 충돌

증상:

Address already in use

해결 방법:

  1. 사용 중인 포트 확인:

    $ sudo ss -tuln | grep 8080
$ sudo lsof -i :8080

  2. 사용 중인 프로세스 중지, 또는 Fess의 포트 번호 변경

    포트 번호 변경은 :doc:포트 및 네트워크 설정 <../config/setup-port-network> 을 참조하세요.

연결 문제

Fess가 OpenSearch에 연결할 수 없음

증상:

로그에 다음과 같은 오류 표시:

Connection refused
또는
No route to host

해결 방법:

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

    $ curl http://localhost:9200/

  2. 연결 URL 확인

    fess.in.sh 또는 fess.in.bat 에서 설정된 URL이 올바른지 확인:

    SEARCH_ENGINE_HTTP_URL=http://localhost:9200

  3. 방화벽 확인:

    $ sudo firewall-cmd --list-all

    포트 9200이 개방되어 있는지 확인합니다.

  4. 네트워크 연결 확인

    다른 호스트에서 OpenSearch를 실행하는 경우:

    $ ping opensearch-host
$ telnet opensearch-host 9200

브라우저에서 Fess에 액세스할 수 없음

증상:

브라우저에서 http://localhost:8080/ 에 액세스할 수 없음.

해결 방법:

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

    $ ps aux | grep fess

  2. 로컬호스트에서 액세스 시도:

    $ curl http://localhost:8080/

  3. 방화벽 확인:

    $ sudo firewall-cmd --list-all

    포트 8080이 개방되어 있는지 확인합니다.

  4. 다른 호스트에서 액세스하는 경우

    Fess가 로컬호스트 이외에서 수신 대기하고 있는지 확인:

    $ ss -tuln | grep 8080

    127.0.0.1:8080 인 경우 0.0.0.0:8080 또는 특정 IP 주소에서 수신 대기하도록 설정을 변경합니다.

성능 문제

검색이 느림

원인:

  • 인덱스 크기가 큼

  • 메모리 부족

  • 디스크 I/O가 느림

  • 쿼리가 복잡함

해결 방법:

  1. 힙 크기 증가

    FESS_HEAP_SIZE 를 환경 변수로 전달하여 Fess 를 시작합니다:

    $ FESS_HEAP_SIZE=4g bin/fess

    bin/fess.in.sh 에서 설정하는 경우에는 힙 크기를 결정하는 줄(FESS_MIN_MEM 의 기본값을 설정하는 줄)보다 앞에 FESS_HEAP_SIZE=4g 를 작성합니다. 파일 끝에 추가해도 그 시점에는 이미 힙 크기가 결정되어 있으므로 반영되지 않습니다. RPM/DEB 버전은 /etc/sysconfig/fess(DEB 버전은 /etc/default/fess)에 설정합니다.

    OpenSearch의 힙 크기도 조정:

    export OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g"

  2. SSD 사용

    디스크 I/O가 병목인 경우 SSD로 이전합니다.

  3. 캐시 활성화

    설정 파일에서 쿼리 캐시를 활성화합니다.

크롤링이 느림

원인:

  • 크롤 간격이 김

  • 대상 사이트 응답이 느림

  • 스레드 수가 적음

해결 방법:

  1. 크롤 간격 조정

    관리 화면에서 크롤 설정의 “간격”을 짧게 합니다(밀리초 단위).

    경고

    간격을 너무 짧게 하면 대상 사이트에 부하가 걸립니다. 적절한 값을 설정하십시오.

  2. 스레드 수 증가

    관리 화면에서 크롤링 설정의 “스레드 수”를 늘립니다. 기본값은 웹 크롤이 1, 파일 시스템 크롤이 5입니다.

  3. 타임아웃 값 조정

    응답이 느린 사이트의 경우 타임아웃 값을 늘립니다.

데이터 문제

검색 결과가 표시되지 않음

원인:

  • 인덱스가 작성되지 않음

  • 크롤링이 실패함

  • 검색 쿼리가 잘못됨

해결 방법:

  1. 인덱스 확인:

    $ curl http://localhost:9200/_cat/indices?v

    Fess 의 인덱스가 존재하는지 확인합니다.

  2. 크롤 로그 확인

    관리 화면의 “시스템 정보”→”로그 파일”에서 크롤 로그(fess-crawler.log)를 다운로드하여 오류가 없는지 조사합니다.

  3. 크롤 재실행

    관리 화면에서 “시스템”→”스케줄러”에서 “Default Crawler”를 실행합니다.

  4. 검색 쿼리를 간단하게

    먼저 간단한 키워드로 검색하여 결과가 반환되는지 확인합니다.

인덱스가 손상됨

증상:

검색 시 오류 발생 또는 예기치 않은 결과 반환.

해결 방법:

  1. 인덱스 삭제 후 재작성

    경고

    인덱스를 삭제하면 모든 검색 데이터가 손실됩니다. 반드시 백업을 취득하십시오.

    $ curl -X DELETE http://localhost:9200/fess*

  2. Fess 재시작

    인덱스는 Fess 시작 시에 생성됩니다. 삭제한 직후에는 사용자 정보 인덱스도 함께 사라졌으므로 관리 화면에 로그인할 수 없습니다(/api/v2/health 는 200 을 계속 반환합니다). Fess 를 재시작하면 인덱스와 기본 작업, 초기 사용자(admin)가 다시 생성됩니다.

  3. 크롤 재실행

    관리 화면에서 “Default Crawler”를 실행하여 검색 대상 문서를 다시 등록합니다.

Docker 고유 문제

컨테이너가 시작되지 않음

증상:

docker compose up 으로 컨테이너가 시작되지 않음.

해결 방법:

  1. 로그 확인:

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

  2. 메모리 부족 확인

    Docker에 할당된 메모리를 늘립니다(Docker Desktop 설정에서).

  3. 포트 충돌 확인:

    $ docker ps

    다른 컨테이너가 포트 8080 또는 9200을 사용하고 있지 않은지 확인합니다.

  4. Docker Compose 파일 확인

    YAML 파일의 구문 오류가 없는지 확인합니다:

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

컨테이너는 시작되지만 Fess에 액세스할 수 없음

해결 방법:

  1. 컨테이너 상태 확인:

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

  2. 로그 확인:

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

  3. 네트워크 설정 확인:

    $ docker network ls
$ docker network inspect <network_name>

Windows 고유 문제

경로 문제

증상:

경로에 공백이나 한국어가 포함된 경우 오류 발생.

해결 방법:

경로에 공백이나 한국어를 포함하지 않은 디렉터리에 설치하십시오.

예:

C:\opensearch  (권장)
C:\Program Files\opensearch  (비권장)

서비스로 등록할 수 없음

해결 방법:

NSSM 등의 타사 도구를 사용하여 Windows 서비스로 등록합니다.

자세한 내용은 Windows 설치 (상세 절차) 를 참조하십시오.

기타 문제

로그 레벨 변경

상세한 로그를 확인하는 경우 로그 레벨을 DEBUG로 변경합니다.

log4j2.xml 편집:

<Logger name="org.codelibs.fess" level="debug"/>

데이터베이스 재설정

설정을 재설정하는 경우 OpenSearch의 인덱스를 삭제합니다:

$ curl -X DELETE 'http://localhost:9200/fess_config.*'

경고

이 명령을 실행하면 모든 설정 데이터가 삭제됩니다.

관리자 비밀번호를 잊은 경우

관리자 비밀번호를 잊은 경우에는 OpenSearch 의 fess_user.user 인덱스에 있는 사용자 문서를 직접 갱신하여 비밀번호를 다시 설정할 수 있습니다. 비밀번호는 password 필드에 {bcrypt}$2a$... 형식의 해시로 저장되어 있습니다. 갱신은 Fess 를 재시작하지 않아도 유효합니다.

  1. 새 비밀번호의 해시를 만듭니다. Fess 가 받아들이는 것은 $2a$ 로 시작하는 bcrypt 해시뿐이므로, htpasswd (apache2-utils 또는 httpd-tools 패키지에 포함)가 출력하는 $2y$ 를 $2a$ 로 바꿉니다. NewPassword 는 새 비밀번호로 바꾸십시오:

    $ HASH=$(htpasswd -bnBC 10 "" 'NewPassword' | tr -d ':\n' | sed 's/^\$2y/$2a/')

  2. admin 사용자 문서의 비밀번호를 갱신합니다. 초기 상태의 admin 사용자의 문서 ID는 YWRtaW4= 입니다:

    $ curl -X POST 'http://localhost:9200/fess_user.user/_update/YWRtaW4=?refresh=true' \
       -H 'Content-Type: application/json' \
       -d "{\"doc\":{\"password\":\"{bcrypt}${HASH}\"}}"

    다른 사용자의 비밀번호를 다시 설정하는 경우에는 curl 'http://localhost:9200/fess_user.user/_search?q=name:사용자명' 로 _id 를 조회하여 그 ID를 지정합니다. OpenSearch 에 인증을 설정한 경우에는 curl 에 인증 정보를 지정하십시오.

  3. 새 비밀번호로 관리 화면에 로그인할 수 있는지 확인합니다. 명령 이력에 비밀번호가 남는 경우에는 로그인 후 [사용자 > 사용자] 에서 비밀번호를 다시 설정하십시오.

지원 정보

문제가 해결되지 않는 경우 다음 지원 리소스를 이용하십시오:

커뮤니티 지원

상용 지원

상용 지원이 필요한 경우 N2SM, Inc.에 문의하십시오:

디버그 정보 수집

문제를 보고할 때 다음 정보를 수집해 두면 도움이 됩니다:

  1. 버전 정보 (bin/fess -v 는 15.9 이상에서 사용할 수 있습니다):

    $ /path/to/fess/bin/fess -v
$ /path/to/opensearch/bin/opensearch --version
$ java -version

  2. 시스템 정보:

    $ uname -a
$ cat /etc/os-release
$ free -h
$ df -h

  3. 로그 파일:

    $ tar czf fess-logs.tar.gz /path/to/fess/logs/

  4. 설정 파일(기밀 정보를 삭제한 후):

    $ tar czf fess-config.tar.gz /path/to/fess/app/WEB-INF/conf/

  5. OpenSearch 상태:

    $ curl http://localhost:9200/_cluster/health?pretty
$ curl http://localhost:9200/_cat/indices?v