프로젝트 소개

방문자 통계는 Cloudflare Pages, Workers, D1 및 GitHub를 기반으로 한 경량 방문자 추적 시스템입니다. 핵심 아이디어는 이미지로 위장한 추적 픽셀을 통해 방문을 기록하는 것입니다. 이미지와 프론트엔드는 Cloudflare 엣지에 호스팅되고, 로그는 D1에 영구 저장되며, Telegram을 통해 실시간 알림을 전송할 수 있습니다. 주요 기능으로는 추적 픽셀 업로드 및 삽입, 시간, IP, 위치, 통신사, 기기, OS, 브라우저, 출처를 포함한 상세 로그 기록, 오늘, 7일, 30일, 3개월, 1년 단위의 유연한 통계 범위와 식별자별 필터링, 기기 지문을 포함한 Telegram 실시간 알림(버튼이 현재 도메인을 자동으로 가리킴), 웹 기반 이미지 관리(Git 저장소에 업로드 후 Pages 자동 배포 트리거), _panel 추적 포인트를 통한 관리 패널 접근 모니터링, UA 블랙리스트 및 /24 세그먼트 쿨다운을 통한 안티 크롤링 및 안티 속도 측정, 순수 D1 저장소 사용으로 쓰기 할당량 문제 방지 등이 있습니다. 아키텍처 측면에서 방문자가 GET /nezha.png를 요청하면 Cloudflare Worker가 처리합니다. 프론트엔드는 Git 정적 리소스를 읽어 이미지를 반환하고, 백엔드는 ctx.waitUntil을 통해 D1에 상세 로그와 일일 요약을 기록하고 Telegram으로 전송합니다. 관리자는 관리 패널을 통해 Worker에 이미지를 업로드하고, Worker는 Git 저장소에 기록한 후 Deploy Hook을 트리거하여 Pages를 재구축한 다음, D1을 조회하여 통계와 로그를 반환합니다. 구성 요소로는 Cloudflare Pages(index.html 및 _worker.js 호스팅), Cloudflare D1(방문 로그, 일일 요약, 이미지 인덱스 저장), Cloudflare Workers(API 및 이미지 요청 처리), GitHub 저장소(public/pic 디렉토리 아래 이미지 바이너리 저장), Telegram Bot API(알림 전송)가 있습니다. 배포에는 Cloudflare 계정, GitHub 계정, Telegram 계정 및 선택적 도메인이 필요합니다. 7개의 환경 변수(PASSWORD, GITHUB_TOKEN, REPO_NAME, BRANCH, CF_DEPLOY_HOOK_URL, TG_ID, TG_TOKEN)와 1개의 D1 바인딩(DB)을 준비해야 합니다. 프로세스는 템플릿으로 저장소 생성, D1 데이터베이스 생성, Telegram Bot 생성 및 토큰과 chat_id 획득, GitHub Fine-grained PAT 생성, Pages 프로젝트 생성(Git 자동 배포 비활성화하여 빌드 낭비 방지), Deploy Hook 생성, 사용자 정의 도메인 바인딩, 환경 변수 및 바인딩 통합 구성, 수동 Retry deployment를 통한 최초 배포 순서로 진행됩니다. 관리 패널에 처음 로그인하면 visits, daily_summary, img_index 세 개의 테이블이 자동으로 생성됩니다. 사용 시 이미지 관리에서 식별자를 추가하고 이미지를 업로드한 후 저장 및 배포하면 추적 링크(예: https://yourdomain.com/nezha.png)를 얻을 수 있습니다. 이 링크를 HTML이나 이메일에 삽입하면 통계가 수집됩니다. 개요 페이지에서는 오늘, 어제, 최근 7일, 최근 1년의 요약과 추세 그래프를 제공하며, 상세 로그 페이지에서는 날짜, 식별자, IP별 필터링 및 페이지네이션을 지원합니다. 관리 패널 자체 접근은 _panel 추적 포인트에 의해 기록되며, 로그인하지 않은 상태에서 접근 시 트리거되고, 로그인 후 새로고침 시에는 트리거되지 않습니다. 주의사항으로는 D1 무료 할당량(5GB 저장소, 일 10만 회 쓰기, 일 500만 회 읽기), GitHub 저장소는 1GB 이하 권장, 단일 이미지 8MB 이하, 지원 형식(PNG, JPG, GIF, WebP, SVG), 식별자는 영숫자, 밑줄, 하이픈으로 구성된 1~64자, 예약 식별자 _panel이 있습니다. Telegram 알림은 동일 IP에 대해 60초 내 한 번만 전송되며, 동일 /24 세그먼트는 쿨다운을 공유하고, 크롤러 UA 및 속도 측정 사이트 Referer는 알림이 전송되지 않습니다. Git 자동 배포를 비활성화한 경우 이미지 업로드는 관리 패널을 통해 저장 및 배포를 트리거해야 하며, 환경 변수 변경 후에는 재배포가 필요합니다. 보안을 위해 강력한 비밀번호 사용, PAT 권한 최소화, Deploy Hook URL 비공개를 권장합니다. 데이터는 wrangler d1 export를 통해 백업할 수 있습니다. 고급 설정으로 _worker.js의 STATS_DAYS(보존 일수) 및 PUSH_COOLDOWN_SEC(쿨다운 시간)을 수정하거나, UA 및 Referer 블랙리스트 정규식을 사용자 정의할 수 있습니다.