TimeTagger v26.1.3 介绍与选型指南
开源时间追踪应用 TimeTagger 的定位、纯 Python 异步架构、标签建模、功能边界与同类量化选型对比，数据溯源日期 2026-10-24，最新稳定版 v26.1.3。
TimeTagger v26.1.3 介绍与选型指南
目标：面向准备自托管时间追踪系统的技术选型者，完整介绍开源时间追踪应用 TimeTagger 的定位、架构、功能边界与同类竞品对比。本文全部信息来自官方网站、官方文档站与 GitHub 发布记录的联网溯源（来源与查询日期 2026-10-24 均已在正文标注），未混入任何未经验证的第三方评测数据。
一、环境信息
本篇为认知与选型篇，全部数据通过联网溯源获得，不涉及本地实测环境。溯源渠道与查询日期如下：
| 渠道 | 用途 | 查询日期 |
|---|---|---|
| https://github.com/almarklein/timetagger/releases | 版本列表、发布节奏、变更内容 | 2026-10-24 |
| https://github.com/almarklein/timetagger/releases/tag/v26.1.3 | 最新稳定版发布日期 | 2026-10-24 |
| https://github.com/almarklein/timetagger | README、许可证、星数/分支数（仓库页 HTML 内嵌数据） | 2026-10-24 |
| https://github.com/almarklein/timetagger/pkgs/container/timetagger | 官方镜像发布渠道与 tag | 2026-10-24 |
| https://timetagger.readthedocs.io/en/latest/libapi/ | 官方配置参数与认证机制文档 | 2026-10-24 |
| https://timetagger.app | 官网、托管版定价 | 2026-10-24 |
| https://github.com/kimai/kimai、https://github.com/Traggo/server、https://github.com/ActivityWatch/activitywatch | 同类竞品星数与许可证（各自仓库页 HTML） | 2026-10-24 |
关键结论先行：TimeTagger 当前最新稳定版为 v26.1.3（2026-02-02 发布），GitHub 星数 1,808、分支数 170（仓库页 HTML 快照，2026-10-24），许可证 GPL-3.0，官方通过 GitHub Container Registry 发布镜像 ghcr.io/almarklein/timetagger（root 与 nonroot 双变体），存储层为内嵌 SQLite，无需外部数据库。
二、软件概述
2.1 定位与身份
TimeTagger 是一款开源的基于 Web 的时间追踪（Time Tracking）应用，官方一句话定位为「Tag your time, get the insight——一个交互式用户体验与强大报表兼备的开源时间追踪器」。它面向个人与自由职业者（aimed at individuals and freelancers），既可以跑在本地机器上，也可以跑在自己的服务器上（来源：GitHub README，2026-10-24）。
与同赛道多数「项目/客户为中心」的工时工具不同，TimeTagger 的核心建模是标签（tag）而非项目：用户给时间段打上若干自由标签，报表按标签组合聚合。官方明言这带来「轻量感」（Lightweight feel by use of tags rather than projects）——它刻意不做客户、费率、发票这类计费链路，把「记录时间并看懂时间去哪了」做到足够顺手（来源：GitHub README 功能描述，2026-10-24）。
项目的身份信息如下（来源：GitHub 仓库页与 README，2026-10-24）：
| 项目 | 内容 |
|---|---|
| 代码仓库 | https://github.com/almarklein/timetagger |
| 官网 | https://timetagger.app |
| 在线演示 | https://timetagger.app/demo |
| 文档站 | https://timetagger.readthedocs.io |
| CLI 工具（独立仓库） | https://github.com/almarklein/timetagger_cli |
| 最新稳定版 | v26.1.3（2026-02-02） |
| 版本命名规则 | CalVer（年.月.序号，如 v25.12.1 = 2025 年 12 月第 1 版） |
| 许可证 | GPL-3.0 |
| GitHub 星数 | 1,808（2026-10-24 快照） |
| GitHub 分支数 | 170（2026-10-24 快照） |
| 官方镜像 | GitHub Container Registry ghcr.io/almarklein/timetagger（另有 nonroot 变体） |
| 托管版 | https://timetagger.app，3 欧元/月（订阅同时赞助开源项目） |
| 作者 | Almar Klein（almarklein，Python 科学计算/可视化领域开发者，asgineer/pscript/flexx 等库作者） |
💡 说明：GPL-3.0 与 AGPL-3.0 的关键差别在于「网络使用是否触发开源义务」。GPL-3.0 只约束分发行为——企业内部部署 TimeTagger、甚至做内部修改，都不产生向外部开源的义务（不分发即不触发）；而 AGPL-3.0（如 Kimai、solidtime 采用）连「对外提供网络服务」也要求公开修改后的源码。对「只想内部自用、可能做些内部定制」的场景，GPL-3.0 的合规负担显著更低。但若把修改版打包分发或对外发行，GPL-3.0 仍要求以同许可证开源。
2.2 版本演进与版本节奏
TimeTagger 采用 CalVer 版本命名，从版本号即可读出发布年月。GitHub Releases 第一页即覆盖 2023-11 至 2026-02 的全部 10 个版本（来源：GitHub Releases，2026-10-24），里程碑梳理如下：
| 版本 | 时间 | 关键内容 |
|---|---|---|
| v23.11.4 | 2023-11 | 报表合计数值忽略标签过滤的缺陷修复、点击标签取消选中 |
| v24.4.1 | 2024-04 | iOS 缩放修复、周一至周五周视图选项、快捷键扩充、桌面通知；自托管侧支持以 import 字符串传入启动项（便于多 worker/热重载）、新增合并多库记录的脚本 |
| v24.07.1 | 2024-07 | 暗色模式「now」线可见性、Android 独立显示、负时间戳防护、多日期格式支持等一轮 UI/健壮性修复 |
| v24.12.1 | 2024-12 | 常规维护版本 |
| v24.12.2 | 2024-12 | 安全修复：为默认启动脚本增加 localhost 认证检查，默认绑定从 0.0.0.0:80 改为 127.0.0.1:8080（公网部署行为分水岭，官方敦促公网用户升级） |
| v25.06.1 | 2025-06 | 常规维护版本 |
| v25.12.1 | 2025-12 | 功能大版本：新增版本查询 API 端点、记录 API 支持服务端过滤、可配置路径前缀与根路径重定向、改进离线使用、SQLite 批量编辑脚本、UI 新版本可用提醒 |
| v26.1.1 / v26.1.2 | 2026-01 | 补丁版本（Release 正文未附变更说明） |
| v26.1.3 | 2026-02-02 | 修复日文等输入法组合字符（compositing chars）被忽略的问题 |
版本节奏量化：2023-11 至 2026-02 约 27 个月发布 10 个版本，平均约 2.7 个月一个版本，节奏偏「稳健低频」而非高速迭代；最近一次功能大版本 v25.12.1（2025-12）一次性合入 14 个 PR，包含 4 位首次贡献者，社区参与度健康。但需注意：截至 v26.1.3 查询时（2026-10-24），距最近一次发布已约 8 个月，作者在 v24.4.1 发布说明中也坦言「精力被其他项目占用，投入 TimeTagger 的时间不如预期」。选型时应把「低频维护、单人主导」作为一项已知风险来接受。
版本阶段提示：项目无 1.0 语义版本承诺，但采用 CalVer 且数据格式为单文件 SQLite、升级基本等于换镜像重启，历史版本间未见破坏性迁移说明，运维负担远低于需要跑数据库迁移脚本的同类。
三、核心架构
3.1 技术栈
以下技术栈信息均出自官方 README 与文档站（来源：GitHub README 与 timetagger.readthedocs.io，2026-10-24）：
| 层 | 技术 | 出处 |
|---|---|---|
| 应用框架 | 纯 Python 异步栈：uvicorn + asgineer（作者自研的极简 ASGI 框架） | README「Under the hood」 |
| 前端 | HTML + CSS + Markdown + Python（经 PScript 编译为 JavaScript 运行），无 Node.js 构建链 | 同上 |
| 数据存储 | SQLite（经 itemdb 库），数据目录默认 ~/_timetagger，每用户一个库文件（datadir/users/） | README 与 libapi 文档 |
| 认证 | 内置凭据认证（用户名 + BCrypt 口令哈希）或反向代理头认证（对接 Authelia 等） | README 与 libapi 文档 |
| 会话令牌 | webtoken（有效期两周，官方建议客户端每日经 GET /api/v2/webtoken 刷新） | libapi 文档 |
| 运行形态 | 单进程异步服务，官方提供 root 与 nonroot（uid 1000）两种镜像变体 | README |
| 可安装形态 | PyPI 包（pip install timetagger，要求 Python 3.6+）或官方镜像 | README |
💡 技术拓展：asgineer 是作者自己写的极简 ASGI 框架，TimeTagger 服务端没有 Flask/Django 这类传统框架的中间件栈；前端用 PScript 把 Python 编译成 JS，意味着前后端同为 Python 单一技术栈。这套「自研全家桶」的代价是第三方贡献门槛较高（需要熟悉小众框架），收益是依赖面极小、资源占用极低——整个应用加上内嵌 SQLite 可以在 512MB 内存的小机上稳定运行，且备份退化为「拷一个文件目录」。
3.2 部署形态与组件分工
TimeTagger 是本赛道里组件最少的部署形态：单个服务 + 一个本地数据卷，无外部数据库、无队列、无独立渲染服务（来源：官方 README 与 deploy 目录 docker-compose.yml，2026-10-24）。官方提供两份 compose 模板：root 版与 nonroot 版（以 uid 1000 运行），数据卷挂载到容器内 _timetagger 目录即可。
多用户能力通过 TIMETAGGER_CREDENTIALS（多组「用户名:BCrypt 哈希」逗号分隔）内置实现；若前端已有统一认证网关（Authelia、Authentik 等），可改走代理头认证三参数（TIMETAGGER_PROXY_AUTH_ENABLED/TRUSTED/HEADER），应用自身不再管口令。完整的编排步骤、参数逐项实测与本篇不展开的内容，见本专栏部署篇与配置篇。
3.3 接口与集成面
TimeTagger 的对外集成面由三部分组成（来源：官方 README、libapi 文档与 Releases v25.12.1 变更记录，2026-10-24）：
- REST API（
/api/v2/前缀）：覆盖认证（webtoken 签发/刷新）、记录（records 的增删改查，v25.12.1 起支持服务端过滤）、标签（tags）、目标（targets）、报表与版本查询（v25.12.1 新增版本端点）。令牌经GET /api/v2/webtoken获取，两周有效。逐端点实测细节见本专栏 API 篇。 - CLI 工具：独立仓库 timetagger_cli 提供命令行录入与查询，走同一套 API。
- 第三方扩展：社区维护的 VSCode 扩展（TimeTagger_VSCodeExtension）等；无官方桌面客户端与浏览器扩展。
与 solidtime 的差异在于集成深度：TimeTagger 的 API 面向「自己的数据自己做主」的轻集成（脚本统计、个人自动化），而 solidtime 提供 OAuth2 + 个人 Token + 桌面客户端/浏览器扩展的完整多端矩阵。
四、功能特性
基于官方 README 与发布记录的功能清单（2026-10-24 溯源）：
时间追踪核心：围绕**交互式时间线（interactive timeline）**的操作模型——拖拽即可创建/调整时间段、计时器一键开始/停止、手动补录；标签自由组合，无需预建项目结构；多设备间数据同步（sync between devices，自托管实例即同步中枢）；v25.12.1 改进离线使用，弱网/断网场景下仍可操作。
报表与目标：PDF 与 CSV 报表导出；按日/周/月设定工时目标（daily/weekly/monthly targets）；报表按标签聚合，v25.12.1 修复未分组报表合计为零的问题。
体验：响应式界面，小屏/大屏均适配；桌面通知（v24.4.1）；多种日期格式（v24.07.1）；命令面板与快捷键（v24.4.1 系列）；实验性番茄钟（integrated Pomodoro method）内置。
运维侧特性：单数据目录、SQLite 单文件存储，备份/迁移即拷贝；root/nonroot 双镜像变体；路径前缀可配置（v25.12.1 起 TIMETAGGER_PATH_PREFIX），便于挂在反向代理的子路径下；版本可用性 UI 提醒（v25.12.1）；SQLite 批量编辑脚本（v25.12.1）与多库合并脚本（v24.4.1）满足批量治理需求。
五、快速开始（最小可用示例）
TimeTagger 同时是一个 PyPI 库，本地单用户场景开箱即用（来源：官方 README，2026-10-24）。以下为最小验证主线；服务器级部署与参数实测见本专栏部署篇。
- 安装并启动（默认绑定
127.0.0.1:8080，数据写入~/_timetagger）：
pip install -U timetagger
python -m timetagger
- 本机（localhost）访问时默认即为单用户模式，无需任何凭据配置，浏览器打开即可使用。
- 若服务不在 localhost 或需要多用户，设置凭据环境变量（BCrypt 哈希可用官方页面 https://timetagger.app/cred 生成）后重启：
export TIMETAGGER_CREDENTIALS='test:$2a$08$0CD1NFiIbancwWsu3se1v.RNR/b7YeZd71yg3cZ/3whGlyU6Iny5i'
python -m timetagger
💡 说明：v24.12.2 起默认绑定收紧为
127.0.0.1:8080，意味着「装完直接暴露公网」不再可能，必须显式改绑定或加反向代理——这是官方在安全事件后做出的默认安全化决策，选型时可作为项目安全态度的参考样本。
六、适用场景与限制
6.1 适用场景
- 个人与自由职业者的时间洞察：这是 TimeTagger 的第一定位——不打项目/客户树，随手打标签记录，月末按标签组合看时间去向，PDF/CSV 导出足够支撑个人复盘与自由职业者的简单工时账。
- 极简自托管偏好者：单数据卷 + 内嵌 SQLite + 低资源占用，一台小机、一条编排文件即可长期运行，备份是「拷目录」，几乎没有运维面。
- 已有统一认证网关的内部工具链：代理头认证（Authelia/Authentik 等）三参数接入，应用零口令管理；路径前缀可配置，能自然嵌入已有反代的子路径规划。
- 需要脚本化集成的个人自动化：REST API + 独立 CLI，适合把「开始/停止计时」接进自己的脚本、快捷指令或编辑器工作流（社区 VSCode 扩展即此路线）。
6.2 限制与注意事项
- 不做计费链路：无客户/项目/费率/发票概念，标签即全部。若诉求是「按客户开票的代理机构工时系统」，TimeTagger 的模型会明显吃力，此类场景应看 solidtime（本站已有专文：《solidtime v0.21.0 介绍与选型指南》）或 Kimai。
- 单人主导、低频维护：约 2.7 个月一个版本，v26.1.3（2026-02-02）至查询日（2026-10-24）已 8 个月无新版本；作者精力分散是官方自陈的事实。选型即接受「功能冻结期可能较长」。
- 多用户能力偏薄：凭据表是一个环境变量，无角色/权限/团队/组织概念，所有人共享同一数据空间；团队级工时管控需求应另选。
- 默认绑定仅 localhost：v24.12.2 起默认
127.0.0.1:8080，公网/局域网使用必须显式配置绑定或反代，并用 BCrypt 凭据或代理认证保护（此默认值变更是官方对历史安全问题的响应）。 - GPL-3.0 而非 AGPL：内部使用与修改无需开源，但对外分发修改版需遵守 GPL-3.0；官方同时以托管版（3 欧元/月）维持项目可持续性。
七、同类选型对比
7.1 竞品概览
下表对比与 TimeTagger 同处「时间追踪」赛道的常见选择。TimeTagger、Kimai、Traggo、ActivityWatch 四行的星数与许可证为本次逐仓实查数据（GitHub 仓库页 HTML，2026-10-24）；solidtime 行引自本站已溯源文档（快照同日）；形态与技术栈描述为官方渠道公开信息：
| 项目 | 形态与技术栈 | 数据存储 | 集成接口 | 许可证（2026-10-24 实查） | 相对 TimeTagger 的取舍 |
|---|---|---|---|---|---|
| TimeTagger v26.1.3 | 自托管 Web 应用；纯 Python 异步栈（uvicorn + asgineer） | 内嵌 SQLite（单数据目录） | REST API /api/v2 + 独立 CLI | GPL-3.0；星数 1,808 | 本体：最轻部署面、标签建模、交互式时间线 |
| solidtime v0.21.0 | 自托管 Web 应用；Laravel + Swoole | 仅 PostgreSQL；本地/S3 | REST API 约 80 端点 + 桌面客户端 + 浏览器扩展 | AGPL-3.0；星数 9,014（本站专文快照） | 计费链路完整、团队/组织模型强，但部署组件多、必须 PostgreSQL；本站专文见文末链接 |
| Kimai | 自托管 Web 应用；PHP 传统部署 | MySQL/MariaDB | API + 插件体系 | AGPL-3.0；星数 5,095 | 老牌、计时/计费特性全、生态插件多；PHP 运维栈与 TimeTagger 完全不同 |
| Traggo | 自托管 Web 应用；无任务模型、以标签为中心 | 内嵌数据库 | 有限 API | GPL-3.0；星数 1,638 | 建模哲学与 TimeTagger 最接近（纯标签、无项目），但 UI 为统计仪表盘导向，无交互式时间线，维护更沉寂 |
| ActivityWatch | 本地优先自动追踪（桌面守护进程 + 本地 Web UI） | 本地 SQLite | 本地 API + 多端采集器 | MPL-2.0；星数 19,357 | 自动采集应用/窗口活动，零手工录入，但非工时台账工具，与手工计时是互补而非替代 |
| Toggl Track / Clockify | 商业 SaaS 为主 | 云端托管 | 成熟 API 与海量集成 | 闭源商业 | 零运维但数据出域；TimeTagger 的交互式时间线体验常被拿来对标 Toggl |
7.2 TimeTagger 量化画像
选型量化维度（全部可溯源，2026-10-24）：
| 维度 | 数据 | 来源 |
|---|---|---|
| 社区规模 | GitHub 星数 1,808、分支数 170 | 仓库页 HTML |
| 版本节奏 | 27 个月 10 版（2023-11 ~ 2026-02），CalVer | GitHub Releases |
| 发布新鲜度 | 最新版 v26.1.3 发布于 2026-02-02，距查询日约 8 个月 | Releases tag 页 datetime |
| 安全响应 | v24.12.2 专项安全修复并收紧默认绑定，官方敦促公网用户升级 | Releases v24.12.2 |
| 架构重量 | 无外部依赖服务；数据目录 + 单服务 | README / libapi 文档 |
| 集成面 | REST API /api/v2（webtoken 认证、记录服务端过滤自 v25.12.1）+ 独立 CLI | libapi 文档 / Releases |
7.3 选型建议
- 如果诉求是「个人/自由职业者的时间洞察 + 极致简单自托管」，TimeTagger 是开源阵营里部署面最短的选择：SQLite、单数据卷、无外部服务，小机长跑，备份即拷贝。
- 如果诉求是「团队工时 + 客户计费 + 开票」，选 solidtime 或 Kimai：TimeTagger 没有费率与客户概念，硬套会痛苦。solidtime 的量化画像与部署实录见本站专文 《solidtime v0.21.0 介绍与选型指南》。
- 如果想要「零手工录入的自动行为统计」，ActivityWatch 是另一个物种（桌面守护进程自动采集），可与 TimeTagger 并存：前者回答「我用了什么」，后者回答「我把时间花在了哪」。
- 如果喜欢纯标签建模但想要更仪表盘化的统计视图，可对比 Traggo；两者星数量级相近（1,808 vs 1,638，2026-10-24 实查），TimeTagger 的优势在交互式时间线录入体验与更活跃的近期维护。
- 如果完全不想运维且预算允许，官方托管版 3 欧元/月是省心选项，且直接反哺开源作者。
八、参考链接
- 官网：https://timetagger.app
- 在线演示：https://timetagger.app/demo
- GitHub 仓库：https://github.com/almarklein/timetagger
- 发布记录：https://github.com/almarklein/timetagger/releases
- 官方镜像：https://github.com/almarklein/timetagger/pkgs/container/timetagger
- 官方文档站：https://timetagger.readthedocs.io
- 配置参数文档（libapi）：https://timetagger.readthedocs.io/en/latest/libapi/
- Web API 文档：https://timetagger.readthedocs.io/en/latest/webapi/
- CLI 工具：https://github.com/almarklein/timetagger_cli
- 凭据哈希生成页：https://timetagger.app/cred
- 本专栏部署篇：《TimeTagger v26.1.3 Docker Compose 部署指南》
- 本专栏配置篇：《TimeTagger v26.1.3 配置参数详解》
- 本专栏 API 篇：《TimeTagger v26.1.3 API 使用详解》
- 同类产品专文：《solidtime v0.21.0 介绍与选型指南》