SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor · 업데이트됨 2026-10-30

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

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

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

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

대부분의 사용자는 SearXNG를 통해 이 개념을 접하게 되며, 두 도구는 서로 다릅니다. 만약 알고 계신 이름이 구형 Searx라면, 해당 프로젝트는 더 이상 유지보수되지 않으며, 현재 README에서는 작성자의 새 프로젝트인 Hister를 안내하고 있습니다. Searx와 SearXNG는 별개의 프로젝트로 남아 있으며, SearXNG는 유지보수 중인 포크 버전이므로 새로운 메타 검색 인스턴스를 구축할 때는 SearXNG를 사용해야 합니다. SearXNG는 메타 검색 프록시입니다. 사용자의 쿼리를 전달받아 대신 다른 검색 엔진에 질의하고, 추적 정보를 제거한 결과를 반환합니다. 색인은 해당 검색 엔진들이 소유합니다. 반면 Hister는 사용자가 제공한 콘텐츠(브라우저 확장 프로그램으로 캡처한 페이지, 가져온 브라우저 기록, 크롤링한 URL, 지정한 디렉터리의 파일)를 바탕으로 자체 색인을 구축합니다. 직접 호스팅하는 SearXNG 인스턴스는 공개 웹에 대한 비공개 접근 권한을 제공합니다. Hister는 사용자가 읽은 자료를 검색할 수 있게 해줍니다. 두 도구의 역할은 다르므로 한 서버에서 두 서비스를 모두 운영하는 것은 일반적입니다. 만약 그렇게 운영한다면, SearXNG가 실제로 검색 내용을 얼마나 숨겨주는지 파악해 두는 것이 좋습니다. SearXNG는 쿼리 자체를 숨기는 것이 아니라 검색 엔진 측에서 사용자의 IP를 서버의 IP로 대체하는 방식이기 때문입니다.

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

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.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에서 나머지 내용을 다룹니다.

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는 페이지 내용을 포함한 전체 브라우징 기록을 서버로 전송합니다"라고 명시되어 있습니다.

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

이로부터 두 가지 사실이 도출됩니다. 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의 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 status

4433번 포트는 의도적으로 위 목록에서 제외되었습니다. 공용 호스트 이름만이 유일한 접속 방법은 아니며, 동일한 루프백 포트를 가리키는 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, 파비콘을 캡처하여 서버로 전송합니다. 추출은 브라우저 내부의 클라이언트 측에서 수행됩니다. 확장 프로그램은 제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이라는 이름의 재개 가능한 작업으로 실행되므로, 중단했다가 나중에 다시 시작할 수 있습니다. 북마크 서비스도 같은 방식으로 가져옵니다. 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로 추가합니다. 전체 사이트를 다른 도구에서 사용하기 좋게 깔끔한 텍스트로 변환하는 작업은 별도의 과정이며, 페이지를 깔끔한 텍스트로 변환하는 자체 호스팅 크롤러를 통해 처리합니다.

검색은 필드 기반으로 이루어지므로, 쿼리 언어를 10분 정도 학습하면 큰 도움이 됩니다:

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

sort: 필드는 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에서 순위가 높은 내용을 검색하는 대신, 사용자가 실제로 읽은 버전의 문서를 검색한다.

이 글이 도움이 되었나요?