이런 경험, 있으신가요?
좋은 글을 북마크해 뒀다가 몇 달 만에 다시 열어보니 — 빈 화면이거나 무한 로딩 스피너가 돌거나, 더 이상 존재하지 않는 analytics 서버 요청 때문에 페이지 전체가 멈춰버린 경우가 있습니다. 그 페이지는 애초에 당신의 것이 아니었습니다. 남의 JavaScript를 얇게 감싼 클라이언트일 뿐이죠.
또 다른 상황: 네트워크 없이 문서를 읽어야 할 때 (비행기 안, 야외 작업, 또는 특정 서버실), 아니면 갑자기 사라질지도 모르는 웹사이트의 콘텐츠를 영구 보존하고 싶을 때.
오늘 소개할 kage (일본어로 "그림자", 발음 /ka-ge/)는 바로 이런 문제들을 해결하기 위해 만들어진 도구입니다.
kage란 무엇인가?
kage는 Go로 작성된 오픈소스 커맨드라인 도구로, headless Chrome으로 페이지를 실제로 렌더링한 뒤 페이지 로드가 완료되면 DOM 스냅샷을 찍고, 모든 JavaScript를 자동으로 삭제하며, CSS, 이미지, 폰트 같은 정적 리소스를 로컬에 다운로드합니다. 최종적으로 당신은 네트워크에 전혀 의존하지 않고 스크립트도 하나도 실행하지 않는, 디스크에서 바로 열어볼 수 있는 .html 파일 집합을 얻게 됩니다.
- ⭐ GitHub Stars: 2600+ (2026년 6월 생성, 급성장 중)
- 🏷️ 언어: Go
- 📜 라이선스: MIT
- 🧑💻 작성자: tamnd
kage vs 전통적인 "다른 이름으로 저장"
| 기능 | 브라우저 "다른 이름으로 저장" | wget / curl | kage |
|---|---|---|---|
| JavaScript 렌더링 | ❌ | ❌ | ✅ headless Chrome으로 완전 렌더링 |
| 자동 JS 제거 | ❌ | ❌ | ✅ 모든 스크립트 완전 삭제 |
| SPA/동적 콘텐츠 지원 | ❌ | ❌ | ✅ Vue/React/Angular 페이지 지원 |
| 전체 사이트 복제 | ❌ | ⚠️ 제한적 | ✅ 링크 자동 추적, 너비 우선 크롤링 |
| 단일 파일 패키징 | ❌ | ❌ | ✅ ZIM / 자체 포함 실행 파일 |
| 오프라인 사용 가능 | ⚠️ 자주 실패 | ⚠️ 자주 실패 | ✅ 완벽 오프라인 |
핵심 동작 원리
URL 방문 → headless Chrome 렌더링 → 페이지 안정 대기 → 최종 DOM 캡처 → 모든 <script> 삭제 → CSS/이미지/폰트 다운로드 → 로컬 저장 → 링크 계속 추적
kage는 단순히 HTML 소스를 다운로드하는 것이 아니라, 실제 브라우저처럼 페이지를 렌더링하여 사용자가 눈으로 보는 그대로의 완전한 페이지를 보존합니다.
kage 설치
kage는 Linux, macOS, Windows 세 가지 플랫폼을 모두 커버하는 다양한 설치 방법을 제공합니다.
방법 1: Go로 설치
Go가 이미 설치되어 있다면 (Go 1.21+ 권장):
go install github.com/tamnd/kage/cmd/kage@latest
방법 2: Homebrew (macOS)
brew install --cask tamnd/tap/kage
방법 3: Scoop (Windows)
scoop bucket add tamnd https://github.com/tamnd/scoop-bucket
scoop install kage
방법 4: apt (Ubuntu/Debian)
# 저장소 키 및 소스 추가
curl -fsSL https://tamnd.github.io/linux-repo/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/tamnd.gpg
echo "deb [signed-by=/usr/share/keyrings/tamnd.gpg] https://tamnd.github.io/linux-repo/apt stable main" | sudo tee /etc/apt/sources.list.d/tamnd.list
sudo apt update && sudo apt install kage
방법 5: dnf (Fedora/RHEL)
sudo dnf config-manager --add-repo https://tamnd.github.io/linux-repo/dnf/tamnd.repo
sudo dnf install kage
방법 6: Docker (Chrome 설치 불필요)
Docker 이미지에 Chromium이 포함되어 있어 바로 사용할 수 있습니다:
docker run --rm -v "$PWD/out:/out" ghcr.io/tamnd/kage clone paulgraham.com
설치 확인
kage --version
kage completion bash # 또는 zsh / fish, 탭 자동완성 활성화
참고: kage는 Chrome 또는 Chromium이 필요합니다. Docker 방식을 제외하고는 호스트 머신에 Chrome/Chromium을 설치해야 합니다. kage가 시스템 설치 경로를 자동으로 찾아줍니다.
--chrome매개변수나KAGE_CHROME환경변수로 직접 지정할 수도 있습니다.
빠르게 시작하기: 3분 만에 웹사이트 복제
Paul Graham의 블로그를 예로 들어, 로컬에 완벽하게 복제해 봅시다:
# 1. 전체 웹사이트를 $HOME/data/kage/paulgraham.com/에 복제
kage clone paulgraham.com
# 2. 로컬에서 미리보기
kage serve $HOME/data/kage/paulgraham.com
# 브라우저에서 http://127.0.0.1:8800 열기
이게 전부입니다! 모든 글, 모든 이미지, 모든 스타일 파일이 디스크에 고정되어, 네트워크 없이도 완벽하게 작동합니다.
복제 범위 제한
빠르게 체험해보고 싶다면 복제 범위를 제한할 수 있습니다:
# 첫 50페이지만, 링크 최대 2레벨까지 추적
kage clone paulgraham.com --max-pages 50 --max-depth 2
# 웹사이트의 특정 하위 디렉토리만 복제
kage clone go.dev --scope-prefix /doc
# 특정 경로 건너뛰기 (광고나 무관한 페이지 제외)
kage clone example.com --exclude /ads --exclude /track
유용한 매개변수 빠른 참조
| 매개변수 | 기본값 | 설명 |
|---|---|---|
-o, --out |
$HOME/data/kage |
출력 루트 디렉토리 |
-p, --max-pages |
0 (제한 없음) |
최대 N개 페이지 복제 |
-d, --max-depth |
0 (제한 없음) |
링크 추적 깊이 |
--scope-prefix |
없음 | 해당 접두사로 시작하는 경로만 복제 |
--subdomains |
false |
서브도메인 포함 |
--scroll |
false |
페이지 자동 스크롤 (지연 로딩 트리거) |
--workers |
4 |
동시 렌더링 페이지 수 |
--no-robots |
false |
robots.txt 무시 |
--refresh |
false |
기존 복제본 증분 업데이트 |
고급 기능
1. 자동 스크롤로 지연 로딩 트리거
많은 현대 웹사이트에서 이미지 지연 로딩(lazy loading)을 사용합니다. 페이지를 스크롤하지 않으면 이미지가 로드되지 않죠. kage는 자동 스크롤을 지원합니다:
kage clone example.com --scroll
이 옵션은 kage가 각 페이지를 자동으로 끝까지 스크롤하여, 모든 지연 로딩 이미지, iframe 등의 콘텐츠가 완전히 렌더링되고 보존되도록 합니다.
2. 증분 업데이트 (--refresh)
한 달 전에 복제한 블로그에 새 글이 업데이트되었다면? 처음부터 다시 복제할 필요가 없습니다:
kage clone paulgraham.com --refresh
--refresh는 기존 페이지를 다시 렌더링하고新增된 콘텐츠를 가져옵니다. kage의 복제는 멱등적입니다: http든 https든 동일한 페이지는 한 번만 저장됩니다.
3. 우아한 중단 및 재개
복제 도중 Ctrl+C를 눌렀다고요? 괜찮습니다. kage가 현재 진행 상황을 자동으로 저장합니다:
# Ctrl+C로 중단, 다음 실행 시 자동으로 재개
kage clone paulgraham.com
4. 서브도메인 포함
kage clone example.com --subdomains
blog.example.com, docs.example.com 등의 서브도메인도 함께 복제합니다.
패키징: 폴더에서 단일 파일로
복제 후镜像는 수천 개의 작은 파일을 포함하는 폴더입니다. 복사해 옮기는 데 시간이 오래 걸리죠. kage는 전체镜像를 단일 파일로 압축할 수 있습니다.
옵션 1: ZIM 파일로 패키징
ZIM은 Kiwix 프로젝트에서 사용하는 개방형 오프라인 형식으로, 장기 아카이빙을 위해 설계되었습니다:
# 패키징
kage pack paulgraham.com # paulgraham.com.zim 생성
# 읽기
kage open paulgraham.com.zim # 로컬 미리보기
# Kiwix로 열 수도 있습니다
kiwix-serve paulgraham.com.zim # HTTP 서비스
왜 ZIM인가요? ZIM은 공개된 개방형 표준입니다. 오늘 kage로 만든
.zim파일은 10년 후에도 Kiwix의 어떤 리더기로도 열 수 있습니다. zstd 압축을 지원하여 텍스트는 고도로 압축되고, 이미지/미디어는 원본 그대로 저장됩니다.
옵션 2: 독립 실행형 바이너리로 패키징
kage의 가장 멋진 기능 — 실행 파일 하나 = 전체 웹사이트:
# 자체 포함 바이너리로 패키징
kage pack paulgraham.com --format binary -o paulgraham
# 바로 실행, 의존성 제로
./paulgraham
# HTTP 서비스가 자동 시작, 브라우저에서 열면 됨
이 파일을 받은 사람은 아무것도 설치할 필요가 없습니다: kage도, 브라우저도, ZIM 리더기도 필요 없습니다. 그냥 실행하면 전체 웹사이트의 오프라인 버전을 얻을 수 있습니다.
바이너리 파일 크기는 약 13 MiB (kage 본체) + 웹사이트 콘텐츠 크기입니다.
크로스 플랫폼 패키징
macOS에서 Windows용 파일을 만들 수 있습니다:
# Mac에서 Windows 실행 파일 생성
kage pack paulgraham.com --format binary \
--base kage-windows-amd64.exe
# paulgraham.exe 출력
releases 페이지에서 대상 플랫폼의 kage 바이너리를 다운로드하여 --base로 사용하기만 하면 됩니다.
옵션 3: 더블클릭으로 실행되는 데스크톱 앱
--app 매개변수를 추가하면 kage가 아이콘이 있는 데스크톱 앱을 생성합니다:
# macOS → .app 패키지
kage pack paulgraham.com --app
open paulgraham.app
# Linux → AppImage
kage pack paulgraham.com --app --base kage-linux-amd64
# paulgraham.AppDir / paulgraham.AppImage 출력
더블클릭으로 실행하면, 터미널 창 없이 바로 웹사이트에 진입합니다.
실전 시나리오
시나리오 1: 기술 블로그를 오프라인 지식 라이브러리로 저장
# Paul Graham 글 전체 복제
kage clone paulgraham.com --scroll -o ~/docs/paulgraham
# ZIM으로 패키징, Kindle/폰에서 언제든 읽기
kage pack paulgraham.com
# 또는 단일 파일로 패키징해 친구에게 공유
kage pack paulgraham.com --format binary -o ~/share/paulgraham-essays
시나리오 2: 문서 사이트 오프라인 버전
# Go 공식 문서 복제
kage clone go.dev --scope-prefix /doc --max-depth 3
# 출장 중 비행기에서 네트워크 없어도? 로컬 serve로 해결
kage serve ~/data/kage/go.dev
시나리오 3: 장기 아카이빙
일부 웹사이트는 폐쇄되거나 이전될 수 있습니다. kage로 정기적으로 아카이빙할 수 있습니다:
# cron에 추가, 매월 자동 업데이트
# 0 2 1 * * kage clone example.com --refresh
주의사항
- robots.txt: kage는 기본적으로
robots.txt규칙을 따릅니다. 개발/테스트 환경에서 무시하려면--no-robots를 추가하세요. - Chrome 의존성: Docker 방식을 제외하고 호스트 머신에 Chrome/Chromium 설치가 필요합니다.
- 디스크 공간: 대형 웹사이트 복제 후 수 GB의 공간을 차지할 수 있습니다.
- 합법성: 웹사이트 저작권과 robots.txt를 존중하고, 영리 목적이나 저작권 침해 콘텐츠에는 사용하지 마세요.
요약
kage는 현재 가장 우아한 웹사이트 오프라인 복제 도구입니다. headless Chrome으로 페이지를 실제로 렌더링하고 모든 JavaScript를 제거하여, 동적 웹페이지를 진정한 "당신의 것"인 정적 HTML로 만듭니다. ZIM 패키징과 자체 포함 실행 파일로 장기 아카이빙과 배포에 완벽한 솔루션입니다.
- GitHub: tamnd/kage
- 공식 사이트: kage.tamnd.com
- 라이선스: MIT
- 설치:
go install github.com/tamnd/kage/cmd/kage@latest
네트워크 없이 문서를 읽어야 할 일이 많거나, 특정 웹사이트 콘텐츠를 영구 보존하고 싶다면, kage를 도구 상자에 추가할 가치가 충분합니다.