源码系统概览
文章正文
TL;DR Kimai 是一款基于 PHP 加 Symfony 的开源时间追踪系统,支持多用户、多时区、SAML 与 LDAP 认证、TOTP 双因素、JSON API、PDF 发票、Excel 与 CSV 导出、30 多种界面语言,采用 AGPL-3.0 协议,可自托管也可订阅官方 SaaS。本中文版源码与 GitHub 官方仓库结构完全一致,适合想要私有化部署工时系统的中小团队与个人开发者。
By the numbers: 1999 个文件,19M 目录大小,39 个 src 子模块,63 个控制器,177 个 Twig 模板,602 个翻译文件(覆盖 30 多种界面语言),1121 个 PHP 文件,最近一次发版 2.65。
| 项目 | 技术栈 | 协议 | 认证方式 | 报表数 | 插件机制 | 部署方式 |
|---|---|---|---|---|---|---|
| Kimai | PHP 8.2 + Symfony 6.4 + MySQL | AGPL-3.0 | 数据库 / SAML / LDAP / TOTP | 14 种 | composer 插件市场 | 自托管 + 官方云 |
| Toggl Track | 闭源 SaaS | 商业 | OAuth + 2FA | 若干 | 无开源插件 | SaaS 订阅 |
| Clockify | 闭源 SaaS | 商业 | OAuth + SSO | 若干 | 无开源插件 | SaaS + 自托管 |
| TimeTagger | Python | AGPL-3.0 | 本地账号 | 简单 | 扩展字段 | 自托管 |
这是一份关于 Kimai 中文版时间追踪系统的源码整理稿。Kimai 是全球活跃度靠前的开源工时记录系统之一,GitHub 仓库 kimai/kimai 的 star 数已超过四千八,周下载量在 Packagist 长期占据时间追踪类项目的头部位置。
本次发布的源码包基于原版 2.x 系列构建,采用 PHP 8.2 加 Symfony 6.4 加 Doctrine ORM 加 MySQL 的技术栈,目录结构与官方仓库保持一致,可以直接覆盖到任意子域名部署,做到开箱即用。
稿子里所有截图都来自 Kimai 官方 demo.kimai.org 实例(账号 admin,密码 password),由 puppeteer 渲染并抓取,未添加任何水印。原版 GitHub 仓库地址会在文末给出,可自行下载到最新版。
下面的内容覆盖源码结构、运行要求、Docker 部署、插件机制、报表与发票、AGPL 协议含义、常见问题排查,以及与 Toggl Track、Clockify 等同类方案的功能对比,便于初次接触 Kimai 的读者快速建立全貌。
源码简介
项目原名 Kimai,作者 Kevin Papst,源代码托管在 GitHub 的 kimai/kimai 仓库。当前稳定版本为 2.x 系列,PHP 最低要求 8.2,数据库支持 MariaDB 10.6 及以上或 MySQL 8.4 及以上。本次发布的中文版是汉化界面与本地化文档之后的版本,核心代码未做修改,后续可以直接通过 git pull 同步上游。
源码根目录共 1999 个文件,19M 大小,src 下分出 39 个职责明确的子模块,包括 Activity、API、Audit、Calendar、Command、Configuration、Controller、Customer、DataFixtures、DependencyInjection、Doctrine、Entity、Event、EventSubscriber、Export、Form、Invoice、Ldap、Logger、Mail、Model、Pdf、Plugin、Project、Reporting、Repository、Saml、Security、Timesheet、Twig、User、Utils、Validator、Voter、Webhook、Widget、Wizard、WorkingTime 等。控制器 63 个,模板 177 个,翻译文件 602 个,覆盖 30 多种界面语言。
代码组织遵循 Symfony 框架的 Bundle 模式,业务实体放在 src/Entity,数据迁移放在 migrations,前端资源构建用 Webpack Encore 加 Tabler UI 主题,插件系统通过 var/plugins/ 目录挂载,允许在不修改主程序的情况下扩展发票、审批、加班、请假等场景。
composer.json 锁定的核心依赖包括 symfony/framework-bundle、symfony/security-bundle、doctrine/orm、doctrine/doctrine-migrations-bundle、jms/serializer-bundle、friendsofsymfony/rest-bundle、phpoffice/phpspreadsheet、horstoeko/zugferd 等,其中 zugferd 用于生成符合欧洲电子发票标准的 ZUGFeRD PDF,phpspreadsheet 用于导出 xlsx 工时报表。
适用场景
个人自由职业者。需要按客户、按项目、按小时计费的开票场景,Kimai 的客户编号、用户费率、项目费率组合可以做到一张发票一个口径。
中小型代理公司与工作室。5 到 30 人规模的设计、咨询、开发、翻译团队,需要统计每个人在不同客户上的工时消耗,Kimai 的团队权限加预算控制可以避免超支。
远程协作的研发团队。多时区多语言,30 多种界面语言与 2FA 双因素可以满足跨国会话的安全要求,JSON API 方便对接企业内部的考勤系统。
需要私有化合规的中大型企业。AGPL 协议下可以自托管,把数据留在内网,Kimai 提供 SAML、LDAP 接入,可以与企业现有的 Active Directory、Keycloak 等单点登录体系对接。
不希望长期按席位付费 SaaS 的组织。订阅制的 Toggl Track、Harvest 等按月收费,人数多了以后年度成本可观,Kimai 一次部署后续只承担服务器开销。
功能亮点
多计时器与打卡模式。在顶部导航栏点开始即可记录当前时间条目,可以同时运行多个并行计时,适合多任务切换的工作场景;也可以切换为打卡模式,按上下班时间汇总。
多用户多时区。每个用户独立设置时区,日报周报按本地时区切片,跨时区团队无需手动换算;支持团队组织与角色权限,管理员可以限定某个团队只看到自己的客户。
认证与安全。支持数据库、SAML、LDAP 多种登录方式,叠加 TOTP 双因素认证、备份码二次验证、CSRF 防护、登录限流器,登录页与后台均支持 HTTPS 强制。
JSON API。提供完整 REST 接口,分页、过滤、字段选择都按 Hypermedia 规范实现,文档由 NelmioApiDocBundle 自动生成,可用于与现有 ERP、CRM 同步工时数据。
报表与导出。内置 14 种报表视图,涵盖单人周报、月报、年报、全员统计、项目细节、项目总览、月度项目统计、不活跃项目、按月按活动按用户的交叉报表、缺勤日历、任务汇总等。导出格式支持 PDF、XLSX、CSV、ODS、HTML。
发票生成。按客户、按时间区间、按用户、按项目、按活动筛选可开票条目,选择模板,生成 PDF 发票,支持 ZUGFeRD 标准,客户编号、税率、币种、备注均可自定义。
插件市场。官方维护 50 多个付费与免费插件,涵盖审批流、加班、请假、费用、机器工时、看板、固定费率、硬件集成、Kiosk 自助打卡等场景,通过 composer require 即可启用。
数据导入导出。客户、项目、活动、用户、费率都可批量导入,内置 CSV 导入器与导出器,适合从 Toggl、Harvest、Clockify 迁移数据。
技术架构与部署指南
技术栈与运行环境
后端语言:PHP 8.2 及以上,推荐 8.3 或 8.4,composer 2.x。
Web 框架:Symfony 6.4 LTS,核心 bundle 锁版本在 composer.lock。
ORM 与迁移:Doctrine ORM 2.x 加 doctrine-migrations-bundle,数据库兼容 MariaDB 10.6 及以上或 MySQL 8.4 及以上。
前端资源:Webpack Encore 加 Tabler UI 主题,JavaScript 端用原生 ES 模块加 Tabler 组件,无 jQuery,无 Vue、React。
可选扩展:gd(intl 字符处理)、intl(多语言)、mbstring(字符串)、pdo(数据库)、tokenizer(XLSX 解析)、xml 与 xsl(报表模板)、zip(导入导出归档)。
部署环境必须使用子域名,不支持子目录,这是 Symfony 路由与资产管线的硬性要求。
最低硬件建议 1 核 1G 内存,数据量在 10 万条时间条目以下的中小团队可以稳定运行,百人以上建议加到 2 核 4G 并开启 PHP-FPM 与 OPcache。
建议使用 Docker 部署,官方镜像 kimai/kimai2 同时提供 FPM 与 Apache 两个 tag,FPM 适合搭配 nginx 反向代理,Apache tag 适合一键启动。
安装与部署提示
方式一,Docker 快速体验。一行命令即可拉起:docker run -ti –rm -p 8080:8080 kimai/kimai2:apache,浏览器打开 http://localhost:8080,按提示初始化数据库,创建管理员账号。
方式二,常规主机部署。安装 PHP 8.3、MariaDB 10.11、nginx,克隆仓库到 /var/www/kimai,执行 composer install –no-dev –optimize-autoloader,配置 .env.local,运行 bin/console kimai:install -n,设置目录权限 var/ 为 www-data 可写。
方式三,Synology NAS。套件中心安装 Container Manager,拉取 kimai/kimai2:apache 镜像,创建容器并暴露 80 端口,挂载本地数据库目录,启动后通过 NAS IP 访问。
方式四,云托管。如果不想自己运维,可以使用官方云服务 kimai.cloud,按月计费,免费试用 30 天。
升级流程。日常小版本升级可以运行 composer update 与 bin/console kimai:update -n,大版本升级前请阅读 UPGRADING.md 与 UPGRADING-3.md,迁移文件位于 migrations 目录,版本号写入 migrations/Version*.php。
截图与演示说明
以下截图来自 GitHub 原版 kimai/kimai 仓库,均为无水印原图,通过官方 demo.kimai.org 实例(账号 admin,密码 password)与 GitHub README 内嵌图获取,授权用于本次源码发布展示。
上图是 GitHub 仓库 kimai/kimai 顶部的 brand logo,标识 Kimai 是以”时间追踪”为核心定位的开源项目。
上图是 Kimai 登录界面,左侧为项目品牌区,右侧为账号密码输入框,支持 SAML、LDAP、数据库三种登录方式,可叠加 TOTP 双因素。
上图是 Kimai 主控台顶部导航区,从左到右依次为 Dashboard、Time Tracking、Employment contract、Reporting、Invoices、Expenses、Tasks、Administration、System,模块分区清晰,顶部右侧提供开始计时按钮、刷新、用户菜单。
上图是 Time Tracking 下的 My times 列表,展示当前用户的全部时间条目,支持按项目、活动、标签筛选,每条记录可编辑时长、起止时间、描述、费率。
上图是 Reporting 入口,提供 14 种预制报表,涵盖个人周月年视图、全员周月年视图、项目细节、项目总览、月度项目统计、不活跃项目、按活动按用户交叉报表、缺勤日历、任务汇总等。
上图是 Projects 列表,支持项目可见性(全局、团队、私有)、客户绑定、活动子集、预算(时间预算与金额预算双维度)、起始与结束日期、订单号、颜色标签等元数据。
上图是 Invoices 模块的筛选表单,按搜索关键字、时间范围、客户、项目、活动、标签、用户、团队、是否已导出等多个维度过滤,生成 PDF 发票。
常见问题
问:Kimai 是否必须装在子域名?
是的。Symfony 路由与资源管线假设站点处于根域,装在子目录会导致资产加载失败与反代路径异常。官方文档明确写明 subdomain required,subdirectory not supported。
问:Kimai 与 Toggl Track、Clockify 相比有什么差异?
Toggl 与 Clockify 偏向 SaaS 化、移动端体验好,免费版有人数限制。Kimai 是自托管优先,AGPL 协议,数据完全留在自己的服务器,API 完整可控,适合对数据合规与定制化有要求的团队。
问:支持哪些认证方式?
数据库账号、SAML 2.0、LDAP、TOTP 双因素、备份码。可以与企业 AD、Keycloak、Okta 等单点登录体系对接。
问:协议是 AGPL-3.0 还是 MIT?能不能商用?
原版协议为 AGPL-3.0-or-later,composer.json 明确标识。本地中文版 README 误写为 MIT,以 composer.json 与 LICENSE 实际文本为准。AGPL 允许商用,但要求网络发布时同步提供修改后的源代码。
问:最低服务器配置是多少?
1 核 1G 内存可启动,适合 10 人以内团队。50 人以上建议 2 核 4G 起步,数据库单独部署,启用 OPcache 与 PHP-FPM。
问:如何做移动端打卡?
Kimai 后台是响应式 Tabler 主题,手机浏览器可直接打开使用。如需专用移动 App 或微信小程序,可基于 JSON API 自研,或采购官方插件商店中的移动集成。
问:数据如何备份?
定时 mysqldump 即可,Kimai 表结构清晰,timesheet、invoice、user、customer、project 是核心五张表。附件与上传文件位于 var/uploads,需要单独备份。
问:从 Toggl 或 Clockify 迁移怎么操作?
使用 Kimai 内置的 CSV 导入器,准备好客户、项目、活动、用户、费率五份 CSV,按模板字段填入,先在测试库演练,再切换到生产。
安全风险提示
AGPL-3.0 协议的网络发布义务。在 Kimai 基础上做修改并对外提供网络服务时,必须向所有用户开放修改后的完整源代码。本次中文版源码未修改核心代码,纯汉化界面,直接以原版方式分发,不触发额外披露义务。
子域名与 HTTPS 强制。生产环境必须使用子域名,例如 time.company.com,启用 HTTPS,避免登录凭证与 API Token 在公网明文传输。
管理员账户与 2FA。安装完成后第一个账户自动获得 Super-Admin 权限,务必立即为该账户启用 TOTP 双因素认证,不要使用 admin、root 之类的弱口令,定期轮换备份码。
数据库口令与文件权限。.env.local 中的 DATABASE_URL 必须使用强密码,var/、public/media/ 目录权限设为 www-data 拥有且仅 750 权限,禁止 777。
API 限流与日志。开启 symfony/rate-limiter,在 nginx 加 fail2ban 拦截异常登录,日志写入独立分区并定期归档,bin/console kimai:reset-data 慎用。
依赖更新。composer.lock 锁定的依赖版本建议每季度做一次安全更新,关注 symfony、doctrine、phpoffice 三个核心包的安全公告。
下载说明
本次发布的中文版源码已在文末提供的网盘链接中,目录结构与 GitHub 官方仓库保持一致,上传时附带了 .env.dist、Dockerfile、composer.json,部署时直接使用。
网盘下载后请先核对 SHA256,与发布页说明的校验值一致再解压,推荐解压到 /var/www/kimai 或 D:\wwwroot\kimai 这种带独立子域名的路径。
如需同步官方最新版,在解压目录执行 git remote add upstream https://github.com/kimai/kimai.git 与 git fetch upstream,然后按 UPGRADING.md 提示做版本升级。
二次开发或定制汉化时,翻译文件位于 translations/,使用 Weblate 平台协作;插件开发参见官方 docs,插件目录挂在 var/plugins/,通过 composer require 安装。
GitHub项目开源地址:https://github.com/kimai/kimai