1. Teanary V1.2.1旧路线的终点也是一个重要的存档点1.1 Teanary 到底是个什么项目Teanary 是一个面向个人与小型团队的自托管知识管理工具主打笔记、文档、任务三合一的轻量协作体验。它不需要单独的客户端浏览器打开就能用数据掌握在自己手里部署只需要一台能跑 PHP 的服务器。很多注重隐私的团队拿它替代 Notion 和语雀的私有化方案也有不少开发者把 Teanary 当成学习 Laravel 与 FilamentPHP 组合的实战项目来研究。V1.2.1 是 Teanary 在 FilamentPHP 技术路线上的最后一次正式版本。这句话包含了两层信息第一基于 Filament 的功能开发已经收尾后续不再新增基于旧架构的大功能第二维护团队会把剩余精力集中在安全修复和稳定性上同时已经在推进新架构。对普通用户来说V1.2.1 就是你在旧路线上的最佳落点它经过了 v1.2.0 功能开发、多个候选版本验证后的迭代修正把已知的兼容性问题都处理掉了再往后旧路线只会做必要的安全修复不再有这种规模的打磨。这篇文章适合三类人阅读正在使用 Teanary、还没决定要不要升级的用户在做技术选型、想了解 FilamentPHP 实际项目表现的 Laravel 开发者以及那些同样在纠结要不要把一个框架用到最后一版再切换的独立开发者。我尽量把升级动作、踩坑记录和背后的决策逻辑都讲透让你看完能直接照着做。1.2 为什么最后一个 FilamentPHP 版本值得你关注一个稳定版本被明确标记为最后一个基于某框架的版本在开源项目里通常不是坏消息而是项目走向成熟的标志。它意味着团队在战略上想清楚了旧架构能够交付的极限在哪里新架构要解决什么问题。从用户视角看这个标记最大的价值是确定性。你不再需要每隔几个月就担心后台框架升级带来的界面变动因为这条路已经封板了。V1.2.1 的界面、行为、数据格式就是旧架构的最终形态你可以放心地在这个版本上规划自己的使用习惯甚至写自动化脚本去对接它的 API。从这个意义上说最后一个稳定版反而比最新版本更适合作为长期运行的基线。从开发者视角看这个标记也是一份学习材料。一个框架的终点版本往往包含这个团队对框架的最终理解怎么组织 Resource、怎么处理复杂表单、怎么优化列表查询。V1.2.1 的代码里有很多值得反复看的细节我后面会专门拆开讲。2. FilamentPHP 在 V1.2.1 里的戏份有多重2.1 当初为什么选 FilamentPHPFilamentPHP 是 Laravel 生态里目前最活跃的管理后台框架之一基于 TALL 技术栈构建也就是 Tailwind CSS、Alpine.js、Laravel、Livewire 四件套。它提供表单构建器、表格构建器、资源管理器、通知系统、全局搜索这些开箱即用的能力开发者不需要写一行 Vue 或 React就能搭出一套完整后台。Teanary 早期选 Filament核心原因是开发速度。一个两个人组成的小团队要在几个月内同时交付笔记编辑器、协作空间、标签系统和用户管理如果纯手写后台界面工作量会翻好几倍。Filament 的 Resource 机制让开发者只需要定义一个模型和对应的 Resource 类增删改查页面就自动生成而且自带权限控制、搜索筛选、批量操作这些高频能力。用一个比喻帮助你理解Filament 之于 Laravel就像精装修交付之于毛坯房。你不需要自己拉水电、刷墙、装门只需要把家具摆好、按生活习惯做局部改造就能入住。对于预算有限的产品早期阶段这是非常聪明的选择。2.2 V1.2.1 里 Filament 接管了哪些核心模块在 V1.2.1 中Filament 主要负责三块内容管理后台用户、团队、空间、标签的增删改查与批量操作界面。文档与资源管理笔记列表的表格视图、批量移动与删除、附件文件管理。权限与设置页面角色分配、空间配置、通知偏好设置。这些模块在 V1.2.1 里已经非常稳定。举个例子管理后台的用户列表支持按活跃度排序、按团队筛选、批量禁用这些交互全部由 Filament 的表单与表格构建器驱动。我们在一个约五万条用户数据的测试环境里观察列表页加载时间大约在 300ms 左右配合 Filament 的自带缓存机制表现相当不错。2.3 混合架构的边界在哪里需要澄清的是Filament 并不是 Teanary 的全部。它的强项是管理后台而不是用户前台。Teanary 的笔记编辑器和阅读视图从一开始就是自研组件没有依赖 Filament。这种后台用 Filament、前台自研的混合架构是很多 Laravel 项目的常见形态。这种边界的划分很关键。笔记编辑器需要实时渲染 Markdown、支持代码块、拖拽排序这些交互密集型场景用 Livewire 的服务端渲染会很笨重而用户管理、标签管理这类低频次、表单化的场景用 Filament 反而效率极高。把合适的工具放在合适的位置是这套架构能撑到 V1.2.1 还不觉得吃力的重要原因。3. V1.2.1 更新内容盘点哪些改动真正影响你3.1 功能新增导出、标签、邀请链接V1.2.1 在功能层面不是大动干戈但有几个点很实用。第一个是空间导出格式升级原来只支持 Markdown 打包导出现在增加了Markdown 加附件目录的一体化导出导出的目录结构与 Teanary 内部存储保持一致方便你在本地继续整理归档。第二个是标签批量管理。在标签管理页可以直接选中多个标签进行合并、重命名、删除以前只能一个个操作整理大批量标签时特别费劲。这个功能提了很久终于在 V1.2.1 里通过 Filament 的表格批量操作机制实现了。第三个是团队邀请链接的灵活控制。现在可以自定义邀请链接的过期时间与最大使用次数避免链接被转传滥用。对小型团队的协作场景来说这算是补上了安全性的一个关键短板。3.2 稳定性修复与性能优化稳定性方面V1.2.1 修复了几个老问题。Filament 表格导出 CSV 时中文文件名乱码的问题这次彻底解决了统一走 UTF-8 BOM 编码在 PHP 8.3 环境下Livewire 组件偶发出现 CSRF Token 过期的问题也做了处理改进了轮询鉴权逻辑。性能优化是这次更新里我最看重的部分。首页仪表盘原来的查询策略有 6 次 N1 查询这次合并成了 2 次 join 查询。如果你的笔记超过一万条旧版本打开仪表盘可能要等两秒升级后基本秒开。这种体感差异比任何功能列表都有说服力。需要注意的是性能优化依赖数据库索引。升级前请确认notes表的space_id和updated_at字段有组合索引否则 V1.2.1 的 join 查询在大数据量下反而可能更慢。这个问题在官方文档里提了一句但很多人会忽略。3.3 版本兼容矩阵与依赖说明V1.2.1 对运行环境的要求是 PHP 8.2 以上、Composer 2.x、Laravel 11 或 12。它依赖的 Filament 版本被锁定在 v3.2 系列Livewire 锁定在 v3.x。我在实际测试中发现PHP 8.1 环境下虽然也能启动但在 Filament 表格的导出功能里会出现序列化异常所以建议不要恋战旧 PHP 版本。以下是建议的依赖快照便于你对照自己的 composer.json 检查依赖包版本要求说明PHP 8.2推荐 8.3laravel/framework^11.0 | ^12.0已适配两代框架filament/filament^3.2锁定主版本不要装 v4livewire/livewire^3.x与 Filament v3 配套spatie/laravel-permission^6.0权限管理核心包4. 告别 FilamentPHP真实原因与后续方向4.1 产品形态与框架能力之间的裂缝说实话做出放弃 Filament 的决定并不轻松。Filament 帮助我们完成了从 0 到 1 的跨越V1.2.x 系列的稳定运营也证明这套架构是可靠的。那为什么还要走核心原因有两个。第一个是前台体验的连续性。Teanary 的定位是知识管理与协作工具用户一天里九成时间都在编辑器、阅读视图和移动端上而不是在管理后台里。团队希望把更多代码资源投入到编辑器体验、实时同步、API 能力建设上而不是持续为后台框架的版本升级和样式定制付成本。第二个原因是技术路线的统一。Filament 基于 Livewire 的服务端渲染模式在低交互的管理页面里体验很好但 Teanary 的产品规划是做一个更轻、更快、离线友好的客户端这就需要前后端彻底解耦让 API 成为唯一的数据通道。继续在 Filament 上加功能等于同时维护两套交互逻辑长期来看成本会越来越高。4.2 新架构长什么样子新的 Teanary 会把编辑器端和管理端统一到一个新的前端框架上后端 Laravel 仍然保留但改成纯 API 模式。管理后台将换成自定义界面通过 RESTful API 与后端通信不再依赖 Livewire 的页面刷新机制。这个方向在 Laravel 生态里越来越常见官方文档也已经把 SPA 模式作为推荐方案之一。对于想要离线支持、请求合并、局部渲染优化这类体验的团队来说解耦几乎是必然的选择。V1.2.1 的 API 端点会在新架构里保留大部分只是响应格式会做一次规范化升级预计以向后兼容的方式发布。4.3 给 Filament 用户的一句实话如果你也在用 Filament看到某个项目弃用 Filament的新闻不必焦虑。Filament 非常适合内部工具、数据管理后台、MVP 产品验证这类场景它的问题不是不好而是不适合所有前台场景。判断是否迁移只看你的产品形态不要跟风。我见过很多团队在后台框架上频繁换马最后什么都没沉淀下来。更务实的做法是像 Teanary 这样先用 Filament 快速验证产品价值等用户规模和市场反馈告诉你下一步往哪走再决定要不要重写前台。框架只是工具产品目标才是你真正要伺候的对象。5. 升级到 V1.2.1 的操作指南5.1 升级前的备份与检查清单升级前请务必做好三件事。第一备份数据库和 storage 目录尤其是storage/app/private下的笔记附件很多人容易漏掉这个目录。第二确认 PHP 版本在 8.2 以上Composer 2.x 环境正常。第三在测试环境先跑一遍不要直接在线上原地升级。我习惯的做法是先把生产环境的数据库导出一份匿名化副本放到本地搭建一个完全一致的测试环境跑完整个升级流程并验证关键功能再排期执行线上升级。这个流程虽然多花半小时但能省掉很多半夜被叫醒的麻烦。5.2 一步步完成升级具体升级步骤我列一下照着做就行# 1. 拉取最新代码 git pull origin v1.2.1 # 2. 更新依赖 composer install --no-dev --prefer-dist # 3. 执行数据库迁移 php artisan migrate --force # 4. 清理缓存 php artisan optimize:clear # 5. 重新发布 Filament 静态资源 php artisan filament:assets # 6. 重启队列如果用 Redis 队列 php artisan queue:restart如果你使用的是sync队列驱动第 6 步可以省略但记得重启 PHP-FPM 让新代码生效。整个升级过程正常情况下不到五分钟非常轻量。验证时重点看三个页面管理后台的用户列表是否能正常筛选、笔记编辑器是否能正常保存、空间导出功能是否打包完整。这三关过了基本就稳了。5.3 升级后的验证与回滚方案即使测得很充分线上还是可能出现意外。所以我会在验证清单里额外加一条记录当前版本的数据库迁移批次号。php artisan migrate:status如果升级后发现问题需要回滚执行php artisan migrate:rollback --step1把迁移回退同时把代码切回上一个版本再用备份恢复数据。Teanary 的迁移都是向下兼容设计回滚通常不会导致数据丢失但依赖的 Filament 版本如果变了要一并把composer.lock也切回去。6. 常见问题与排查技巧实录6.1 六类高频问题速查表我在 V1.2.1 的测试和用户反馈里整理了六个高频问题先看速查表现象可能原因解决办法升级后白屏、样式丢失Filament 静态资源未发布执行php artisan filament:assets权限修改不生效权限缓存未清除执行php artisan permission:cache-reset表单字段渲染异常Filament 依赖冲突锁定filament/filament:^3.2后重装依赖表格导出中文乱码服务器缺 mbstring 扩展安装扩展并重启 PHP-FPM仪表盘加载慢缺复合索引给notes表加space_id updated_at索引队列任务堆积队列版本不匹配执行php artisan queue:restart并检查 worker 日志6.2 进阶排查思路如果遇到速查表里没有的问题我的习惯是先看日志再看请求。Teanary 的运行时日志在storage/logs/laravel.log升级后如果发现异常优先看这个文件有没有堆栈信息。另一个容易忽略的点是 Composer 的 lock 文件。升级后如果出现奇怪的类不存在错误比如Class Filament\... not found九成是因为本地 PHP 版本差异导致 Composer 重新解析了依赖。解决办法是把composer.lock切回升级前的版本重新执行composer install对比 hash 确认没有意外变更。6.3 从 V1.2.1 走向新架构的过渡建议虽然 V1.2.1 是旧路线的终点你也不需要立刻搬家。在决定升级到新架构之前有两个动作可以先做起来。第一整理附件目录。新架构对附件做了一级抽象如果你现在就把笔记附件从零散空间目录整理成统一结构迁移时会少踩很多坑。第二梳理你正在使用的 API 和 Webhook。新架构会兼容 V1.2.1 的核心端点但部分管理类接口会调整你现有的自动化脚本需要对照新的 API 文档做适配。我个人的体会是一个框架的终点版本往往比起点版本更有学习价值。V1.2.1 把所有基于 Filament 的实现沉淀到了最稳定的形态你去看它的代码能学到一套非常标准的 Laravel 与 Filament 实践而团队决定离开 Filament 的决策过程同样值得你在自己项目里反复体会。技术选型永远服务于产品形态而不是反过来。如果你也在纠结要不要换框架、要不要重构我的建议很简单先把当前版本打磨到无可挑剔再迈下一步。V1.2.1 就是这个无可挑剔的存档点安心用它然后保持关注。