Hister 개인용 검색 엔진 서버 구축 및 설치 가이드
Hister를 VPS에 직접 호스팅하여 방문한 페이지와 로컬 파일을 검색하는 방법을 설명합니다. Docker 설치, TLS 설정, 로그인 보안 및 MCP 엔드포인트 구성 등 v0.17.0 버전 기준의 상세한 단계별 가이드를 제공합니다.
Hister란 무엇이며 무엇이 아닌가
Hister는 직접 호스팅하는 개인 검색 엔진이다. 방문한 페이지와 보관 중인 파일의 전체 텍스트를 색인한 다음, 웹 인터페이스, 터미널 클라이언트, HTTP API 또는 AI(인공지능) 어시스턴트에서 해당 모음을 검색할 수 있게 한다. Hister는 한 가지 질문에 답한다. 어디에서 읽었는가.
대부분의 독자는 SearXNG를 통해 이 개념을 접하며, 두 도구는 동일하지 않다. 알고 있는 이름이 이전 버전인 Searx라면 해당 프로젝트는 더 이상 유지 관리되지 않는다. 현재 README는 독자에게 작성자의 새 프로젝트인 Hister를 안내한다. Searx와 SearXNG는 여전히 별도의 프로젝트이며, SearXNG가 유지 관리되는 fork이므로 새로운 메타검색 인스턴스를 구축할 때는 SearXNG를 사용해야 한다. SearXNG는 메타검색 프록시다. 사용자의 query를 SearXNG로 보내면 SearXNG가 사용자를 대신해 다른 엔진에 요청하고, 추적 정보를 제거한 결과를 반환한다. 색인은 해당 엔진에 있다. Hister는 사용자가 제공한 콘텐츠로 자체 색인을 만든다. 여기에는 브라우저 확장 프로그램으로 캡처한 페이지, 가져온 브라우저 기록, crawl한 URL, 지정한 디렉터리의 파일이 포함된다. 직접 호스팅한 SearXNG 인스턴스는 공용 웹에 비공개로 접근하게 한다. Hister는 자신이 읽은 내용을 검색하게 한다. 두 도구의 역할은 다르므로 하나의 서버에서 둘 다 실행하는 것은 일반적이다. 두 도구를 함께 실행한다면 SearXNG가 실제로 검색 내용을 얼마나 숨기는지 알아둘 필요가 있다. SearXNG는 query 자체를 숨기는 것이 아니라 엔진에 전달할 때 사용자의 IP를 서버의 IP로 바꾼다.
Hister는 AGPLv3(GNU Affero General Public License, version 3) 또는 이후 버전으로 제공되는 free software다. telemetry가 없으며 cloud service도 필요하지 않다. 이 가이드는 2026-07-28 당시 current release였던 version v0.17.0에 고정되어 있다. 2026-10-12 당시 current release는 v0.20.0이었다. 2026-10-29 당시 current release는 v0.21.0이었다. 2026-11-19 현재 current release는 v0.22.0이며, 프로젝트의 새 이름인 Nogon으로 제공되는 첫 release다. 아래 명령은 v0.17.0을 기준으로 작성했으며, 이후 추가된 기능 중 이 문서에서 언급하는 기능에는 추가된 release가 표시되어 있다. 내용을 복사하기 전에 releases page에서 current tag를 확인한 다음, 그곳에서 확인한 tag를 고정해야 한다.
v0.22.0으로 upgrade하려면 아래의 version number만 바꾸는 것으로 충분하지 않다. 새 download에서는 nogon binary name을 사용하고, config create가 create-config을 대체하며, user create과 user update가 create-user과 update-user을 대체한다. Upgrade하기 전에 서버를 중지하고 전체 backup을 생성해야 하며, 기존 data path와 container volume은 유지해야 한다. 기존 browser extension 설치본은 store update를 통해 이름 변경을 적용받으며 설정은 유지한다.
VPS에서 Hister를 직접 호스팅하는 이유
색인은 완전할 때만 유용하며, 읽는 동안 서버가 실행 중이어야만 완전해진다. 노트북은 하루의 절반 동안 절전 상태에 들어간다. 그동안 휴대폰에서 연 페이지는 노트북에 도달하지 않으며, 야간 가져오기도 시작되지 않는다. VPS(virtual private server)는 계속 실행되므로, 보유한 모든 기기에서 같은 색인으로 데이터를 보내고 잠자는 동안에도 crawler가 계속 작업한다.
두 번째 이유는 분리다. app 섹션에서 user_handling: true을 설정하면 단일 인스턴스에서 각 계정에 자체 자격 증명과 자체 문서 모음을 제공할 수 있다. 따라서 한 서버에 가정이나 소규모 팀을 수용하면서 서로의 읽기 기록을 검색하지 않도록 할 수 있다.
세 번째 이유는 연결 구성이다. 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.ymlcreate-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.comopenssl rand -hex 32 명령으로 토큰을 생성하십시오. 이제 파일에 자격 증명이 포함되었으므로, 서비스가 시작되기 전에 파일 권한을 제한하십시오.
sudo chown root:hister /etc/hister/config.yml
sudo chmod 640 /etc/hister/config.ymlsystemd에서 실행하기
/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.targetHISTER_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에서 나머지 내용을 다룹니다.
user: '1000:1000' 줄은 컨테이너를 UID 1000 및 GID 1000으로 실행하며, 공식 v0.17.0 이미지의 기본값인 UID/GID 65532를 재정의합니다. 따라서 ./data은 UID 1000 및 GID 1000이 쓰기 가능해야 합니다. 디렉터리가 존재하지 않으면 mkdir -p ./data로 생성하고, sudo chown -R 1000:1000 ./data으로 해당 계정에 소유권을 부여하십시오. SELinux가 활성화된 호스트에서는 Docker가 적절한 레이블을 할당하도록 ./data:/hister/data:Z을 사용하십시오. 해당 숫자가 생소하다면 먼저 컨테이너가 어떤 UID와 GID로 파일을 작성하는지를 읽어보시기 바랍니다.
개인 검색 인덱스를 외부에 공개하면 안 되는 이유
Hister는 기본적으로 127.0.0.1:4433에서 수신 대기하며, 이는 의도적인 기본 설정이다. 한 달 동안 사용한 뒤 인덱스에 무엇이 저장되는지 생각해 보자. 내부 위키 페이지, 청구서, 로그인한 상태에서 연 지원 티켓, 비밀번호 재설정 페이지, 그 밖에 읽은 모든 콘텐츠의 전체 텍스트가 포함된다. 프로젝트 문서에도 다음과 같이 명시되어 있다. "Hister는 페이지 콘텐츠를 포함한 전체 브라우징 기록을 서버와 주고받는다."
유출된 비밀번호 데이터베이스는 여전히 크래킹해야 한다. 유출된 개인 인덱스는 평문이고 이미 검색할 수 있으므로, 겉보기와 달리 규모가 작은 self-hosted 애플리케이션보다 더 주의해서 다뤄야 한다.
여기에서 2가지 사실이 도출된다. Hister는 기본적으로 인증을 요구하지 않으므로 reverse proxy만 설정해도 호스트 이름을 알아낸 누구에게나 사용자가 읽은 콘텐츠의 검색 가능한 사본이 공개된다. MCP endpoint도 기본적으로 /mcp에서 제공되며, token이 없으면 해당 endpoint에 도달할 수 있는 모든 client가 인덱스에서 검색을 실행할 수 있다.
서비스가 처음으로 localhost를 벗어나기 전에 인증을 설정해야 한다. 사용자 1명만 사용하는 경우에는 app.access_token만 필요하다. 브라우저 extension, terminal client 및 모든 MCP client가 하나의 shared secret을 전송한다. 여러 사람이 사용하는 경우에는 user_handling: true를 설정하고 계정을 생성한다.
sudo -u hister hister create-user alice --admin --config /etc/hister/config.yml이 명령은 8~72 UTF-8 bytes 길이의 password를 입력하라는 메시지를 표시한다. Unicode 문자는 여러 bytes를 사용할 수 있으므로 8자 미만이어도 조건을 충족할 수 있다. 각 계정에는 고유한 문서와 개인 API token이 할당된다. 소유자는 profile page에서 또는 hister update-user의 --regen-token flag를 사용해 token을 다시 생성할 수 있다. 새 token을 생성하면 이전 token이 즉시 무효화되므로, 해당 계정이 사용하는 모든 device를 이후에 업데이트해야 한다.
의도한 경우가 아니라면 app.public을 변경하지 않는다. Public mode에서는 인증되지 않은 search, preview, file serving 및 MCP search를 허용한다. 단, write, history access 및 admin operation은 계속 차단한다.
리버스 프록시, 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의 DNS 레코드가 이 서버를 가리키고 있어야 합니다. IPv4를 위한 A 레코드, IPv6를 위한 AAAA 레코드, 혹은 둘 다 해당합니다. Caddy는 기본적으로 80번 포트에서의 HTTP-01 검증과 443번 포트에서의 TLS-ALPN-01 검증을 모두 활성화하므로, 443번 포트에서 검증이 성공하면 80번 포트는 필요하지 않습니다. Let's Encrypt는 IPv4뿐만 아니라 IPv6로도 검증을 수행하며 AAAA 주소를 우선적으로 시도합니다. 따라서 이전 호스트에서 남은 오래된 AAAA 레코드가 있으면 A 레코드가 올바르더라도 검증에 실패할 수 있습니다. DNS가 잘못되었거나 두 가지 챌린지 모두 성공하지 못하면, 브라우저는 페이지 대신 TLS 오류를 표시하며 Caddy 로그에는 실패한 챌린지가 반복해서 기록됩니다.
그다음 나머지 포트를 모두 닫습니다.
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status4433번 포트는 의도적으로 위 목록에서 제외되었습니다. 공용 호스트 이름만이 유일한 접속 방법은 아니며, 동일한 루프백 포트를 가리키는 onion 서비스를 사용하면 DNS 레코드나 인바운드 포트를 전혀 열지 않고도 자신의 기기에서 인덱스에 접근할 수 있습니다.
server.base_url는 스킴을 포함하여 브라우저에 입력하는 주소와 일치해야 합니다. base_url에 잘못된 경로 접두사가 설정되면 에셋 링크가 깨져 인터페이스에 스타일이 적용되지 않거나 이미지가 표시되지 않습니다. 동일한 URL을 브라우저 확장 프로그램에도 입력해야 합니다.
인덱스 채우기
브라우저 확장 프로그램이 주요 수집기다. Mozilla Add-ons 또는 Chrome Web Store에서 설치하고, 옵션 페이지를 연 다음 서버 URL을 https://hister.example.com로 설정하고 액세스 토큰을 붙여 넣는다. 확장 프로그램의 토큰 지원은 v0.18.0에서 추가되었다. v0.17.0 확장 프로그램은 대신 웹 인터페이스에 로그인할 때 생성된 세션을 사용한다. 이후 확장 프로그램은 방문하는 각 페이지의 제목, 전체 텍스트, HTML, favicon을 수집하고 서버로 전송한다. 추출은 브라우저 내부에서 클라이언트 측으로 수행된다. 확장 프로그램은 제3자와 통신하지 않으며, 외부로 보내는 유일한 요청은 페이지 favicon을 가져오기 위한 요청이다.
클라이언트 측 추출을 사용하면 비공개 인덱스를 만들 수 있다. 확장 프로그램은 로그인과 렌더링이 완료된 뒤 사용자가 보는 것과 정확히 같은 페이지를 확인한다. 따라서 내부 위키 페이지나 유료 문서도 올바르게 인덱싱되며, 서버에 자격 증명을 전달할 필요가 없다. 반면 확인하는 모든 항목이 인덱스 후보가 된다는 뜻이기도 하다. 따라서 더 많은 콘텐츠를 추가하기 전에 건너뛰기 규칙을 먼저 설정해야 한다.
단일 사용자 설치에서는 rules.json에 건너뛰기 규칙을 저장한다. 여러 사용자 설치에서는 사용자별로 데이터베이스에 저장한다. 웹 인터페이스의 Rules 탭이 규칙을 편집하는 가장 쉬운 방법이다. 규칙은 전체 URL에 대해 일치 여부를 검사하는 Go 정규 표현식이다.
^https://mail\.example\.com
^https://bank\.example\.com^mail.example.com과 같은 패턴은 검사 대상 문자열이 https://로 시작하므로 일치하지 않는다. 정규화 후에도 쿼리 문자열이 남아 있으면 끝의 $도 일치하지 않는다. utm_* 매개변수만 제거되므로 /login$는 https://example.com/login?utm_source=email와 일치할 수 있지만 https://example.com/login?auth=1과는 일치하지 않는다.
기존 방문 기록은 브라우저 자체 데이터베이스를 읽어 가져온다. 따라서 이 명령은 브라우저 프로필이 있는 컴퓨터, 즉 VPS가 아니라 노트북에서 실행해야 한다. 같은 바이너리를 해당 컴퓨터에 설치하고 서버를 지정한다.
export HISTER_TOKEN='your-access-token'
hister import browser firefox -u https://hister.example.com -t "$HISTER_TOKEN"가져오기는 browser-import-YYYY-MM-DD이라는 이름의 재개 가능한 작업으로 실행된다. 따라서 중단한 뒤 나중에 다시 시작할 수 있다. 북마크 서비스도 같은 방식으로 가져온다. v0.17.0은 Linkwarden, Karakeep, Shaarli를 지원한다. v0.18.0에서는 Linkding, Readeck, Wallabag이 추가되었고, v0.20.0에서는 Raindrop.io가 추가되었다. Linkwarden, Karakeep, Shaarli, Linkding, Readeck 또는 Wallabag에서 다시 가져오기를 실행하면 이전 가져오기 이후에 추가된 항목만 가져온다.
서버의 파일은 설정에서 디렉터리를 지정하여 인덱싱한다.
indexer:
directories:
- path: '/var/lib/hister/documents'
filetypes: ['pdf', 'docx', 'md', 'txt']PDF, DOCX, Markdown, Org mode 및 유효한 UTF-8 텍스트 파일은 전체 텍스트로 읽는다. 사진과 동영상은 이 목록에 없으므로 이미지 라이브러리에는 텍스트가 아니라 얼굴, 장소, 날짜를 인덱싱하는 서버가 필요하다. 이 용도에서는 PhotoPrism과 Immich를 주로 비교한다. hister index https://example.com을 사용하면 단일 페이지를 추가할 수 있다. 다른 도구에서 사용할 수 있도록 전체 사이트를 정제된 텍스트로 변환하는 작업은 별도의 작업이며, 페이지를 정제된 텍스트로 변환하는 self-hosted 크롤러가 처리한다.
검색은 필드 기반이므로 쿼리 언어를 10분 정도 읽어 두면 유용하다.
"connection reset" domain:github.com added:<30d
title:(wireguard|nftables) -tutorial sort:-visitssort: 필드는 v0.18.0에서 추가되었다. 따라서 v0.17.0에서는 두 번째 쿼리에서 이 필드를 제외한다.
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에 대한 단일 요청을 제한합니다. 후자의 설정은 v0.17.0 이후에 추가되었으며, v0.17.0 버전에서는 배치 요청이 5 MiB로 고정되어 있습니다.
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수집기가 여전히 해당 페이지를 제출하면 삭제된 페이지가 다시 생성되므로, 삭제하기 전에 건너뛰기 규칙을 추가하십시오.
수정되지 않은 Hister 사본을 직접 실행하는 것에는 어떠한 의무도 따르지 않습니다. AGPLv3는 수정되지 않은 프로그램을 실행할 수 있는 무제한의 권한을 보장하기 때문입니다. 수정 여부와 관계없이 사본을 타인에게 전달할 때는 저작권 및 라이선스 고지를 그대로 유지하고 수령인에게 라이선스 사본을 제공해야 하는 등의 조건이 따릅니다. Hister를 수정하여 네트워크를 통해 타인이 귀하의 버전을 사용하도록 할 경우, 라이선스에 따라 수정된 소스 코드를 제공해야 합니다.
실패 유형 및 표시되는 문자열
서버가 시작되지 않습니다. 포트 4433이 점유되었거나 YAML 문법 오류가 발생한 경우가 주된 원인입니다. 설정 유효성 검사 실패나 데이터 디렉터리 접근 권한 문제로도 시작이 중단될 수 있습니다. server.base_url 없이 0.0.0.0에 바인딩하면 base_url must be specified when listening on이 발생하며, 비밀 키를 기록하지 못하면 failed to create secret key file가 발생합니다. sudo ss -lntp | grep 4433을 사용하면 포트를 점유 중인 프로세스를 확인할 수 있고, journalctl -u hister -n 50 --no-pager을 실행하면 시작 오류 내용을 출력합니다.
인터페이스는 로드되지만 깨져 보입니다. 텍스트가 엉키거나 이미지가 보이지 않는다면 server.base_url의 경로 접두사를 확인하십시오. Hister는 해당 설정의 마지막 슬래시를 제거합니다.
확장 프로그램이 연결되지 않습니다. 확장 프로그램에 설정된 서버 URL은 base_url과 일치해야 합니다. 서버가 실행 중이고 최신 버전인지 확인하십시오. 중간에 방화벽이 있으면 페이지에 아무런 메시지 없이 연결이 차단됩니다. Firefox는 확장 프로그램 로그를 일반 콘솔에 표시하지 않습니다. about:debugging#/runtime/this-firefox를 열어 Hister 확장 프로그램을 검사하십시오.
컨테이너가 시작 시 종료됩니다. ./data에서 권한 오류가 발생하면 소유권, 쓰기 권한, SELinux 레이블을 확인해야 합니다. 이 compose 파일은 명시적으로 UID 1000과 GID 1000으로 실행되므로, 이미지의 기본값인 UID/GID 65532를 덮어씁니다. 해당 계정에 ./data에 대한 쓰기 권한을 부여하십시오. SELinux 호스트를 사용하는 경우 바인드 마운트에 :Z을 추가하십시오.
관리자 경로에서 403 Forbidden 오류가 발생합니다. 사용자 관리 기능이 켜져 있을 때 POST /api/reindex과 POST /api/cleanup는 관리자 전용이므로, 일반 계정은 접근이 거부됩니다.
가져오기(import) 도중 메모리 사용량이 증가합니다. 방대한 기록에 대한 언어 감지 기능이 주된 원인입니다. detect_languages: false을 설정한 뒤 hister reindex을 실행하십시오.
FAQ
Hister는 SearXNG와 어떻게 다른가?
SearXNG는 metasearch proxy다. 사용자의 query를 공개 search engine으로 전달하고 tracking을 제거한 결과를 반환하므로, 색인은 해당 search engine에 속한다. Hister는 사용자가 방문한 페이지와 보관한 파일의 자체 full-text index를 유지한다. 따라서 Hister는 "어디에서 읽었지"라는 질문에 답하고, SearXNG는 "웹에서 무엇이라고 말하지"라는 질문에 답한다. 두 도구는 서로 다른 문제를 해결하며, 한 서버에서 둘 다 실행하는 사람도 많다.
VPS에 전체 browsing history를 저장해도 안전한가?
먼저 노출 방지 작업을 수행한 경우에만 안전하다. Hister는 127.0.0.1:4433에 바인딩되며 기본적으로 authentication이 필요하지 않다. app.access_token 또는 user_handling: true을 설정하고, 앞에 TLS를 사용하는 reverse proxy를 배치하며, firewall에서 port 4433을 닫아 둔다. 읽기 기록의 full-text index는 평문이므로, 해당 port에 도달할 수 있는 사람은 어떤 것도 해독하지 않고 모든 내용을 읽을 수 있다.
브라우저 확장 프로그램이 필요한가? 아니면 history만 가져오면 되는가?
가져오기는 1회성 backfill이다. 브라우저 자체 history database를 읽으므로 서버가 아니라 browser profile이 있는 컴퓨터에서 실행된다. 이후에는 확장 프로그램이 색인을 최신 상태로 유지한다. 또한 페이지가 렌더링된 뒤 브라우저에서 내용을 추출하므로 login 뒤에 있는 페이지도 수집한다. 일반적인 구성은 먼저 1회 가져오기를 수행한 뒤 확장 프로그램을 사용하는 것이다.
coding agent가 Hister 색인을 검색할 수 있는가?
가능하다. Hister는 기본 URL의 POST /mcp에 있는 MCP (model context protocol) server이며, search, get_preview 및 get_history을 노출한다. Authorization: Bearer header에 access token을 넣고 client를 https://your-host/mcp에 지정한다. 그러면 agent는 현재 공개 search engine에서 순위가 높은 내용을 검색하는 대신, 사용자가 실제로 읽은 버전의 문서를 검색한다.