Elasticsearch 8을 사용하여 Nextcloud에서 전체 텍스트 검색을 설정하는 방법

Nextcloud의 Elasticsearch 통합은 2026년에도 여전히 활성화되어 있지만, 시작하기 전에 확인해야 할 호환성 관련 사항이 하나 있습니다. 현재 전체 텍스트 검색 - Elasticsearch 플랫폼 앱은 Elasticsearch 8만 지원하며 Elasticsearch 9는 지원하지 않습니다. 프로젝트 공식 저장소에 따르면 버전 26.0.0 이상은 Elasticsearch 8과만 호환됩니다. 또한 Nextcloud 35에는 2026년 9월 18일에 출시된 35.0.0 버전의 Elasticsearch 플랫폼이 있습니다. 기존 서버를 업그레이드하는 경우 검색 인덱스를 수정하기 전에 Nextcloud 주요 릴리스와 일치하는 앱 버전을 확인하십시오.

이 가이드는 Nextcloud에서 Elasticsearch 8을 사용하여 파일 콘텐츠를 인덱싱하는 실용적인 설정 방법을 보여줍니다. 표준적인 세 가지 애플리케이션 스택, 즉 전체 텍스트 검색 프레임워크, Elasticsearch 플랫폼 커넥터 및 파일 공급자에 중점을 둡니다. occ웹 인터페이스에만 의존하는 것보다 검증 및 자동화가 용이하기 때문에 Nextcloud CLI를 사용하여 명령어를 실행합니다.

공식 참조: Nextcloud 전체 텍스트 검색 - Elasticsearch 플랫폼 앱 , Nextcloud Elasticsearch 플랫폼 저장소 , Nextcloud 전체 텍스트 검색 프레임워크 , Nextcloud 파일 전체 텍스트 검색 공급자 및 Elastic의 단일 노드 Docker 설치 가이드 .

Nextcloud 전문 검색 스택의 실제 구성 요소

Nextcloud 전문 검색은 단일 앱이 아닙니다. 핵심 전문 검색 앱은 프레임워크를 제공하고, 플랫폼 앱은 해당 프레임워크를 검색 엔진에 연결하며, 하나 이상의 제공자 앱이 검색 가능한 콘텐츠를 추출합니다. 파일 콘텐츠의 경우 제공자는 파일 전문 검색 앱입니다. Elasticsearch는 결과 인덱스를 저장하고 쿼리에 응답합니다.

• 전문 검색: 핵심 프레임워크 및 검색 오케스트레이션 계층.
• 전체 텍스트 검색 - Elasticsearch 플랫폼: 문서와 쿼리를 Elasticsearch로 전송하는 커넥터입니다.
• 전체 텍스트 검색 - 파일: 사용자의 파일을 색인화를 위해 프레임워크에 노출하는 제공자입니다.
• Elasticsearch 8: 인덱스를 저장하는 외부 검색 엔진입니다.

문제 해결 시 구성 요소 간의 분리는 중요합니다. Elasticsearch HTTP 엔드포인트가 정상적으로 작동한다고 해서 Nextcloud가 파일 콘텐츠를 추출할 수 있다는 것을 보장하는 것은 아니며, 파일 공급자가 활성화되어 있다고 해서 플랫폼 커넥터가 Elasticsearch에 연결할 수 있다는 것을 보장하는 것도 아닙니다. 내장 fulltextsearch:test명령어는 단일 구성 요소가 아닌 구성된 체인 전체를 확인하기 때문에 유용합니다.

시작하기 전에

Nextcloud에 대한 관리자 권한, Nextcloud가 실행되는 서버 또는 컨테이너에 대한 셸 액세스 권한, 그리고 해당 환경에서 접근 가능한 Elasticsearch 8 인스턴스가 필요합니다. 아래 예제는 Linux 서버를 가정하고 검색 서비스를 격리하기 위해 Docker를 사용하여 Elasticsearch를 배포합니다. 이미 관리형 또는 전용 Elasticsearch 8 클러스터를 실행 중인 경우 기존 HTTPS 엔드포인트를 사용하십시오.

프로덕션 환경에서는 9200번 포트를 공용 인터넷에 직접 노출하지 마십시오. Elastic의 최신 Docker 문서에서는 HTTP 포트를 제어된 인터페이스에 바인딩하고 보안 기능을 유지할 것을 권장합니다. 또한 Elastic은 vm.max_map_count프로덕션 Docker 배포에 필요한 호스트 요구 사항도 문서화하고 있습니다. 보안이 비활성화된 단일 노드 명령은 로컬 랩 환경에서의 간단한 테스트 용도로만 사용해야 하며, 프로덕션 환경에서는 사용하지 마십시오.

1단계: 필수 Nextcloud 앱 3개를 설치합니다.

Nextcloud 앱 페이지에서 전체 텍스트 검색 , 전체 텍스트 검색 - Elasticsearch 플랫폼 및 전체 텍스트 검색 - 파일을occ 설치하고 활성화하세요. 헤드리스 서버에서는 명령어를 사용하여 설치하는 것이 더 간단할 수 있습니다 .

sudo -u www-data php /var/www/nextcloud/occ app:install fulltextsearch
sudo -u www-data php /var/www/nextcloud/occ app:install fulltextsearch_elasticsearch
sudo -u www-data php /var/www/nextcloud/occ app:install files_fulltextsearch

Nextcloud 파일이 다른 위치에 있는 경우 경로를 로 조정하세요 occ. 공식 Nextcloud Docker 이미지에서 경로는 일반적으로 입니다 /var/www/html/occ. 설치 후, 명령어를 사용하여 occ app:list세 가지 앱이 모두 활성화됨에 표시되는지 확인하세요.

캡션: 핵심 전문 검색 프레임워크, Elasticsearch 플랫폼 커넥터 및 파일 공급자가 활성화된 Nextcloud 앱 페이지.

2단계: Elasticsearch 8을 시작하고 Nextcloud에서 Elasticsearch에 연결할 수 있는지 확인합니다.

Nextcloud 앱 26.0.0 버전부터 Elasticsearch 커넥터는 Elasticsearch 8을 필요로 합니다. 사용 중인 앱 버전에 대한 공식 호환성 설명이 변경되지 않는 한 Elasticsearch 9으로 대체하지 마십시오.

로컬 랩 환경의 경우, Elastic은 단일 노드 Docker 방식을 권장합니다. 최소한의 테스트 인스턴스는 비공개 인터페이스에서 시작할 수 있습니다. 프로덕션 환경에 배포할 때는 인증 및 TLS를 활성화하고 보안을 비활성화하는 대신 Elastic의 최신 설치 지침을 따르십시오.

docker run --name es01   --net elastic   -p 127.0.0.1:9200:9200   -it -m 6GB   docker.elastic.co/elasticsearch/elasticsearch:<ELASTICSEARCH_8_VERSION>

Elasticsearch의 안전한 기본 시작 기능은 내장 elastic사용자 암호를 출력하고 HTTP TLS 인증서를 생성합니다. 그런 다음 공식 가이드에 설명된 대로 CA 인증서와 자격 증명을 사용하여 노드를 확인할 수 있습니다. Nextcloud가 다른 Docker 컨테이너에 있는 경우, 해당 경로가 127.0.0.1Elasticsearch 컨테이너가 아닌 Nextcloud 컨테이너 자체를 가리키도록 설정해야 합니다. 두 서비스를 공유 Docker 네트워크에 배치하고 Elasticsearch 서비스 이름(예: `Nextcloud.next https://elasticsearch:9200...

캡션: 단일 노드 Elasticsearch 서비스가 시작되고 점검되는 터미널 화면입니다. 프로덕션 환경에서는 보안이 취약한 랩 환경 설정을 사용하는 대신 인증 및 TLS를 활성화해야 합니다.

3단계: Nextcloud에서 Elasticsearch를 사용하도록 구성합니다.

관리 인터페이스에서 플랫폼을 구성할 수도 있지만, CLI 방식이 더 정확하고 재현성이 높습니다. Nextcloud의 올인원 통합 기능은 Elasticsearch 플랫폼 클래스를 선택하여 프레임워크를 구성한 다음, Elasticsearch 호스트와 인덱스 이름을 커넥터에 전달합니다.

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch:configure '{"search_platform":"OCA\\FullTextSearch_Elasticsearch\\Platform\\ElasticSearchPlatform"}'

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch_elasticsearch:configure '{"elastic_host":"https://elastic:YOUR_PASSWORD@elasticsearch:9200","elastic_index":"nextcloud_index"}'

Nextcloud PHP 프로세스에서 접근 가능한 호스트 URL을 사용하십시오. Elasticsearch 엔드포인트가 개인 CA를 사용하는 경우, 인증서 확인을 비활성화하는 대신 Nextcloud 환경에서 해당 CA를 신뢰하도록 설정하십시오. 공유 시스템의 셸 기록에 자격 증명을 저장하지 마십시오. 배포 환경에 적합한 보호된 구성 방법을 사용하십시오.

인덱스 이름은 소문자여야 하며 해당 Nextcloud 인스턴스 전용이어야 합니다. 예를 들어 `Nextcloud.index.index`와 같은 이름은 nextcloud_index쉽게 식별할 수 있습니다. 여러 Nextcloud 인스턴스가 하나의 Elasticsearch 클러스터를 공유하는 경우 각 인스턴스에 고유한 인덱스 이름을 지정하십시오.

캡션: Elasticsearch가 검색 플랫폼으로 선택되고 전용 인덱스 이름이 구성된 전체 텍스트 검색 관리 화면.

4단계: 색인화할 파일 콘텐츠를 선택합니다.

파일 공급자는 색인 생성을 위해 전송되는 파일 콘텐츠 범주를 제어합니다. Nextcloud의 올인원 초기화는 현재 다음 명령어를 사용하여 PDF 및 오피스 문서 추출을 지원합니다.

sudo -u www-data php /var/www/nextcloud/occ files_fulltextsearch:configure '{"files_pdf":true,"files_office":true}'

앱 버전에 따라 사용 가능한 제공업체 옵션이 다를 수 있으므로 이전 튜토리얼의 설정을 복사하기 전에 현재 구성을 확인하십시오. 또한 텍스트 추출 품질은 원본 파일에 따라 달라진다는 점을 기억하십시오. 텍스트가 포함된 일반 PDF는 스캔한 이미지로만 구성된 PDF보다 색인화하기 훨씬 쉽습니다. 전체 텍스트 검색 기능이 있다고 해서 OCR 품질이 자동으로 향상되는 것은 아닙니다.

5단계: 전체 검색 구성을 테스트합니다.

대규모 라이브러리를 인덱싱하기 전에 프레임워크 테스트를 실행하세요.

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch:test

테스트가 성공하면 플랫폼에 연결할 수 있고 구성된 공급자/플랫폼 조합이 정상적으로 작동하는지 확인해야 합니다. 테스트에 실패하면 초기 인덱싱을 시작하기 전에 연결 문제를 해결해야 합니다. 일반적인 원인으로는 localhost잘못된 컨테이너 사용, 인증서 신뢰 문제, 인증 실패, 호환되지 않는 Elasticsearch 주요 버전 또는 Elasticsearch에서 거부하는 인덱스 구성 등이 있습니다.

6단계: 초기 인덱스 생성

테스트가 통과되면 초기 인덱스를 생성합니다.

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch:index

대형 서버에서는 이 작업에 시간이 오래 걸리고 CPU, 메모리, 스토리지 I/O 및 Elasticsearch 힙을 많이 사용할 수 있습니다. 트래픽이 적은 시간대에 첫 번째 크롤링을 실행하고 Nextcloud 및 Elasticsearch 로그를 모두 확인하십시오. 또한 이 프레임워크는 Nextcloud All-in-One의 초기 설정 시 사용되는 오류 재설정 양식을 지원합니다.

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch:index '{"errors":"reset"}' --no-readline

특별한 이유 없이 정상적인 인덱스를 반복적으로 재설정하고 재구축하지 마십시오. 업그레이드 시에는 먼저 세 가지 검색 앱의 릴리스 노트를 읽고 재인덱싱이 실제로 필요한지 확인하십시오.

7단계: 인덱스를 최신 상태로 유지하세요

초기 색인은 단지 스냅샷일 뿐입니다. 새로운 업로드와 편집 내용에 대해서는 지속적인 색인 작업이 필요합니다. 전체 텍스트 검색 프레임워크에는 fulltextsearch:live지속적인 처리를 위한 명령어가 포함되어 있습니다. 이 명령어를 사용하는 경우, 프로세스 관리자 또는 다른 서비스 관리자를 통해 실행하여 오류 발생 또는 호스트 재부팅 후에도 자동으로 다시 시작되도록 하십시오.

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch:live

SSH 세션에서 관리되지 않는 포그라운드 프로세스를 실행하고 로그아웃 후에도 인덱싱이 계속될 것이라고 가정하지 마십시오. 컨테이너 배포 환경에서는 라이브 워커를 전용 관리 프로세스로 실행할 수 있으며, 기존 서버에서는 systemd 또는 슈퍼바이저를 사용할 수 있습니다. 다른 백그라운드 서비스와 마찬가지로 해당 프로세스를 모니터링하십시오.

8단계: CLI와 Nextcloud 인터페이스 모두에서 검색 결과를 확인합니다.

초기 크롤링이 완료되면 파일 이름뿐 아니라 알려진 문서 내부에 나타나는 구문을 검색하십시오. 이렇게 하면 콘텐츠 추출 및 색인 생성이 제대로 작동하는지 확인할 수 있습니다. 최근 전체 텍스트 검색 버전은 파일 이름 내 검색도 지원하므로 occ백엔드 색인 생성 문제와 브라우저 또는 통합 검색 문제를 구분하는 데 유용합니다.

웹 인터페이스에서 Nextcloud의 검색 필드를 사용하여 색인화된 PDF, DOCX 또는 텍스트 파일에서 특정 구문을 검색하십시오. 파일 이름 검색은 되지만 문서 본문 검색이 되지 않는 경우 파일 공급자 설정과 원본 문서 유형을 확인하십시오.

캡션: 프레임워크 테스트 및 초기 인덱싱이 성공적으로 완료된 후, Nextcloud 검색을 통해 인덱싱된 문서를 반환합니다.

일반적인 오류 해결 방법

Elasticsearch는 curl을 통해 연결되지만 Nextcloud는 연결되지 않습니다.

Nextcloud PHP 프로세스와 동일한 네트워크 네임스페이스에서 테스트하십시오. Docker 환경에서 호스트의 요청이 성공했다고 해서 Nextcloud 컨테이너가 Elasticsearch 서비스에 접근하거나 연결할 수 있다는 것을 보장하는 것은 아닙니다. DNS, 컨테이너 네트워크, 방화벽 규칙, TLS 신뢰 설정 및 구성된 URL의 정확한 스키마를 확인하십시오.

커넥터에서 Elasticsearch 버전 문제가 발생했다고 보고합니다.

배포하려는 이미지 태그뿐만 아니라 실제 Elasticsearch 메이저 버전을 확인하세요. 현재 공식 커넥터 저장소에는 앱 버전 26.0.0 이상에 대해 Elasticsearch 8 호환성이 명시되어 있습니다. 이 글을 작성하는 시점에서 Elasticsearch 9 지원에 대한 업스트림 요청이 진행 중이므로 Elasticsearch 9와의 호환성을 보장해서는 안 됩니다.

인덱싱이 메모리를 너무 많이 사용합니다.

Elasticsearch 힙, 컨테이너 메모리 제한 및 호스트 메모리를 함께 모니터링하세요. Elastic의 Docker 프로덕션 문서에서는 호스트 수준 설정(예: `.js`)에 대해서도 언급합니다 vm.max_map_count. JVM이 종료되는 경우 Nextcloud PHP 메모리 제한만 늘리는 것으로는 Elasticsearch 관련 문제를 해결할 수 없습니다.

공유 파일이나 외부 파일 중 일부가 누락되었습니다.

검색 동작은 제공업체 지원 여부 및 앱 버전에 따라 달라질 수 있습니다. 파일 제공업체 프로젝트는 공유 폴더, 그룹 폴더 및 외부 저장소와 관련된 문제를 지속적으로 추적하고 있습니다. 특정 저장소 유형이 일반 로컬 파일과 다르게 동작하는 경우, 전체 인덱스를 재구축하기 전에 간단한 예제를 만들어 문제를 재현하고 제공업체의 공식 문제 추적기를 확인하십시오.

설치가 완료되었는지 어떻게 알 수 있나요?

정상적인 배포는 다음과 같은 네 가지 징후로 확인할 수 있습니다. Nextcloud에서 Elasticsearch 8에 액세스할 수 있고 fulltextsearch:test, 초기 fulltextsearch:index테스트가 오류 없이 완료되며, 권한이 있는 사용자가 알려진 문서 내에서 텍스트를 검색하면 해당 파일이 반환됩니다. 인덱스 엔드포인트를 비공개로 유지하고, 프로덕션 환경에서 Elasticsearch 보안을 유지하며, Nextcloud의 주요 릴리스에 맞춰 세 가지 Nextcloud 검색 앱을 업그레이드하십시오.

버전 관련 세부 정보는 Nextcloud Elasticsearch 플랫폼 공식 릴리스 목록 과 Elasticsearch 프로덕션 Docker 가이드라인을 참조하십시오 . 이러한 자료는 주요 업그레이드 전에 호환성 및 호스트 요구 사항을 확인하는 가장 안전한 방법입니다.