n1try/wakapi

Wakapi

概述

Wakapi 是一个极简的自托管后端服务，兼容 WakaTime 客户端，用于收集、存储和展示代码编写时间统计数据。它由开发者为开发者打造，完全开源免费，支持多种数据库，并提供 REST API 和统计徽章功能，适合需要自主掌控代码统计数据的个人或团队使用。

核心功能与特性

• ✅ 100% 免费开源，无商业限制
• ✅ 支持项目、语言、编辑器、主机和操作系统的多维度统计
• ✅ 提供统计徽章生成功能，可集成到个人主页或项目文档
• ✅ 实现部分 WakaTime API 兼容，支持现有 WakaTime 客户端无缝对接
• ✅ 支持 WakaTime 数据中继，可同时向 Wakapi 和 WakaTime 发送数据
• ✅ 提供 Prometheus 指标导出能力，便于集成监控系统
• ✅ 自托管部署，数据完全自主掌控，支持 SQLite、MySQL、Postgres 等多种数据库

使用场景与适用范围

• 个人开发者希望追踪自己的代码编写时间分布，无需依赖第三方服务
• 小型开发团队需要内部代码统计工具，保护数据隐私
• 希望自定义代码统计维度或集成到现有监控系统（如Grafana）的场景

使用方法

前置要求

• 客户端需安装 WakaTime 插件（支持主流IDE/编辑器，如VS Code、JetBrains系列等）
• 自托管时需确保服务器满足对应部署方式的环境要求（如Docker环境、Go环境等）

部署方式

选项1：使用官方托管服务

访问 wakapi.dev 注册账号，直接使用免费托管服务。注意：官方不保证数据持久性，可能存在数据丢失风险。

选项2：Docker部署（推荐）

bash
# 创建持久卷以保存数据
$ docker volume create wakapi-data

# 启动容器
$ docker run -d \
  -p 3000:3000 \
  -e "WAKAPI_PASSWORD_SALT=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)" \
  -v wakapi-data:/data \
  --name wakapi n1try/wakapi

说明：默认使用SQLite数据库。如需使用MySQL或PostgreSQL，需通过环境变量或配置文件指定数据库参数（详见配置选项）。

选项3：使用发布版

bash
# 下载并解压发布包
$ wget https://github.com/muety/wakapi/releases/download/1.20.2/wakapi_linux_amd64.zip
$ unzip wakapi_linux_amd64.zip

# （可选）修改配置文件
$ vi config.yml

# 启动服务
$ ./wakapi

选项4：从源码运行

前置依赖：

• Go ≥ 1.13（需正确配置$GOPATH）
• gcc（用于编译go-sqlite3）：
  • Fedora/RHEL：dnf install @development-tools
  • Ubuntu/Debian：apt install build-essential
  • Windows：参考https://github.com/mattn/go-sqlite3/issues/214#issuecomment-253216476

编译与运行：

bash
# 复制并修改配置文件
$ cp config.default.yml config.yml
$ vi config.yml

# 安装打包工具
$ export GO111MODULE=on
$ go get github.com/markbates/pkger/cmd/pkger

# 构建可执行文件
$ go generate
$ go build -o wakapi

# 启动服务（生产环境建议设置ENV=production）
$ ./wakapi

客户端设置

1. 为IDE/编辑器安装 WakaTime插件
2. 编辑本地 ~/.wakatime.cfg 文件：

ini
[settings]
# Wakapi服务器URL（自托管时填写http://localhost:3000/api/heartbeat，官方服务为https://wakapi.dev/api/heartbeat）
api_url = http://localhost:3000/api/heartbeat
# 从Wakapi网页界面获取的API密钥
api_key = 406fe41f-6d69-4183-a4cc-121e0c524c2b

配置选项

可通过配置文件（默认config.yml，可通过-c参数指定）或环境变量配置，以下为主要选项：

支持的数据库

• SQLite：默认选项，无需额外配置，适合个人使用
• MySQL/MariaDB：推荐团队使用，需配置主机、端口、用户和密码
• PostgreSQL/CockroachDB：支持分布式部署，需启用SSL（通过db.ssl配置）

API端点

• POST /api/heartbeat：客户端发送心跳数据
• GET /api/summary?interval={today|day|week|month|year|any}：获取统计摘要
• GET /api/compat/wakatime/v1/users/current/all_time_since_today：兼容WakaTime的总时间统计API
• GET /api/compat/wakatime/v1/users/current/summaries：兼容WakaTime的摘要统计API
• GET /api/health：服务健康检查

Prometheus导出

可使用第三方工具https://github.com/MacroPower/wakatime_exporter%E5%B0%86Wakapi%E6%95%B0%E6%8D%AE%E5%AF%BC%E5%87%BA%E5%88%B0Prometheus%EF%BC%8C%E9%85%8D%E7%BD%AE%E7%A4%BA%E4%BE%8B%EF%BC%9A

bash
# 设置Wakapi实例地址和API密钥
export WAKA_SCRAPE_URI="https://wakapi.your-server.com/api/compat/wakatime/v1"
export WAKA_API_KEY="your-wakapi-api-key"

最佳实践

• 启用HTTPS：建议通过反向代理（如Caddy、Nginx）部署，以启用TLS加密
• 生产环境配置：设置ENV=production以提升性能和安全性，同时确保server.listen_ipv4设为0.0.0.0（如需公开访问）
• 数据备份：定期备份数据库文件（SQLite）或通过数据库自带工具备份（MySQL/PostgreSQL）

常见问题

数据如何计算？

Wakapi通过分析客户端发送的"心跳"数据统计编码时间。与WakaTime不同，Wakapi对长时间间隔后的心跳数据自动添加2分钟填充时间，因此统计结果可能略有差异。

离线时数据如何处理？

客户端会本地缓存心跳数据，待重新联网后批量发送至服务器。

支持哪些编辑器/IDE？

支持所有WakaTime兼容的客户端，包括VS Code、IntelliJ IDEA、PyCharm、Vim等（详见WakaTime插件列表）。