Leantime 3.12.0 完整部署与实战指南

目标：用一篇文章建立对 Leantime 的完整认知——它解决什么问题、由哪些组件构成、能力边界在哪里、与 Jira / Plane / Taiga / OpenProject 的差异是什么，并给出本系列其余 4 篇部署与实战文档的阅读路径。本文为认知篇，版本与生态数据均于 2026-10-27 联网核实官方源，不含本地部署实测。

一、环境信息

本文的数据来源、核实时间与目标运行环境如下。认知篇只做官方资料溯源，所有版本号、星标数、许可证均可在文末参考链接中复核。

• 版本核实日期：2026-10-27
• 最新稳定版：v3.12.0
• 版本发布依据：GitHub Releases Leantime/leantime 的 latest 为 v3.12.0，发布于 2026-10-15T23:11:05Z
• 官方镜像依据：Docker Hub leantime/leantime 的 3.12.0 tag 于 2026-10-21T20:04:07Z 推送，提供 amd64 / arm64 / arm 三种架构
• 仓库数据（GitHub API，2026-10-27 查询）：stars 11915、forks 1163、主语言 PHP、许可证 AGPL-3.0、最近推送 2026-10-27T05:27:31Z
• 目标操作系统（后续部署篇实测环境）：Ubuntu 22.04 LTS
• 运行栈：Nginx（或 Apache）+ PHP 8.2+（PHP-FPM）+ MySQL 8.0+ / MariaDB 10.6+
• 应用框架：Laravel 11（composer.json 要求 laravel/framework: ^v11.44）
• 默认监听：容器镜像内置 8080 端口；源码部署由 Web 服务器监听 80/443
• 代码根目录：发布包根目录的 public/ 为唯一 Web 入口，其余目录不得暴露

💡 说明：版本号必须以下载当天的 GitHub Releases 与 Docker Hub tag 为准。本文核实时 latest 与 3.12.0 指向同一镜像摘要（sha256:8e093293224cf48a24cfac7f32631aa5335014a065cd62b8ced4a74e4d548b80），说明 3.12.0 就是当前最新稳定版。

二、软件概述

Leantime 是一套面向「非项目经理」的开源项目管理与目标管理系统，官方自我定位是「简单如 Trello、功能丰富如 Jira」，并明确针对 ADHD、阅读障碍与自闭症人群做了可用性设计（减少信息噪音、突出今日待办、单页完成操作）。它把战略层（目标、指标）、规划层（里程碑、冲刺、看板）与执行层（任务、工时、文档）放在同一个 Web 应用里，避免团队在多个工具之间切换。

核心事实清单：

• 开源许可：AGPL-3.0-only，允许自托管与二次开发，但通过网络对外提供服务时需按 AGPL 要求开放修改后的源码
• 维护方：Leantime 官方团队（作者 Marcel Folaron），官网 leantime.io，另有托管云服务与插件市场
• 技术栈：PHP 8.2+ / Laravel 11 / MySQL 或 MariaDB / 原生 PHP 模板渲染 + 少量前端构建产物
• 部署形态：源码包（LEMP/LAMP）与官方容器镜像两种，均以 public/ 为文档根
• 生态：20 多种语言、插件扩展、LDAP/OIDC 单点登录、Slack/Mattermost/Discord 通知、S3 兼容对象存储
• 版本节奏：从 Docker Hub 时间线可见 3.10.0（2026-09-24）→ 3.10.1~3.10.4（2026-10-02 ~ 10-05）→ 3.11.0（2026-10-09）→ 3.12.0（2026-10-21），属于「月度功能版 + 周级补丁版」的节奏

💡 技术拓展：项目管理工具的服务端渲染技术路线不止一种。常见三类——

路线	代表	特点	适用场景
传统服务端渲染（PHP/Ruby 模板）	Leantime、Kanboard、OpenProject	部署简单、单机即可、SEO/首屏友好；交互依赖页面刷新或局部 JS	中小团队自托管、运维人力有限
前后端分离（REST + SPA）	Plane、Jira Cloud	前端体验接近桌面应用、扩展 API 丰富；需维护前端构建与 API 两层	大型团队、需要深度定制的产品研发
实时协同（WebSocket/CRDT）	部分白板类工具	多人实时编辑体验好；状态同步与冲突处理复杂	实时共创、白板评审

本文所讲的 Leantime 采用第一类「传统服务端渲染 + Laravel」路线，换来的是单机 LEMP 即可跑、备份只需「数据库 + 上传目录 + .env」的运维简洁性。

三、核心架构

Leantime 的运行时结构是典型的「Nginx/Apache → PHP-FPM → Laravel 应用 → MySQL」四层。理解这条链路，后面部署篇里的文档根目录、权限、.env、伪静态规则才有依据。

浏览器
  │  HTTPS 443
  ▼
Nginx / Apache ──► public/index.php（唯一入口）
  │                    │
  │                    ▼
  │              Laravel 11 内核
  │                 ├── 路由 / 中间件（认证、CSRF、会话）
  │                 ├── 领域模块（项目、任务、目标、工时、Wiki…）
  │                 ├── 插件（app/Plugins）
  │                 └── JSON-RPC API（/api/jsonrpc）
  ▼                    │
PHP-FPM 8.2+           ▼
                 MySQL 8.0 / MariaDB 10.6+
                       │
                 storage/（日志、缓存、会话、上传文件）

关键目录与职责：

架构层面的三个要点：

1. 单进程、无内置集群模式：Leantime 自身不做多节点协调，水平扩展依赖「无状态 PHP 进程 + 共享数据库 + 共享上传存储（S3）」。会话默认落文件，多节点部署必须改为共享会话存储或启用 S3。
2. 数据模型以项目为边界：用户、客户、项目、任务（To-Do）、里程碑、目标、Wiki 文档、工时记录、评论、附件构成主要实体，权限按「全局角色 + 项目成员角色」两层控制。
3. 扩展走插件与 API：插件以目录形式放在 app/Plugins，通过应用内的钩子机制挂载；对外集成走 JSON-RPC 接口，使用 API Key 鉴权（详见本系列 API 篇）。

💡 技术拓展：自托管项目管理系统的持久化方案常见三种组合——

组合	代表	运维成本	一致性/事务能力
MySQL/MariaDB 单库	Leantime、Kanboard	低：一个库、一条备份命令	强事务，适合任务/工时这类关系数据
PostgreSQL 单库	Plane、Taiga、OpenProject	中：需熟悉 PG 的备份/升级路径	强事务，JSON 字段与索引能力更强
多存储（关系库 + 对象存储 + Redis）	Jira Data Center 等	高：三类组件分别运维	各取所长，但故障面扩大

Leantime 选择「MySQL/MariaDB 单库 + 本地或 S3 附件」的最简组合，代价是大规模并发下需要自行加缓存与读写分离，收益是中小团队一个人就能维护。

四、功能特性

Leantime 的功能可以按「任务执行、项目规划、知识管理、管理集成」四块理解。下表按官方 README 的功能清单整理，并标注自托管场景下的实际取舍。

三个容易被忽略的能力边界：

• 没有原生 Git 仓库托管/代码评审：它做的是任务与项目层，代码托管需另配 GitLab/Gitea，再通过 API 或 Webhook 关联。
• 没有内置的高可用与多租户隔离：一套实例服务一个组织；多租户需要多套实例 + 独立库。
• 报表以项目仪表盘为主：跨项目组合分析、自定义 BI 报表能力弱于 Jira + eazyBI 或 OpenProject 的企业版报表。

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

本节给出官方文档定义的最小可用路径，用于判断「这套系统是否值得进一步部署」，具体命令与逐条实测回显见本系列的 Ubuntu 安装篇与 Compose 部署篇。以下步骤来自 v3.12.0 官方 README 的生产安装说明，尚未在本机执行，因此只描述流程与预期结果，不伪造回显。

前置条件（官方 composer.json 与 README 双重确认）：

• PHP 8.2+，启用 bcmath、ctype、curl、dom、exif、fileinfo、filter、gd、hash、ldap、mbstring、mysqli、openssl、pcntl、pdo、pdo_mysql、phar、posix、session、simplexml、tokenizer、zip、opcache
• MySQL 8.0+ 或 MariaDB 10.6+，提前建好空库与专用账号
• Nginx 或 Apache，文档根指向发布包的 public/ 目录

最小步骤：

1. 从 GitHub Releases 下载 Leantime-v3.12.0.zip（同版本另有 Leantime-v3.12.0.tar.gz），解压到服务器目录，例如 /opt/leantime。
2. 在数据库中创建空库 leantime 与账号 leantime。
3. 把 config/sample.env 复制为 config/.env，填写数据库主机、库名、账号、密码。
4. Web 服务器文档根指向 /opt/leantime/public，配置 PHP-FPM 转发与伪静态。
5. 浏览器访问 https://<你的域名>/install，按向导完成建表与首个管理员账号创建。
6. 安装完成后删除或重命名 public/install 相关入口，登录进入「我的工作」首页。

预期结果（依据官方安装向导描述，非本机实测）：

• /install 页面能读到数据库连接并自动执行建表 SQL；
• 创建管理员后自动跳转到登录页，登录成功进入 My Work 仪表盘；
• 访问 /api/jsonrpc 返回与鉴权相关的 JSON 错误（未带 API Key 时的正常表现），证明应用路由已生效。

⚠️ 注意：源码部署时若把文档根指到包根目录，config/.env、storage/ 会暴露在 Web 下，属于严重安全问题。必须确认文档根是 public/。

六、适用场景与限制

Leantime 最适合「10~50 人、以交付项目为主、希望一个工具覆盖目标—计划—执行」的团队。下面按场景给出匹配度判断。

适用场景：

不适用或需谨慎评估的场景：

• 千人级组织、需要跨部门组合报表：单库 + 单实例的架构需要额外做读写分离与报表外置，建议评估 OpenProject 企业版或 Jira Data Center。
• 强实时多人协同编辑：Wiki 与文档不是实时协同模型，多人同时编辑同一页会以保存覆盖为准。
• 需要原生代码仓库/CI：Leantime 不做代码托管与流水线，必须外接。
• 需要开箱即用的高可用：官方不提供集群编排，HA 需自行设计共享存储、会话与数据库主从。

七、同类选型对比

选型的核心不是「谁功能多」，而是「团队规模、运维人力、合规要求、预算」四者的匹配。下表把 Leantime 与四个常见替代品放在一起，数据来自 2026-10-27 的 GitHub API 与各项目官方资料。

如何选：

• 团队没有专职运维、希望一天内上线并覆盖目标/任务/工时：选 Leantime。
• 已重度使用 Atlassian 生态（Confluence、Bitbucket）、需要成熟插件市场：选 Jira。
• 研发团队规模较大、追求现代前端体验与 API 优先：选 Plane。
• 需要严格的 Scrum 流程（史诗/用户故事/看板泳道）且能接受多服务运维：选 Taiga。
• 需要预算、成本、甘特与组合项目管理的完整闭环：选 OpenProject。

💡 技术拓展：自托管项目管理工具的「部署重量」差异，本质来自进程模型不同——

模型	例子	进程数	备份复杂度
单体 Web 应用	Leantime、Kanboard	1 个 PHP-FPM 池 + 1 个库	低
前后端分离多服务	Plane、Taiga	web/api/worker/队列/库	中
JVM 企业应用	Jira DC	JVM + 搜索 + 库 + 集群	高

本文系列以「单体 Web 应用」为默认运维模型展开，B1/B2 两篇分别覆盖源码与容器两种落地方式。

八、系列导航

本系列共 5 篇，按「认知 → 部署 → 配置 → 集成」递进，每篇均可独立执行：

阅读建议：先读本篇判断是否匹配，再按部署方式选第 2 或第 3 篇落地，最后用第 4、5 篇完成配置与集成。

九、参考链接

• 官网：https://leantime.io
• 官方文档：https://docs.leantime.io
• GitHub 仓库：https://github.com/Leantime/leantime
• v3.12.0 发布页：https://github.com/Leantime/leantime/releases/tag/v3.12.0
• 官方镜像：https://hub.docker.com/r/leantime/leantime
• 官方 Compose 示例：https://github.com/Leantime/docker-leantime
• 插件市场：https://marketplace.leantime.io
• 许可证全文：https://www.gnu.org/licenses/agpl-3.0.en.html