简介
Wakapi 是一套兼容 WakaTime 客户端协议的开源编码时间统计后端。开发者在编辑器中安装 WakaTime 插件后，可以把心跳数据发送到自己的 Wakapi 实例，用仪表盘查看语言、项目、编辑器和操作系统的时间分布，而不必把完整统计交给第三方平台。
杂货喵小编结合 Wakapi 官网、GitHub 仓库、官方 Wiki、Release 与 WarpNav 原文重新核对，重点说明编辑器插件配置、数据库选择、公开徽章、Prometheus 和自托管隐私边界。截至 2026 年 7 月 15 日核对时，最新正式版为 v2.17.4，后端主要使用 Go 编写并采用 MIT 许可证。
本文要点
- 兼容 WakaTime 插件协议，可复用常见编辑器的现有客户端。
- 统计项目、语言、编辑器、机器与操作系统的编码时间。
- 支持 Docker、预编译二进制和源码运行，也提供托管实例。
- 默认可用 SQLite，并可按规模选择 MySQL、MariaDB 或 PostgreSQL。
- 公开徽章、API 与 Prometheus 指标需要单独评估隐私和访问控制。
Wakapi 如何记录编码时间
编辑器插件会周期性发送“心跳”，内容通常包含当前项目、语言、文件类别、编辑器与机器等元数据。Wakapi 接收并汇总这些记录，生成每天、每周和长期统计。它记录的是插件上报的活动，不等同于人工填写工时，也不能证明某段时间的产出质量。
若编辑器退出、插件离线、API 地址错误或网络被阻断，心跳就可能缺失。团队不应把这类统计直接用于绩效处罚；更合适的用途是个人复盘、估算项目投入、观察技术栈变化与发现工作节奏。
与 WakaTime 云服务的关系
| 比较项 | Wakapi 自托管 | 托管统计服务 |
|---|---|---|
| 数据位置 | 由部署者控制 | 遵循服务商条款 |
| 维护责任 | 升级、备份、监控均需自理 | 主要由服务商承担 |
| 客户端 | 可使用 WakaTime 兼容插件 | 通常开箱即用 |
| 功能边界 | 以 Wakapi 当前实现为准 | 以订阅计划和平台功能为准 |
协议兼容不代表所有云端功能完全一致。迁移前应确认历史导入、报告、团队功能、目标和集成是否满足需求。若只需要个人编码统计和数据控制，Wakapi 的范围更清晰；若依赖成熟团队分析和正式支持，托管服务可能更合适。
Docker 部署与数据库选择
- 准备 Docker Compose、HTTPS 域名、持久化目录和稳定时区配置。
- 为账号、会话和数据库设置随机强密钥，不使用示例默认值。
- 个人或小规模实例可先使用 SQLite，避免过早增加数据库服务。
- 启动后创建账号与 API Key，再用一个编辑器测试心跳和统计。
- 配置备份、监控和升级流程，验证数据库恢复后再长期使用。
SQLite 部署简单，适合单人和低并发场景；MySQL、MariaDB 或 PostgreSQL 更适合已有数据库运维体系的环境。数据库类型不是性能保证，真正需要关注的是写入量、保留周期、备份恢复和升级迁移。切换数据库前应使用官方说明并保留原始副本。
编辑器插件配置
通常先安装对应编辑器的 WakaTime 插件，再把 API URL 指向自己的 Wakapi 地址，并填入 Wakapi 生成的 API Key。不同插件保存配置的位置不同，应参考插件与 Wakapi 文档，不要把密钥写进会提交到 Git 的项目配置。
完成后先编码几分钟，再检查服务器日志和仪表盘。若没有数据，依次核对系统时间、HTTPS 证书、API 地址、密钥、代理和防火墙。统计归类异常时，可检查项目名、分支和编辑器插件的项目识别规则。
报告、API 与 Prometheus
Wakapi 可以生成编码摘要与周期报告，也提供兼容 API、公开徽章和 Prometheus 指标。公开徽章适合个人主页展示语言或时间数据，但可能暴露工作节奏与项目特征；启用前应确认展示范围，不要把私人仓库名或客户信息意外公开。
Prometheus 主要用于监控 Wakapi 服务运行状态，并非替代编码统计仪表盘。抓取端点应放在受控网络中，API 也要限制调用者和日志留存。团队环境应明确谁能看个人统计，以及数据保留多久。
隐私与安全边界
自托管减少了第三方持有数据的范围，但服务器管理员仍可访问数据库和备份。心跳元数据可能透露项目名称、使用语言、工作时间与设备信息，因此数据库、备份、日志和监控都应按工作数据保护。
公开注册应谨慎开启，管理账号使用独立强密码并通过 HTTPS 访问。API Key 泄露后应及时轮换；反向代理、数据库端口和监控端点不要直接暴露到公网。项目当前维护资源有限，升级前尤其需要阅读 Release 与仓库公告并保留回滚方案。
适用人群
Wakapi 适合希望量化个人编码习惯、控制统计数据位置，并具备 Docker 或服务器维护能力的开发者。已经使用 WakaTime 插件，又只需要个人仪表盘、报告和 API 的用户迁移成本相对较低。
需要严格工时审计、企业 SLA、复杂团队绩效分析或完全免维护体验的组织，不应把 Wakapi 当作现成管理平台。编码时长也不能单独代表产出和质量，应作为个人观察信号而非绝对指标。
编辑整理体验
Wakapi 的优势是目标明确：接收编辑器心跳并把它们变成可读统计。Go 后端和多种部署方式让个人实例比较容易开始，WakaTime 协议兼容也减少了客户端重新选择的成本。
长期价值取决于数据是否可信。稳定的插件、正确的项目识别、统一时区和可恢复备份，比堆积更多图表重要。建议把每周报告用于复盘专注时间和项目切换，而不是追求更长的数字。
常见问题（FAQ）
Wakapi 会读取源代码内容吗？
核心统计来自编辑器插件发送的心跳元数据。具体上报字段取决于客户端配置，敏感环境应检查插件隐私设置和服务器实际日志。
个人使用必须安装 PostgreSQL 吗？
不必须。默认 SQLite 更便于小规模部署；已有数据库维护需求或更大规模时，再评估 MySQL、MariaDB 或 PostgreSQL。
可以直接使用原来的 WakaTime 插件吗？
可以使用兼容客户端，但需要把 API 地址改为 Wakapi 实例并填入对应 API Key。不同编辑器的配置方式应参考当前文档。
编码时间能作为绩效指标吗？
不建议单独使用。心跳可能缺失，也无法衡量设计、沟通、评审和代码质量，更适合作为个人复盘或项目投入的辅助信号。
部署建议
先用单个编辑器和测试账号运行几天，核对时区、项目名、语言统计与缺失心跳，再决定数据保留周期。确认备份恢复可用后，才适合把长期统计完全迁移到自托管实例。
项目版本与维护状态会变化，安装、升级与许可判断应以 Wakapi GitHub README、官方 Wiki、Release 和 MIT 许可证原文为准。
相关链接
- GitHub 仓库：https://github.com/muety/wakapi
- 官方网站：https://wakapi.dev
- 官方 Wiki：https://github.com/muety/wakapi/wiki
- Release：https://github.com/muety/wakapi/releases/latest
暂无评论内容