G7 통합 검색 확장 모듈 - Glitter Search Hub
그누보드7의 게시글·페이지 및 다양한 확장 모듈의 콘텐츠를 하나의 검색으로 통합하고, OR/AND 복합 검색·정확 구문 검색·관련도 정렬과 검색 제공자 관리·통계·진단 기능을 지원하는 통합 검색 모듈
Glitter Search Hub는 그누보드7(Gnuboard7)의 기존 검색 API와 검색 제공자 구조를 기반으로, 게시글·페이지 및 다양한 확장 모듈의 콘텐츠를 하나의 검색 화면에서 탐색할 수 있도록 지원하는 통합 검색 확장 모듈입니다.
검색 제공자의 자동 발견과 등록, 통합 Registry, 검색 통계, 관리자 진단 기능에 더해 OR/AND 복합 검색, 정확 구문 검색, 짧은 검색어 보완, 검색 대상 선택 및 결과 정렬 기능을 제공합니다.
그누보드7의 코어 검색 API를 대체하지 않고, 공식 검색 훅과 각 콘텐츠 모듈의 검색 계약을 활용하여 검색 기능을 확장합니다.
1. 주요 특징
다양한 콘텐츠를 하나의 검색 화면에서
사용자는 콘텐츠가 어느 모듈에 저장되어 있는지 알지 못하더라도 통합 검색을 통해 관련 정보를 찾을 수 있습니다.
검색 대상은 그누보드7의 기본 콘텐츠와 검색 제공자 계약을 구현한 확장 모듈에 따라 동적으로 구성됩니다.
| 검색 대상 | 검색 유형 | 제공 방식 |
|---|---|---|
| 게시글 | posts |
게시판 모듈의 검색 제공자 |
| 페이지 | pages |
페이지 모듈의 검색 제공자 |
| 확장 콘텐츠 | 제공자별 등록 유형 | 확장 모듈의 검색 제공자 |
| 사용자 정의 콘텐츠 | 제공자별 등록 유형 | 사용자 템플릿 또는 커스텀 검색 제공자 |
실제 검색 대상은 설치된 모듈, 활성화된 검색 제공자, 검색 실행 계약 및 사용자 접근 권한에 따라 달라집니다.
게시글은 제목과 본문을 검색할 수 있으며, 다른 콘텐츠 유형은 해당 제공자가 정의한 검색 필드와 실행 계약에 따라 검색합니다.
이를 통해 기본 게시판 검색을 넘어 다양한 콘텐츠 유형을 통합하는 확장 가능한 검색 환경을 구성할 수 있습니다.
OR/AND 복합 검색
여러 단어를 입력했을 때 검색 조건을 직접 선택할 수 있습니다.
OR 검색
입력한 검색어 중 하나 이상이 일치하는 콘텐츠를 찾습니다.
예시: 설치 설정 오류
설치, 설정, 오류 중 하나 이상의 단어가 일치하는 콘텐츠를 검색합니다.
폭넓게 관련 자료를 탐색하거나 다양한 검색 결과를 확인할 때 유용합니다.
AND 검색
입력한 검색어가 모두 일치하는 콘텐츠를 찾습니다.
예시: 모듈 설치 오류
모듈, 설치, 오류가 모두 검색 대상 콘텐츠에 포함된 결과를 찾습니다.
검색 범위를 좁혀 보다 구체적인 자료를 확인할 수 있습니다.
기본 검색 조건은 OR이며, 사용자가 검색 화면에서 AND로 전환할 수 있습니다.
복합 검색의 실제 적용 범위는 검색 제공자의 구현 및 지원 계약에 따라 달라질 수 있습니다.
정확 구문 검색
큰따옴표로 감싼 검색어는 개별 단어 검색이 아니라 연속된 구문으로 처리합니다.
예시: "모듈 업데이트"
모듈과 업데이트가 서로 다른 위치에 등장하는 결과가 아니라, 해당 구문이 연속해서 등장하는 콘텐츠를 검색합니다.
일반 복합 검색과 정확 구문 검색을 구분하여 검색 목적에 맞는 결과를 얻을 수 있습니다.
정확 구문 검색은 이를 지원하는 검색 엔진 및 제공자 경로에 적용됩니다.
짧은 검색어 지원
MariaDB의 기본 FULLTEXT 검색은 토큰 길이와 색인 설정에 따라 짧은 검색어가 누락될 수 있습니다.
Glitter Search Hub는 이를 보완하기 위해 검색어의 특성에 따라 FULLTEXT와 LIKE 검색을 함께 활용합니다.
예를 들어 API, DB, UI처럼 짧은 검색어도 게시글 제목과 본문에서 찾을 수 있도록 보완합니다.
이 기능은 MariaDB 검색 엔진 확장 경로에 적용되며, 모든 데이터베이스와 검색 제공자에 동일한 최적화가 적용된다는 의미는 아닙니다.
검색 대상 및 정렬 선택
검색 화면에서 다음 조건을 지정할 수 있습니다.
- 검색 대상: 전체 또는 개별 콘텐츠 유형
- 검색 조건: OR 또는 AND
- 정렬: 관련도순, 최신순, 오래된순
선택한 조건은 URL 검색 파라미터에 반영되어 검색 결과와 페이지 이동에 유지됩니다.
필터가 변경되면 페이지 및 커서 상태를 초기화하여 새로운 검색 조건으로 결과를 다시 조회합니다.
2. 검색 제공자 Registry
Glitter Search Hub의 핵심 구조는 검색 제공자 Registry입니다.
Registry는 검색 제공자의 소유자, 검색 유형, 활성화 상태, 표시 순서, 실행 계약 및 사용 가능 여부를 통합 관리합니다.
활성 모듈 제공자 자동 발견
활성 모듈이 getSearchProviders() 계약으로 검색 제공자를 선언하면 해당 선언을 발견하고 Registry에 반영할 수 있습니다.
기존 관리자 설정이 존재하면 이를 우선 적용합니다.
단, 제공자 선언만으로 검색 기능이 생성되는 것은 아닙니다. 실제 결과를 반환하려면 지원되는 검색 실행 계약이 구현되어 있어야 합니다.
사용자 템플릿 제공자 지원
활성 사용자 템플릿의 search-providers.json 선언을 통해 검색 제공자를 발견할 수 있습니다.
선언 형식, 소유권, 식별자 충돌, 검색 실행 계약 등을 검증하며, 실행 계약이 없는 제공자를 실제 검색 가능한 제공자로 활성화하지 않습니다.
이를 통해 모듈뿐 아니라 사용자 템플릿에서도 검색 제공자를 선언하고 통합 검색 구조에 참여할 수 있습니다.
호스트 검색 엔드포인트 탐색
그누보드7 호스트에 등록된 검색 관련 로컬 GET 라우트를 탐색하여 관리자에게 진단 정보를 제공합니다.
엔드포인트 URI, HTTP 메서드, 인증 필요 여부, 소속 모듈 추정 정보, Registry 연결 상태 및 지원 제외 사유 등을 확인할 수 있습니다.
이 기능은 읽기 전용 진단 기능이며, 외부 웹사이트 크롤링이나 임의 엔드포인트 실행 기능이 아닙니다.
3. 통합 검색 API
Glitter Search Hub는 그누보드7의 공식 검색 API를 활용합니다.
GET /api/search
주요 파라미터는 다음과 같습니다.
| 파라미터 | 설명 |
|---|---|
q |
검색어 |
type |
검색 대상 |
operator |
OR/AND 검색 조건 |
sort |
관련도·최신순·오래된순 |
page |
결과 페이지 |
per_page |
페이지당 결과 수 |
검색 요청 예시:
/api/search?q=API&type=all&operator=or&sort=relevance&page=1
/api/search?q=모듈+설치&type=posts&operator=and&sort=latest&page=1
검색어의 앞뒤 공백과 연속 공백을 정규화하고, 일반 검색어를 토큰으로 분석합니다.
검색어 길이와 토큰 수에 제한을 두며, SQL 파라미터 바인딩을 유지합니다.
검색 제공자별 관련도 산정 방식은 서로 다를 수 있으므로 모든 제공자의 점수를 동일한 기준으로 임의 합산하지 않습니다.
통합 검색 API는 검색 제공자의 실행 계약과 접근 권한을 존중하며, 결과를 콘텐츠 유형별로 구분하여 처리합니다.
4. 사용자 검색 화면
Glitter Search Hub는 사용자에게 통합 검색 인터페이스를 제공할 수 있도록 검색 레이아웃과 관련 리소스를 제공합니다.
검색 화면은 일반적으로 다음 요소로 구성됩니다.
- 검색어 입력창 및 검색 실행 버튼
- 검색 대상 선택
- OR/AND 검색 조건 선택
- 관련도순·최신순·오래된순 정렬
- 검색 결과 건수 및 콘텐츠 유형별 결과
- 결과 제목·요약 및 원본 콘텐츠 연결
- 페이지네이션 및 검색 조건 유지
검색 조건을 URL에 유지하므로 동일한 조건의 검색 페이지를 다시 열거나 공유할 수 있습니다.
검색 화면은 그누보드7의 레이아웃 시스템을 활용하며, 활성 사용자 템플릿에 따라 디자인과 배치가 달라질 수 있습니다.
모듈이 제공하는 기본 검색 레이아웃과 사용자 템플릿에서 구성한 검색 화면은 구분됩니다.
따라서 모듈을 설치한다고 모든 사용자 템플릿에 동일한 화면이 자동 적용되는 것은 아닙니다.
5. 관리자 기능
Glitter Search Hub는 검색 기능뿐 아니라 검색 운영 상태를 확인할 수 있는 관리자 화면을 제공합니다.
| 메뉴 | 경로 | 기능 |
|---|---|---|
| 대시보드 | /admin/search-hub/dashboard |
제공자 및 검색 활동 현황 |
| 검색 제공자 | /admin/search-hub/providers |
Registry 관리 및 제공자 탐색 |
| 검색 통계 | /admin/search-hub/analytics |
검색 요청·성공·실패 통계 |
| 검색 진단 | /admin/search-hub/diagnostics |
API·DB·제공자 상태 확인 |
| 설정 | /admin/search-hub/settings |
검색 운영 설정 확인 |
검색 제공자 관리
등록된 검색 제공자의 유형, 소유자, 활성화 상태 및 검색 실행 가능 여부를 확인하고 관리합니다.
검색 통계
검색 요청 수, 성공·실패 수, 결과가 없는 요청, 검색 유형별 및 날짜별 활동 등을 집계합니다.
이를 통해 검색 이용 현황과 검색 결과 제공 상태를 확인할 수 있습니다.
검색 진단
API 경로, 데이터베이스 연결, 제공자 사용 가능 여부, 필수 테이블 존재 여부 등을 확인합니다.
검색 제공자 등록 상태와 실행 계약의 문제를 점검하는 데 활용할 수 있습니다.
6. 검색 권한과 보안
통합 검색은 각 콘텐츠 제공자의 기존 공개 범위와 접근 권한을 존중합니다.
- 비공개 또는 접근이 제한된 콘텐츠의 권한 검사 유지
- 게시글의 공개·삭제·비밀글 및 읽기 권한 조건 유지
- 확장 콘텐츠 제공자의 공개 범위와 접근 정책 유지
- 관리자·내부 엔드포인트의 공개 검색 등록 제한
- 검색어 SQL 파라미터 바인딩 및 LIKE 특수문자 처리
- 검색 제공자 선언과 실행 계약 분리
검색 제공자를 활성화하는 것만으로 원본 모듈의 권한 검사를 우회하지 않습니다.
확장 모듈이 검색 제공자를 구현하는 경우에도 해당 모듈의 기존 권한 및 공개 범위 정책을 유지해야 합니다.
7. 확장 구조 및 호환성
Glitter Search Hub는 특정 웹사이트나 개별 확장 모듈에 종속되지 않는 검색 제공자 기반 구조를 지향합니다.
기본 검색 제공자뿐 아니라 공식 검색 계약을 구현한 확장 모듈과 사용자 템플릿도 통합 검색에 참여할 수 있습니다.
코어 검색 API 유지
그누보드7의 기존 /api/search 엔드포인트를 활용하며, 별도의 독립 검색 API로 코어 기능을 대체하지 않습니다.
공식 검색 훅 활용
그누보드7의 공개 검색 훅과 제공자 계약을 활용하여 검색 기능을 확장합니다.
검색 제공자별 독립성
각 제공자는 자신의 콘텐츠 구조, 검색 필드, 접근 권한 및 관련도 계산 방식을 유지할 수 있습니다.
선택적 검색 기능 확장
OR/AND 복합 검색, 정확 구문 검색 및 짧은 검색어 보완 기능은 해당 기능을 지원하는 검색 엔진과 제공자 계약에 따라 적용됩니다.
확장 모듈이 추가되더라도 모든 검색 제공자의 검색 의미와 결과 처리 방식이 자동으로 동일해지는 것은 아닙니다.
공식 모듈 생명주기 지원
모듈의 설치와 업데이트는 그누보드7의 공식 모듈 관리 및 업데이트 절차를 통해 수행합니다.
업데이트 시 모듈 버전, 레이아웃, 캐시 및 설치 파일 상태를 확인할 수 있습니다.
8. 버전 및 변경 이력
Glitter Search Hub는 초기 검색 제공자 관리 기능을 기반으로 검색어 처리, 검색 조건 제어 및 다양한 검색 제공자 연동 기능을 단계적으로 확장해 왔습니다.
주요 개선 내용은 다음과 같습니다.
| 기능 영역 | 주요 개선 |
|---|---|
| 검색 제공자 | 자동 발견, Registry 등록 및 관리 |
| 검색어 처리 | 공백 정규화, 복합 검색어 분석 |
| 검색 조건 | OR/AND 선택 및 정확 구문 검색 |
| 검색 엔진 | MariaDB 짧은 검색어 보완 |
| 검색 결과 | 관련도 정렬, 최신순·오래된순 정렬 |
| 사용자 화면 | 검색 필터, 검색 조건 유지, 반응형 레이아웃 |
| 운영 관리 | 검색 통계 및 관리자 진단 |
세부 변경 이력과 기능별 도입 버전은 해당 배포본의 CHANGELOG.md를 기준으로 확인할 수 있습니다.
현재 설치 가능한 버전과 공개 릴리스에 포함된 기능은 module.json 및 GitHub 릴리스 자산을 기준으로 확인해야 합니다.
9. 설치
그누보드7 관리자 모듈 관리 기능에서 GitHub 저장소 또는 ZIP 패키지를 통해 설치할 수 있습니다.
GitHub 저장소
https://github.com/glitter-node/glitter-search_hub
릴리스 목록
https://github.com/glitter-node/glitter-search_hub/releases
설치 전에 그누보드7 버전, PHP 환경, 데이터베이스 및 연동 모듈의 호환성을 확인해야 합니다.
설치 이후에는 검색 제공자의 등록 상태, 실행 계약, 접근 권한 및 검색 API 동작 여부를 확인하는 것이 좋습니다.
사용자 템플릿에서 별도의 검색 화면을 구성하는 경우에는 해당 템플릿의 레이아웃 및 스타일 적용 상태도 확인해야 합니다.
10. 라이선스
MIT License
Copyright (c) 2026 Glitter.kr
Glitter Search Hub는 MIT 라이선스 기반의 오픈소스 프로젝트입니다.
프로젝트 정보
| 항목 | 내용 |
|---|---|
| 프로젝트 | Glitter Search Hub |
| 플랫폼 | Gnuboard7 |
| 분류 | 통합 검색 확장 모듈 |
| 검색 API | /api/search |
| 검색 대상 | 기본 콘텐츠 및 확장 검색 제공자 |
| 검색 조건 | OR / AND / 정확 구문 |
| 검색 정렬 | 관련도순 / 최신순 / 오래된순 |
| 제공자 구조 | 모듈·템플릿·호스트 검색 Registry |
| 검색 엔진 확장 | MariaDB FULLTEXT 및 LIKE 보완 |
| 관리자 기능 | 제공자 관리, 통계, 진단, 설정 |
| 확장 방식 | 공식 검색 훅 및 제공자 계약 |
| 라이선스 | MIT |
| 개발 | Glitter.kr |
*Glitter Search Hub는 그누보드7의 기존 검색 기능을 존중하면서 다양한 콘텐츠 제공자를 하나의 검색 환경으로 연결하고, 검색 조건 제어와 운영 관리 기능을 확장하는 통합 검색 플랫폼입니다.
이 개발자의 다른 프로젝트