Wakapi 2.18.2 介绍与选型指南

Wakapi 是开源、可自托管的编码时间追踪服务，兼容 WakaTime 客户端生态；本文联网溯源其定位、架构、功能与社区数据，并给出与 WakaTime 官方服务、ActivityWatch 等的量化选型对比。

WakapiWakapi时间追踪Go2026/10/25

Wakapi 2.18.2 介绍与选型指南

目标：讲清 Wakapi 是什么、解决什么问题、与 WakaTime 官方服务及同类自托管方案的差异，帮助开发者/团队决定是否采用以及采用哪种形态。本文为认知选型篇，内容基于官方仓库与官网联网溯源（查询日期 2026-10-25），不含本地实测数据。

一、环境信息

  • 信息来源：GitHub 官方仓库 muety/wakapi（README、Releases）、WakaTime 官网定价页、shields.io 徽章服务
  • 溯源查询日期：2026-10-25
  • 溯源版本基线：Wakapi 最新稳定版 2.18.2（2026-10-14 发布，来源：GitHub Releases 页）
  • 本文属性：联网溯源认知篇，部署与实测操作见本专栏安装/部署/API 各篇

二、软件概述

Wakapi 是一个自托管（self-hosted）的编码时间追踪后端服务，由德国开发者 Ferdinand Mütsch 以 MIT 许可证开源（来源：仓库 README License 节，shields.io license 徽章显示 MIT，查询日期 2026-10-25）。它接收编辑器/IDE 插件上报的「心跳（heartbeat）」数据，聚合出按项目、编程语言、编辑器、操作系统、机器等维度拆分的编码时间统计，并提供仪表盘、排行榜、徽章（badge）、周报邮件与 REST API。

Wakapi 最大的特点是与 WakaTime 生态兼容：它复用 WakaTime 官方开源的编辑器插件体系（wakatime-cli 及数十种 IDE 插件），客户端只需把 ~/.wakatime.cfg 中的 api_url 指向自己的 Wakapi 实例即可无缝切换。WakaTime 官方是 SaaS 付费服务，Wakapi 则是「数据主权在自己手里」的开源替代方案——作者在 FAQ 中自述，项目起点就是「不想为 WakaTime 付 $9/月」（来源：仓库 README FAQ，查询日期 2026-10-25）。

项目社区数据（shields.io 徽章，查询日期 2026-10-25）：

  • GitHub Stars：约 4.5k
  • 最近提交：查询时显示「yesterday」，处于活跃维护状态
  • 许可证：MIT
  • 官方托管实例：wakapi.dev（官方运营的免费云服务，可直接注册使用）

三、核心架构

Wakapi 的技术形态非常克制，是一个典型的「单二进制 + 关系库」单体应用：

层次组成说明
语言与运行时Go编译为单个静态二进制，无运行时依赖，资源占用低
Web/HTTP 层内置 HTTP 服务器默认监听 127.0.0.1:3000，支持 IPv4/IPv6/UNIX Socket，可挂反向代理子路径（base_path）
数据模型heartbeat → summary客户端每次按键/保存产生一条心跳；服务端定时任务聚合为 summary 供仪表盘查询
存储SQLite（默认）/ MySQL / MariaDB / Postgres基于 GORM ORM，SQLite 零依赖起步，生产推荐 MySQL（官方说明"测试最充分"）
后台任务内置 job queue聚合、排行榜生成、数据清理、数据库 vacuum、周报邮件等定时任务（cron 表达式可配）
API 兼容层/api/compat/wakatime/v1兼容 WakaTime API 协议，客户端无感知切换
可观测Prometheus /api/metrics（默认关闭）、Sentry 集成需显式开启

💡 技术拓展：「心跳驱动的活动时间统计」不止 Wakapi/WakaTime 一种实现思路。常见方案对比——

方案原理代表
心跳上报编辑器插件定期上报「正在编辑某文件」事件，服务端按时间间隔推断时长WakaTime / Wakapi
本地窗口监听在本机监听活动窗口与进程标题推断活动类型ActivityWatch
手动打标签计时用户显式开始/结束任务并打 tagTraggo / Toggl

Wakapi 采用心跳上报，优点是精度高、可细到文件级，代价是必须依赖客户端插件生态（Wakapi 直接复用 WakaTime 插件）。

四、功能特性

按官方 README「Features」清单（查询日期 2026-10-25）并结合 Releases 记录归纳：

  • 完全免费且开源（MIT），数据完全自有
  • 统计维度：项目 / 语言 / 编辑器 / 操作系统 / 机器（hostname）多维统计与图表仪表盘
  • 徽章（Badges）：可嵌入 README 的编码时长徽章（如 wakapi.dev 给自身项目打的徽章）
  • 每周邮件报告（需配置 SMTP）
  • REST API：自有 API + WakaTime 兼容 API，官方提供 Swagger 文档（wakapi.dev/swagger-ui）
  • 与 WakaTime 并行：支持把心跳同时转发到 WakaTime 官方（relay / 客户端多目标配置）
  • Prometheus 指标导出（security.expose_metrics）
  • 数据导入：支持从 WakaTime 官方或其他 Wakapi 实例导入历史数据
  • 认证：本地账号、OIDC 单点登录、WebAuthn（默认禁用）、反向代理可信头认证
  • 多数据库：SQLite / MySQL / MariaDB / Postgres
  • 订阅计费（可选）：内置 Stripe 订阅能力，供搭建成付费托管服务使用（默认关闭）

版本节奏（来源：GitHub Releases 页，查询日期 2026-10-25）：2.17.x → 2.18.x 一年内多个小版本持续迭代；近期版本包含 AI 编程助手工时统计增强（如 2.18.0 修复 AI agent thinking time 重复计数）、性能修复（2.18.1 修复 SQLite 下活动图慢查询）、以及 2.18.2 为 heartbeats 表新增 idx_user_project_time 索引优化大表查询（大实例升级前建议手工预建索引）。

五、快速开始（最小可用示例）

官方给出四种使用方式（来源：README「How to use」，查询日期 2026-10-25）：

  1. 官方托管：直接注册 wakapi.dev，零运维成本；
  2. 单二进制快跑：curl -L https://wakapi.dev/get | bash；
  3. Docker 单容器：官方镜像 ghcr.io/muety/wakapi，一条命令挂载数据卷即可；
  4. 源码编译：go install github.com/muety/wakapi@latest。

无论哪种形态，服务端就绪后的客户端接入是统一的两步：

# ~/.wakatime.cfg（客户端配置文件）
[settings]
api_url = http://你的服务器:3000/api
api_key = <Web 界面注册账号后获取的 API Key>

IDE 侧安装对应的 WakaTime 插件（VS Code / JetBrains / Vim 等均支持）即可开始上报。部署细节与实测命令见本专栏《Ubuntu 22.04 安装 Wakapi 2.18.2 指南》与《Wakapi 2.18.2 Docker Compose 部署指南》。

六、适用场景与限制

适用场景：

  • 个人开发者想要 WakaTime 级体验但不愿付费/不想把代码活动数据交给第三方 SaaS；
  • 小团队内部统一统计编码投入（内置排行榜、多用户）；
  • 隐私合规要求严格、数据必须留在内网的组织；
  • 需要把编码数据接入自有 BI / Prometheus 监控体系的技术团队。

已知限制（来源：README 与 Releases 注记）：

  • 与 WakaTime 的兼容是「部分兼容（partially compatible）」，WakaTime 官方近期力推的 AI 用量/花费分析等高级面板在 Wakapi 侧为简化实现或没有；
  • 官方镜像自 2.17.2 起切换到 distroless + nonroot（UID 65532），本地目录挂载需注意属主；
  • 2.18.2 的数据库索引迁移在大数据量实例上可能耗时数小时（官方给出预建索引的规避 SQL）；
  • 默认配置未启用 TLS，生产使用官方建议置于 Caddy/Nginx 反向代理之后；
  • 无内置集群/HA 能力，属单实例应用（数据库可用外部高可用库）。

七、同类选型对比

下表为量化对比（Stars 与价格来源：shields.io 徽章与各官网定价页，查询日期 2026-10-25）：

维度Wakapi 2.18.2WakaTime 官方服务ActivityWatchTraggo
定位自托管 WakaTime 替代后端SaaS 编码统计服务本地优先的活动追踪手动标签式工时记录
开源/许可是，MIT服务端闭源（客户端开源）是，MPL-2.0是，AGPL-3.0
GitHub Stars≈4.5k（muety/wakapi）—（客户端 wakatime-cli ≈464）≈19k≈1.6k
成本自托管免费Free $0（仅 1 周历史）/ Basic $9/月 / Premium $14/月 / Team $21/人·月免费免费
数据主权自有服务器官方云（可导出）完全本地自有服务器
统计方式心跳上报（文件级）心跳上报（文件级）窗口监听（应用级）手动开始/结束
客户端生态复用 WakaTime 全部 IDE 插件官方插件最全自有 watcher，编辑器插件较少无编辑器插件
自动统计编码时长✅✅⚠️ 间接（需配 watcher）❌ 手动
部署复杂度单二进制/单容器，极低无需部署桌面应用单容器，低
多用户/团队✅ 内置多用户+排行榜✅（付费档位）❌ 偏单机✅

选型建议：

  • 要「免费 + 数据自有 + 全 IDE 插件生态 + 精确到文件的编码时长」→ Wakapi；
  • 不愿运维任何服务端、接受付费换省心与 AI 用量分析 → WakaTime 官方 Premium；
  • 更关心「整天电脑都干了什么」（不限于编码）且偏好纯本地 → ActivityWatch；
  • 只需要按任务手动记工时、不需要编辑器集成 → Traggo。

八、参考链接