Private Search Gateway

이 프로젝트는 AI 프론트엔드를 위한 결정론적이고 자체 호스팅되는 검색 및 페이지 검색 백엔드입니다. SearXNG 호환 검색 엔드포인트를 노출하고, 소수의 검색 엔진으로 소스를 발견하며, 가장 강력한 페이지를 열고, 실제 콘텐츠를 추출하고, 제한된 수의 관련 동일 사이트 링크를 따라가며, 로컬에서 증거를 재순위화하고, 인용된 소스 URL과 페이지에서 추출된 텍스트를 반환합니다.

유료 검색 API나 내부 언어 모델을 호출하지 않습니다. 프론트엔드의 모델이 검색된 증거를 받아 답변을 작성합니다. 이는 서비스를 비공개적이고 예측 가능하게 유지하며, 사용자 정의 SearXNG 또는 JSON 검색 제공자를 수용하는 모든 프론트엔드에서 사용할 수 있게 합니다.

실행 구성 요소

• search-gateway: 유일한 클라이언트 대면 서비스, 내부 포트 8080에서 실행

• searxng: 웹, 기술, 뉴스, 이미지 및 연구 검색

• reranker: 로컬 BAAI/bge-reranker-base 관련성 순위화

• crawl4ai: 어려운 페이지를 위한 JavaScript 인식 크롤링

• web-runner: Unix 소켓을 통한 격리된 Crawl4AI 및 Playwright 제어

• pdf-runner: 네트워크 격리된 PDF 추출

• safe-egress: 브라우저의 사설 네트워크 및 메타데이터 대상 차단

• redis: 응답 캐시 및 오래된 결과 대체

스택은 호스트 포트를 게시하지 않습니다. 프론트엔드는 공유 Docker 네트워크를 통해 다음 주소로 접근합니다:

http://search-gateway:8080/search

해당 공유 네트워크에 연결된 모든 컨테이너는 게이트웨이를 호출할 수 있습니다. 다른 관련 없는 컨테이너가 접근하지 못하도록 하려면 전용 공유 네트워크를 사용하세요.

Related MCP server: wigolo

요구 사항

• 64비트 Linux VPS

• Docker Engine 및 Docker Compose v2.24.4 이상

• 이미지, Chromium 및 reranker 모델을 위한 약 10GB의 여유 디스크

• 전체 스택에 권장되는 16GB RAM

제공된 상한선은 공유 메모리와 일반 Docker 오버헤드를 제외하고 총 약 10.5GB입니다. 이는 예약이 아닌 제한이지만, 16GB 호스트에서 유용한 여유 공간을 남깁니다. 첫 번째 빌드는 Chromium, Crawl4AI 이미지 및 reranker 모델을 다운로드하기 때문에 느립니다.

깨끗한 설치

Docker 네트워크가 아직 존재하지 않으면 한 번 생성합니다:

docker network inspect docker-stacks_app-network >/dev/null 2>&1 || \
  docker network create docker-stacks_app-network

프로젝트를 클론하고 구성합니다:

git clone https://github.com/ZDOSt/Research-MCP.git
cd Research-MCP
cp .env.example .env
chmod 600 .env

두 개의 다른 비밀을 생성합니다:

openssl rand -hex 32
openssl rand -hex 32

.env를 편집하고 SEARXNG_SECRET 및 CRAWL4AI_API_TOKEN을 해당 값으로 바꿉니다. 프론트엔드가 다른 외부 Docker 네트워크를 사용하는 경우에만 CLIENT_DOCKER_NETWORK를 변경하세요.

전체 스택을 검증하고 시작합니다:

docker compose config --quiet
docker compose up -d --build --wait
docker compose ps

ports: 항목이 필요하지 않습니다. 의도적으로 게이트웨이를 Docker 외부에 노출하려는 경우가 아니라면 추가하지 마세요.

확인

게이트웨이 컨테이너에서 상태 확인을 실행합니다:

docker compose exec -T search-gateway python -c \
  "import urllib.request; print(urllib.request.urlopen('http://127.0.0.1:8080/healthz').read().decode())"

공유 네트워크의 모든 컨테이너에서 실제 검색을 실행합니다. your-frontend-container를 anythingllm, librechat 또는 다른 컨테이너 이름으로 바꾸세요:

docker exec your-frontend-container sh -lc \
  "wget -qO- 'http://search-gateway:8080/search?q=how+to+install+docker+compose&format=json' | head -c 1000"

응답에는 results, 소스 URL, 추출된 content 및 진단 정보가 포함되어야 합니다. 검색 스니펫은 사이트가 추출을 차단하거나 요청 기한이 도달한 경우에만 명확하게 표시된 대체 수단으로 사용됩니다.

프론트엔드 설정

프론트엔드가 SearXNG URL을 요청하는 곳마다 다음 기본 URL을 사용하세요:

http://search-gateway:8080

전체 검색 경로를 요청하는 경우 다음을 사용하세요:

http://search-gateway:8080/search

AnythingLLM은 필드가 SearXNG API Base URL로 표시되어 있더라도 전체 검색 경로가 필요합니다. 다음과 같이 구성하세요:

http://search-gateway:8080/search

표준 요청은 다음과 같습니다:

GET /search?q=your+question&format=json

지원되는 쿼리 매개변수는 다음과 같습니다:

• language=auto

• time_range=day|week|month|year

• categories=general,it,news,science,images

• max_results=1..8

• mode=auto|quick|balanced|deep

카테고리가 제공되지 않으면 게이트웨이는 요청에서 유용한 SearXNG 카테고리를 추론합니다. auto는 간단한 조회에는 빠른 모드를 사용하고 기술 질문 및 추천에는 균형 모드를 사용합니다.

직접 통합을 위해 더 풍부한 JSON 엔드포인트도 사용할 수 있습니다:

POST /v1/research
Content-Type: application/json

{
  "query": "What are the recommended settings for an AW3426DW?",
  "mode": "balanced",
  "max_results": 5,
  "language": "auto",
  "categories": []
}

업데이트

VPS의 저장소 디렉토리에서:

git pull --ff-only
docker compose config --quiet
docker compose up -d --build --remove-orphans --wait
docker compose ps

일반 업데이트를 위해 docker compose down을 실행할 필요가 없습니다. 기존 Redis 캐시 및 reranker 다운로드는 명명된 볼륨에 남아 있습니다.

운영

유용한 명령어:

docker compose ps
docker compose logs --tail=200 search-gateway searxng reranker
docker compose logs --tail=200 crawl4ai web-runner safe-egress pdf-runner
docker compose restart search-gateway
docker compose down
docker compose up -d --wait

docker compose down은 명명된 볼륨을 보존합니다. docker compose down -v는 캐시와 다운로드된 reranker 모델을 삭제하며, 의도적인 전체 재설정에만 사용해야 합니다.

제한 사항

이 도구는 문서, 문제 해결, 제품 설정, 게임, 최신 정보 및 일반 연구를 위한 호스팅 검색 도구에 접근할 수 있지만, 상용 제공자와 동일한 범위를 보장할 수는 없습니다. 키가 없는 엔진은 데이터센터 IP에 속도 제한을 가할 수 있으며, 일부 사이트는 모든 자동화된 브라우저를 차단하고, 단일 VPS는 Google, Brave 또는 유료 응답 엔진이 사용하는 독점 검색 인덱스를 가지고 있지 않습니다. 게이트웨이는 여러 검색 제공자, 동시 추출, 로컬 재순위화, 제한된 브라우저 대체, 캐싱 및 답변을 조작하는 대신 정직한 부분 결과를 통해 이를 보완합니다.