Onionmixer: 오타 수정

2025-10-03T09:21:34Z

오타 수정

← Older revision		Revision as of 09:21, 3 October 2025
Line 1:		Line 1:
	;mediaiwki 1.34 이상에서 SphinxSearch Extension 사용하기		;mediaiwki 1.43 이상에서 SphinxSearch Extension 사용하기

	==배경사양==		==배경사양==

Onionmixer: mediaiwki 1.34 이상에서 SphinxSearch Extension 사용하기 내용 추가

2025-10-01T15:14:33Z

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

New page

;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 세팅 에서 주의할점===

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

==manticore 세팅==

===manticore docker 작업===

file :: docker-compose.yml

<pre>
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:
- webnet

networks:
webnet:
driver: bridge
</pre>

이상의 정보로 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 이 있는 곳에서 실행해야 합니다.

<pre>
docker compose up -d manticore
</pre>

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

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

이 글을 읽는 당신이 manticore 를 mediawiki 를 대상으로 사용할거라면, 대부분의 앖은 수정할 필요가 없습니다. 이 글에서 언급된 github 에서 얻은 manticore.conf 파일의 내용은 거의 변경할 필요가 없습니다. manticore.conf 는 이미 한글을 포함한 multibyte 검색을 위해 준비된 값을 세팅하고 있고, 검색엔진 색인에 사용할 SQL 은 이미 mediawiki 에 맞춰져 있습니다. 당신은 다음의 값만 주의하면 됩니다.

<pre>
type = mysql
sql_host = localhost
sql_user = mysqluser
sql_pass = mysqluserpassword
sql_db = wikidbname
sql_port = 3306
sql_query_pre = SET NAMES utf8
</pre>

이 글의 manticore 는 mysql(mariadb) 로 운영되는 환경을 대상으로 하고 있습니다. 때문에 manticore.conf 설정파일도 mysql 에 맞춰져 있습니다. 물론 저는 mariadb 를 사용하고 있으며, 별도의 이상은 없이 사용할 수 있습니다.

manticore.conf 내에서 주의해야할 부분이 하나 더 있습니다.

<pre>
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
}
</pre>

이 내용을 보면 "data_dir" 에 대한 부분이 있습니다. data_dir 이 설정되어 있으면 manticore 는 RT mode 로 동작하며, 설정되어 있지 않으면 plain mode 로 동작합니다. 제가 올린 설정대로라면 plain mode 로 동작하게 되며, 각 mode 는 index 를 갱신하는 경우에 대한 차이점을 가지게 됩니다.

manticore 의 문서에 따르면 manticore 를 rt 와 plain 을 혼용해서 사용하지 않기를 권장하고 있습니다. 다만 그냥 manticure 가 구동되었을 때에는 이를 구별하기가 쉽지 않으며, 이후에 index 를 생성한 이후에 관련된 내용을 확인할 수 있습니다. 아래는 index 를 확인한 경우에 대한 결과입니다.

<pre>
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":""
}]
</pre>

docker 설정에 의해 내부의 9308 port 는 29308 port 로 docker instance 의 외부에서 접근할 수 있습니다. manticore 는 이렇게 curl 을 통해서 manticore 의 상황을 알아볼 수 있습니다. RT mode 에서 생성된 index 는 "Type" 부분에 "rt" 라는 값이 나오게 됩니다.

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

manticore.conf 에 보면 index 가 2개로 설정되어 있습니다.

* wiki_main
* wiki_incremental

wiki_main 은 주 index 고 wiki_incremental 은 주 index 외의 변경된 부분만 index 를 만드는것을 의미합니다.

====case 별 index====

아래의 docker 명령은 docker-compose.yml 이 있는 디렉터리애서 진행시켜야 합니다.

* 모든 index 갱신

<pre>
docker exec manticore sh -lc 'indexer --all --rotate'
</pre>

* wiki_main 만 갱신

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

* 증분만 갱신

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

* 증분을 wiki_main 으로 병합

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

* 증분을 wiki_main 으로 병합한뒤 기존의 증분을 제거

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

이상의 내용을 cron 등에 등록해서 mediawiki 의 자료 편집 주기에 따라 필요한 만큼 manticore 의 index 갱신을 해줘야 manticore 의 색인 내용이 의미있게 동작할 수 있음을 꼭 기억하시고, 위의 스크립트들은 bash script 등으로 /usr/local/bin 등에 넣고 동작시키는 것이 좋습니다.

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

====manticore docker log 모니터링====

<pre>
docker compose logs -f manticore
</pre>

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

<pre>
docker compose exec manticore mysql -h127.0.0.1 -P9306
</pre>

====manticore docker 버전확인====

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

====manticore docker instance 의 index 상태 확인====

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

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

====index reload====

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

====manticore 검색테스트====

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

<pre>
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"
</pre>

====index 강제삭제====

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

==SphinxSearch extension 세팅==

* https://github.com/onionmixer/SphinxSearch_Extension

위의 경로에서 "SphinxSearch" 부분을 다운로드 받아서 운영하고 있는 "~/mediawiki/extensions/" 안쪽으로 넣어줍니다.

이후 운영하고 있는 mediawiki 의 "LocalSettings.php" 부분에 다음의 내용을 추가합니다.

<pre>
wfLoadExtension( 'SphinxSearch' );
$wgSearchType = 'SphinxMWSearch' ;

$wgSphinxSearch_host = 'localhost';
$wgSphinxSearch_port = 29312;
$wgSphinxSearch_index = "wiki_main";
$wgSphinxSearch_index_list = "*";
$wgSphinxSearchMWHighlighter = True;
$wgSphinxSearch_index_weights = "null";
</pre>

port 부분에 주의해주세요. manticore docker 에서 설정한 3개의 port 중에 "sphinx raw api port" 으로 정의한 docker 의 외부 port 를 연결해 주어야 합니다.

이렇게 설정한 다음 mediawiki 의 page 를 refresh 하면(물론 그 이전에 indexer 를 돌렸다는 전제하에) mediawiki 에서 manticore 의 검색엔진 결과를 사용할 수 있습니다.

Mediawiki SphinxSearch Extension - Revision history

Onionmixer: 오타 수정

Onionmixer: mediaiwki 1.34 이상에서 SphinxSearch Extension 사용하기 내용 추가