mediaiwki 1.34 이상에서 SphinxSearch Extension 사용하기

배경사양

linux server
mediawiki 1.43+
mysql(mariadb)
sphinxsearch patch 버전 + 개량버전
manticore docker

소개

mediawiki 는 wikipedia 의 기본이 되는 wiki 시스템으로서 이미 유명한 시스템입니다. 이번 문서에서는 mysql 로 운영되는 mediawiki 를 대상으로 검색엔진인 manticore 를 연동하는 방법을 설명합니다. mediawiki 의 설치는 거의 다루지 않으며 mediawiki 는 스스로 세팅할 수 있는 경우를 대상으로 합니다. 가능한한 manticore 설정에 대한 설명을 위주로 합니다.

서론

왜 mediawiki 에 검색엔진을 도입해야 하나요?

mediawiki 의 기본 검색은 sql 의 like 검색으로 이루어져 있습니다. 그래서 sql 검색이라 그 이상을 제공하지 못합니다. 예를들자면 단어와 조사가 띄어쓰기 없이 결합되어 있는 경우 검색에 걸리지 않을 확률이 높다... 뭐 그런얘기죠. 별로 불편함이 없는 분도 있을 수 있겠습니다만... 제 경우는 대부분의 제가 만드는 자료들을 주로 mediawiki 에 넣는 편인데.. 이렇게 자료가 꽤 쌓이는 경우라면 아무래도 작업한 자료를 찾는데 좀 더 민감할 수 있습니다. 이런 경우라면 mediawiki 에 검색엔진을 도입해야 합니다.

왜 manricore 를 사용했나요?

mediawiki 에서 사용할 수 있는 검색엔진에는 다음의 종류가 있습니다.

sphinxsearch
- sphinx 검색엔진
- manticore 검색엔진
CirrusSearch
- Elasticsearch 검색엔진

개인적인 취향입니다만, Elasticsearch 는 java 기반이라 제 취향이 아닙니다. 그리고 sphinx 를 써봤던 예전의 기억이 해당 계열의 최신 프로젝트인 manticore 를 선택하게 했습니다. manticore 자체는 sphinx 와는 달리 내부를 unicode 로 전부 고쳤기때문에 sphinx 보다는 manticore 가 더 적합하다고 생각했습니다. 이건 취향의 차이며, Elasticsearch 에 큰 거부감이 없으신 분이라면 그쪽의 진행이 개인적으로는 더 쓸모있지 않을까 라고 생각합니다.

sphinxsearch extension 의 문제

mediawiki 의 sphinxsearch extension 은 mediawiki 1.33 을 마지막으로 더이상 관리되지 않습니다. 이 글을 작성하는 시점의 mediawiki 안정버전은 1.43 버전으로서 sphinxsearch extension 이 정상적으로는 동작하지 않습니다.

다행히도 누군가가 작업을 해둔 버전이 있더군요.
https://gerrit.wikimedia.org/r/c/mediawiki/extensions/SphinxSearch/+/1166058

그런데 말입니다.. 정상 동작이 안돼요...... 원래라면 sphinxsearch extension 의 압축을 해제하고, pip 등으로 필요한 패키지등을 설치하면 되어야 합니다만.. 안타깝게도 안됩니다. 그런데 그걸 claude code 의 도움을 받아 mediawiki 1.43 에 맞는 코드로 개량을 해서, 여튼.. 중요한건 되게 만들었었다는 겁니다. :D

manticore 세팅 에서 주의할점

기본적으로 한글을 지원하기는 하는데.. 일반적으로 얻을 수 있는 정보를 사용해서는 한글 검색이 되지 않습니다.
manticore 는 docker 로 세팅해도 사용이 충분합니다.
manticore 는 api/sql/sphinx native 의 3가지 mode 의 port 를 제공합니다. 이건 좀 중요한 부분인게..(한숨) 그 어떤 문서에도 이게 따로 적혀있지 않더라구요. mediawiki 의 sphinxsearch extension 은 native 방식을 사용해야 합니다.

manticore 세팅

manticore docker 작업

file :: docker-compose.yml

services:  manticore:    image: manticoresearch/manticore:13.6.7    container_name: manticore    ports:      - "29306:9306"   # SQL/MySQL port      - "29308:9308"   # HTTP port      - "29312:9312"   # sphinx raw api port    volumes:      - ./data/manticore:/var/lib/manticore      - ./data/manticore/data:/var/lib/manticore/data      - ./conf/manticore/manticore.conf:/etc/manticoresearch/manticore.conf:rw      - ./conf/manticore/stopwords.txt:/etc/manticoresearch/stopwords.txt:rw    environment:      - MANTICORE_CONFIG=/etc/manticoresearch/manticore.conf    restart: unless-stopped    networks:      - webnetnetworks:  webnet:    driver: bridge

이상의 정보로 docker-compose.yml 을 준비합니다.

https://github.com/onionmixer/SphinxSearch_Extension
위의 URL 에서 conf 안쪽에 있는 파일을 받아옵니다.
받아온 파일을 위의 docker-compose.yml 을 참고해서 적당히 배치합니다.
data 아래쪽의 폴더를 사용하게 됩니다. 해당되는 폴더는 미리 생성해둬야 합니다.
오타가 있으면 manticore docker 가 이상동작 합니다. 오타를 못보고 고생을 꽤 했어요...
manticore.conf 안에는 stopwords.txt 관련된 내용이 설정되어 있습니다. 관련된 부분을 감안해서 yml 및 conf 파일을 수정해 주어야 합니다.

정보가 전부 제대로 기입되어 있다는 전제하에 다음의 명령을 실행합니다. 물론 이 명령어는 docker-compose.yml 이 있는 곳에서 실행해야 합니다.

docker compose up -d manticore

이때 사용하는 "manticore" 값은 위의 docker-compose.yml 에서 "container_name" 부분에 적어준 값을 사용하면 됩니다.

manticore.conf 에서 주의해아할 내용

이 글을 읽는 대상이 manticore 를 mediawiki 를 대상으로 사용할거라면, 대부분은 많은 수정이 필요 없습니다. 언급된 github의 manticore.conf 파일은 한글을 포함한 multibyte 검색을 위해 준비되어 있고, 색인 SQL도 mediawiki 에 맞춰져 있습니다. 다음 값만 주의하면 됩니다.

type            = mysqlsql_host        = localhostsql_user        = mysqlusersql_pass        = mysqluserpasswordsql_db          = wikidbnamesql_port        = 3306sql_query_pre   = SET NAMES utf8

이 글의 manticore 는 mysql(mariadb) 환경을 대상으로 하며, 필자는 mariadb 를 사용해도 별도 이슈 없이 동작합니다.

searchd {    listen          = 0.0.0.0:9306:mysql    listen          = 0.0.0.0:9308:http    listen          = 0.0.0.0:9312    log             = /var/log/manticore/searchd.log    query_log       = /var/log/manticore/query.log    pid_file        = /var/run/manticore/searchd.pid    #set data_dir then rt mode, disable then plain mode    #data_dir       = /var/lib/manticore}

위에서 "data_dir" 이 설정되어 있으면 RT mode, 비설정이면 plain mode 로 동작합니다. 본 설정대로라면 plain mode 이며, 각 mode 는 index 갱신 방식이 다릅니다.

index 생성 후 타입 확인 예시:

curl -s 'http://127.0.0.1:29308/sql' -d 'mode=raw&query=SHOW TABLES'[{"columns":[{"Table":{"type":"string"}},{"Type":{"type":"string"}}],"data":[{"Table":"wiki_incremental","Type":"local"},{"Table":"wiki_main","Type":"local"}],"total":2,"error":"","warning":""}]

docker 포트 매핑에 따라 내부 9308 이 외부 29308 로 노출됩니다. RT 모드에서 생성된 index 는 Type 필드가 "rt" 로 표시됩니다.

manticore 에 검색할 내용을 넣어보자. indexer 의 동작

manticore.conf 에는 두 개의 index 가 정의되어 있습니다.

wiki_main
wiki_incremental

wiki_main 은 주 인덱스, wiki_incremental 은 변경분(증분) 인덱스입니다.

case 별 index

다음 docker 명령은 docker-compose.yml 이 있는 디렉터리에서 실행합니다.

모든 index 갱신

docker exec manticore sh -lc 'indexer --all --rotate'

wiki_main 만 갱신

docker exec manticore sh -lc 'indexer --config /etc/manticoresearch/manticore.conf wiki_main --rotate'

증분만 갱신

docker exec manticore sh -lc 'indexer --config /etc/manticoresearch/manticore.conf wiki_incremental --rotate'

증분을 wiki_main 으로 병합

docker exec manticore sh -lc 'indexer --config /etc/manticoresearch/manticore.conf --merge wiki_main wiki_incremental --rotate'

증분 병합 후 기존 증분 제거

docker exec manticore sh -lc 'indexer --config /etc/manticoresearch/manticore.conf --merge wiki_main wiki_incremental --rotate --drop-src'

위 작업을 cron 등에 등록하여 편집 주기에 맞춰 갱신하는 것이 좋으며, 스크립트로 /usr/local/bin 등에 배치해 운용하는 방식을 권장합니다.

manticore 의 테스트 및 운영을 위한 몇가지 명령행들

manticore docker log 모니터링

docker compose logs -f manticore

manticore docker instance 안쪽의 searchd 접속(SQL)

docker compose exec manticore mysql -h127.0.0.1 -P9306

manticore docker 버전확인

curl -s 'http://127.0.0.1:29308/cli' -d 'show version'

manticore docker instance 의 index 상태 확인

docker compose exec manticore mysql -h127.0.0.1 -P9306 -e "SHOW TABLES; SELECT COUNT(*) FROM wiki_main;"

curl -s 'http://127.0.0.1:29308/sql' -d 'mode=raw&query=SHOW TABLE wiki_main STATUS'

index reload

curl -s 'http://127.0.0.1:29308/sql' -d 'mode=raw&query=RELOAD TABLES'

manticore 검색테스트

curl -s 'http://127.0.0.1:29308/search' -H 'Content-Type: application/json' -d '{"index":"wiki_main","query":{"match":{"*":"검색어"}},"limit":5}'

curl -s 'http://127.0.0.1:29308/sql' \  --data-urlencode "mode=raw" \  --data-urlencode "query=SELECT id, WEIGHT() FROM wiki_main WHERE MATCH('검색어') LIMIT 2"

index 강제삭제

curl -X POST 'http://127.0.0.1:29308/sql' -d 'mode=raw&query=DROP TABLE IF EXISTS wiki_main'

SphinxSearch extension 세팅

https://github.com/onionmixer/SphinxSearch_Extension

위 경로에서 "SphinxSearch" 를 다운로드하여 운영 중인 "~/mediawiki/extensions/" 경로에 배치합니다. 이후 LocalSettings.php 에 다음을 추가합니다.

wfLoadExtension( 'SphinxSearch' );$wgSearchType = 'SphinxMWSearch' ;$wgSphinxSearch_host = 'localhost';$wgSphinxSearch_port = 29312;$wgSphinxSearch_index = "wiki_main";$wgSphinxSearch_index_list = "*";$wgSphinxSearchMWHighlighter = True;$wgSphinxSearch_index_weights = "null";

port 값은 manticore docker 에서 개방한 "sphinx raw api port" (외부 포트)에 맞춰 설정해야 하며, 인덱서를 미리 수행한 상태에서 페이지를 갱신하면 manticore 검색 결과를 사용할 수 있습니다.

=======================================================

wiki page 로도 보실 수 있습니다. 붙여넣기 해야할 부분을 좀 더 편하게 보실 수 있을거에요. :D

https://workspace.onionmixer.net/wiki/Mediawiki_SphinxSearch_Extension

추가 메뉴