项目放到 GitHub 以后, 我想知道后来怎样了
有一次, 我做的面板里显示克隆数是 22, GitHub 上却是 24.
差得不多, 但既然做的是统计工具, 就不能靠差不多糊弄过去. 查下来才发现, 面板保存的数据还停在前几天. 手动同步后, 那个范围内的数值才对上.
这件事发生在 RepoPulse 的开发过程中.
它是我给自己的 GitHub 项目做的一个数据面板. 起初想做的事很直接: 把仓库访问, 克隆, Stars 和 Release 下载放到一起看, 不用在几个页面之间来回找.
项目放出去以后, 我会想知道后来怎样了: 有没有人来看, 有没有人下载了安装包, 这几天和之前相比有什么变化. 光看一个 Star 数字, 回答不了这些问题.
结果, 面板画出来只是开始. 后面花时间最多的, 是把每个数字究竟代表什么弄清楚.
先有一个能看的地方
RepoPulse 做成了可以自托管的 Web 应用. 前端用 Next.js, 数据放在 MySQL, 另外有一个负责同步的 worker.
界面里可以选要跟踪的仓库, 看总览和单个项目的数据, 查看 Release 资源的下载次数, 再生成报告或导出 CSV. 我也给它加了中英文切换.
这些页面对我来说, 是把分散的信息收在一处的办法. 比如一个 Android 项目, 仓库本身有人访问, Release 里又有不同版本的 APK, 我想在同一个地方看见它们各自的情况.
看板很容易造成错觉: 卡片有数字, 折线有起伏, 就像整个系统已经在正常工作.
开发时用演示数据试布局很方便. 真正接入 GitHub 后, 我希望两者分清. 没有配置好连接, 页面就说明还缺什么, 不继续拿一组好看的演示数字填满首页.
页面空着时, 至少能明确知道眼前还没有可用数据.
有总数, 未必有今天的增量
Release 下载是一个很典型的例子.
某个安装包当前累计下载了多少次, 可以查到. 但刚接入时看到一个总数, 并不能知道其中多少发生在今天.
早期报告里就出现过这种别扭: 一边列着累计下载, 一边又用当天新增的说法描述它. 数字各自能显示, 放在一起读, 却不对劲.
后来先把文案改回数据真正支持的意思. 按当前 Stars 排名, 就写 Stars 排名; 只有下载总数, 就写累计下载. 没有历史比较, 也不在旁边摆一个像模像样的增长百分比.
要看变化, 得先留下前一次的记录.
于是同步时也开始保存下载快照. 第一次看到的总数作为基线, 不把它全部算成新增. 后面的快照再与之前的记录比较. 如果中间隔了几天没采集, 这段差值也不能轻易理解成某一天精确发生的下载量.
这些处理并不显眼, 却决定了报告里的句子有没有依据.
历史, 得从开始记录的时候攒
访问和克隆还有另一层问题.
GitHub 的相关 Traffic API 提供最近 14 天的统计. 时间往前走, 窗口也跟着移动, 它并不是一份可以随时取回所有过去的账本. 这个范围在 GitHub 官方文档里有明确说明.
RepoPulse 因此要把每次取得的每日数据保存下来. 同一天再次出现, 就更新那一天的记录, 而不是把整个窗口的总数再加一次. 连续记录下去, 才会慢慢积累出比单个窗口更长的历史.
这里的累计也有边界. 它是 RepoPulse 实际收集到的次数, 不是项目自诞生以来的完整历史. 早于首次采集窗口的部分, 不能凭空补回来; 如果漏采太久, 也可能留下缺口.
访问次数更不能直接叫作有多少个人. 同一个人可能多次访问, 不同日期的去重访客数也不能简单相加, 就宣布得到了全程去重的人数.
这些说明需要留在对应的位置, 以后回来看时不用重新猜累计从哪里开始.
22 和 24, 差在没有继续记
再回到开头那次检查.
2026 年 7 月 13 日, Modify Positioning 在面板里的累计克隆仍然显示 22. 查保存的明细, 数据只到 7 月 8 日. 同步刷新到 7 月 12 日以后, 对应 14 天范围的合计变成了 24, 与当时 GitHub Traffic 对上.
这两个数只是那一次检查的快照, 不是项目现在的成绩.
原因也不神秘: 页面读到了数据库里的记录, 但记录没有跟着时间继续更新. 再刷新页面, 读到的仍然是那些旧数据.
做一个这样的工具, 如果还要靠我想起来就点一下同步, 很容易把遗漏变成常态. 后来把独立 worker 部署起来, 当时设定为每天北京时间 09
同步, 保存仓库和 Release 的快照, 同时记录任务结果.那次上线后还实际跑过一轮同步, 确认跟踪的仓库能采集成功. 至于后续每天有没有正常完成, 仍然要看任务记录. 定时规则写在那里, 不能替每一次执行作保证.
定时同步省掉了每天记得点按钮这件事, 但数据仍然需要核对.
也不能每看一眼, 就让所有请求重来
数据接上以后, 页面速度又成了问题.
早先仓库列表会逐个补充实时流量和 Release 信息. 仓库多一些, 打开列表就要等一串请求. 我只是想扫一眼, 页面却像要重新做一遍调查.
后来把这部分调整为读取已经保存的流量和最新快照, 仓库列表本身再按需要更新. 列表不用每次都把每个项目的所有细节重新问一遍, 真要深入, 再进入详情页.
图表也补了说明. 只有一份基线的时候, 不应该留一块空白让人猜是不是坏了. 它确实还画不出一段趋势, 那就告诉我还需要后续快照.
这些改动没有增加多少功能, 但日常打开时不必等太久, 看见空白也知道原因.
数字之外, 我还想知道什么
RepoPulse 的源码放在 AuroraNest / github-repo-pulse, 使用 MIT License.
它可以替我保存一些变化, 把几处散开的数据放在一起. 克隆一次不等于已经运行过, 下载了安装包也不等于愿意一直用下去. 一个工具到底帮到了谁, 仍然要从反馈和交流里知道.
现在可以在一个面板里查看几个项目的数据, 也能查到此前保存的记录. 对比数字之前, 我会先确认统计范围和最近一次同步时间.
本文主要根据 2026 年 7 月的开发和部署记录整理, 并核对了本地实现. 示例数字均为历史快照, 写作时未查询生产数据库或触发同步. 私有部署信息与凭据已省略.