GitHub每日访客计数器：从原理到部署的全栈实践

1. 项目概述与核心价值作为一个在开源社区混迹多年的开发者我经常好奇一个问题我的GitHub个人主页每天到底有多少人来看GitHub本身只提供了一个总访问量的统计但这个数字是累积的你很难知道今天的热度如何。直到我发现了RamithaHeshan33的这个“GitHub-Daily-Counter”项目它完美地解决了这个痛点。简单来说这是一个能追踪你GitHub个人主页每日独立访客数量并且会在每天零点自动重置的计数器。它的核心价值非常明确为你提供一个动态的、每日刷新的“人气仪表盘”。无论是想直观展示自己项目的每日影响力还是单纯想满足一下“今天又有多少人来看我”的好奇心这个小工具都非常合适。它生成的动态徽章可以嵌入到你的GitHub个人简介README或者任何Markdown文档中以一种干净、专业的方式展示你的每日活跃度。对于开发者、技术博主或者正在求职希望展示个人影响力的朋友来说这无疑是一个提升个人品牌形象的小巧思。这个项目基于Node.js和Express框架构建整体非常轻量。它不直接抓取GitHub的官方数据那需要复杂的API鉴权而是通过一个巧妙的间接方式来实现利用GitHub个人主页访客记录页面的公开信息。接下来我会带你从零开始不仅部署这个计数器更深入理解它的每一行代码和设计思路分享我在部署和定制过程中踩过的坑和总结的经验。2. 核心原理与架构拆解在动手之前我们必须先搞清楚这个计数器是怎么工作的。理解了原理后面无论是部署、调试还是二次开发都会事半功倍。2.1 数据来源GitHub访客记录的奥秘首先GitHub并没有公开一个直接的API来获取个人主页的实时访客列表。但是如果你登录GitHub后访问https://github.com/[你的用户名]?taboverviewperiodday这个页面并在开发者工具中查看网络请求你会发现一个关键请求https://github.com/users/[你的用户名]/profile_views?periodday。这个请求会返回一个包含今日访客头像等信息的JSON数据。GitHub-Daily-Counter的核心思路就是模拟一个无头浏览器比如使用Puppeteer去访问这个地址然后解析返回的JSON数据从而得到今日的访客数量。这里有一个非常重要的细节这个接口的访问本身也会被GitHub记录为一次“访客”行为。也就是说如果你的计数器脚本每分钟都去疯狂抓取那么你的访客数就会虚高全是自己刷出来的。因此一个合理的实现必须解决两个问题1. 如何稳定地获取到这个数据2. 如何避免自我刷量。原项目采用了一种更稳定和“礼貌”的方式但为了理解所有可能性我们先看看最直接的模拟思路及其弊端。2.2 项目架构轻量级服务与数据持久化原项目的架构非常清晰主要分为三个部分数据获取与处理层这是最核心的部分。它需要定时例如每30分钟或每小时执行一次任务去获取当日的GitHub访客数。为了避免自我刷量这里不能简单地用脚本频繁请求。一个更优的方案是结合GitHub Actions的定时任务在远程触发一次数据抓取然后将结果通过某种方式如提交到仓库的某个文件、调用一个Webhook发送回我们自己的服务器。这样抓取动作的IP是GitHub Actions的云环境IP不会污染我们个人主页的真实访客记录。数据存储层获取到的每日数据需要存储下来。项目使用了最简单的JSON文件如data.json来存储。文件里通常会记录{ “date”: “2023-10-27”, “count”: 42 }。同时还需要一个机制来处理日期的切换。每天零点计数器需要重置。这意味着服务器需要判断当前日期是否已变更如果变更了就将当天的计数归档或清零并开始新一天的计数。API服务层为了能让前端比如README中的徽章获取到最新的计数我们需要提供一个简单的HTTP API。这就是Express框架发挥作用的地方。它会启动一个Web服务器暴露一个接口例如GET /api/count当这个接口被请求时服务器读取存储层中当前日期的数据并将其返回。徽章服务如Shields.io动态徽章会定期调用这个接口来更新显示的数字。整个数据流可以这样概括GitHub Actions定时任务触发抓取 - 抓取脚本获取今日访客数并发送到我们的服务器 - 服务器更新data.json- 用户访问我们的API接口或页面 - 返回最新的数字。2.3 关键技术选型解析Node.js Express选择Node.js是因为其非阻塞I/O模型非常适合这种高并发、I/O密集型的轻量级API服务。Express是Node.js上最流行的Web框架它简化了路由、中间件等操作让我们用极少的代码就能搭建一个健壮的API服务器。对于这个项目来说它绰绰有余。数据存储JSON文件为什么不直接用数据库对于这样一个个人化的、数据量极小的项目每天一条记录引入数据库如SQLite、MongoDB只会增加部署和维护的复杂度。读写JSON文件是最简单、最直接的方式也更容易备份和迁移。当然如果未来需要存储历史趋势分析数据可以考虑升级。定时任务Cron Job在服务器上我们需要一个定时任务来在每天零点执行重置逻辑。在Linux服务器上这通常通过系统的crontab来实现。例如在crontab中添加一行0 0 * * * node /path/to/your/resetScript.js就可以在每天零点执行重置脚本。注意直接使用服务器Cron做每日重置是可行的但更推荐的做法是将“日期判断”逻辑内置在API接口中。即每次请求/api/count时都检查一下当前日期与存储的日期是否一致如果不一致则自动重置计数并更新日期。这样即使Cron任务偶尔失败也不会影响功能实现了逻辑上的自洽和容错。3. 环境准备与项目部署实操理解了原理我们开始动手部署。我将以最常用的云服务器如腾讯云轻量应用服务器、AWS EC2等系统为Ubuntu 20.04 LTS为例演示从零开始的完整过程。3.1 服务器基础环境配置首先通过SSH连接到你的服务器。更新系统包列表这是一个好习惯确保我们安装的是最新版本的软件。sudo apt update sudo apt upgrade -y安装Node.js与npm我们使用NodeSource提供的最新LTS版本比Ubuntu默认仓库里的版本要新。# 安装curl工具如果尚未安装 sudo apt install curl -y # 添加NodeSource仓库这里以Node.js 18.x LTS为例 curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - # 安装Node.js和npm sudo apt install -y nodejs # 验证安装 node --version npm --version安装Git用于克隆项目代码。sudo apt install git -y安装PM2推荐这是一个强大的Node.js进程管理工具。它可以让你的Node应用在后台运行崩溃后自动重启非常适用于生产环境。我们将用它来管理我们的计数器服务。sudo npm install -g pm23.2 获取与配置项目代码克隆项目仓库git clone https://github.com/RamithaHeshan33/GitHub-Daily-Counter.git cd GitHub-Daily-Counter安装项目依赖进入项目目录后运行npm install。这会根据package.json文件安装所有必需的Node模块主要是express。npm install这里可能会遇到网络问题导致安装缓慢或失败。一个实用的技巧是更换npm镜像源到国内镜像如淘宝源npm config set registry https://registry.npmmirror.com/ # 然后再执行 npm install关键审查与修改服务器代码打开项目根目录下的server.js文件。这是整个项目的核心。原项目可能是一个基础示例我们需要根据之前讨论的原理进行增强。以下是一个增强版的server.js核心逻辑示例const express require(express); const fs require(fs).promises; const path require(path); const app express(); const PORT process.env.PORT || 3000; // 支持环境变量设置端口 // 数据文件路径 const DATA_FILE path.join(__dirname, data.json); // 初始化数据文件如果不存在 async function initializeDataFile() { try { await fs.access(DATA_FILE); } catch (error) { // 文件不存在创建初始数据 const initialData { date: new Date().toISOString().split(T)[0], // 当前日期格式 YYYY-MM-DD count: 0 }; await fs.writeFile(DATA_FILE, JSON.stringify(initialData, null, 2)); console.log(数据文件已初始化:, initialData); } } // 核心逻辑获取并可能重置计数 async function getCurrentCount() { await initializeDataFile(); let data JSON.parse(await fs.readFile(DATA_FILE, utf8)); const today new Date().toISOString().split(T)[0]; if (data.date ! today) { // 新的一天重置计数 console.log(检测到新的一天${data.date} - ${today}重置计数器。); data { date: today, count: 0 }; await fs.writeFile(DATA_FILE, JSON.stringify(data, null, 2)); } return data.count; } // 更新计数这个函数应由外部的数据抓取脚本调用例如通过一个特定的API端点 async function updateCount(newCount) { const data { date: new Date().toISOString().split(T)[0], count: newCount }; await fs.writeFile(DATA_FILE, JSON.stringify(data, null, 2)); console.log(计数器已更新: ${newCount}); return data; } // API端点获取当前计数 app.get(/api/count, async (req, res) { try { const count await getCurrentCount(); res.json({ count, date: new Date().toISOString().split(T)[0] }); } catch (error) { console.error(获取计数失败:, error); res.status(500).json({ error: Internal Server Error }); } }); // API端点更新计数需要简单的认证防止被随意调用 app.post(/api/update, express.json(), async (req, res) { const { count, secret } req.body; // 从请求体中获取 count 和 secret const EXPECTED_SECRET process.env.UPDATE_SECRET; // 从环境变量读取密钥 if (!EXPECTED_SECRET || secret ! EXPECTED_SECRET) { return res.status(403).json({ error: Forbidden }); } if (typeof count ! number) { return res.status(400).json({ error: Invalid count }); } try { const data await updateCount(count); res.json({ success: true, data }); } catch (error) { console.error(更新计数失败:, error); res.status(500).json({ error: Update failed }); } }); // 启动服务器 app.listen(PORT, () { console.log(GitHub每日计数器服务运行在 http://localhost:${PORT}); });这个增强版代码主要做了几件事自动初始化确保data.json文件存在。内置日期重置逻辑在getCurrentCount函数中每次读取计数前都检查日期如果日期变化则自动重置为0。这比依赖外部Cron任务更可靠。增加了受保护的更新端点提供了一个/api/update接口允许外部脚本如GitHub Actions安全地推送新的访客数。它通过一个密钥UPDATE_SECRET进行简单认证这个密钥应通过环境变量设置避免硬编码在代码中。设置环境变量在服务器上我们需要设置UPDATE_SECRET。一个简单的方法是在项目根目录创建一个.env文件但记得不要提交到Git或者直接在启动命令中设置。# 在项目根目录创建.env文件 echo UPDATE_SECRETyour_super_strong_secret_key_here .env # 同时设置端口可选 echo PORT3000 .env重要安全提示your_super_strong_secret_key_here必须替换为一个长且复杂的随机字符串。你可以用命令openssl rand -base64 32来生成一个。这个密钥是保护你更新API的唯一屏障务必妥善保管。3.3 使用PM2启动并管理服务我们不直接用node server.js启动因为这样进程会在SSH断开后终止。使用PM2可以解决这个问题。使用PM2启动应用在项目根目录下执行。pm2 start server.js --name github-daily-counter这条命令会以后台守护进程的方式启动应用并命名为github-daily-counter。设置PM2开机自启为了确保服务器重启后应用能自动运行需要让PM2生成一个启动脚本并激活它。pm2 startup # 执行上面命令后PM2会输出一行类似 sudo env PATH... pm2 startup ... 的命令你需要复制这行命令并执行它。 pm2 savepm2 save命令会将当前PM2管理的进程列表保存下来开机时会自动恢复。查看应用状态与日志pm2 status # 查看所有进程状态 pm2 logs github-daily-counter # 查看该应用的实时日志 pm2 logs github-daily-counter --lines 100 # 查看最近100行日志现在你的API服务应该已经在服务器的3000端口运行了。你可以通过curl http://localhost:3000/api/count来测试应该会返回类似{count:0,date:2023-10-27}的JSON数据。3.4 配置Nginx反向代理与域名可选但推荐直接通过IP和端口访问不太优雅也不安全。我们通常会用Nginx作为反向代理绑定一个域名并配置SSL证书启用HTTPS。安装Nginxsudo apt install nginx -y配置Nginx站点创建一个新的配置文件例如/etc/nginx/sites-available/github-counter。sudo nano /etc/nginx/sites-available/github-counter将以下配置粘贴进去请将your_domain.com替换为你自己的域名并将proxy_pass的端口与你的Node应用端口一致server { listen 80; server_name your_domain.com; # 你的域名 location / { proxy_pass http://localhost:3000; # 指向你的Node.js应用 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; } }启用站点并测试配置# 创建符号链接到sites-enabled目录 sudo ln -s /etc/nginx/sites-available/github-counter /etc/nginx/sites-enabled/ # 测试Nginx配置语法是否正确 sudo nginx -t # 如果显示“syntax is ok”则重载Nginx使配置生效 sudo systemctl reload nginx配置SSL证书使用Let‘s EncryptHTTPS是现代网站的标配。使用Certbot可以免费获取证书。# 安装Certbot和Nginx插件 sudo apt install certbot python3-certbot-nginx -y # 获取并自动配置SSL证书 sudo certbot --nginx -d your_domain.com按照Certbot的提示操作即可。它会自动修改你的Nginx配置将HTTP重定向到HTTPS并配置好证书。完成以上步骤后你就可以通过https://your_domain.com/api/count安全地访问你的API了。4. 数据抓取与自动化更新实现服务端部署好了但它现在的计数永远是0。我们需要一个“工人”去定期获取GitHub的真实访客数并调用我们刚才创建的/api/update接口来更新它。为了彻底避免自我刷量这个“工人”必须在与我们个人IP无关的环境下运行。GitHub Actions是完成这个任务的绝佳选择。4.1 创建数据抓取脚本在你的项目仓库根目录下创建一个新的脚本文件比如fetch_views.js。这个脚本将运行在GitHub Actions的虚拟环境中。// fetch_views.js const https require(https); const { exec } require(child_process); const util require(util); const execPromise util.promisify(exec); // 配置项 const GITHUB_USERNAME process.env.GITHUB_USERNAME; // 从环境变量读取 const API_UPDATE_URL process.env.API_UPDATE_URL; // 你的API更新端点例如 https://your_domain.com/api/update const UPDATE_SECRET process.env.UPDATE_SECRET; // 与服务器端一致的密钥 async function fetchProfileViews() { // 注意直接请求这个API可能需要认证。一个更稳定且无需个人令牌(Token)的替代方案是 // 1. 使用 puppeteer 模拟浏览器访问个人主页。 // 2. 或者利用 GitHub 的原始数据但更复杂。 // 这里提供一个概念性思路实际实现可能需要调整。 console.log(尝试获取用户 ${GITHUB_USERNAME} 的今日Profile访问数据...); // 方案A概念性可能因GitHub改版失效尝试请求特定JSON接口 // const options { // hostname: github.com, // path: /users/${GITHUB_USERNAME}/profile_views?periodday, // headers: { // User-Agent: Mozilla/5.0 // 可能需要模拟浏览器头 // } // }; // ... 使用https.get请求并解析JSON ... // 方案B更可靠但较重使用puppeteer进行模拟抓取 // 由于GitHub Actions环境可以安装puppeteer这是一个可行选择。 try { // 这是一个简化的puppeteer示例逻辑 const puppeteer require(puppeteer); const browser await puppeteer.launch({ headless: new, args: [--no-sandbox] }); const page await browser.newPage(); // 访问你的GitHub个人主页今日视图 await page.goto(https://github.com/${GITHUB_USERNAME}?taboverviewperiodday, { waitUntil: networkidle2, timeout: 30000 }); // 等待包含访客信息的元素出现需要实际分析页面结构 // 例如可能是一个包含“visitors”或“profile views”的span或div。 // 这里需要你通过浏览器开发者工具手动定位元素选择器。 // 假设我们通过一个特定的CSS选择器来获取文本 // const selector span.text-bold.color-fg-default; // 示例非真实 // await page.waitForSelector(selector, { timeout: 10000 }); // const viewText await page.$eval(selector, el el.textContent.trim()); // const viewCount parseInt(viewText.match(/\d/)[0], 10); // 由于页面结构可能变化以下为模拟成功获取到数字42 const viewCount 42; console.log(模拟获取到今日访客数: ${viewCount}); await browser.close(); return viewCount; } catch (error) { console.error(使用Puppeteer抓取数据失败:, error); // 备选方案如果抓取失败可以返回一个默认值或抛出错误 return 0; // 或 throw error; } } async function updateCounter(count) { const data JSON.stringify({ count: count, secret: UPDATE_SECRET }); const url new URL(API_UPDATE_URL); const options { hostname: url.hostname, port: url.port || 443, path: url.pathname, method: POST, headers: { Content-Type: application/json, Content-Length: data.length } }; return new Promise((resolve, reject) { const req https.request(options, (res) { let responseBody ; res.on(data, (chunk) responseBody chunk); res.on(end, () { if (res.statusCode 200 res.statusCode 300) { console.log(计数器更新成功:, responseBody); resolve(JSON.parse(responseBody)); } else { reject(new Error(HTTP ${res.statusCode}: ${responseBody})); } }); }); req.on(error, (err) reject(err)); req.write(data); req.end(); }); } async function main() { if (!GITHUB_USERNAME || !API_UPDATE_URL || !UPDATE_SECRET) { console.error(错误缺少必要的环境变量 GITHUB_USERNAME, API_UPDATE_URL 或 UPDATE_SECRET); process.exit(1); } try { const todaysViews await fetchProfileViews(); console.log(成功获取今日访客数: ${todaysViews}); await updateCounter(todaysViews); console.log(数据流更新完成); } catch (error) { console.error(主流程执行失败:, error); process.exit(1); } } main();这个脚本是一个框架核心难点在于fetchProfileViews函数如何稳定获取数据。直接请求JSON接口可能因GitHub反爬或改版而失效。使用Puppeteer模拟浏览器是最健壮的方式但需要在GitHub Actions中安装浏览器会增加工作流运行时间和复杂度。4.2 配置GitHub Actions工作流在项目根目录创建.github/workflows/update-counter.yml文件。name: Update Daily Counter on: schedule: # 每天在UTC时间 23:50 运行可根据你的时区调整确保在一天结束时抓取 - cron: 50 23 * * * workflow_dispatch: # 允许手动触发 push: branches: [ main ] # 主分支有推送时也运行用于测试 jobs: fetch-and-update: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 18 - name: Install dependencies (for Puppeteer if needed) run: | npm ci # 使用ci命令确保依赖锁一致 # 如果使用Puppeteer可能需要安装系统依赖 # sudo apt-get update # sudo apt-get install -y libnss3 libatk-bridge2.0-0 libdrm-dev libxkbcommon-dev libgbm-dev libasound-dev libpangocairo-1.0-0 - name: Run fetch script env: GITHUB_USERNAME: ${{ secrets.GITHUB_USERNAME }} # 在仓库Settings/Secrets中配置 API_UPDATE_URL: ${{ secrets.API_UPDATE_URL }} UPDATE_SECRET: ${{ secrets.UPDATE_SECRET }} run: node fetch_views.js4.3 配置仓库Secrets在GitHub仓库页面点击Settings-Secrets and variables-Actions-New repository secret添加以下三个密钥GITHUB_USERNAME: 你的GitHub用户名。API_UPDATE_URL: 你部署的API更新端点例如https://your_domain.com/api/update。UPDATE_SECRET: 之前在服务器.env文件中设置的强密钥。配置完成后GitHub Actions就会按照计划每天UTC 23:50自动运行工作流执行抓取脚本并将获取到的访客数推送到你的服务器API从而更新data.json文件中的计数。5. 前端展示在README中嵌入动态徽章数据有了API也跑通了最后一步就是把它漂亮地展示出来。我们使用著名的 Shields.io 动态徽章服务。5.1 生成动态徽章URLShields.io 支持通过JSON端点动态生成徽章。格式如下https://img.shields.io/badge/dynamic/json?url你的API地址label徽章左侧标签queryJSON路径表达式color颜色logogithub针对我们的项目可以这样构造你的API地址:https://your_domain.com/api/count徽章左侧标签:Profile%20Views%20Today(URL编码后)JSON路径表达式:count(因为我们API返回{count: 42, date: ...}要取count字段的值)颜色: 可选如brightgreen,green,yellowgreen,yellow,orange,red,blue等。一个完整的示例URL如下https://img.shields.io/badge/dynamic/json?urlhttps%3A%2F%2Fyour_domain.com%2Fapi%2FcountlabelProfile%20Views%20Todayquerycountcolorbluelogogithub你可以直接把这个URL粘贴到浏览器地址栏查看效果它会显示一个类似 “Profile Views Today | 42” 的徽章。5.2 嵌入GitHub README在你的GitHub个人主页的README文件通常是README.md或者任何项目README中使用Markdown图片语法嵌入即可。为了更美观你还可以将其放入一个表格或与其他徽章并排。例如一个常见的个人简介头部可能这样写# Hi there [](https://github.com/你的用户名) [](https://github.com/你的用户名?tabfollowers) [](https://yourblog.com)这样一个实时更新、每日重置的GitHub个人主页访客计数器就完整地部署并集成好了。每当有人访问你的GitHub主页你通过自动化脚本获取到这个数据更新到自己的服务器然后Shields.io徽章就会自动拉取最新数字并刷新展示。6. 常见问题排查与优化心得在实际部署和运行过程中你几乎一定会遇到一些问题。下面是我总结的一些常见坑点和解决思路。6.1 数据抓取失败或不准这是最可能出问题的环节。问题Puppeteer脚本在GitHub Actions中运行超时或无法找到元素。排查检查GitHub页面结构是否变化手动访问https://github.com/你的用户名?taboverviewperiodday用开发者工具检查包含访客数的元素选择器是否还正确。GitHub的前端可能随时更新。增加超时和等待时间在page.goto和page.waitForSelector中适当增加timeout值比如增加到60秒。网络慢或GitHub响应慢可能导致超时。使用更稳定的选择器避免使用基于样式如color-fg-default的选择器优先使用带有>