Wakapi 是用 Go 编写的开源编码统计后端,采用 MIT 许可,可以接收 WakaTime 客户端上报的活动心跳,按项目、语言、编辑器、机器与系统汇总时间。你可以使用托管实例,也可以把统计保存在自己的服务器;两种方式都需要另外配置编辑器客户端。

它适合复盘一段时间里主要写了什么、项目切换是否频繁。时间统计根据客户端上报的活动推算,不会自动包含设计、沟通、评审等全部工作,也不能直接代表产出质量。
服务端与编辑器之间,靠心跳连接
编辑器插件记录活动,客户端把心跳发给配置的 API,Wakapi 再生成汇总。仅把服务启动起来而不修改客户端,数据不会自动从 WakaTime 云端改投自己的实例。项目说明是部分兼容 WakaTime,也不能预设所有云端功能都一致。
以自有域名为例,先创建 Wakapi 账户,从网页设置获取 API Key,再编辑用户目录中的 .wakatime.cfg。以下占位值需要替换,正式实例使用 HTTPS:
[settings]
api_url = https://stats.example.com/api
api_key = YOUR_WAKAPI_API_KEY
API 地址要带上 /api,密钥使用 Wakapi 生成的值。不要把个人配置放进会公开提交的项目目录。Windows 等系统应按客户端说明找到对应用户配置位置。
没有统计时,按请求链路排查
- 确认所用编辑器已经安装并启用 WakaTime 插件,客户端实际读取的是刚修改的配置。
- 检查 API 地址、HTTPS 证书和 Key,确认网络、代理及防火墙允许编辑器访问实例。
- 在编辑器中产生新的活动,再看客户端日志与服务端是否接收到请求;先判断心跳有没有到达,再看统计汇总。
- 心跳已到而归类不对时,再核对项目识别、语言字段、日期范围和时区,避免把归类问题当成连接失败。
日志可能含项目名、文件路径或账户信息,分享排错材料前应遮去敏感字段。插件漏报、离线积压和空闲间隔都会影响统计,因此图表更适合个人观察,而不是作为严格考勤记录。
自托管先选存储方式,再配访问范围
单人实例可以使用默认 SQLite,容器按 README 把 /data 挂载到持久化卷。需要接入已有数据库体系时,可以选择 PostgreSQL 或 MySQL 等;当前仓库的 compose.yml 示例采用 PostgreSQL,并从源码构建应用,不能把它当作默认 SQLite 的同一套配置。
WAKAPI_PASSWORD_SALT:设置自己的随机值,用于密码哈希,不沿用示例里的changeme。WAKAPI_PUBLIC_URL:设置实际访问地址,邮件等功能才能生成正确链接。WAKAPI_ALLOW_SIGNUP:按实例用途控制本地注册;个人使用可在账户建好后关闭。- 数据库、配置和备份:一起规划保留位置与恢复方式。容器镜像能够重建应用,但不包含原来的统计记录。
按官方 README 选择容器、二进制或源码运行方式,再配置反向代理和 HTTPS。升级前保存可恢复的数据副本,阅读版本变化。当前 README 提醒维护者时间有限、暂不接受 PR,计划依赖二次开发或快速支持时,应把这一维护条件纳入判断。
保留 Wakapi 之外的去向,也需要主动确认
Wakapi 可以与 WakaTime 并行使用:客户端可配置多个 API 目标,实例也有 relay 转发功能。需要数据只留在自有实例时,应同时检查客户端多目标设置和服务端 relay;只改主 API 地址,不一定会关闭其他上传去向。
自托管后,服务器管理员仍可能接触数据库、备份和日志。心跳元数据可透露项目、设备和工作节奏,是否上传客户项目名称、谁能查看统计、保留多久,应按工作环境决定。
报告、徽章和 Prometheus 分别用在哪里
- 周期邮件报告:适合个人定期复盘,需要配置邮件发送。
- 公开徽章与主页卡片:适合展示选择公开的统计,先核对 Settings → Permissions 的公开范围。
- Prometheus:可以把 Wakapi 统计导出到 Grafana 等看板;不只是进程运行监控。设置
WAKAPI_EXPOSE_METRICS=true后,按 README 配置/api/metrics与认证,抓取端点仍应受控。
需要自定义数据导出时,仓库提供 scripts/download_heartbeats.py 将原始心跳导出为 CSV。先确定是连接客户端、导出统计还是更改汇总行为,再选择 API、脚本或服务端源码,不必为一个展示需求先改整个后端。
- 仓库、部署及客户端说明:
https://github.com/muety/wakapi - 托管入口:
https://wakapi.dev - 原始心跳导出脚本:
https://github.com/muety/wakapi/blob/master/scripts/download_heartbeats.py











暂无评论内容