Build Note

깃허브 블로그 댓글 기능 만들기: Cloudflare Worker와 D1로 익명 댓글 구현

2026. 7. 1. · 수정 2026. 7. 2.

GitHub Pages로 만든 깃허브 블로그에 댓글 기능을 붙이고 싶다면, 먼저 알아야 할 게 있습니다. GitHub Pages는 글을 보여주는 데는 좋지만, 방문자가 남긴 댓글을 저장해주지는 않습니다. 이 글은 Astro와 GitHub Pages 블로그에 Cloudflare Worker와 D1을 붙여서 익명 댓글, 삭제 비밀번호, 비공개 댓글까지 만든 과정을 정리한 글입니다.

처음에는 단순하게 생각했습니다. 사용자가 댓글을 쓰면 GitHub 저장소 어딘가에 저장하면 되지 않을까. 하지만 직접 붙여보니 정적 블로그와 서버가 있는 블로그의 차이가 꽤 분명했습니다. 댓글 기능을 붙이고 싶은 사람이라면, giscus나 Disqus 같은 기존 도구를 쓸지, Cloudflare Worker와 D1로 직접 만들지 판단하는 데 도움이 될 것 같습니다.

생성된 참고 이미지입니다.

핵심 요약

목표: GitHub Pages 블로그에 익명 댓글 기능 붙이기
구성: Astro 댓글 폼 → Cloudflare Worker → D1 Database
기능: 공개 댓글, 비공개 댓글, 삭제 비밀번호
비교: giscus/Utterances는 편하지만 GitHub 로그인 장벽이 있음
주의: 스팸 방지, IP 처리, 관리자 화면은 별도 설계 필요

생성된 참고 이미지입니다.

정적 블로그 한계

GitHub Pages는 정적 파일을 보여주는 서비스입니다. HTML, CSS, JavaScript 파일을 만들어서 올려두면 방문자는 그 파일을 받아 봅니다. 이 구조는 단순하고 안정적입니다. 서버 비용도 거의 들지 않습니다.

대신 방문자가 무언가를 입력했을 때 그 내용을 저장해줄 곳이 없습니다. 댓글을 쓴다고 해서 GitHub Pages의 파일이 바로 수정되는 것은 아닙니다.

처음에는 이런 흐름을 떠올렸습니다.

방문자 댓글 작성
→ comments.json 같은 파일에 저장
→ 블로그에 표시

하지만 GitHub Pages만으로는 이 흐름이 되지 않습니다. 브라우저에서 GitHub 저장소 파일을 직접 수정하려면 인증 토큰이 필요한데, 그 토큰을 프론트엔드 코드에 넣을 수는 없습니다. 노출되는 순간 누구나 저장소를 건드릴 수 있기 때문입니다.

결국 댓글에는 저장을 담당하는 중간 서버가 필요했습니다.

생성된 참고 이미지입니다.

기존 댓글 도구

처음에는 GitHub Discussions나 Issues를 댓글 저장소처럼 쓰는 방법도 생각했습니다. Giscus나 Utterances 같은 도구가 이미 있고, 개발 블로그에서는 꽤 자연스럽게 보입니다.

다만 이 방식은 대부분 GitHub 로그인이 필요합니다. 개발자 대상으로는 괜찮지만, 일반 방문자가 가볍게 댓글을 남기기에는 조금 높은 장벽입니다.

익명 댓글처럼 보이게 하려면 중간 서버가 방문자 입력을 받아 GitHub API로 Discussion에 대신 남기는 구조도 가능합니다. 하지만 그렇게 하면 결국 봇 계정, GitHub 토큰, 스팸 처리, 삭제 처리까지 같이 고민해야 합니다. GitHub에 댓글을 남기는 장점은 있지만, 댓글 시스템으로는 생각보다 무거워졌습니다.

생성된 참고 이미지입니다.

구현 구조

이번에는 Cloudflare Worker와 D1을 사용했습니다.

구조는 단순합니다.

Astro 블로그 댓글 폼
→ Cloudflare Worker
→ D1 SQLite Database
→ 공개 댓글만 블로그에 표시

Worker는 작은 API 서버처럼 동작합니다. 댓글을 저장하고, 댓글 목록을 불러오고, 삭제 요청을 처리합니다. D1은 SQLite 기반 데이터베이스라 댓글 같은 작은 데이터를 저장하기에 충분했습니다. 무료로 시작할 수 있다는 점도 개인 블로그에는 중요했습니다.

댓글 테이블에는 대략 이런 값이 들어갑니다.

글 slug
닉네임
댓글 내용
IP 일부 표시값
IP 해시
삭제 비밀번호 해시
공개/비공개 여부
상태값
작성 시간

원본 IP와 삭제 비밀번호는 그대로 저장하지 않았습니다. IP는 일부만 표시하고, 내부적으로는 해시를 저장합니다. 삭제 비밀번호도 원문이 아니라 해시만 저장합니다. 작은 기능이어도 이런 부분은 처음부터 조심하는 게 낫다고 봤습니다.

생성된 참고 이미지입니다.

삭제 비밀번호

처음에는 익명 댓글을 바로 공개하는 것만 생각했습니다. 그런데 막상 테스트 댓글을 달아보니 문제가 보였습니다. 로그인 없이 댓글을 쓰게 하면, 나중에 작성자가 자기 댓글을 지울 방법이 없습니다.

그래서 댓글 작성 시 삭제 비밀번호를 같이 받도록 바꿨습니다.

닉네임
댓글 내용
삭제 비밀번호
비공개 댓글 체크박스

작성자는 댓글을 남길 때 입력한 비밀번호로 나중에 삭제할 수 있습니다. 물론 완전한 계정 기반 권한 관리는 아니지만, 익명 댓글이라는 조건에서는 현실적인 타협이라고 생각했습니다.

삭제도 실제로는 바로 DB에서 지우는 방식이 아니라, 상태를 바꿔 목록에서 숨기는 방식으로 처리했습니다.

approved → rejected

운영하다 보면 스팸이나 문제 댓글이 생길 수 있기 때문에, 처음부터 상태값을 두는 편이 관리하기 쉽습니다.

비공개 댓글

댓글 기능을 만들다 보니 공개 댓글만으로는 부족하다는 생각이 들었습니다. 블로그 글에 공개적으로 남기기는 애매하지만, 작성자에게만 전하고 싶은 말도 있을 수 있습니다. 네이버 블로그의 비밀댓글에 익숙한 사람도 많습니다.

그래서 체크박스로 비공개 댓글을 선택할 수 있게 했습니다.

비공개 댓글은 D1에는 저장되지만, 공개 댓글 목록에는 나오지 않습니다. 운영자는 D1에서 내용을 확인할 수 있습니다. 지금 단계에서는 별도 관리자 페이지까지 만들지는 않았습니다. 개인 블로그라면 처음부터 관리자 화면을 크게 만드는 것보다, 필요한 기능을 작게 붙이는 쪽이 더 맞다고 봤습니다.

IP 표시

익명 댓글에서 IP를 일부 표시하는 방식도 고민이 있었습니다. 완전 익명으로 열어두면 가볍게 쓰기는 좋지만, 스팸이나 무책임한 댓글이 늘어날 수 있습니다. 반대로 IP를 전부 노출하면 개인정보 측면에서 부담이 큽니다.

그래서 전체 IP가 아니라 일부만 표시했습니다.

221.143.xxx.xxx

이 정도면 완전한 신원 정보는 아니지만, 댓글이 완전히 흔적 없이 떠다니는 느낌도 줄어듭니다. 내부적으로도 원본 IP를 그대로 저장하지 않고 해시로 저장했습니다.

입력 기능

이번에 댓글 기능을 붙이면서 가장 크게 느낀 건 이 부분입니다.

정적 블로그는 글을 보여주는 데에는 정말 좋습니다. 빠르고, 비용이 적고, 구조도 단순합니다. 하지만 사용자가 무언가를 입력하는 순간 이야기가 달라집니다.

댓글, 좋아요, 문의 폼, 비공개 메시지 같은 기능은 결국 어딘가에 데이터를 저장해야 합니다. 그때부터는 API, DB, 권한, 스팸 방지, 삭제 정책을 같이 생각해야 합니다.

처음에는 댓글창 하나 붙이는 일처럼 보였는데, 실제로는 작은 서비스 하나를 붙이는 일에 가까웠습니다.

직접 구현

물론 Cusdis나 Giscus 같은 도구를 쓰면 더 쉽게 끝났을 수도 있습니다. 하지만 직접 붙여보니 정적 사이트의 한계와 확장 방식이 더 잘 보였습니다.

특히 Astro와 GitHub Pages 조합은 기본은 정적으로 두고, 필요한 기능만 Worker로 붙이기에 괜찮았습니다. 블로그 전체를 서버 기반으로 옮기지 않아도 댓글 같은 동적인 기능을 추가할 수 있었습니다.

지금 구조가 완벽한 댓글 시스템은 아닙니다. 관리자 화면도 아직 없고, Turnstile 같은 봇 방지도 운영 전에 더 다듬어야 합니다. 그래도 개인 블로그에서 익명 댓글, 삭제 비밀번호, 비공개 댓글 정도를 무료에 가깝게 붙이는 출발점으로는 충분해 보였습니다.

최종정리

GitHub Pages 블로그에는 기본 댓글 기능이 없습니다. 하지만 그게 꼭 단점만은 아니었습니다. 필요한 기능을 직접 고르면서 붙일 수 있고, 너무 무거운 블로그 시스템으로 가지 않아도 됩니다.

이번에 해보면서 느낀 건, 정적 블로그는 글을 쌓기에는 좋고, 입력 기능은 작게 분리해서 붙이는 게 좋다는 점이었습니다. 댓글 하나에도 저장소, API, DB, 개인정보, 삭제 흐름이 따라옵니다.

그래서 오히려 블로그를 운영하기 전에 이런 구조를 한 번 직접 만져보는 게 꽤 도움이 됐습니다. 글을 쓰는 공간을 만든다는 건 단순히 화면을 꾸미는 일이 아니라, 사람들이 어떻게 들어오고 어떻게 반응을 남길지도 같이 정하는 일이었습니다.