引言

在追求个人成长和习惯养成的过程中，每日打卡是一种简单有效的自我监督方式。为了方便记录和追踪打卡进度，我在bigpeter博客中开发了一个打卡功能。本文将详细介绍该功能的使用方法、技术原理以及常见问题解决方案。

2026年5月更新：打卡系统已从 GitHub Issues 架构升级为 Cloudflare Workers + D1 数据库，支持 GitHub OAuth 一键登录，无需手动配置 Token。

功能亮点

  • 每日打卡记录：轻松记录每天的打卡情况
  • 多设备同步：通过 Cloudflare D1 数据库实现数据云端存储
  • 智能统计：自动计算总天数、连续打卡、最长连续、本月打卡等数据
  • 贡献日历：GitHub 风格的热力图展示全年打卡记录
  • GitHub OAuth 登录：一键授权，无需手动配置 Token
  • 响应式设计：适配手机、平板和电脑等多种设备
  • 暗色/亮色主题：支持双主题切换

快速开始

1. 访问打卡页面

打开 https://bigpeter.top/checkin/

2. GitHub 登录

点击”GitHub 登录”按钮，在 GitHub 授权页面点击”Authorize”即可。系统仅请求 read:user 权限（读取公开用户信息），不会访问你的代码仓库。

3. 开始打卡

登录后，点击”立即打卡”按钮即可完成每日打卡。同一天只能打卡一次，后端会自动防重。

使用方法

查看统计信息

打卡页面显示四个关键统计指标：

  • 总打卡天数：累计打卡的总天数
  • 连续打卡：当前连续打卡的天数
  • 最长连续：历史上最长的连续打卡记录
  • 本月打卡：本月内已打卡的天数

贡献日历

页面下方以 GitHub 贡献图风格的日历热力图展示全年打卡记录，支持按年份切换查看。颜色深浅代表当日打卡次数。

退出登录

点击页面顶部用户栏右侧的”退出”按钮即可。

技术架构

后端

  • 运行环境：Cloudflare Workers
  • 数据库：Cloudflare D1（SQLite）
  • 认证：GitHub OAuth（read:user scope）
  • API 地址：https://github-checkin-api.751802108.workers.dev

前端

  • Jekyll 静态页面 + 原生 JavaScript
  • Session 存储在浏览器 localStorage 中
  • 无框架依赖，兼容现代浏览器

数据存储

数据库包含三张表：

  • users：用户信息（GitHub 用户名、头像）
  • checkins：打卡记录（日期、时间戳、备注）
  • sessions：登录会话（24 小时有效期）

安全性

  • GitHub OAuth 仅请求最小权限（read:user）
  • Session 24 小时自动过期
  • 打卡数据按用户隔离
  • 退出登录清除服务端 Session 和本地存储

故障排除

常见问题

1. 登录后加载失败

  • 检查浏览器控制台（F12 → Console）查看具体错误
  • 检查 https://github-checkin-api.751802108.workers.dev/api/leaderboard 能否正常访问
  • 清除 localStorage 中的 checkin_session 后重试

2. 打卡失败

  • 确认是否今天已经打过卡（”Already checked in today”）
  • Session 可能已过期，退出后重新登录
  • 检查网络连接

3. 统计数据不正确

清除本地缓存后刷新：

localStorage.removeItem('checkin_history_cache');

浏览器兼容性

  • 需要现代浏览器支持 ES6+、localStorage、Fetch API
  • 推荐：Chrome 60+、Firefox 55+、Safari 11+、Edge 79+

版本更新

v2.0.0 (2026-05-22)

  • 架构升级：从 GitHub Issues 迁移到 Cloudflare Workers + D1 数据库
  • 认证改进：GitHub OAuth 一键登录，无需手动配置 Personal Access Token
  • 数据迁移：历史打卡数据自动从 GitHub Issues 导入 D1
  • 后端重构：全新 RESTful API（/api/auth/*、/api/checkin、/api/stats、/api/leaderboard）
  • 贡献日历：保留 GitHub 风格热力图展示

v1.1.0 (2026-04-06)

  • 修复黑夜模式下按钮悬浮样式异常
  • 修复配置页面与底部按钮组重叠的布局问题
  • 添加多用户支持

v1.0.0 (2026-04-06)

  • 初始版本，基于 GitHub Issues 评论存储打卡数据

结语

打卡功能从最初基于 GitHub Issues 的简单实现，逐步演进为基于 Cloudflare Workers 的独立后端服务。希望这个工具能帮助更多人培养良好的打卡习惯。

如有问题或建议，欢迎在 GitHub 仓库 提交 Issue。

坚持打卡，记录成长，每一天都算数！