Leantime 版本演进深度解析：从 CHANGELOG 看 3.1 到 3.9 的架构现代化之路

Leantime 版本演进深度解析从 CHANGELOG 看 3.1 到 3.9 的架构现代化之路【免费下载链接】leantimeLeantime is a goals focused project management system for non-project managers. Building with ADHD, Autism, and dyslexia in mind.项目地址: https://gitcode.com/GitHub_Trending/le/leantimeLeantime 是一款以目标为导向的开源项目管理工具其官方 CHANGELOG.md 完整记录了从 3.1 到 3.9 的每一次版本迭代。本文以该文档为骨架逐版本拆解 Leantime 的核心演进脉络——原生权限引擎、JSON-RPC API、Blade 模板迁移、Tiptap 富文本编辑器、跨项目 Program Board 等关键架构决策——并结合仓库源码如 PermissionService.php、PermissionEnforcer.php、Jsonrpc.php 等验证底层实现帮助你快速判断各版本的能力边界、安全修复范围与升级注意事项。CHANGELOG 全景版本节奏与文档结构CHANGELOG.md2022 行覆盖 3.1.2 → 3.9.8采用了典型的自上而下编排最新版本在最顶部每个版本条目按Highlights里程碑特性→New Features→Bug Fixes→Improvements→Security→Localization→Dependency Updates→Breaking Changes的顺序组织部分版本还附带了提交清单。从版本节奏可以观察到两条清晰的演进主线技术债清理3.4.x 起逐步向 Laravel 靠拢Laravel 会话处理、Laravel 数据库类、Laravel 异常处理器3.8.0 完成全量 Blade 模板迁移3.9.0 引入原生权限引擎与 JSON-RPC API能力外延3.5.x 加入 Redis 缓存/会话3.7.0 引入实验性 PostgreSQL 支持3.9.x 加入跨项目 Program Board、MCP 端点与移动端 API 面。对于运维与二次开发者CHANGELOG 也是天然的升级风险清单每个版本都会标注破坏性变更如 3.7.0 移除 TinyMCE和需要人工介入的配置变更如 3.8.0 修正会话过期时间单位。3.9.x 主线权限引擎、JSON-RPC 与跨项目视图Native Permission Engine从散落角色检查到集中式鉴权层3.9.0 最大的架构变更是原生权限引擎Native Permission Engine。CHANGELOG 明确指出它取代了分散的 ad-hoc 角色检查以默认拒绝fail-closed的集中式授权层治理整个应用的访问控制并逐域落地到 Tickets、Comments、Users、Clients、Settings、Sprints、Wiki、Ideas、Goals、Blueprints、Canvas、Calendar、Timesheets、Files、Reports 与 Projects 服务期间关闭了大量跨用户 IDOR越权访问与信息泄露漏洞#3461、#3469、#3471、#3472、#3473。源码验证了这套引擎的三层结构声明层通过RequiresPermission属性attribute在控制器方法上声明所需权限键PermissionEnforcer统一从三类入口读取该属性——传统路由Frontcontroller::executeAction()、原生 Laravel 路由CheckPermissions中间件、JSON-RPCJsonrpc::executeApiRequest()保证一处声明、处处一致决策层PermissionService.php 的currentUserCan(string $permissionKey, ?int $projectId, ?bool $forceGlobal)是唯一运行时入口它区分两个关注点能力capability——用户的有效角色是否持有该权限查缓存的角色→权限授权映射表以及数据访问data access——对于项目级权限用户是否真是该项目成员admin/owner 绕过落地层PermissionSeeder.php 将代码中发现的domain.action词汇表幂等同步进zp_permissions表并以仅追加方式为六个内置角色授予默认权限DefaultRolePermissions矩阵保证管理员的自定义授权在重新同步后不被覆盖。一个值得注意的工程细节是audit mode审计模式PermissionEnforcer.php 的注释显示当config(permissions.enforce)为假时默认引擎只记录本应拒绝的日志而不真正拦截使权限可以按域逐步灰度观察后再切换为阻断模式。此外projectIdParam无法解析为具体项目且为必填参数时失败关闭fail closed避免误用会话项目做错误授权。JSON-RPC API替代遗留 REST/JSON 控制器3.9.0 同期引入的 JSON-RPC 2.0 API 层替代了遗留 REST/JSON 控制器迁移了 Tickets、Users、Ideas、Calendar、Notifications、Reactions、Sessions、Submenu 等端点并提供插件门控属性plugin gate attribute与能力发现端点#3457。在 Jsonrpc.php 中可以看到它的关键约定仅显式标记api注解的服务方法可被远程调用3.8.0 起强制执行标量返回值不再被包装成单元素数组id参数使用类型化声明RPC 场景下被拒绝的服务方法抛出类型化异常并配合JsonRpcErrorResponse/JsonRpcResponse统一响应格式。配套的认证链路也在 3.9.1–3.9.3 之间逐步完善3.9.1 恢复 Sanctum Bearer 请求的用户上下文修复 3.9.0 回归#35143.9.3 修复了 Bearer 令牌错误-32001——根因是 Sanctum guard 会话里存的是原始角色整数而非权限引擎期望的角色名#3525并由此推动所有认证路径Web 登录、API Key、Bearer 令牌统一走同一个会话工厂#3526从根上避免角色与二因素状态分叉。跨项目 Program Board 与统一 Blueprints 域3.9.7 的里程碑特性是跨项目 Program 视图任务视图可以跨多个项目组成 Program冲刺sprint在 Program Board 上跨项目继承从而支持更高层级的计划与跟踪#3587。3.9.8 继续打磨该模块修复里程碑 0% 完成度、时间线Show Tasks空视图见 #3624、#3625、#3628并调整卡片状态下拉框位置#3599。3.9.0 的Unified Blueprints Domain则是一次大规模去重重构原本 16 个各自独立的 canvas 变体域被合并为统一的 Blueprints 域原生 Laravel 控制器在保留全部画布类型的同时大幅减少重复代码遗留的 Canvas 与 Strategy 代码退化为薄薄的弃用适配器#3483、#3486。配合新增的 Logic Model Board#3455与 WorkStructure 元模型#3454Leantime 正在把画布结构化工作层级抽象为可编排的基础设施。移动端与 MCP3.9.x 的外部集成面3.8.0 引入了支撑 Leantime Mobile App 的后端 API 面核心是服务端权威的会话解析移动客户端通过 Bearer 令牌认证后无需预先知道自己的 userId 即可解析我是谁#3395。具体到方法层包括Users::getUser()缺省取会话用户、Auth\AccessToken::revokeCurrentToken()安全登出、Tickets::markTicketDone/markTicketReopen快速完成流程等。3.9.8 对 MCP 端点的修复值得一提/mcp端点现在接受 Leantime API Key并提供一个针对已移除 php-mcp provider 的 shim使原地升级可以正常引导#3601、#3602、#3607。3.9.7 则把 MCP 工具类重组进各自对应的领域模块#3581并在端到端测试中发现并修复了运行时缺陷#3586。3.8 与 3.7前端统一与编辑器换代3.8.0Complete Blade 模板迁移3.8.0 完成了所有遗留.tpl.php、.sub.php、.inc.php模板到 Laravel Blade 的转换删除 272 个遗留文件、新增 200 个 Blade 文件净减少 72 个文件覆盖全部 16 个 canvas 域、共享子模块Tickets、Comments、Files、Projects以及简单/复杂域#3362。对插件开发者而言这意味着模板层的扩展点全部切换到 Blade 生态。3.7.0TinyMCE → Tiptap 与实验性 PostgreSQL3.7.0 最醒目的事件是富文本编辑器换代TinyMCE 被完全移除替换为基于 Tiptap 的现代编辑器#3362 同期相关支持/斜杠命令、提及、多列布局、字体与字号、颜色与高亮、KaTeX 数学公式、带语法高亮的代码块、表格与任务列表、全移动端适配以及为 AI 辅助写作预留的 Copilot 扩展钩子。同版本还进行了 Wiki 三栏式重构导航/内容/属性面板 审计驱动的活动流与通知系统改进按项目静音、按事件类型过滤。破坏性变更提示CHANGELOG 明确警告——现有内容无需修改即可渲染但任何自定义 TinyMCE 插件或编辑器扩展必须针对 Tiptap API 重写。同版本还引入了实验性 PostgreSQL 支持新的 SchemaBuilder 负责跨数据库 schema 管理castAs()辅助方法处理跨库 CASTwrapColumn()取代双引号 SQL 标识符#3447 起持续修复。Postgres 兼容问题在后来的版本中反复出现也反向证明了这套辅助层在真实部署中的价值。3.6看板体验、无障碍与多协作者3.6.0 聚焦交互层Kanban 看板可折叠泳道collapsible swimlanes、水平泳道头含状态分布与吸顶、看板快速添加表单含键盘快捷键、按截止日期分组、乐观 UI 更新、跨泳道拖拽#3205 系列无障碍WCAG 2.1 AA全局对比度与焦点指示器优化、暗色模式与灰度下的低视力支持、自定义输入组件下拉、日期选择器的无障碍改造、TinyMCE 屏幕阅读器修复多协作者单个 ticket 可分配多个协作者在 3.9.0 中补完确保协作者始终收到 ticket 通知并在列表/组件视图中展示完整元数据#1099时间表过滤支持按 ticket 与开票状态过滤3.5.12 期间持续打磨。安全修复脉络跨版本的安全演进线把 CHANGELOG 的 Security 章节串联起来可以看到一条完整的加固时间线3.4.x–3.5.x转义邮件内容、API Key 名称转义、项目 webhook URL 转义、SVG 禁用显示、开放重定向修复、文件管理加固3.6.0LDAP 类型加固、2FA QR 码生成修复3.9.0七大类漏洞族综合治理——projectIdParam必须为真实正整数且无法解析时失败关闭#3507、#3509、Projects 上帝服务增加递归安全的 manager 校验#3505、Calendar/Files/Reports/Timesheets/Goals/Canvas 各域门控并关闭 by-id IDOR、评论授权收敛到宿主实体的真实项目、TagsgetTagsIDOR 关闭、CSRF 加固安装路由豁免 表单 token 化3.9.6授权、SSRF、重置令牌、LDAP、存储型 XSS 修复#3584插件管理要求正确权限且安装输入严格校验#3583头像图片源中编码用户 ID 防 DOM XSS#3582getUserAPI 响应剥离凭据#3556、#3576。这些条目为安全审计者提供了绝佳的排查起点例如 3.9.3 的 Bearer 认证修复可直接定位到认证会话工厂与RoleResolver的衔接逻辑。运维配置要点从 CHANGELOG 提炼的部署注意事项CHANGELOG 中的多个 Bug Fix 条目实际是在纠正配置语义对部署者有直接价值会话过期时间单位3.8.0/3.4.7helm/values.yaml的app.session.expiration曾默认28800秒而应用期望的是分钟对应LEAN_SESSION_EXPIRATION与 Laravel 的session.lifetime现已修正为480分钟8 小时并显式注释单位同时在 config/sample.env 与 laravelConfig.php 中澄清防止回归#3378。升级到 3.8.0 的 Helm 用户应注意该键的语义Redis 会话隔离3.9.8会话被隔离到独立的 Redis database避免与其他缓存数据冲突#36043.5.10 起支持redis db配置#3103 相关API 速率限制3.9.7默认 API 速率限制从 10 次/分钟提升到 120 次/分钟#3591配合Retry-After标准响应头3.2.0-beta 引入与RateLimiter中间件app/Core/Middleware/RateLimiter.phpMySQL 版本底线3.2.0 起要求 MySQL 8.05.7 已 EOL并同步支持实验性 PostgreSQL缓存一致性3.9.7 修复系统更新后未清理缓存引导清单的问题3.9.2 修复陈旧路由缓存导致的 500#3523。从 CHANGELOG 追溯源码给开发者的阅读指南CHANGELOG 的本质是变更索引每个条目都可以在仓库中找到对应实现。推荐按以下映射关系深挖权限引擎RequiresPermission属性声明见 RequiresPermission.php强制器见 PermissionEnforcer.php决策逻辑见 PermissionService.php角色-权限矩阵见 DefaultRolePermissions.php播种逻辑见 PermissionSeeder.phpJSON-RPC控制器 Jsonrpc.php 与响应类型 JsonRpcResponse.php、JsonRpcErrorResponse.php请求样例见 tests/Httprequests/JsonRPC.http 与 MCP.httpAPI 认证Sanctum 桥接见 SanctumServiceProvider.phpBearer 契约测试见 tests/Acceptance/API/BearerApiCest.php3.9.1 起带 CI 门禁跨数据库兼容castAs()/wrapColumn()辅助见 DatabaseHelper.phpPostgres 连接封装见 LtPostgresConnection.php模板层Blade 组件库见 app/Views/Templates/components3.8.0 迁移成果的落点。结语把 CHANGELOG 当作架构决策日志Leantime 的 CHANGELOG 远超变更列表的意义——它记录了项目从传统 PHP 模板架构向 Laravel 生态、从散落权限检查向声明式鉴权、从单一 MySQL 向双数据库、从 Web-only 向 API/移动端/MCP 多入口演进的完整决策链。对评估者它提供了各版本能力与安全状态的权威快照对升级者它标注了每个破坏性变更与配置语义陷阱对开发者每条条目都是指向源码的精确路标。结合本文给出的源码映射你可以快速把任何一条变更还原为可读、可验证的实现细节。【免费下载链接】leantimeLeantime is a goals focused project management system for non-project managers. Building with ADHD, Autism, and dyslexia in mind.项目地址: https://gitcode.com/GitHub_Trending/le/leantime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考