Traggo 0.8.3 介绍与选型指南

目标：帮助读者快速理解 Traggo 是什么、能做什么、与 Kimai / solidtime / ActivityWatch / TimeTagger 等时间追踪工具有何差异，并给出可落地的选型建议。本文为认知篇，所有数据均来自 2026-10-25 对官方网站、GitHub 仓库、Docker Hub 等公开渠道的实查溯源，未做本地实测（实测内容见本专栏部署与 API 篇）。

一、环境信息

• 溯源查询日期：2026-10-25
• 溯源来源：Traggo 官网（traggo.net）、GitHub 仓库 traggo/server（Releases 页 HTML / shields.io 徽章）、Docker Hub（traggo/server）
• 目标读者：需要自托管时间追踪工具的个人开发者、小团队技术负责人

二、软件概述

Traggo 是一款基于标签（tag-based）的时间追踪工具，使用 Go 语言编写，以单二进制 + SQLite 的形态交付，由 traggo 组织维护，采用 GPL-3.0 开源协议。

Traggo 最鲜明的特征是它的数据模型：没有「任务（task）」的概念，只有「带标签的时间段（tagged time spans）」。传统时间追踪工具要求你先建项目、再建任务、最后才能在任务上计时；Traggo 彻底抛弃了这套层级，你只需记录「从几点到几点，贴了哪些标签」。例如一条时间段可以贴上 project: traggo-docs、type: writing 两个标签，统计时按任意标签键聚合即可。

💡 技术拓展：时间追踪工具的「数据模型」大体分三派——

模型派别	代表产品	特点
项目→任务层级模型	Kimai、solidtime、Toggl	结构严谨，适合按项目核算/开票，但建单前置成本高
纯标签模型	Traggo	零层级、随记随贴，统计自由度最高，但没有任务/费率等概念
自动采集模型	ActivityWatch	按窗口活动自动记录，无需手动开始/停止，但精度依赖采集器

Traggo 属于纯标签模型，适合「不想维护项目层级、只想灵活记录并事后统计」的用户。

核心身份信息（2026-10-25 实查）：

三、核心架构

Traggo 的架构极为精简，是典型的「单进程全栈应用」：

1. 单二进制交付：Go 后端把 React 前端静态资源直接嵌入二进制（buildMode=prod），解压后只有一个 traggo 可执行文件（约 17MB），无需 Node、无需 Web 服务器。
2. 嵌入式存储：默认使用 SQLite，数据库默认落在 data/traggo.db（相对工作目录），整个应用状态就是一个文件，备份即复制该文件。
3. GraphQL API 优先：Web UI 与第三方客户端共用同一套 /graphql API，鉴权采用「设备（Device）令牌」机制——每次登录生成一个设备令牌（Cookie 携带），可按设备吊销。
4. 配置即环境变量：全部配置只有 7 个 TRAGGO_* 项，支持环境变量、.env、.env.local、~/.config/traggo/server.ini、/etc/traggo/server.ini 五级来源，首个出现的值生效。

💡 技术拓展：轻量自托管应用常见的存储选型——

存储	特点	适用
SQLite 内嵌	零依赖、单文件、备份简单	个人/小团队，低并发
MySQL/PostgreSQL 外置	支持多实例与高并发	团队级、需要集中备份

Traggo 默认 SQLite，源码中保留了 MySQL/PostgreSQL 方言入口，但官方文档仅声明支持 sqlite3，生产使用建议以 SQLite 为准。

四、功能特性

依据官方 README（traggo/server，2026-10-25 实查），Traggo 的功能清单刻意保持克制：

• 时间追踪：手动开始/停止计时器（timer），或事后补录带起止时间的时间段（time span）；时间段可附备注（note）。
• 标签系统：先定义标签键（tag definition，含颜色），时间段上再贴 键:值 形式的标签；支持标签建议（suggestTag/suggestTagValue）。
• 列表与日历视图：时间段可按列表或日历两种视图浏览。
• 可定制仪表盘：自定义 Dashboard，支持饼图、柱状图、堆叠柱状图、折线图、横/纵表格六种图表类型（EntryType 枚举实查），统计区间支持绝对时间与 now-7d 这类相对表达式。
• 多主题 Web UI：内置 Gruvbox Dark/Light、Material Dark/Light 四套主题（Theme 枚举实查）。
• 简单用户管理：支持多用户（admin/普通用户），无 OAuth/LDAP 等外部认证集成。
• GraphQL API：14 个查询 + 27 个变更（实查 schema），可编程完成计时、标签、统计、仪表盘等全部操作。

明确不具备的能力（选型时务必注意）：没有任务/项目实体、没有费率与开票、没有报表导出（CSV/PDF）、没有外部身份认证（OIDC/LDAP）、没有移动端官方 App、没有团队协作功能（无共享工作区/审批流）。

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

以下命令在 Linux x86_64 服务器上实测通过（完整过程见本专栏安装篇）：

# 下载并解压 v0.8.3（官方源不可直连时走代理，见安装篇说明）
wget https://github.com/traggo/server/releases/download/v0.8.3/traggo_0.8.3_linux_amd64.tar.gz
mkdir -p /opt/traggo && tar xzf traggo_0.8.3_linux_amd64.tar.gz -C /opt/traggo

# 直接前台启动（首次启动自动创建 admin/admin 默认账号）
cd /opt/traggo && ./traggo

实测启动日志：

INF Traggo buildDate=2026-03-01T10:30:56Z buildMode=prod commit=6321119c3c2d55f04e2e4967f6492aabd6067b76 version=0.8.3
INF Creating default user.
INF Start listening port=3030

浏览器访问 http://<服务器IP>:3030，用 admin / admin 登录即可开始计时。注意 traggo 二进制没有 --help/--version 子命令——任何参数都会被忽略并直接启动服务，版本号只能在启动日志或 GraphQL version 查询中看到。

六、适用场景与限制

适用场景：

• 个人开发者/自由职业者记录「在什么事上花了多少时间」，事后按标签维度复盘；
• 小团队（个位数用户）内部工时记录，不想维护项目/任务层级；
• 需要完全自托管、数据不出内网的隐私敏感场景（SQLite 单文件，备份即拷贝）。

限制与边界：

• 0.x 版本阶段：SemVer 语义下 0.x 不保证向后兼容，升级前需备份 traggo.db 并阅读 Release Notes；
• 无任务/项目/费率概念：需要「按项目向客户开票」的场景应选 Kimai/solidtime；
• 无外部认证：不能接入企业 IdP；
• 官方仅声明支持 SQLite：多副本水平扩展不在设计目标内；
• GPL-3.0 协议：对二次分发有 Copyleft 约束，自用/SaaS 内部使用无碍。

七、同类选型对比

以下数据均为 2026-10-25 通过 shields.io 徽章与官方仓库实查：

选型建议（「如果…则…」）：

• 如果你讨厌维护项目/任务层级，只想灵活贴标签并事后统计 → 选 Traggo；
• 如果你需要按项目核算、给客户开票 → 选 Kimai（本站已有专栏与部署文档）；
• 如果你需要团队协作 + OIDC 企业认证 → 选 solidtime；
• 如果你想要全自动、不打断心流的追踪 → 选 ActivityWatch；
• 如果你想要比 Traggo 更「玩具级」的极简记录 → TimeTagger。

站内相关专栏文档（本平台实查，2026-10-25）可参考对比阅读：

• 《TimeTagger v26.1.3 介绍与选型指南》
• 《solidtime v0.21.0 介绍与选型指南》

八、参考链接

• 官网与文档：https://traggo.net/ （查询日期 2026-10-25）
• 配置项官方说明：https://traggo.net/config/ （查询日期 2026-10-25）
• GitHub 仓库与 Releases：https://github.com/traggo/server （v0.8.3，2026-10-25 查询）
• Docker Hub 镜像：https://hub.docker.com/r/traggo/server （查询日期 2026-10-25）