가이드

작성자 Matt Connor 2026-08-20 · 업데이트됨 2026-08-28

Hister 개인용 검색 엔진 서버 구축 및 설치 가이드

Q: 코딩 에이전트가 Hister 인덱스를 검색할 수 있나요?

네, 가능합니다. Hister는 기본 URL의 POST /mcp에서 MCP(Model Context Protocol) 서버로 동작하며, search, get_preview, get_history를 노출합니다. 클라이언트를 https://your-host/mcp으로 지정하고 액세스 토큰이 포함된 Authorization: Bearer 헤더를 설정하십시오. 그러면 에이전트는 오늘날 공개 검색 엔진에서 상위에 노출되는 정보가 아니라, 사용자가 실제로 읽었던 버전의 문서를 검색하게 됩니다.

Hister를 VPS에 직접 호스팅하여 방문한 페이지와 로컬 파일을 검색하는 방법을 설명합니다. Docker 설치, TLS 설정, 로그인 보안 및 MCP 엔드포인트 구성 등 v0.17.0 버전 기준의 상세한 단계별 가이드를 제공합니다.

Hister란 무엇이며, 무엇이 아닌가

Hister는 직접 호스팅하는 개인용 검색 엔진입니다. 방문한 페이지의 전체 텍스트와 보관 중인 파일을 색인화한 뒤, 웹 인터페이스, 터미널 클라이언트, HTTP API 또는 AI(인공지능) 어시스턴트를 통해 해당 컬렉션을 검색할 수 있게 해줍니다. Hister는 "내가 그것을 어디서 읽었더라?"라는 질문에 답을 제공합니다.

대부분의 독자는 SearXNG를 통해 이 개념을 접하지만, 두 도구는 동일하지 않다. 알고 있는 이름이 이전 버전인 Searx라면, 해당 프로젝트는 2023년 이후 코드 커밋이 없으며 SearXNG가 이를 이어가고 있으므로, 현재 새로 구축하는 인스턴스는 어느 경우든 SearXNG다. SearXNG는 메타검색 프록시다. 사용자의 검색어를 SearXNG로 보내면 SearXNG가 사용자를 대신해 다른 검색 엔진에 질의하고, 추적 정보를 제거한 결과를 반환한다. 색인은 해당 검색 엔진이 보유한다. Hister는 사용자가 제공한 콘텐츠로 자체 색인을 구축한다. 여기에는 브라우저 확장 프로그램이 캡처한 페이지, 가져온 브라우저 기록, 크롤링한 URL, 사용자가 지정한 디렉터리의 파일이 포함된다. 자체 호스팅한 SearXNG 인스턴스는 공개 웹에 비공개로 접근하게 해준다. Hister는 사용자가 직접 읽은 콘텐츠를 검색하게 해준다. 두 도구의 역할은 다르므로 하나의 서버에서 둘 다 실행하는 것은 일반적이다. 두 도구를 함께 사용한다면 SearXNG가 실제로 검색의 어느 부분까지 숨기는지 알아둘 필요가 있다. SearXNG는 검색어 자체를 숨기는 대신 검색 엔진에 전달되는 IP를 사용자의 IP에서 서버의 IP로 바꾸기 때문이다.

Hister는 AGPLv3(GNU Affero General Public License, version 3) 이상을 따르는 자유 소프트웨어입니다. 텔레메트리 기능이 없으며 클라우드 서비스도 필요하지 않습니다. 이 가이드는 2026-07-28 기준 최신 릴리스인 v0.17.0 버전을 기준으로 작성되었습니다. 명령어를 복사하기 전에 릴리스 페이지에서 현재 태그를 확인하고, 해당 태그를 고정하여 사용하십시오.

VPS에서 Hister를 직접 호스팅하는 이유

인덱스는 완전할 때만 유용하며, 읽는 동안 서버가 실행 중이어야만 완전해집니다. 노트북은 하루의 절반을 절전 모드로 보냅니다. 그 시간 동안 휴대폰으로 여는 페이지는 서버에 도달하지 않으며, 밤새 진행하려던 가져오기 작업도 시작되지 않습니다. VPS(가상 사설 서버)는 항상 켜져 있으므로, 사용자가 소유한 모든 기기가 동일한 인덱스에 데이터를 전송하고 크롤러는 사용자가 잠든 사이에도 계속 작동합니다.

두 번째 이유는 분리입니다. user_handling: true 섹션에서 app을 설정하면 단일 인스턴스 내에서 각 계정마다 고유한 자격 증명과 문서 모음을 가질 수 있습니다. 따라서 서버 한 대로 다른 사람의 읽기 기록을 검색할 염려 없이 가구나 소규모 팀의 데이터를 관리할 수 있습니다.

세 번째 이유는 연결 구성이다. VPS에는 이미 공개 호스트 이름과 인증서가 있다. 브라우저 확장 프로그램이 제어할 수 없는 네트워크에서 서버에 연결하려면 이 두 가지가 필요하다. 동일한 호스트 이름과 인증서는 서버의 다른 부분에서도 사용된다. openGym은 처음 활성화된 호스트 이름을 기준으로 첫 번째 패스키를 등록한다. 따라서 첫 계정을 만들기 전에 호스트 이름과 인증서를 확정해야 한다.

설치 경로 1: 릴리스 바이너리

Hister는 플랫폼별로 하나의 바이너리를 제공합니다. 바이너리와 체크섬 파일을 함께 다운로드하고, 설치하기 전에 검증하십시오.

cd /tmp
curl -LO https://github.com/asciimoo/hister/releases/download/v0.17.0/hister_0.17.0_linux_amd64
curl -LO https://github.com/asciimoo/hister/releases/download/v0.17.0/hister_0.17.0_checksums.txt
sha256sum --ignore-missing -c hister_0.17.0_checksums.txt

정상적인 결과는 hister_0.17.0_linux_amd64: OK 한 줄입니다. FAILED 줄이 나타나면 다운로드 파일이 손상되었거나 변조된 것이므로, 설치하지 말고 다시 다운로드하십시오.

바이너리를 설치한 다음, 시스템 계정과 서비스가 사용할 디렉터리를 생성하십시오.

sudo install -m 755 /tmp/hister_0.17.0_linux_amd64 /usr/local/bin/hister
sudo useradd --system --home-dir /var/lib/hister --shell /usr/sbin/nologin hister
sudo install -d -o hister -g hister -m 750 /var/lib/hister
sudo install -d -m 755 /etc/hister
sudo hister create-config /etc/hister/config.yml

create-config 명령은 기본 설정 파일을 생성하며, 바이너리가 해당 머신에서 정상적으로 실행되는지 확인하는 역할도 합니다. 잘못된 아키텍처용 바이너리를 다운로드했다면 이 단계에서 cannot execute binary file: Exec format error 오류가 발생합니다.

중요한 설정 몇 가지만 수정하십시오. 생성된 파일의 나머지 부분은 그대로 두어도 됩니다.

app:
  directory: /var/lib/hister
  access_token: 'paste-a-long-random-string-here'
server:
  address: 127.0.0.1:4433
  base_url: https://hister.example.com

openssl rand -hex 32 명령으로 토큰을 생성하십시오. 이제 파일에 자격 증명이 포함되었으므로, 서비스가 시작되기 전에 파일 권한을 제한하십시오.

sudo chown root:hister /etc/hister/config.yml
sudo chmod 640 /etc/hister/config.yml

systemd에서 실행하기

/etc/systemd/system/hister.service을(를) 작성합니다:

[Unit]
Description=Hister personal search engine
After=network-online.target
Wants=network-online.target

[Service]
User=hister
Group=hister
Environment=HISTER_CONFIG=/etc/hister/config.yml
ExecStart=/usr/local/bin/hister listen
Restart=on-failure
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/hister

[Install]
WantedBy=multi-user.target

HISTER_CONFIG은(는) 설정 경로를 지정하기 위해 문서화된 환경 변수이므로, 이 유닛은 hister 계정의 홈 디렉터리에 의존하지 않습니다. ProtectSystem=strict은(는) 이 서비스에 대해 전체 파일 시스템을 읽기 전용으로 설정하므로, ReadWritePaths에서 데이터 디렉터리를 명시해야 합니다. ProtectHome=yes은(는) 서비스로부터 /home을(를) 숨기므로, /home 아래의 감시 대상 디렉터리는 인덱서에게 비어 있는 것으로 보입니다. 해당 위치의 파일을 인덱싱해야 한다면 이 줄을 삭제하십시오.

sudo systemctl daemon-reload
sudo systemctl enable --now hister
systemctl status hister --no-pager
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4433/

마지막 명령이 출력하는 HTTP 상태 코드가 무엇이든 프로세스가 수신 대기 중임을 의미합니다. curl: (7) Failed to connect은(는) 수신 대기 중이 아님을 의미하며, journalctl -u hister -n 50 --no-pager은(는) 그 이유를 알려줍니다.

설치 경로 2: Docker Compose

이미지는 GitHub 컨테이너 레지스트리에 게시되며, 릴리스마다 하나의 태그가 부여됩니다.

services:
  hister:
    image: ghcr.io/asciimoo/hister:v0.17.0
    container_name: hister
    user: '1000:1000'
    restart: unless-stopped
    environment:
      - HISTER__SERVER__ADDRESS=0.0.0.0:4433
      - HISTER__SERVER__BASE_URL=https://hister.example.com
      - HISTER__APP__ACCESS_TOKEN=${HISTER_ACCESS_TOKEN}
    volumes:
      - ./data:/hister/data
    ports:
      - 127.0.0.1:4433:4433

모든 설정 키는 HISTER__<SECTION>__<KEY> 형태의 환경 변수로 덮어쓸 수 있으며, 구분자로 언더스코어 두 개를 사용합니다. 따라서 컨테이너 배포 시 설정 파일을 별도로 마운트할 필요가 없습니다. HISTER_ACCESS_TOKEN는 compose 파일 옆의 .env 파일에 보관하십시오. 파일을 직접 편집하고 싶다면 docker run --rm ghcr.io/asciimoo/hister:v0.17.0 create-config > config.yml 명령어로 기본값을 출력할 수 있습니다.

위의 두 줄은 실수하기 쉬우며, 둘 다 이해해 두는 것이 좋습니다.

컨테이너 내부 주소는 반드시 0.0.0.0:4433이어야 합니다. 컨테이너는 고유한 네트워크 네임스페이스를 가지므로, 127.0.0.1에 바인딩된 프로세스는 해당 컨테이너 내부에서만 접근할 수 있으며, 게시된 포트로 전달할 대상이 없게 됩니다.

게시된 포트는 4433:4433가 아니라 127.0.0.1:4433:4433로 작성해야 합니다. Docker는 자체 netfilter 규칙을 삽입하여 포트를 게시하며, 이 규칙은 ufw 규칙보다 먼저 평가됩니다. 따라서 ufw status에서 포트가 닫힌 것으로 표시되더라도, 일반적인 4433:4433 설정은 인터넷에서 여전히 접근 가능합니다. 호스트 측을 127.0.0.1에 바인딩해야 리버스 프록시를 통해서만 접근할 수 있습니다. 동일한 함정이 서버의 모든 컨테이너에 적용되며, VPS에서의 Docker Compose에서 나머지 내용을 다룹니다.

기본 이미지는 UID 1000 및 GID 1000으로 실행되므로, ./data는 해당 계정으로 쓰기 가능해야 합니다. 그렇지 않으면 컨테이너가 시작 시 권한 오류로 중단됩니다. sudo chown -R 1000:1000 ./data으로 이 문제를 해결할 수 있습니다. 해당 숫자가 생소하다면 먼저 컨테이너가 파일을 작성할 때 사용하는 UID 및 GID 확인을 읽어보시기 바랍니다.

개인 검색 인덱스를 외부에 노출하는 것이 위험한 이유

Hister는 기본적으로 127.0.0.1:4433에서 수신 대기하며, 이 기본값은 의도된 것입니다. 한 달 동안 사용한 후 인덱스에 어떤 정보가 담길지 생각해 보십시오. 내부 위키 페이지, 송장, 로그인 상태에서 작성한 지원 티켓, 비밀번호 재설정 페이지, 그리고 읽은 모든 내용의 전문이 포함됩니다. 프로젝트 문서에는 "Hister는 페이지 내용을 포함한 전체 브라우징 기록을 서버로 전송합니다"라고 명시되어 있습니다.

유출된 비밀번호 데이터베이스는 크래킹 과정을 거쳐야 하지만, 유출된 개인 인덱스는 평문 상태이며 즉시 검색이 가능합니다. 따라서 겉보기에는 작은 자체 호스팅 앱처럼 보일지라도 훨씬 더 엄격한 관리가 필요합니다.

이로부터 두 가지 사실이 도출됩니다. Hister는 기본적으로 인증을 요구하지 않으므로, 리버스 프록시만 설정하면 호스트 이름을 아는 누구에게나 검색 가능한 읽기 기록 사본을 공개하는 셈이 됩니다. 또한 MCP 엔드포인트도 기본적으로 /mcp에서 제공되며, 토큰이 없으면 해당 주소에 접근하는 모든 클라이언트가 인덱스를 대상으로 검색을 수행할 수 있습니다.

서비스를 처음으로 localhost 외부에서 접근하게 만들기 전에 반드시 인증을 설정하십시오. 단일 사용자의 경우 app.access_token만 있으면 충분하며, 브라우저 확장 프로그램, 터미널 클라이언트, 모든 MCP 클라이언트가 하나의 공유 비밀값을 사용합니다. 여러 사용자가 이용한다면 user_handling: true을 설정하고 계정을 생성하십시오.

sudo -u hister hister create-user alice --admin --config /etc/hister/config.yml

이 명령은 최소 8자 이상의 비밀번호를 요구합니다. 각 계정은 고유한 문서와 개인 API 토큰을 가지며, 소유자는 프로필 페이지나 hister update-user의 --regen-token 플래그를 사용하여 토큰을 재생성할 수 있습니다. 새 토큰을 생성하면 이전 토큰은 즉시 무효화되므로, 해당 계정을 사용하는 모든 기기의 설정을 이후에 업데이트해야 합니다.

의도한 경우가 아니라면 app.public는 변경하지 마십시오. 공개 모드(Public mode)는 쓰기, 기록 접근, 관리자 작업을 차단하지만 인증되지 않은 검색, 미리보기, 파일 제공, MCP 검색을 허용합니다.

리버스 프록시, TLS 및 방화벽

Hister는 자체적으로 HTTPS를 제공하지 않으므로, 앞단에서 TLS(Transport Layer Security)를 종료해야 합니다. Caddy는 ACME(Automatic Certificate Management Environment)를 통해 인증서를 스스로 요청하고 갱신하므로 가장 간편한 방법입니다.

hister.example.com {
    reverse_proxy 127.0.0.1:4433
}

sudo systemctl reload caddy 명령으로 설정을 다시 불러옵니다. 인증서가 발급되려면 두 가지 조건이 충족되어야 합니다. hister.example.com의 A 레코드가 이 서버를 가리키고 있어야 하며, HTTP-01 챌린지에 응답하기 위해 80번 포트가 열려 있어야 합니다. 이 중 하나라도 누락되면 브라우저는 페이지 대신 TLS 오류를 표시하며, Caddy 로그에는 실패한 챌린지 기록이 반복됩니다.

그다음, 나머지 포트를 모두 닫으십시오.

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

목록에서 4433번 포트가 의도적으로 제외되었습니다. 외부 호스트 이름만이 유일한 접속 방법은 아니며, 동일한 루프백 포트를 가리키는 onion 서비스를 사용하면 DNS 레코드나 인바운드 포트 개방 없이도 본인의 기기에서 인덱스 페이지에 접근할 수 있습니다.

server.base_url는 스킴(scheme)을 포함하여 브라우저에 입력하는 주소와 일치해야 합니다. 일치하지 않으면 인터페이스가 스타일 없이 텍스트만 표시되거나 이미지가 누락된 상태로 로드됩니다. 이는 서버가 base_url을 기반으로 에셋 링크를 생성하는데, 브라우저가 응답하지 않는 오리진에 해당 링크를 요청하기 때문입니다. 동일한 URL을 브라우저 확장 프로그램에도 입력해야 합니다.

인덱스 채우기

브라우저 확장 프로그램이 주요 수집기 역할을 합니다. Mozilla Add-ons 또는 Chrome Web Store에서 설치한 뒤, 옵션 페이지를 열어 서버 URL을 https://hister.example.com로 설정하고 액세스 토큰을 붙여넣으십시오. 이후 방문하는 모든 페이지의 제목, 전체 텍스트, HTML, 파비콘을 캡처하여 서버로 전송합니다. 추출은 브라우저 내부의 클라이언트 측에서 수행됩니다. 확장 프로그램은 제3자와 통신하지 않으며, 외부로 보내는 유일한 요청은 페이지 파비콘을 가져오는 것뿐입니다.

클라이언트 측 추출 방식 덕분에 개인 인덱스 구축이 가능합니다. 확장 프로그램은 사용자가 로그인하고 렌더링을 마친 후 보는 페이지를 그대로 확인하므로, 내부 위키 페이지나 유료 기사도 정확하게 인덱싱되며 서버는 사용자의 자격 증명을 알 필요가 없습니다. 이는 사용자가 보는 모든 것이 인덱스 대상이 될 수 있음을 의미하며, 따라서 콘텐츠를 추가하기 전에 건너뛰기 규칙(skip rules)을 먼저 설정해야 합니다.

건너뛰기 규칙은 단일 사용자 설치 시 rules.json에 저장되거나, 사용자별로 데이터베이스에 저장됩니다. 웹 인터페이스의 규칙(Rules) 탭을 이용하는 것이 가장 편집하기 쉽습니다. 규칙은 전체 URL과 대조되는 Go 정규 표현식을 사용합니다:

^https://mail\.example\.com
^https://bank\.example\.com
.*?utm_source=

^mail.example.com와 같은 패턴은 일치하지 않습니다. 테스트 대상 문자열이 https://로 시작하기 때문입니다. 또한 쿼리 문자열이 포함된 URL의 경우, 매칭 과정에서 쿼리 매개변수가 유지되므로 끝에 $를 붙이는 방식도 실패합니다.

기존 기록은 브라우저 자체 데이터베이스를 읽어 가져옵니다. 따라서 이 명령은 VPS가 아닌 브라우저 프로필이 저장된 로컬 컴퓨터(노트북 등)에서 실행해야 합니다. 동일한 바이너리를 해당 기기에 설치하고 서버를 가리키도록 설정하십시오:

export HISTER_TOKEN='your-access-token'
hister import browser firefox -u https://hister.example.com -t "$HISTER_TOKEN"

가져오기 작업은 browser-import-YYYY-MM-DD라는 이름의 재개 가능한 작업으로 실행되므로, 중간에 중단했다가 나중에 다시 시작할 수 있습니다. 북마크 서비스도 동일한 방식으로 가져올 수 있으며, 여기에는 Linkwarden, Karakeep, Wallabag, Linkding, Readeck, Shaarli가 포함됩니다. 반복해서 가져오기를 수행하면 마지막 작업 이후에 추가된 새로운 항목만 가져옵니다.

서버의 파일은 설정 파일에 디렉터리를 지정하여 인덱싱합니다:

indexer:
  directories:
    - path: '/var/lib/hister/documents'
      label: 'documents'
      filetypes: ['pdf', 'docx', 'md', 'txt']

PDF, DOCX, Markdown, Org mode 및 유효한 UTF-8 텍스트 파일은 전체 텍스트로 읽어 들입니다. 사진과 비디오는 이 목록에 포함되지 않으므로, 이미지 라이브러리의 경우 텍스트보다는 얼굴, 장소, 날짜를 인덱싱하는 서버가 필요합니다. 이 용도로는 보통 PhotoPrism 및 Immich가 비교 대상이 됩니다. 단일 페이지는 hister index https://example.com을 사용하여 추가합니다. 전체 사이트를 다른 도구에서 사용하기 좋게 깔끔한 텍스트로 변환하는 작업은 별도의 과정이며, 페이지를 깔끔한 텍스트로 변환하는 자체 호스팅 크롤러를 통해 처리합니다.

검색은 필드 기반으로 이루어지므로, 쿼리 언어에 대해 10분 정도 시간을 내어 읽어보는 것이 좋습니다:

"connection reset" domain:github.com added:<30d
title:(wireguard|nftables) -tutorial sort:-visits

MCP를 통해 나만의 인덱스를 코딩 에이전트에 연결하기

MCP(model context protocol)는 assistant가 서버의 도구를 호출하는 데 사용하는 인터페이스다. Hister는 동일한 base URL에서 streamable HTTP transport를 통해 POST /mcp로 MCP를 제공하며, search, get_preview 및 get_history를 노출한다. 인증에는 API의 나머지 부분과 동일한 bearer token을 사용한다. 도구 호출이 처음이라면 간단한 agent loop를 직접 작성하기가 이와 같은 endpoint가 assistant에 실제로 무엇을 전달하는지 가장 빠르게 확인하는 방법이다.

{
  "mcpServers": {
    "hister": {
      "url": "https://hister.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

X-Access-Token 헤더는 Authorization의 대안으로 사용할 수 있습니다.

이 방식의 가치는 에이전트가 무엇을 검색하느냐에 있습니다. 일반적인 웹 검색은 오늘날의 순위를 기준으로 결과를 반환하는데, 빠르게 변화하는 소프트웨어의 경우 현재 실행 중인 버전이 아닌 다른 버전의 문서를 가져오는 경우가 많습니다. 반면 나만의 인덱스는 이미 읽고 보관하기로 선택한 페이지를 반환하며, get_preview이 저장된 사본을 제공하므로 원본 페이지가 오프라인 상태가 되어도 답변을 얻을 수 있습니다. 공개된 결과까지 함께 얻으려면 에이전트에게 두 가지 소스를 모두 제공하십시오. SearXNG 기반의 브라우저 검색 기술을 사용하면 개방형 웹을 별도의 도구로 추가할 수 있습니다. 이러한 엔드포인트를 하나 이상 실행하게 되면, 모든 엔드포인트가 동일한 노출 문제를 공유하므로 VPS에서 MCP 서버 호스팅하기 문서를 읽어보는 것이 좋습니다.

디스크, 백업 및 유지보수

문서화에 따르면 압축된 미리보기를 포함하여 인덱싱된 페이지 한 개당 약 100 KB를 차지하므로, 10만 페이지는 대략 10 GB 정도입니다. 할당량 시스템은 없습니다. 두 가지 설정을 혼동하는 경우가 많습니다. indexer.max_file_size_mb(기본값 1 MiB)은 감시 대상 단일 파일의 크기를 제한하며, server.max_batch_body_size(기본값 40 MiB)는 단일 API 요청의 크기를 제한합니다.

app.directory에 지정된 디렉터리에는 언어별 인덱스 파일이 포함된 index.db, 계정 및 작업용 db.sqlite3, 미리보기용 data/html/, 그리고 rules.json가 저장됩니다. 백업은 서비스를 중지한 후 해당 디렉터리 전체와 설정 파일을 복사하는 방식으로 수행합니다. hister export backup.json는 마이그레이션을 위해 문서를 JSON 형식으로 기록하며, 이는 서버 백업 용도가 아닙니다.

두 가지 유지보수 명령어를 알아두는 것이 좋습니다. hister reindex은 검색 인덱스를 재구축하며, 인덱서 설정을 변경한 후에 반드시 실행해야 합니다. 대규모 가져오기 작업 중에 메모리 사용량이 증가하면 indexer 섹션에 detect_languages: false을 설정한 뒤 다시 인덱싱하십시오. hister cleanup는 삭제 후 남겨진 고아(orphaned) 미리보기 및 파비콘 파일을 제거합니다.

삭제는 쿼리 방식으로 이루어지므로 먼저 dry 모드로 실행하십시오.

hister delete 'domain:example.com' --dry --verbose

수집기가 여전히 해당 페이지를 제출하면 삭제된 페이지가 다시 생성될 수 있으므로, 삭제 전에 건너뛰기(skip) 규칙을 추가하십시오.

AGPLv3는 코드를 수정하는 경우에만 적용됩니다. 수정하지 않은 사본을 개인적으로 실행하는 것에는 어떠한 의무도 따르지 않습니다. Hister를 수정하여 다른 사람들이 네트워크를 통해 귀하의 버전을 사용하게 할 경우, 라이선스에 따라 수정된 소스 코드를 제공해야 합니다.

실패 유형과 표시되는 메시지

서버가 시작되지 않습니다. 4433 포트가 이미 사용 중이거나 설정 파일에 YAML 문법 오류가 있는 경우입니다. sudo ss -lntp | grep 4433 명령으로 포트를 점유 중인 프로세스를 확인하고, journalctl -u hister -n 50 --no-pager 명령으로 구문 분석 오류를 확인하십시오.

인터페이스는 로드되지만 깨져 보입니다. 텍스트가 엉망이거나 이미지가 보이지 않는다면 server.base_url 값이 주소창의 URL과 일치하지 않는 것입니다. 마지막의 슬래시(/) 하나도 불일치로 간주됩니다.

확장 프로그램이 연결되지 않습니다. 확장 프로그램에 설정된 서버 URL이 base_url과 정확히 일치해야 하며, 서버가 실행 중이고 최신 버전이어야 합니다. 중간에 방화벽이 있다면 아무런 메시지 없이 연결을 차단할 수 있습니다. Firefox는 확장 프로그램 로그를 일반 콘솔에 표시하지 않습니다. about:debugging#/runtime/this-firefox를 열어 Hister 확장 프로그램을 검사하십시오.

컨테이너가 시작하자마자 종료됩니다. ./data 경로에 권한 오류가 발생한 경우입니다. 이는 해당 디렉터리의 소유자가 기본 이미지 내부의 계정인 1000번 UID가 아님을 의미합니다.

관리자 경로에서 403 Forbidden 오류가 발생합니다. 사용자 관리 기능이 켜져 있을 때 POST /api/reindex 및 POST /api/cleanup 경로는 관리자만 접근할 수 있으므로, 일반 계정은 접근이 거부됩니다.

가져오기(import) 도중 메모리 사용량이 급증합니다. 대규모 기록에 대한 언어 감지 기능이 주된 원인입니다. detect_languages: false을 설정한 뒤 hister reindex를 실행하십시오.

FAQ

Hister는 SearXNG와 어떻게 다른가요?

SearXNG는 메타 검색 프록시입니다. 사용자의 질의를 공개 검색 엔진으로 전달하고 추적 정보를 제거한 결과를 반환하므로, 인덱스는 해당 엔진들이 소유합니다. 반면 Hister는 사용자가 방문한 페이지와 보관한 파일에 대한 자체 전문(full-text) 인덱스를 유지합니다. 따라서 SearXNG가 "웹에 무엇이 있는가"를 답한다면, Hister는 "내가 어디서 그것을 읽었는가"를 답합니다. 두 서비스는 서로 다른 문제를 해결하므로 많은 사용자가 한 대의 서버에서 두 서비스를 모두 운영합니다.

전체 브라우징 기록을 VPS에 올리는 것은 안전한가요?

사전에 노출 방지 작업을 완료한 경우에만 안전합니다. Hister는 기본적으로 127.0.0.1:4433에 바인딩되며 별도의 인증을 요구하지 않습니다. app.access_token 또는 user_handling: true을 설정하고, 앞단에 TLS를 적용한 리버스 프록시를 배치한 뒤, 방화벽에서 4433 포트를 닫아두어야 합니다. 읽기 기록의 전문 인덱스는 일반 텍스트 형태이므로, 포트에 접근할 수 있는 사람은 누구나 별도의 해킹 과정 없이 모든 내용을 읽을 수 있습니다.

브라우저 확장 프로그램이 꼭 필요한가요, 아니면 기록만 가져오면 되나요?

기록 가져오기(import)는 일회성 백필(backfill) 작업입니다. 브라우저 자체의 기록 데이터베이스를 읽는 방식이므로 서버가 아닌 브라우저 프로필이 저장된 컴퓨터에서 실행됩니다. 이후부터는 확장 프로그램이 인덱스를 최신 상태로 유지하며, 페이지가 렌더링된 후 브라우저에서 콘텐츠를 추출하므로 로그인 뒤에 숨겨진 페이지도 캡처할 수 있습니다. 일반적으로는 한 번 가져오기를 수행한 뒤 확장 프로그램을 사용하는 방식을 권장합니다.

코딩 에이전트가 Hister 인덱스를 검색할 수 있나요?

네, 가능합니다. Hister는 기본 URL의 POST /mcp에서 MCP(Model Context Protocol) 서버로 동작하며, search, get_preview, get_history를 노출합니다. 클라이언트를 https://your-host/mcp으로 지정하고 액세스 토큰이 포함된 Authorization: Bearer 헤더를 설정하십시오. 그러면 에이전트는 오늘날 공개 검색 엔진에서 상위에 노출되는 정보가 아니라, 사용자가 실제로 읽었던 버전의 문서를 검색하게 됩니다.

#hister#search #self-hosting #privacy #mcp #docker