G7 게시글·페이지 검색 모듈 - Glitter Search Hub

Glitter Search Hub는 그누보드7(Gnuboard7)의 기존 검색 기능을 활용하여 여러 콘텐츠 유형을 하나의 검색 체계로 연결하고, 검색 제공자의 자동 발견·등록, 운영 관리, 검색 통계 및 시스템 진단 기능을 제공하는 확장 모듈입니다.

새로운 검색 엔진을 개발하거나 그누보드7의 기본 검색 API를 대체하지 않습니다.

대신 기존 검색 구조를 기반으로 활성 모듈, 사용자 템플릿, 호스트 검색 엔드포인트를 통합 관리하는 검색 제공자 Registry를 구축하여 사이트의 검색 대상을 체계적으로 확장할 수 있도록 설계했습니다.

초기 기능은 게시글과 페이지 검색을 중심으로 구성되었으며, 이후 모듈 검색 제공자 자동 발견, 템플릿 제공자 선언 지원, 호스트 검색 엔드포인트 탐색 기능으로 확장되었습니다.

Glitter Learning과 연동한 운영 환경에서는 강좌와 차시 검색도 지원합니다.

버전 안내: 기존 공개 배포 기준 버전은 v0.1.7입니다. 아래에서 설명하는 확장 기능은 이후 운영 번들에 구현·반영된 내용을 포함합니다. GitHub 릴리스에 동일한 기능이 배포되었는지는 해당 릴리스의 소스 및 변경 이력을 확인해야 합니다.

1. Glitter Search Hub가 필요한 이유

그누보드7 기반 웹사이트에는 다양한 콘텐츠가 존재합니다.

게시판에는 공지사항과 일반 게시글이 있고, 페이지 모듈에는 서비스 소개나 정책 문서가 저장됩니다. 학습 관리 모듈을 사용한다면 강좌와 차시 같은 별도의 콘텐츠도 존재할 수 있습니다.

사용자는 원하는 정보가 어느 모듈에 저장되어 있는지 알기 어렵습니다.

Glitter Search Hub는 각 모듈이 제공하는 검색 기능을 하나의 검색 체계로 연결하고, 운영자가 검색 제공자의 상태와 검색 활동을 관리할 수 있도록 지원합니다.

그누보드7 기본 검색과의 차이

Glitter Search Hub를 설치한다고 검색 정확도나 검색 속도가 자동으로 향상되는 것은 아닙니다.

이 모듈의 핵심 가치는 검색 기능의 통합 관리와 확장 가능한 제공자 구조에 있습니다.

2. 검색 제공자 통합 Registry

Glitter Search Hub는 검색 제공자 Registry를 중심으로 동작합니다.

Registry는 검색 제공자의 소유자, 검색 유형, 활성화 상태, 검색 실행 계약 및 사용 가능 여부를 관리합니다.

현재 구현 구조에서는 세 가지 출처를 구분합니다.

2.1 활성 모듈 검색 제공자

활성 모듈이 getSearchProviders() 계약을 통해 검색 제공자를 선언하면 Search Hub가 이를 발견하고 Registry에 반영합니다.

선언 정보에는 다음 항목이 포함됩니다.

• 제공자 ID
• 소유 모듈 ID
• 검색 유형
• 제공자 표시 이름
• 기본 활성화 여부
• 기본 표시 순서

유효한 선언은 자동 발견·등록되며, 기존 관리자 설정이 있으면 해당 설정을 우선 적용합니다.

다만 제공자 선언만으로 검색 실행 기능이 자동 생성되는 것은 아닙니다.

실제 검색 결과를 반환하려면 해당 모듈이 그누보드7의 검색 훅 등 지원되는 검색 실행 계약을 구현해야 합니다.

2.2 활성 사용자 템플릿 검색 제공자

Glitter Search Hub는 활성 사용자 템플릿이 선언한 검색 제공자도 발견할 수 있도록 확장되었습니다.

활성 사용자 템플릿은 search-providers.json 선언 파일을 통해 검색 제공자 메타데이터를 제공할 수 있습니다.

Search Hub는 다음 사항을 확인합니다.

• 현재 활성 사용자 템플릿 여부
• 선언 파일 경로의 안전성
• JSON 선언 형식
• 제공자 ID와 검색 유형 충돌
• 템플릿 소유권
• 검색 실행 계약 유무

검색 실행 계약이 확인되지 않은 제공자는 진단 대상으로 표시할 수 있지만, 실제 검색 가능한 제공자로 활성화하지 않습니다.

템플릿 선언 파일에서 임의 PHP 코드, 클래스 또는 외부 URL을 실행하는 방식은 지원하지 않습니다.

중요: 사용자 템플릿의 일반 페이지나 URL이 모두 검색 대상으로 자동 등록되는 것은 아닙니다. 명시적 선언과 실제 검색 실행 계약이 필요합니다.

2.3 호스트 검색 엔드포인트 탐색

Search Hub는 그누보드7 호스트에 등록된 검색 관련 라우트를 탐색할 수 있습니다.

탐색 대상은 Laravel 라우트 컬렉션에 등록된 로컬 GET 라우트입니다.

URI, 라우트명, 컨트롤러 액션 등의 검색 관련 신호를 바탕으로 후보를 식별하고 다음 정보를 관리자에게 제공합니다.

• 엔드포인트 URI 및 라우트명
• HTTP 메서드
• 소속 모듈 추정 정보
• 인증 필요 여부
• 관리자 전용 여부
• 검색 계약 상태
• 기존 Registry 연결 상태
• 지원 제외 사유

이 과정에서 외부 웹사이트를 크롤링하거나 임의의 엔드포인트를 실행하지 않습니다.

관리자·내부 검색 라우트는 공개 검색 제공자로 취급하지 않습니다.

현재 관리자 화면의 호스트 탐색 기능은 읽기 전용 진단 기능으로 제공되며, 수동 제공자 추가 버튼은 표시하지 않습니다.

라우트를 발견했다고 해서 해당 라우트가 자동으로 검색 제공자로 등록되는 것은 아닙니다.

3. 지원하는 검색 대상

기본 검색 대상은 게시글과 페이지입니다.

Glitter Learning 연동 운영 환경에서는 강좌와 차시도 검색할 수 있습니다.

게시글 검색

그누보드7의 sirsoft-board 모듈이 제공하는 검색 기능을 활용합니다.

게시판 공개 범위와 콘텐츠 접근 권한 등 기존 정책을 따릅니다.

페이지 검색

sirsoft-page 모듈이 제공하는 검색 기능을 활용합니다.

서비스 소개, 이용 안내, 정책 문서 등 페이지 콘텐츠를 검색할 수 있습니다.

강좌 검색

Glitter Learning 모듈이 제공하는 공개 강좌를 검색할 수 있습니다.

강좌 제목과 설명 등 모듈이 제공하는 검색 대상 필드를 활용합니다.

차시 검색

Glitter Learning 모듈의 차시 검색 기능과 연동합니다.

차시 검색은 접근 권한을 고려하며, 로그인 여부와 강좌 수강 상태에 따라 검색 가능 범위가 달라집니다.

관리자가 Search Hub에서 차시 제공자를 활성화하더라도 원본 학습 모듈의 권한 검사를 우회하지 않습니다.

강좌와 차시 검색은 Glitter Learning 연동 사례입니다. Search Hub만 설치하면 모든 LMS 또는 외부 학습 모듈이 자동으로 검색되는 것은 아닙니다.

4. 주요 기능

4.1 통합 검색

기존 그누보드7 검색 API를 활용합니다.

공개 검색 API

GET /api/search

주요 검색 파라미터:

예시:

/api/search?q=HTML&type=courses

/api/search?q=공지사항&type=posts

지원되는 검색 유형은 현재 활성화되고 사용 가능한 검색 제공자에 따라 달라질 수 있습니다.

모듈 검색 페이지 /search-hub를 사용할 수도 있으며, 사용자 템플릿에서 /api/search를 호출하여 별도의 검색 화면을 구성할 수도 있습니다.

Glitter Search Hub는 기존 /api/search를 대체하는 독립 검색 서버를 운영하지 않습니다.

4.2 검색 제공자 자동 발견 및 관리

관리자는 /admin/search-hub/providers에서 검색 제공자의 상태를 확인할 수 있습니다.

주요 관리 항목:

• 제공자 이름
• 소유 유형 및 소유 ID
• 검색 유형
• 사용 가능 상태
• 검색 응답 포함 여부
• 표시 순서
• 활성 사용자 템플릿 제공자 상태

활성 모듈과 사용자 템플릿이 선언한 제공자를 자동 발견하고, 기존 설정을 우선 적용하도록 설계되었습니다.

제공자가 비활성화되거나 검색 실행 계약이 유효하지 않으면 사용 가능 상태에 반영합니다.

4.3 호스트 검색 엔드포인트 진단

검색 제공자 관리자 화면에서 호스트 검색 엔드포인트 탐색 결과를 확인할 수 있습니다.

현재 운영 환경에서 확인된 탐색 결과는 다음과 같습니다.

• 검색 관련 후보 10개
• 기존 검색 진입점 연결 1개
• 별도 등록 가능 후보 0개
• 관리자·내부 등 지원 제외 후보 9개

/api/search는 기존 제공자를 연결하는 코어 검색 진입점으로 표시됩니다.

이 숫자는 특정 운영 환경의 확인 결과이며, 다른 그누보드7 설치 환경에서는 달라질 수 있습니다.

4.4 검색 통계

검색 요청 및 처리 결과를 집계합니다.

주요 통계:

• 검색 요청 수
• 성공한 요청 수
• 실패한 요청 수
• 검색 결과가 없는 요청 수
• 검색 유형별 통계
• 날짜별 검색 활동

관리자 검색 통계 화면에서는 날짜를 YYYY-MM-DD 형식으로 표시합니다.

검색 성공은 요청이 정상 처리되었다는 의미이며, 반드시 검색 결과가 존재한다는 뜻은 아닙니다.

검색 통계는 실제 검색 이벤트가 기록된 경우에 누적됩니다.

4.5 검색 시스템 진단

관리자 진단 화면에서 다음 항목을 확인할 수 있습니다.

• 검색 API 경로
• 데이터베이스 연결 상태
• 사용 가능한 검색 제공자 수
• 검색 관련 필수 테이블 존재 여부

진단 화면은 기본 시스템 구성을 확인하기 위한 도구입니다.

진단이 정상이라고 해서 모든 검색어의 결과 정확성이나 사용자 브라우저의 검색 경험까지 보장하는 것은 아닙니다.

4.6 관리자 대시보드 및 설정

대시보드에서는 사용 가능한 검색 제공자 수와 최근 검색 활동을 확인할 수 있습니다.

설정 화면에서는 운영 정책과 관련된 현재 설정 상태를 확인할 수 있습니다.

실제 설정 항목과 사용 가능 여부는 설치된 모듈 버전 및 운영 환경에 따라 달라질 수 있습니다.

5. 관리자 메뉴

Glitter Search Hub를 설치하고 활성화하면 관리자 메뉴에 통합 검색 항목이 제공됩니다.

관리자 화면은 그누보드7의 기존 인증·권한 및 관리자 레이아웃 체계를 사용합니다.

한국어와 영어 언어 리소스를 제공합니다.

6. 사용자 검색 화면 구성

Glitter Search Hub의 검색 기능과 사용자에게 표시되는 검색 화면은 서로 구분됩니다.

Search Hub는 검색 제공자와 검색 관리 기능을 담당하고, 사용자 템플릿은 검색창과 검색 결과 화면을 구성할 수 있습니다.

방법 A. Search Hub 기본 검색 페이지

모듈이 제공하는 /search-hub 경로를 사용할 수 있습니다.

사용자 템플릿 메뉴에 해당 링크를 연결하는 방식입니다.

방법 B. 기존 사용자 템플릿에 검색 기능 연결

기존 사용자 템플릿의 헤더나 메뉴에 검색창을 배치하고 /api/search를 활용할 수 있습니다.

검색어 전달, 결과 표시, 검색 유형 선택 등은 템플릿의 구조에 맞춰 구현합니다.

방법 C. 사용자 템플릿 전용 검색 결과 화면

사용자 템플릿에서 별도의 검색 결과 화면을 만들 수 있습니다.

예를 들어 다음과 같은 기능을 구성할 수 있습니다.

• 전체 검색
• 게시글 검색
• 페이지 검색
• 강좌 검색
• 차시 검색
• 검색 유형별 탭
• 결과 페이지 이동

실제 지원하는 검색 유형은 연결된 모듈과 제공자 상태에 따라 달라집니다.

Search Hub를 설치한다고 모든 사용자 템플릿에 검색 화면이 자동으로 추가되는 것은 아닙니다.

실제 연동 사례: Glitter Learning Academy

Glitter Learning Academy 사용자 템플릿은 /search 화면을 통해 검색 기능을 제공합니다.

Glitter Learning과 Search Hub를 연동하여 게시글, 페이지, 강좌, 차시 등의 검색 유형을 구성했습니다.

운영 환경에서 공개 강좌 검색 API가 정상 응답하는 것을 확인했습니다.

다만 검색창 입력, 검색 버튼, 검색 유형 전환, 차시 접근 권한 등 브라우저의 전체 사용자 흐름은 각각 별도의 검증 대상입니다.

기존 연동 사례: Glitter Project Hub

Glitter Project Hub 사용자 템플릿 v0.1.204에서도 공개 검색 API를 이용한 검색 화면 연동 사례가 있습니다.

기존 확인 기록에는 게시글·페이지 검색과 정렬, 빈 결과 응답 등이 포함되어 있습니다.

이 사례는 특정 템플릿의 연동 사례이며 모든 템플릿에 동일한 검색 화면이 기본 제공된다는 의미는 아닙니다.

7. 검색 제공자를 확장하려면?

Glitter Search Hub는 검색 대상을 추가하기 위한 확장 구조를 제공합니다.

모듈 개발자

검색 기능을 제공하는 모듈은 getSearchProviders()를 통해 검색 제공자를 선언할 수 있습니다.

Search Hub는 활성 모듈의 선언을 발견하고 Registry에 반영합니다.

실제 검색을 수행하려면 그누보드7의 검색 훅 등 지원되는 실행 계약도 구현해야 합니다.

사용자 템플릿 개발자

활성 사용자 템플릿은 search-providers.json 선언 파일을 이용할 수 있습니다.

Search Hub는 선언 파일을 발견하고 소유권, 식별자 충돌, 검색 실행 계약 등을 검증합니다.

검색 실행 계약이 없는 제공자는 실제 검색 가능한 제공자로 취급하지 않습니다.

사이트 운영자

관리자는 Registry에서 제공자 상태와 설정을 확인할 수 있습니다.

호스트 엔드포인트 탐색 화면에서는 검색 관련 라우트의 상태와 지원 제외 사유를 확인할 수 있습니다.

현재 관리자 UI에서는 호스트 엔드포인트를 수동으로 추가하는 기능을 제공하지 않습니다.

중요: 자동 발견은 검색 대상 콘텐츠를 자동으로 분석하거나 인덱싱하는 기능이 아닙니다. 실제 검색 구현이 제공된 경우에만 검색 결과를 반환할 수 있습니다.

8. 설계 및 보안 원칙

Glitter Search Hub는 다음 원칙을 따릅니다.

1. 그누보드7의 기존 검색 기능 재사용
2. 독립 검색 엔진 중복 구현 지양
3. 명시적 선언 기반 검색 제공자 발견
4. 모듈·템플릿·호스트 엔드포인트의 소유권 구분
5. 검색 실행 계약이 없는 제공자 활성화 제한
6. 기존 콘텐츠 접근 권한 존중
7. 관리자·내부 검색 라우트의 공개 검색 등록 방지
8. 검색 기능과 사용자 화면의 역할 분리
9. 기존 관리자 설정과 운영 데이터 보존
10. 한국어·영어 관리자 인터페이스 지원

검색 제공자 활성화는 원본 모듈의 권한 검사를 대체하지 않습니다.

관리자 전용 데이터나 비공개 콘텐츠가 검색 제공자 등록만으로 공개되는 구조를 지향하지 않습니다.

9. 버전 및 개발 방향

공개 배포 기준

v0.1.7

초기 기능 범위는 게시글·페이지 검색 연동, 제공자 관리, 검색 통계, 시스템 진단 및 관리자 화면입니다.

이후 운영 구현 기능

현재까지 운영 번들에 구현·반영된 확장 기능은 다음과 같습니다.

• 활성 모듈 검색 제공자 자동 발견·등록
• Glitter Learning 강좌·차시 검색 연동
• 활성 사용자 템플릿 검색 제공자 선언 발견
• 통합 검색 제공자 Registry
• 호스트 검색 엔드포인트 탐색
• 관리자용 읽기 전용 엔드포인트 진단 테이블
• 제공자 소유 유형 및 검색 계약 상태 관리
• 관리자 UI 가독성 및 날짜 표시 개선

이 기능들이 공개 GitHub v0.1.7 릴리스에 모두 포함되어 있다는 의미는 아닙니다.

정식 공개 버전과 운영 구현 버전의 차이는 릴리스 시점에 정리해야 합니다.

향후 개발 방향

• 템플릿 검색 제공자의 실제 종단 간 연동 사례 확대
• 검색 제공자 개발 문서 및 예제 강화
• 사용자 템플릿 연동 편의성 개선
• 검색 통계 및 운영 분석 기능 개선
• 검색 제공자 진단 정보 고도화

독립 검색 인덱스, 오타 교정, 자동 완성, 검색 순위 최적화 등의 기능은 현재 제공 기능으로 안내하지 않습니다.

10. 설치 방법

Glitter Search Hub는 그누보드7의 관리자 모듈 관리 기능을 통해 설치할 수 있습니다.

설치 전에 사용 중인 그누보드7 버전, PHP 환경 및 관련 모듈과의 호환성을 확인하십시오.

GitHub 저장소 설치

관리자 → 모듈 관리 → 수동 설치 → GitHub

저장소:

https://github.com/glitter-node/glitter-search_hub

ZIP 패키지 설치

GitHub Releases에 설치 패키지가 게시되어 있다면 해당 ZIP 파일을 내려받아 설치할 수 있습니다.

관리자 → 모듈 관리 → 수동 설치 → 파일 업로드

v0.1.7 패키지 주소:

https://github.com/glitter-node/glitter-search_hub/releases/download/v0.1.7/glitter-search_hub-v0.1.7.zip

릴리스 목록:

https://github.com/glitter-node/glitter-search_hub/releases

실제 릴리스 자산의 게시 여부와 포함 기능은 GitHub Releases에서 확인하십시오.

운영 사이트에서는 설치·업데이트 전에 파일과 데이터베이스 백업을 권장합니다.

11. 라이선스

MIT License

Copyright (c) 2026 Glitter.kr

Glitter Search Hub는 MIT 라이선스를 적용하는 오픈소스 프로젝트입니다.

사용, 수정, 재배포 및 상업적 이용은 MIT 라이선스 조건에 따릅니다.

정확한 조건은 저장소의 LICENSE 파일을 확인하십시오.

12. 자주 묻는 질문

Q. Glitter Search Hub를 설치하면 기존 검색 엔진이 교체되나요?

아닙니다. 그누보드7의 기존 검색 API와 검색 훅을 활용합니다.

Q. 검색 정확도나 속도가 자동으로 향상되나요?

아닙니다. 검색 정확도와 성능은 실제 검색 구현 및 데이터 구조에 따라 달라집니다.

Q. 게시글과 페이지를 함께 검색할 수 있나요?

네. 활성화된 게시글·페이지 제공자를 통해 통합 검색할 수 있습니다.

Q. 강좌와 차시도 검색할 수 있나요?

Glitter Learning 모듈과 연동된 운영 환경에서는 가능합니다. 강좌·차시 검색은 해당 모듈의 공개 범위와 접근 권한을 따릅니다.

Q. 새로운 모듈을 설치하면 검색 제공자가 자동으로 등록되나요?

해당 모듈이 지원되는 검색 제공자 선언 계약을 구현한 경우 자동 발견·등록할 수 있습니다. 단순히 모듈을 설치하는 것만으로 모든 콘텐츠가 검색되지는 않습니다.

Q. 사용자 템플릿도 검색 제공자를 선언할 수 있나요?

네. 활성 사용자 템플릿의 search-providers.json 선언 파일을 발견하도록 구현되어 있습니다. 다만 실제 검색을 수행하려면 유효한 검색 실행 계약이 필요합니다.

Q. 호스트에 검색 API가 있으면 자동으로 검색 제공자가 되나요?

아닙니다. 검색 관련 엔드포인트를 탐색하고 계약 상태를 진단하지만, 발견된 모든 API를 자동으로 검색 제공자로 활성화하지는 않습니다.

Q. 검색 제공자를 활성화하면 비공개 콘텐츠도 검색되나요?

아닙니다. 실제 검색 가능 범위는 원본 모듈과 콘텐츠의 접근 권한 정책을 따릅니다.

Q. 사용자 템플릿의 검색창도 자동으로 변경되나요?

아닙니다. 검색 화면은 사용자 템플릿에 맞게 연결해야 할 수 있습니다.

Q. 어떤 사이트에 적합한가요?

게시글과 페이지 외에도 여러 콘텐츠 모듈을 운영하며, 검색 제공자 상태와 통계·진단을 중앙에서 관리하려는 사이트에 적합합니다.

프로젝트 정보

Glitter Search Hub는 그누보드7의 기존 검색 기능을 기반으로 검색 제공자를 통합 관리하고, 다양한 모듈과 사용자 템플릿으로 검색 대상을 확장할 수 있도록 지원하는 검색 관리 플랫폼입니다.