Postcodify 매뉴얼

검색서버 구축 안내

프로그램 다운로드

검색서버를 직접 구축하려면 먼저 GitHub에서 Postcodify의 서버용 프로그램을 다운로드해야 합니다.

리눅스 터미널에서는 아래의 명령으로 다운로드할 수 있습니다.

git clone https://github.com/kijin/postcodify.git

만약 git을 사용할 수 없는 경우 GitHub 화면 오른쪽 아래의 “Download ZIP” 버튼을 클릭해도 됩니다.

DB 구축 방법

서버용 프로그램을 다운로드한 후에는 검색에 사용할 DB를 구축해야 합니다. DB를 구축하는 데는 두 가지 방법이 있습니다. 각각 장단점이 있으니 아래의 내용을 주의깊게 읽어 주시기 바랍니다.

  1. Postcodify 개발자가 생성해 놓은 DB 덤프를 서버에 복사하여 사용
  2. 행정자치부, 우체국 등에서 제공하는 DB를 직접 변환하여 사용

DB 덤프 사용하기

장점

  • DB 변환 프로그램(인덱서)을 구동하기 위한 복잡한 환경을 구축하지 않아도 됩니다. 인덱서 구동이 불가능한 PHP 5.2 이하의 환경, 인덱서 구동에 긴 시간이 걸리는 구형 서버나 가상서버 등에서도 쉽게 검색서버 구축이 가능합니다.
  • SQLite는 압축만 풀면 1분 이내에 사용할 수 있으므로 신속하게 검색서버를 구축할 수 있습니다.
  • 최적의 환경에서 Postcodify 개발자가 직접 생성한 DB이므로 데이터 누락이나 오류의 가능성이 낮습니다.

단점

  • 개발자의 사정으로 DB 업데이트가 지연 또는 중단될 수도 있습니다. 이 경우 DB를 직접 변환하여 사용하실 준비가 되어 있어야 합니다.

DB 버전 및 종류 선택

DB 덤프는 포에시스 파일서버에 부정기적으로 (1년에 몇 차례) 업데이트됩니다. 날짜순으로 정렬되어 있으니 가장 최근의 덤프를 다운로드하시면 됩니다. 단, DB 덤프의 버전과 서버측 검색 API의 버전이 크게 다를 경우 호환이 되지 않을 수도 있으니 주의해 주십시오.

DB 덤프에는 두 가지가 있습니다.

  • mysqldump로 표시된 덤프는 MySQL 5.1 이상에서 사용하실 수 있습니다. 압축 파일의 용량은 250MB 내외, 압축 해제 후의 용량은 2GB, 복구가 완료된 후 DB의 용량은 4GB 내외입니다.
  • sqlite로 표시된 덤프는 압축만 풀면 별도의 복구 과정 없이 그대로 사용하실 수 있습니다. 압축 파일의 용량은 450MB 내외, 압축 해제 후의 용량은 3GB 내외입니다.

모든 파일은 용량을 최소화하기 위해 xz 포맷으로 압축하여 제공합니다. 리눅스 환경에서는 xz -d 명령으로 압축을 풀 수 있고, 윈도우 환경에서는 7-Zip, 반디집 등의 무료 유틸리티를 사용하시면 됩니다. (알집은 xz 포맷을 열지 못합니다.)

하루 100만 건 이상의 검색이 필요하거나 주소 신설·변경 내역을 수시로 적용하기를 원하신다면 MySQL DB 덤프를 사용하여 검색서버를 구축한 후, 인덱서와 함께 제공되는 업데이트 프로그램을 사용하시기를 권장합니다. 그 외의 경우에는 SQLite를 사용하셔도 무방합니다. 주소 검색은 SELECT 쿼리만 사용하므로 MySQL과 SQLite의 성능 차이가 거의 없습니다.

MySQL 덤프 사용법

콘솔 또는 SSH 쉘에서 아래의 코드를 참조하여 압축을 풀고 DB에 복구하시면 됩니다. 복구 과정은 서버 사양에 따라 최소 10분에서 최대 3시간 이상 걸릴 수 있으니 유의하시기 바랍니다.

xz -d postcodify.20150531.v3.mysqldump.xz
mysql -u아이디 -p암호 DB이름 < postcodify.20150531.v3.mysqldump

DB를 복구한 후에는 인덱서 구동 매뉴얼 페이지의 “테스트” 부분을 참조하여 DB가 정상적으로 복구되었는지 확인하고, lib 폴더 내의 config-example.php 파일을 config.php로 복사하여 DB 접속 정보를 입력하시기 바랍니다.

define('POSTCODIFY_DB_DRIVER', 'mysql');
define('POSTCODIFY_DB_DBNAME', 'DB이름');
define('POSTCODIFY_DB_HOST', 'localhost');
define('POSTCODIFY_DB_PORT', 3306);
define('POSTCODIFY_DB_USER', '아이디');
define('POSTCODIFY_DB_PASS', '암호');

SQLite 파일 사용법

압축만 풀면 그대로 사용 가능합니다.

xz -d postcodify.20150531.v3.sqlite.xz

압축을 푼 후에는 lib 폴더 내의 config-example.php 파일을 config.php로 복사하여 아래와 같이 DB 접속 정보를 입력하시기 바랍니다.

define('POSTCODIFY_DB_DRIVER', 'sqlite');
define('POSTCODIFY_DB_DBNAME', 'DB파일경로');
define('POSTCODIFY_DB_HOST', null);
define('POSTCODIFY_DB_PORT', null);
define('POSTCODIFY_DB_USER', null);
define('POSTCODIFY_DB_PASS', null);

업데이트 적용

MySQL DB를 업데이트하려면 업데이트 적용 페이지를 참조하십시오. SQLite는 업데이트가 되지 않습니다.

직접 변환하기

장점

  • 개발자가 길을 가다가 벼락을 맞거나, 그 밖의 이유로 DB 업데이트가 중단되는 일이 발생하더라도 행정자치부, 우체국 등에서 제공하는 데이터를 사용하여 검색 서버를 지속적으로 업데이트할 수 있습니다.
  • Postcodify의 구동 방식을 공부하고 싶은 분들께 추천합니다.

단점

  • 인덱서를 구동할 수 있도록 서버 환경을 준비해야 합니다. PHP 5.2 이하 버전에서는 구동이 불가능합니다.
  • 많은 시간과 서버 자원(CPU, 메모리, 디스크 I/O 등)이 소요됩니다. 다른 서비스를 운영중인 서버에서는 인덱서를 구동하지 않는 것이 좋으며, 가상서버에서 구동할 경우 다른 사용자에게 심각한 영향을 줄 수도 있습니다.
  • 정상적으로 동작하지 않을 경우 데이터가 누락되거나 잘못 입력될 수 있습니다. 새주소 DB는 데이터 양이 많으므로 일부가 누락되거나 잘못 입력되더라도 쉽게 찾을 수 없습니다.

사용법

DB를 직접 변환하려면 데이터 파일을 다운로드한 후 인덱서 구동 매뉴얼 페이지를 참조하여 인덱서 프로그램을 구동하십시오.