Kimai 2.71 介绍与选型指南

本文为 Kimai 认知与选型篇，全部信息基于官方渠道联网溯源实查，来源与查询日期（2026-10-27）逐项标注，不含本地实测内容。部署、配置与命令行的端到端实测请见本专栏后续三篇。

一、产品概述

1.1 Kimai 是什么

Kimai 是一个开源的时间跟踪（工时记录）系统，面向「项目驱动型团队」，核心解决的问题是：员工的时间花在了哪个客户、哪个项目、哪个活动上，以及这些时间如何换算成对客户的账单。它由德国开发者 Kevin Papst 于 2016 年前后从同名 PHP 项目重写而来（项目名来自斯瓦希里语「庆祝」），当前主体仓库为 github.com/kimai/kimai，官方站点为 kimai.org，采用 AGPL-3.0 许可证发布（来源：kimai.org 官网与 GitHub 仓库 LICENSE 徽章，2026-10-27 查询）。

官方对它的定位是「面向项目驱动团队的时间跟踪开源平台」：跟踪工作时间，并按需输出活动摘要——按年、月、日，或按客户、项目、活动任意维度汇总。官网强调其客户基础为「超过 5000 个客户信任 Kimai」，产品形态是「一个软件、两个版本」：自托管的开源版与官方托管的 Kimai 云（SaaS）版，两者共享同一套内核（来源：kimai.org 首页，2026-10-27 查询）。

💡 技术拓展：时间跟踪器（Time Tracker）与项目管理工具的边界 时间跟踪器关注「时间与账单」：记录谁在哪段时间做了什么、按小时计费、生成发票；项目管理工具关注「任务与协作」：Issue、看板、甘特图、冲刺。两者常被混为一谈，但数据模型完全不同——时间跟踪器的核心实体是「时间记录（Timesheet）」，项目管理的核心实体是「任务/工单」。同类产品中，Toggl Track、Clockify、solidtime、Traggo、Wakapi 都是纯时间跟踪器；OpenProject、Redmine、Plane 是项目管理工具（附带时间跟踪模块）。Kimai 属于前者中「发票能力最强」的一类，本专栏对比对象 Traggo/solidtime 与商业品 Toggl Track 亦均为时间跟踪器。

1.2 当前版本现状（2026-10-27 实查）

GitHub Releases 页给出的最新稳定版为 2.71.0（2026-10-25 发布），兼容 PHP 8.2 至 8.5（来源：github.com/kimai/kimai/releases，2026-10-27 查询）。近期版本发布节奏如下：

从 2.66.0 到 2.71.0 不足两个月内发布 8 个版本，minor/patch 节奏约为每 1–2 周一版，社区翻译（Hosted Weblate）与依赖更新持续滚动，维护活跃度高。安全公告通过 kimai.org/security.xml 的 RSS 订阅与 bughunter 页发布（来源：同上 Releases 页，2026-10-27 查询）。

版本号形态说明：Kimai 采用 主版本.次版本.修订号 语义化版本，当前主版本线为 2.x。官方 Docker 镜像提供 kimai/kimai2:2（锁定主版本线、自动获得 2.x 内更新，官方推荐）与 kimai/kimai2:stable（始终最新稳定版）等标签（来源：kimai.org/documentation/docker.html，2026-10-27 查询）。

二、核心功能与特性

以下功能面依据 kimai.org 官网功能列表与文档站整理（来源：kimai.org 首页及 documentation 目录各页，2026-10-27 查询）：

2.1 客户—项目—活动三层结构与时间表

Kimai 的数据模型围绕三层业务结构展开：**客户（Customer）**管理地址、联系人、国家、货币、可见性等字段；**项目（Project）**挂在客户之下，带订单号、预算与归档可见性；**活动（Activity）**挂在项目之下（也可全局共享）。员工的时间记录（Timesheet）必须落在「项目 × 活动」上，从而天然形成「谁的多少钱花在了什么上」的计费口径。

时间表支持两种记录模式：自由模式（补录任意时间段）与时钟模式（Clock mode）——管理员可禁用任意补录，只允许用户「打卡/打卡下班」。时间记录支持暂停时长、标签、描述、可编辑性锁定等字段。

2.2 报告、导出与发票

• 报告与分析：可按用户、客户、项目、活动、标签、时间段等维度交叉统计记录的时间，2.68.0 起报表支持横向表冻结首列等改进；
• 导出：时间表数据可导出为 XLSX（Excel）、PDF、CSV、HTML 四种格式，导出后的记录可被「锁定」防止再改动（满足审计口径）；
• 发票：这是 Kimai 相对同类开源产品的差异化能力——内置多种发票模板、条目分组选项、可配置的发票编号生成器，且允许用户上传自己的 PDF、DOCX、HTML、XLSX、ODS 模板；付费的 Invoice 插件进一步支持符合 EN 16931、XRechnung 3.0、Zugferd/Factur-X 标准的电子发票（CII 与 UBL 语法）。

2.3 团队、权限与企业认证

• 多用户与角色：单实例支持无限用户，内置不同角色（超级管理员/管理员/团队领导/用户），权限体系细到字段级；
• 团队：可创建团队把用户分组，客户与项目可指派给团队，从而限制其他用户的可见性与访问范围；
• 认证集成：支持 LDAP 与 SAML 2.0 单点登录，可对接 Google Workspace、Azure AD（Entra ID）、Authentik 等身份提供方；2.69.0 起还支持把 LDAP/SAML 账号切换回内部账号；
• 双因素认证：内置基于 TOTP 令牌的 2FA，2.70.x 连续多个版本加固了 2FA 与记住我、密码重置的交互边界。

2.4 集成与扩展

• JSON API：官方提供覆盖读写的完整 RESTful JSON API，外部应用与自定义工具可以完全通过 API 驱动 Kimai（2.66.0–2.71.0 期间 API 面持续增强：发票更新/删除端点、收藏端点、预算字段进集合端点等）；
• 插件商店：Kimai 采用插件（Bundle）机制扩展功能，官方商店提供费用管理（Expenses）、任务规划（Task management）、电子发票（E-Invoices）、客户门户（Customer Portal，通过秘密 URL 向客户分享统计与时间表）等付费插件；
• 多语言：界面已翻译为 30 余种语言（含简体中文），基于 Weblate 平台持续本地化；
• 自定义字段：客户、项目、活动、时间表均可挂自定义字段（meta fields），SaaS 版与付费插件更进一步。

三、技术架构速览

Kimai 是典型的 PHP 全栈单体应用，技术组成如下（来源：kimai.org 文档站、GitHub 仓库与官方 Docker 文档页，2026-10-27 查询）：

配置体系完全遵循 Symfony 惯例：敏感项与部署相关项走环境变量（DATABASE_URL、APP_SECRET、TRUSTED_HOSTS、MAILER_URL 等），应用行为走 config/packages/ 下的 YAML 覆盖；命令行工具为 bin/console（含 kimai:install、kimai:reload、kimai:user:create 等专用命令与 Symfony/Doctrine 通用命令）。官方镜像的环境变量中，APP_SECRET 与 TRUSTED_HOSTS 为必填，memory_limit 默认 256M（来源：kimai.org/documentation/docker.html，2026-10-27 查询）。

四、快速开始（官方安装路径速览）

本节为官方文档给出的最小可用路径转述（未在本文实测，端到端实测见本专栏部署篇）。官方在 kimai.org/documentation/docker.html 提供「快速测试（Quick test setup）」两条命令的路径：先起一个 MySQL 数据库，再以官方镜像 kimai/kimai2:apache（现行等价标签 kimai/kimai2:stable）启动 Kimai 并映射 8001 端口，随后用一条命令创建超级管理员账号：

# 官方文档 Quick test setup 中的建号命令（引自官方文档，本文未实测）
docker exec -ti kimai-test /opt/kimai/bin/console kimai:user:create admin admin@example.com ROLE_SUPER_ADMIN

官方同时明确：该快速测试路径的数据不落持久卷、临时性强，不适用于生产；生产路径应使用官方的 Docker Compose 设置（kimai.org/documentation/docker-compose.html），提供多种变体。镜像内的 Kimai 工作目录为 /opt/kimai/，因此文档中的常规命令在镜像内都需要加该前缀。

裸机（无 Docker）安装路径为：PHP 8.2+ 与所需扩展、Composer 依赖安装、bin/console kimai:install 交互式建库建表建管理员。官方文档安装章节（kimai.org/documentation/installation.html）提供逐步说明。

五、适用场景与限制

5.1 适合选择 Kimai 的场景

• 按客户/项目计费的服务团队：代理公司、律所、设计/开发工作室、咨询机构——需要把工时直接转成对客户的账单，Kimai 的发票引擎（模板自定义、编号生成、条目分组、导出锁定）在开源时间跟踪器中最完整；
• 需要工时合规留痕的组织：导出锁定、审计日志（SaaS 版内置、自托管版经插件）、预算与「项目锁定日期」（2.66.0+，限制补录过去时段）等特性面向工时审计场景；
• 已有企业身份体系、需要自托管的团队：LDAP/SAML/TOTP 齐备，AGPL-3.0 允许企业内部部署使用而不必开源内部改造（只要不分发、不做网络服务转售）；
• 远程/混合办公团队：浏览器界面跨平台，移动端可用，时钟模式配合打卡下班满足考勤口径。

5.2 不适合的场景与已知边界

• 不要把 Kimai 当项目管理工具：它没有看板、甘特图、Issue、需求管理——这些需求应选 OpenProject/Redmine/Plane 类工具，再考虑插件级联动；
• 部分高阶功能在付费插件墙后：费用管理、任务规划、电子发票（EN 16931/XRechnung/Zugferd）、客户门户等在自托管开源版需购买官方 Bundle 许可证，开源版自带的是核心时间跟踪 + 发票 + 报告；
• AGPL-3.0 的网络条款：若把 Kimai 改造后作为网络服务对外提供（含给客户使用的 SaaS），需要开源修改；纯企业内部使用不受影响；
• 无原生离线客户端：记录依赖浏览器可达服务端，弱网环境需借助第三方移动客户端走 JSON API。

六、量化选型对比

为定位 Kimai 在「时间跟踪」赛道的位置，选取三个可比对象：solidtime（新生代开源时间跟踪器，现代 Web 技术栈）、Traggo（标签式轻量时间跟踪器）、Toggl Track（商业 SaaS 市场标杆，闭源，作为「不开源替代」参照）。星数均取自 shields.io 徽章接口（img.shields.io/github/stars/*.json），许可证取自同站 license 徽章接口，查询日期 2026-10-27。

6.1 四款时间跟踪工具量化对比

6.2 对比结论

• 要「工时直接换账单」选 Kimai：四者中唯一把「客户/项目/活动三层计费结构 + 可挂自定义模板的发票引擎 + 导出锁定」作为核心开箱能力的产品；solidtime 的发票能力相对基础，Traggo 完全没有发票概念；
• 要「最轻量的个人/小组时间记录」选 Traggo：单二进制、纯标签模型，几乎零运维，但企业集成（LDAP/SAML/2FA）与计费能力缺位；
• 要「现代 UI + 云原生新项目」看 solidtime：星数（9k）已反超 Kimai，技术栈更年轻，但功能纵深（发票模板、LDAP、插件生态）仍在追赶，成熟度需时间验证；
• 要「零运维、预算充足、接受数据出户」选 Toggl Track：闭源 SaaS 的 polished 体验与报表生态最强，但自托管与数据主权为零——这正是欧盟开发、德国托管的 Kimai 主打的对位卖点；
• 许可证敏感场景：三者均为著佐权许可（AGPL/GPL），若所在组织法务对 AGPL 有红线（如禁止网络服务类 AGPL 组件），需要提前确认——这是 Kimai 选型中最常被忽略的一项。

七、本专栏阅读指引

本专栏四篇构成「认知 → 部署 → 配置 → 运维」完整链路，除本篇外均基于 Kimai 2.71.0 实测：

1. 本篇：介绍与选型（联网溯源）；
2. 《Kimai 2.71 Docker Compose 部署实战》：官方 kimai/kimai2 镜像 + MariaDB 栈端到端部署，含建号、计时打卡、发票生成的全流程实测；
3. 《Kimai 2.71 配置参数详解》：.env 环境变量与 config/packages 本地覆盖体系（DATABASE_URL、MAILER、APP_SECRET、LDAP/SAML）详解；
4. 《Kimai 2.71 常用命令与运维实战》：bin/console 工具链全家桶、JSON API 实测与备份恢复。

跨组件对比阅读（同批次交付，链接以平台实际 slug 为准）：《Redmine 7.0 介绍与选型指南》（项目管理 + 工时模块的对照位）等 G18 质量与工单组篇目。

附：来源清单（查询日期均为 2026-10-27）