[🛠] GitHub Pages 블로그에 방문자 카운터 붙이기

✨ GPT-5.5의 요약 　

정적 GitHub Pages 블로그에 무료 범위의 Cloudflare Worker와 D1을 붙여, 기존 GA 누적값을 살리면서 오늘 방문 수와 글별 조회수를 보여주게 만든 기록.

블로그에 방문자 카운터를 붙이고 싶어졌다.

기능 자체가 대단해서는 아니다. 오히려 반대다. 너무 당연한 기능처럼 느껴지는데, GitHub Pages로 만든 정적 블로그에는 자연스럽게 붙어 있지 않았다.

Google Analytics는 이미 달려 있었다. 운영자인 나는 GA에 들어가면 방문자 수와 조회수를 볼 수 있었다. 그런데 그건 블로그 안에 보이는 숫자가 아니었다. 방문자는 이 블로그가 오늘도 읽히는지, 최근 글이 어느 정도 읽혔는지 알 수 없다.

네이버 블로그처럼 오늘, 누적, 글별 조회수가 작게 보이는 느낌을 원했다. 허세용 숫자라기보다는, 블로그가 죽은 정적 페이지가 아니라 계속 읽히고 있다는 신호에 가까웠다.

그래서 문제는 단순했다.

무료 정적 블로그의 장점은 유지하면서, 방문 통계만 아주 작게 동적으로 붙일 수 있을까?

조건부터 정했다

방문자 카운터 하나 붙이겠다고 구조가 커지는 건 싫었다.

처음부터 조건을 몇 개 정했다.

• GitHub Pages와 Jekyll 작성 흐름은 유지한다.
• 유료 서버는 쓰지 않는다.
• Cloudflare든 Firebase든 무료 범위 안에서 해결한다.
• 프로필 근처에 작게 붙인다.
• 모바일에서도 이상하게 길어지지 않게 한다.
• 블로그 전체 통계뿐 아니라 글별 조회수도 보여준다.
• 기존 GA 누적값을 버리지 않는다.

마지막 조건이 특히 중요했다.

새 카운터를 붙인다고 조회수가 0부터 시작하면 이상하다. 블로그는 이미 운영 중이었고, GA에는 예전부터 쌓인 조회수가 있었다. 그렇다고 GA만 계속 읽으면 내가 원하는 카운터 느낌과는 거리가 있었다.

GA만 읽으면 끝날 줄 알았다

처음에는 Google Analytics API를 읽으면 된다고 생각했다.

이미 GA가 데이터를 갖고 있으니, Cloudflare Worker 하나가 GA API를 호출해서 숫자를 반환하면 될 것 같았다. 실제로 서비스 계정을 만들고, GA 속성에 권한을 붙이고, API 호출까지는 가능했다.

그런데 막상 붙여보니 내가 원한 것과 달랐다.

GA는 분석 도구다. 운영자가 나중에 흐름을 보는 데는 좋지만, 블로그 화면에서 바로 반응하는 방문자 카운터로 쓰기에는 애매했다. 특히 오늘 숫자가 문제였다. 내가 방금 들어갔는데도 오늘 값이 0으로 보이면, 방문자 입장에서는 그냥 고장난 것처럼 보인다.

또 지표 이름도 헷갈렸다. active users와 page views는 서로 다른 값이다. 방문자 수를 엄격하게 잡으려 하면 숫자가 너무 보수적으로 보이고, page view를 쓰면 체감상 더 자연스럽지만 이름을 조심해야 한다.

결국 판단은 단순했다.

GA는 과거 기준값으로 쓰고, 지금부터 올라가는 카운트는 내가 직접 잡자.

baseline과 증가분을 나눴다

최종 구조는 이렇게 잡았다.

공개 조회수 = GA baseline + Cloudflare D1 증가분

GA baseline은 기존에 쌓인 숫자다. 기준일을 정하고, 그 시점까지의 전체 조회수와 글별 조회수를 저장한다.

그 다음부터는 Cloudflare Worker가 직접 카운트한다. 방문자가 블로그에 들어오면 JavaScript가 Worker를 호출하고, Worker는 D1에 오늘/월/전체/page path별 증가분을 기록한다.

정리하면 이렇다.

기존 누적값: Google Analytics baseline
새 증가분: Cloudflare Worker + D1
공개 API: Cloudflare Worker
블로그 표시: Jekyll include + JavaScript

이 방식이 마음에 들었던 이유는 둘 다 버리지 않기 때문이다.

GA의 기존 데이터는 살린다. 동시에 앞으로의 카운트는 블로그 화면에서 바로 반응하게 만든다.

왜 Cloudflare Worker와 D1이었나

Firebase도 후보였다. 하지만 이 정도 기능에는 Cloudflare 쪽이 더 단순했다.

GitHub Pages는 정적 사이트라 서버 코드를 둘 곳이 없다. Worker는 그 빈자리를 작게 채워준다. D1은 SQLite 기반이라 방문자 카운터처럼 단순한 숫자 저장에는 충분했다.

비용 조건도 맞았다. 개인 블로그 방문자 카운터 정도는 무료 범위 안에서 처리할 수 있다. 갑자기 많은 사람이 몰리면 카운트가 일부 흔들릴 가능성은 있지만, 글 자체가 망가지지는 않는다. 애초에 이건 결제 시스템이나 금융 장부가 아니다.

내가 원한 건 정확한 회계가 아니라, 블로그가 읽히고 있다는 흐름을 보여주는 쪽이었다.

봇과 중복 방문은 적당히 막았다

공개 페이지에 카운터를 붙이면 봇도 숫자를 올릴 수 있다.

완벽하게 막기는 어렵다. 그리고 너무 빡빡하게 막으면 오히려 내가 원한 카운터와 멀어진다. 나는 네이버 블로그처럼 어느 정도 넉넉하게 잡히는 쪽을 원했다.

그래서 Worker에서 몇 가지 정도만 처리했다.

• 명백한 bot user-agent는 제외한다.
• 같은 방문자와 같은 페이지 조합은 일정 시간 안에 다시 세지 않는다.
• 글별 조회수도 같은 방식으로 path 기준 증가분을 쌓는다.

즉, 너무 엄격한 분석 도구가 아니라 공개용 방문 카운터에 맞췄다.

화면에는 작게 붙였다

처음에는 통계를 여러 칸으로 보여주려 했다. 그런데 프로필 옆에 들어가는 UI는 작아야 했다. 숫자가 많아지면 오히려 블로그 첫 화면이 지저분해졌다.

그래서 결국 남긴 것은 세 가지다.

오늘 / 월 / 총

오늘은 지금 블로그가 읽히는 느낌을 준다. 월은 최근 규모감을 보여준다. 총은 블로그가 쌓아온 시간을 보여준다.

글 목록에는 각 글마다 조회수를 붙였다.

조회수 10회

이 값도 전체 통계와 같은 구조다.

글별 조회수 = GA 글별 baseline + Cloudflare D1 글별 증가분

예를 들어 어떤 글이 GA 기준으로 9회 조회된 상태였고, 새 카운터 전환 이후 1회 더 읽혔다면 화면에는 10회로 보인다.

이게 가장 자연스러웠다. 과거 조회수는 버리지 않고, 앞으로의 조회수는 바로 쌓인다.

결과

결과적으로 블로그 프로필 근처에는 이런 숫자가 붙었다.

오늘 1 / 월 66 / 총 4,944

그리고 글 목록에는 이런 식으로 조회수가 붙는다.

조회수 10회

기능 하나만 보면 작다. 하지만 이 작업은 꽤 마음에 든다.

문제는 명확했다. GitHub Pages 블로그에는 방문자 카운터가 없었다. GA는 있었지만 공개 화면의 카운터로는 부족했다. 그렇다고 블로그 하나 때문에 서버를 크게 만들고 싶지는 않았다.

그래서 기존 GA 데이터는 baseline으로 살리고, Cloudflare Worker와 D1로 이후 증가분만 직접 세는 구조를 붙였다.

정적 블로그의 장점은 그대로 뒀다. Markdown으로 글을 쓰고, GitHub Pages로 배포하고, 유지비는 거의 0원에 가깝다. 대신 딱 부족한 부분에만 작은 서버리스 조각을 얹었다.

나중에 이 블로그를 포트폴리오처럼 보여줄 일이 있다면, 이런 작업이 오히려 설명하기 좋을 것 같다. 거창한 기능은 아니지만, 실제 불편함에서 출발했고, 비용과 복잡도를 제한했고, 운영 가능한 형태로 끝까지 붙였으니까.