solidtime v0.21.0 介绍与选型指南

‍‍​​‌​> 目标：面向准备自托管时间追踪系统的技术选型者，完整介绍开源时间追踪应用 solidtime 的定位、架构、功能边界与同类竞品对比。本文全部信息来自官方站点、官方文档站与 GitHub 发布记录的联网溯源（来源与查询日期 2026-10-24 均已在正文标注），未混入任何未经验证的第三方评测数据。

一、环境信息

本篇为认知与选型篇，全部数据通过联网溯源获得，不涉及本地实测环境。溯源渠道与查询日期如下：

关键结论先行：solidtime 当前最新稳定版为 v0.21.0（2026-09-22 发布），GitHub 星数 9,014（winterflow.io 汇编快照，2026-10-24），许可证 AGPL-3.0，官方通过 Docker Hub 发布镜像 solidtime/solidtime，自托管依赖 PostgreSQL 数据库。

二、软件概述

2.1 定位与身份

solidtime 是一款现代开源时间追踪（Time Tracking）应用，官方定位为「面向自由职业者与代理机构（freelancers and agencies）的现代开源时间追踪应用」，明确对标商业 SaaS 产品 Toggl、Clockify、Harvest（来源：winterflow.io 项目页汇编，2026-10-24）。它解决的核心问题是：团队需要记录工时、按项目/任务/客户核算可计费时间（billable hours）、生成报表与导出数据，但又希望数据留在自己控制的服务器上，而不是托付给第三方 SaaS。

项目的身份信息如下（来源：winterflow.io 项目页与发布记录，2026-10-24）：

💡 说明：AGPL-3.0 是「网络分发即需开源」的强互惠许可证——如果读者基于 solidtime 对外提供在线服务（修改版），需要向使用者公开修改后的源码；仅企业内部使用、不对外提供网络服务则没有开源义务。这也是 Toggl/Clockify 类闭源 SaaS 与自托管开源替代品在合规层面最关键的分界线之一。选型时若计划二次开发后商用对外，务必先评估 AGPL 义务。

2.2 版本演进与版本节奏

solidtime 自 2024 年 6 月发布首个版本以来保持高频迭代。以下为版本里程碑梳理（来源：GitHub Releases 汇编，2026-10-24）：

版本节奏量化：2026-02-16 至 2026-09-22 的约 7 个月内发布 19 个版本（v0.11.1 ~ v0.21.0），平均不到两周一个版本；其中至少 5 个版本（v0.12.2、v0.16.0、v0.17.0、v0.19.0、v0.20.1）包含安全修复（涉及惯性 props 数据泄露、路径穿越、时间条目越权改派、ZIP 解压与密码重置漏洞、Host 头投毒防护等）。这表明项目处于活跃维护期且对安全问题响应较快。

版本阶段提示：主版本号仍为 0.x，官方尚未宣布 1.0 稳定承诺。从发布记录看，安全修复频繁、API 与数据结构仍在演进（如 v0.5.0 升级后要求重算计算属性），选型时应预期「升级需跟随官方迁移说明」，不宜按 1.0 语义锁死版本长期不动。

三、核心架构

3.1 技术栈

以下技术栈信息均出自官方文档与发布记录（来源：docs.solidtime.io 与 GitHub Releases，2026-10-24）：

💡 技术拓展：PHP 长驻应用的 HTTP 运行时目前有三条主流路线——传统 PHP-FPM（每请求加载框架，兼容性最好）、Swoole/OpenSwoole Octane（常驻内存、性能高，但需注意内存泄漏与状态残留）、FrankenPHP（Caddy 内嵌 PHP，支持 worker 模式与早早期 hints）。solidtime 官方镜像的形态是「FrankenPHP 基础运行时 + Swoole HTTP 服务」，即以 Swoole Octane 常驻进程对外服务；这与 Kimai 等仍走 PHP-FPM 传统部署的项目不同，意味着 solidtime 单实例吞吐更好，但也更依赖官方镜像的调优，自行以 PHP-FPM 方式部署社区版不在官方支持路径内。

3.2 部署形态与组件分工

官方自托管形态是 Docker Compose 多容器编排（来源：docs.solidtime.io/self-hosting/guides/docker，2026-10-24）。单个 solidtime 应用镜像通过 CONTAINER_MODE 环境变量拆分出三种角色：

外围组件：PostgreSQL 数据库（唯一支持的数据库）、Gotenberg（PDF 渲染，可选）、反向代理（TLS 终结，官方示例仓库 solidtime-io/self-hosting-examples 提供 Traefik 与「纯 Docker + 数据库」两套示例）。数据库迁移通过 php artisan migrate --force 手动执行，或设置 AUTO_DB_MIGRATE=true 随启动自动执行。

3.3 接口与集成面

solidtime 的对外集成面由四部分组成（来源：官方 OpenAPI 规格与 Docker 指南，2026-10-24）：

1. REST API（主要集成形态）：路径前缀 /api/v1，覆盖组织、项目、客户、任务、标签、成员、邀请、报表、图表、目标、导入导出、时间条目等约 80 个端点，认证走 Bearer Token（用户在设置页创建的个人 API Token）或 OAuth2。官方 API 文档地址 https://docs.solidtime.io/api-reference。
2. 桌面客户端：通过 OAuth 公共客户端（passport:client --name=desktop --redirect_uri=solidtime://oauth/callback --public）接入自托管实例，客户端内配置 API URL 与 Client ID。
3. 浏览器扩展：Chrome / Firefox 扩展，同样以 OAuth 公共客户端接入，扩展 ID 官方已在文档中给出固定回调地址。
4. 导入导出：内置导入器（Clockify、Harvest、通用格式，随版本持续修复）与全量数据导出（API 端点 POST /v1/organizations/{organization}/export）。

四、功能特性

基于官方发布记录与文档的功能清单（2026-10-24 溯源）：

时间追踪核心：计时器一键开始/停止、手动补录、日历视图（v0.10.0）、表格化 Timesheet 批量录入口（v0.14.0，支持复制上周工时）、工间休息 Breaks（v0.18.0，计时器/工时表/日历三视图联动）、重叠条目防护（v0.10.0）、录入取整规则（v0.9.0）、命令面板快速操作（v0.11.1）。

计费与报表：项目/组织级可计费费率体系（v0.0.2 即有，v0.1.0 支持时间条目级费率更新）、详版报表与标签分组（v0.4.0、v0.10.0）、PDF 与可分享报表（v0.5.0，PDF 依赖 Gotenberg）、报表导出、发票收件人体系（v0.20.0，Business 特性）。

组织与权限：多组织（API 以 organization 为作用域）、成员与占位成员管理（placeholder member，v0.20.0 系列增强）、成员合并、邀请制注册（v0.20.0 APP_ENABLE_REGISTRATION=invite-only）、超级管理员面板（/admin，SUPER_ADMINS 邮箱白名单控制）、安全审计（v0.2.0 引入审计功能）。

生态与集成：REST API（v0.6.0 起公共可用，v0.20.0 起限流可配置：默认认证用户 200 次/分钟、访客 60 次/分钟）、个人 API Token 管理（创建/撤销/删除 API 化）、桌面客户端与浏览器扩展 OAuth 接入、导入器（Clockify/Harvest/通用）、全量导出（API + 本地文件系统导出）、S3 兼容对象存储、多语言与浅色主题（v0.7.0）。

运维侧特性：三容器角色分离（http/scheduler/worker）、可选启动自动迁移（AUTO_DB_MIGRATE）、双环境文件配置（compose 侧 .env + 应用侧 laravel.env）、密钥一键生成命令（self-host:generate-keys）、容器模式文档化、On-Premise Business 商业扩展通道。

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

以下流程为官方 Docker 部署指南（https://docs.solidtime.io/self-hosting/guides/docker，2026-10-24）的最小主线摘引，供选型验证参考；完整参数解释与实测回显见本专栏部署篇。

1. 准备 Docker 环境与官方示例：官方在 solidtime-io/self-hosting-examples 仓库提供「Docker + Traefik + 数据库」与「Docker + 数据库（自带反代或本地 HTTP）」两套模板，复制对应目录后按 README 调整。
2. 准备两份环境文件：compose 侧 .env.example 复制为 .env，应用侧 laravel.env.example 复制为 laravel.env，分别调整。
3. 生成应用密钥（输出 APP_KEY、PASSPORT_PRIVATE_KEY、PASSPORT_PUBLIC_KEY 三个随机值，回填进 laravel.env）：

docker compose run scheduler php artisan self-host:generate-keys

4. 启动全部服务：

docker compose up -d

5. 初始化数据库表结构（每次升级应用后同样需要执行；单容器简化场景可改用 AUTO_DB_MIGRATE=true 自动迁移）：

docker compose exec scheduler php artisan migrate --force

6. 创建首个用户（默认注册关闭，需 CLI 建号；命令输出随机密码，如需超管将邮箱加入 SUPER_ADMINS 后重启）：

docker compose exec scheduler php artisan admin:user:create "Firstname Lastname" "firstname.lastname@some-email-provider.test" --verify-email

7. 浏览器访问实例地址登录；如需启用 API Token 集成，先执行一次 php artisan passport:client --personal --name="API" 创建个人访问令牌客户端。

💡 说明：官方镜像默认监听 8000 端口、设计上置于反向代理之后；本地快速验证可以走 HTTP 直连（APP_URL=http://localhost:8000），生产环境建议按官方示例加 Traefik 或 Nginx 做 TLS 终结，并配置 APP_FORCE_HTTPS 与 TRUSTED_PROXIES。

六、适用场景与限制

6.1 适用场景

• 自由职业者与代理机构工时计费：这是 solidtime 的第一定位——按客户/项目/任务记录可计费工时，配合费率与报表导出直接支撑开票流程；导入器可从 Clockify/Harvest 平滑迁入。
• 数据主权敏感的团队：AGPL-3.0 + 全量自托管 + PostgreSQL 单库存储 + API 全量导出，数据可完全留在自有基础设施（含 S3 兼容私有对象存储），随时可迁移。
• 需要 API 深度集成的团队：约 80 个 REST 端点覆盖核心域，配合个人 API Token 可对接自有工单/薪酬/BI 系统；桌面客户端与浏览器扩展亦可指向自托管实例。
• 中小团队内部工时管理：多组织、成员邀请、占位成员、超管面板与审计满足内部管控；邀请制注册防止匿名注册滥用。

6.2 限制与注意事项

• 仅支持 PostgreSQL：官方配置文档明确不支持 MySQL/MariaDB，已有 MySQL 栈的团队需另起 PG 实例。
• 0.x 阶段：尚无 1.0 稳定承诺，升级需跟随官方迁移说明（部分版本要求重算计算属性、执行数据库迁移）；安全修复频繁，应保持跟进。
• 必须自备 SMTP 与反向代理：邮件（通知/密码重置）依赖外部 SMTP；官方镜像不做 TLS，生产部署需要 Nginx/Traefik/Traefik 类反代并正确配置 APP_FORCE_HTTPS、TRUSTED_PROXIES、TRUSTED_HOSTS。
• AGPL-3.0 合规边界：修改后对外提供网络服务需开源修改部分；商业闭源扩展走官方 On-Premise Business 付费计划。
• 报表 PDF 依赖 Gotenberg：不部署 Gotenberg 则 PDF 导出类特性不可用（其余功能不受影响）。
• API 限流默认偏紧：生产环境（APP_ENV=production）默认认证用户 200 次/分钟，高频集成需按官方文档调大 API_RATE_LIMIT_AUTH_PER_MINUTE。

七、同类选型对比

7.1 竞品概览

下表对比与 solidtime 同处「时间追踪」赛道的常见选择。solidtime 行的数据为已溯源量化数据（2026-10-24）；其余项目为公开常识性定性描述（其星数/版本数未在本篇逐一实查，引用时请以各自官方渠道为准，特此声明以免误导）：

7.2 solidtime 量化画像

选型量化维度（全部可溯源，2026-10-24）：

7.3 选型建议

• 如果诉求是「团队工时 + 客户计费 + 数据自主」三位一体，solidtime 是当前开源阵营里定位最贴合的选择之一：计费费率、报表、发票收件人、导入器一应俱全。
• 如果只需要个人自动统计编码时间，选 Wakapi/ActivityWatch 更合适，solidtime 的人工/半自动工时模型反而是负担。
• 如果已经在 MySQL 栈上有强路径依赖且不愿引入 PostgreSQL，Kimai 更顺手。
• 如果完全不想运维，Toggl/Clockify 的 SaaS 仍是低摩擦选项，但代价是数据出域——solidtime 的导入器保留了你未来迁回自托管的通道。
• 如果计划修改后对外提供商业服务：先做 AGPL 合规评估，或直接走官方 On-Premise Business 计划获取商业授权与扩展。

八、参考链接

• 官网：https://www.solidtime.io
• GitHub 仓库：https://github.com/solidtime-io/solidtime
• 官方自托管文档（Docker 指南）：https://docs.solidtime.io/self-hosting/guides/docker
• 官方配置文档：https://docs.solidtime.io/self-hosting/configuration
• 官方 CLI 命令文档：https://docs.solidtime.io/self-hosting/cli-commands
• 官方容器模式文档：https://docs.solidtime.io/self-hosting/container-mode
• 官方 API 文档：https://docs.solidtime.io/api-reference
• 官方 OpenAPI 规格：https://api-docs.solidtime.io/api-docs.json
• 自托管示例仓库：https://github.com/solidtime-io/self-hosting-examples
• 版本记录汇编（本文发布节奏与星数出处）：https://winterflow.io/catalog/solidtime/releases/
• 本专栏系列篇：《solidtime v0.21.0 Docker Compose 部署指南》《solidtime v0.21.0 配置参数详解》《solidtime v0.21.0 API 使用详解》