kage 딥다이브
— 진짜 브라우저로 렌더링한 뒤 JS를 전부 뜯어내는 오프라인 웹 복제기

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

제공하는 명령은 네 개뿐으로 단순하다. kage clone <url>로 사이트를 복제하고, kage serve [dir]로 로컬에서 미리 보고, kage pack <dir>로 폴더를 단일 ZIM 파일 또는 자기완결 실행파일로 압축하고, kage open <file.zim>으로 그 패킹된 파일을 다시 열어 본다.

2왜 주목받는가

수많은 웹 아카이빙 도구가 있는데, kage가 트렌딩에 오른 이유.

웹 아카이빙 도구는 많다. wget --mirror, HTTrack, SingleFile, ArchiveBox… kage가 차별화되는 지점은 두 가지 결정이다 — ① "렌더링 후 캡처"로 JS 사이트의 진짜 내용을 잡고, ② "캡처 후 JS 완전 제거"로 코드가 안 도는 영구 사본을 만든다는 것.

3기술 스택 전체 지도

go.mod와 실제 import를 뜯어 본 kage의 기술 구성.

kage는 순수 Go 단일 바이너리를 지향한다(기본 빌드는 CGO_ENABLED=0). 외부 의존성은 신중히 골랐고, 핵심은 "브라우저 제어 + HTML 파싱 + 압축 + CLI" 네 갈래다.

왜 go-rod인가 (Puppeteer/Playwright 대신)

go-rod는 Go 네이티브 DevTools 프로토콜 클라이언트다. Node 런타임 없이 Go 바이너리 하나로 Chrome을 제어할 수 있어, "단일 정적 바이너리" 목표와 맞는다. stealth 플러그인은 자동화 탐지(navigator.webdriver 등)를 우회해, 봇 차단이 있는 사이트도 렌더링할 여지를 준다.

4아키텍처 심화 — 렌더→JS제거→복제 파이프라인

한 줄의 URL이 디스크 위의 정적 사본이 되기까지.

kage의 전체 흐름은 README가 압축해 보여 준다: seed URL ▶ headless Chrome(render) ▶ final DOM(snapshot) ▶ strip JS(sanitize) ▶ localise assets(rewrite links) ▶ disk. 이를 실제 패키지 단위로 펼치면 다음과 같다.

핵심 설계 패턴 4가지

JS를 "어떻게" 제거하나 — sanitize 내부

가장 핵심인 JS 제거를 코드 수준으로 보면, golang.org/x/net/html로 파싱한 트리를 재귀 순회하며 노드별로 처리한다.

// sanitize.CleanTree — DOM 트리를 제자리에서 청소 (요지)
switch c.DataAtom {
case atom.Script:           // <script> 통째로 삭제
    n.RemoveChild(c); rep.ScriptsRemoved++
case atom.Noscript:         // 기본은 삭제, KeepNoscript면 본문으로 펼침
    n.RemoveChild(c)
case atom.Meta:             // JS 타깃 meta-refresh 제거
    if isMetaRefresh(c) { n.RemoveChild(c) }
case atom.Link:             // 오프라인에서 무의미한 preconnect/preload 제거
    if isDeadLink(c) { n.RemoveChild(c) }
}
stripHandlers(c, rep)        // onclick, onload 등 on* 속성 제거
neutralizeJSURLs(c, rep)     // href="javascript:..." 무력화

특히 영리한 부분은 IE 조건부 주석 처리다. <!--[if lt IE 9]><script src=...><![endif]-->은 하나의 "주석 노드"로 파싱되는데, 그 안에 <script>가 텍스트로 숨어 있다. 요소만 순회하면 이 스크립트를 못 보고 지나치므로, kage는 조건부 주석을 통째로 삭제해 주석에 밀반입된 JS까지 차단한다. 또 문서에 charset이 없으면 ensureCharset으로 추가해 오프라인에서 한글·UTF-8이 깨지지 않게 한다.

5디렉토리 구조 해부

"관심사별로 쪼갠다" — kage 저장소는 패키지 경계가 곧 설계도다.

kage는 README가 직접 밝히듯 "관심사로 분할(split by concern)"된 구조다. 각 디렉토리가 파이프라인의 한 단계에 정확히 대응한다.

이 구조의 미덕은 의존성이 한 방향으로 흐른다는 것이다. cli가 clone을 부르고, clone이 browser·sanitize·asset·urlx를 조립한다. 가장 밑바닥의 urlx는 아무것도 의존하지 않는 순수 패키지라, 단위 테스트가 쉽고 전체를 추론하기 좋다(각 패키지마다 *_test.go가 동반된다).

6학습 포인트 (기술별)

이 레포를 읽으며 실제로 손에 남기면 좋은 것들.

① 헤드리스 브라우저 자동화 (go-rod / DevTools 프로토콜)

"JS 사이트를 어떻게 캡처하나"의 답이 여기 있다. browser/pool.go는 페이지로 이동(navigate) → 네트워크가 조용해질 때까지 대기(settle, 기본 1.5초) → (옵션) 자동 스크롤로 lazy 이미지 트리거 → 최종 DOM 직렬화의 순서를 보여 준다. 스크래핑·E2E 테스트·스크린샷 서비스의 토대가 되는 패턴이다.

// autoScroll — lazy-load 이미지를 끌어내기 위해 페이지를 단계적으로 스크롤
page.Eval(`() => new Promise((resolve) => {
    let total = 0; const step = 400;
    const timer = setInterval(() => {
      window.scrollBy(0, step); total += step;
      if (total >= document.body.scrollHeight) {
        clearInterval(timer); window.scrollTo(0, 0); resolve();
      }
    }, 100);
})`)

② DOM 파싱과 트리 변형 (x/net/html)

정규식으로 HTML을 자르는 건 위험하다. kage는 golang.org/x/net/html로 제대로 된 DOM 트리를 만들어 재귀 순회하며 노드를 삭제·치환한다. "트리를 한 번만 파싱해 여러 변형기가 공유"하는 CleanTree 패턴은 어떤 HTML 처리기에도 응용된다.

③ 결정적 URL↔경로 매핑 (멱등성의 비결)

크롤러의 영원한 골칫거리인 "같은 페이지를 여러 URL로 만나는 문제"를 urlx.Normalize가 정규화로 푼다. 그리고 경로를 해시 충돌 없이 결정적으로 만들어, 자산이 받아지기 전에 링크를 미리 재작성하는 비동기 파이프라인을 가능케 한다. "순수 함수로 부수효과를 격리"하는 설계의 교과서.

④ Go 동시성: 워커 풀과 세마포어

chan struct{} 세마포어로 동시 실행 수를 제한하고, sync.WaitGroup·sync.Mutex로 공유 상태(seenAssets, frontier)를 보호하는 전형적이고 견고한 Go 동시성 패턴을 실전 코드로 볼 수 있다.

⑤ 바이너리 포맷 직접 다루기 (ZIM)

zim/은 외부 라이브러리 없이 순수 Go로 ZIM 포맷을 읽고 쓴다. 헤더·디렉토리 엔트리·클러스터·zstd 압축을 직접 구현한 것이라, 파일 포맷 설계와 직렬화를 배우는 살아있는 예제다. "패킹이 결정적(같은 입력→바이트 동일 출력)"이라 체크섬·캐시가 안전하다는 점도 주목할 만하다.

7시스템 요구사항

kage를 돌리려면 무엇이 필요한가.

8직접 해볼 수 있는 실습 과제

"읽기"에서 "하기"로 — 난이도별 5단계.

9관련 기술 심화 학습 로드맵

kage를 발판으로 "웹 자동화 + 시스템 프로그래밍"을 4주에 쌓는다면.

10핵심 키워드 사전

kage를 읽다 막히는 용어 빠른 참조.

11참고 링크

• GitHub: tamnd/kage (본 분석 대상)
• 공식 문서·가이드: kage.tamnd.com
• 브라우저 제어: go-rod/rod · stealth
• HTML 파싱: golang.org/x/net/html
• 오프라인 포맷: OpenZIM · Kiwix
• CLI: cobra · fang
• 비교 도구: SingleFile · ArchiveBox