从 Firefly 到 BuTro：我把一个博客主题改成了自己的博客系统

为什么选择 Firefly#

BuTro 基于 CuteLeaf/Firefly 二次开发，而 Firefly 本身又建立在 Fuwari 的设计与工程基础之上。

Firefly 已经提供了很完整的博客前端体验，包括：

• Astro、Svelte 与 Tailwind CSS 组成的现代技术栈；
• 桌面端、平板和移动端响应式布局；
• 亮色、暗色与跟随系统模式；
• 自定义主题色、字体、壁纸、导航栏和页脚；
• 单侧栏、双侧栏、文章列表、网格与瀑布流布局；
• 多语言 UI、全文搜索和丰富的 Markdown 扩展；
• 动态、相册、追番、番组计划、书签导航等内容页面；
• Twikoo、Waline、Giscus、Disqus、Artalk 等第三方评论方案。

这些能力构成了 BuTro 的视觉和内容基础。我没有重新造一个博客主题，而是在尽量保持 Firefly 设计语言的前提下，补充我真正需要的管理、互动和运维能力。

本文对比时，上游仓库版本为 v6.15.8，BuTro 当前主题版本为 v6.15.6。版本号只代表各自的发布进度，下面比较的是功能方向和实际源码差异。

最核心的变化：从静态主题到自托管应用#

上游 Firefly 的主要使用方式是通过配置文件和 Markdown 管理内容，再构建为静态站点或部署到托管平台。BuTro 则启用了 Astro 的 Node 服务端输出，并在 Nginx 后运行一个持续在线的 Node 进程。

这项变化让网站可以处理登录、数据库读写、评论、邮件、审核和实时监控等动态请求。

简单来说，上游更像一套功能丰富的博客主题，BuTro 则在此基础上增加了一个完整的服务端和管理工作区。

功能差异一览#

我为它加入了一个真正能用的后台#

BuTro CMS 是这次二次开发中体量最大的一部分。

后台不是简单地把几个配置项放进表单，而是建立了用户、会话、文章、文章修订、动态、媒体、评论、设置、审计日志、友链申请和 QQ 音乐等数据结构。管理界面也按照日常使用流程划分为仪表盘、内容中心、文章、媒体、社交、音乐、站点资料和系统设置。

目前后台可以完成：

• 创建、编辑、发布、删除和恢复文章；
• 保存文章修订记录，并恢复到历史版本；
• 使用 Markdown 编辑器或富文本能力编写内容；
• 管理动态、媒体文件和页面资料；
• 将已有 Markdown 内容导入数据库；
• 管理主页、个人资料、友链、相册、项目、时间线和导航菜单；
• 查看评论、访客统计和操作审计记录；
• 区分管理员与编辑角色，限制不同账号的操作范围。

这意味着我不需要每次修改一句简介、增加一个项目或发布一篇文章都登录服务器编辑源码。Firefly 原有的文件内容依然可以使用，而新内容也可以直接在后台维护。

评论系统变成了网站自己的功能#

Firefly 上游允许接入多种成熟的第三方评论系统。BuTro 仍然保留这些适配，但默认启用了我自己实现的 QQ 邮箱评论。

访客输入 QQ 邮箱后，需要通过邮件验证码完成身份确认。评论区会读取 QQ 昵称和头像，并支持：

• 发布评论，并保留评论之间的回复关系；
• 点赞和取消点赞；
• Emoji 与颜文字选择；
• 后台隐藏、恢复和删除评论；
• 新评论自动向站长邮箱发送通知；
• 记录评论时间、页面、回复关系和必要的风控信息。

我希望评论区既保持轻量，不强迫访客注册完整账号，又能比完全匿名评论多一层真实性和滥用防护。

友链申请不再依靠私信#

上游的友链主要由站长编辑配置文件维护。BuTro 在友链页面增加了自助申请表单，申请者可以填写站点名称、描述、网址、头像和联系邮箱。

提交后，服务器会保存申请并发送审核邮件。邮件内包含完整站点资料，以及“同意”和“拒绝”入口。审核链接会先打开确认页，只有再次确认后才会执行操作；通过的申请会自动加入友链数据。

这一流程还加入了提交频率限制、隐藏字段、防重复申请、审核令牌和有效期控制。它减少了来回沟通，也避免邮件中的链接被意外点击后直接修改数据。

从音乐播放器到 QQ 音乐管理#

Firefly 已经拥有很漂亮的前端音乐播放器，BuTro 在此基础上补上了音乐数据的管理端。

后台可以通过二维码维护 QQ 音乐账号，创建和同步歌单，并管理歌曲元数据。前台播放列表不再只是写死在配置文件里，而是可以从服务端读取。歌曲链接和歌词也由站内接口统一处理，避免把内部音乐服务直接暴露到公网。

这部分改造没有替换 Firefly 的播放器交互，而是让播放器背后的数据来源更适合长期维护。

新增数据分析和服务器监控#

BuTro 接入了自托管 Umami。除了页面上的浏览量，侧边栏还可以显示总浏览量、访问次数和访客数，后台则提供趋势、来源、设备、浏览器、地区和热门页面等统计信息。

仪表盘中还加入了服务器状态监控，包括：

• CPU 使用率与系统负载；
• 内存使用量；
• 磁盘空间；
• 系统与 Node 进程运行时间；
• 服务健康状态和异常级别。

当指标持续异常时，系统可以向站长邮箱发送告警，并且后台提供独立开关控制是否启用邮件提醒。它不能代替专业监控平台，但对一台个人博客服务器来说，已经能覆盖最常见的运行状态检查。

页面和侧边栏也更像我自己的站点#

除了后台和服务端，我也调整了不少访客能够直接看到的内容。

首先是品牌层面的修改：站点名称改为 BuTro，使用自己的 Logo、Favicon、域名、主题色和站点描述。导航栏增加“其他”菜单，并加入“项目”和“时间线”两个页面。

项目页可以按照网页、移动端、桌面端等类型筛选，展示项目状态、技术栈、演示地址和代码仓库。时间线则用于整理教育、工作、项目和个人成就，让博客不只记录文章，也能记录经历。

侧边栏新增或重做了以下组件：

• 今日一言，并修正来源信息显示；
• 根据站点配置城市查询的天气信息；
• 问候语与实时时钟；
• Umami 访客统计；
• 年、月、周、日进度和节日倒计时；
• 更适合当前布局的站点信息与精确运行时长。

这些组件都沿用网站主题变量，在亮暗模式、不同主题色和移动端布局下保持一致，而不是单独拼接一块风格不同的卡片。

工程层面的改造#

为了支撑这些功能，BuTro 的代码结构也发生了明显变化。

服务端按控制器、服务、仓储和数据表拆分，使用 Drizzle 操作 SQLite；请求参数通过 Schema 校验，管理接口统一处理登录会话、角色权限、CSRF 和来源校验。评论、登录、验证码和友链申请均有数据库限流，上传文件会同时检查大小、MIME 类型和文件头。

Markdown 内容在服务端渲染时会清理不安全标签和属性，SMTP、Umami 和 QQ 音乐凭据不会直接返回给前端，生产环境错误也不会把服务器堆栈暴露给访客。

这些工作在页面上并不显眼，却决定了动态功能能否稳定地长期运行。

哪些东西我选择保留#

二次开发并不意味着所有东西都要重写。

BuTro 继续使用 Firefly 的整体布局、主题系统、文章展示、响应式设计、Markdown 生态、动画效果和大量基础组件。Astro 与 Svelte 的组合也非常适合这种“内容页面以服务端渲染为主、局部功能需要交互”的网站。

我的改造重点始终是补齐个人使用中缺少的部分，而不是改变 Firefly 本身清新、克制的视觉方向。

写在最后#

BuTro 从 2026 年 8 月 6 日开始运行。它现在已经可以承担内容发布、评论互动、友链审核、音乐管理、数据分析和基础运维，但仍然会继续调整。

后续我希望继续完善移动端体验、后台内容管理、备份恢复和服务器安全，也会持续关注 Firefly 上游的更新。能够站在成熟开源项目的基础上继续搭建自己的东西，是这次建站过程中最有价值的部分。

感谢 Firefly 与 Fuwari 的作者和贡献者。BuTro 的变化属于二次开发，而它最初的设计、体验与灵感，依然来自这些优秀的开源项目。

• BuTro：https://buchuo.cloud
• BuTro 仓库：https://github.com/ackingchen/ButroBlog
• Firefly 上游：https://github.com/CuteLeaf/Firefly
• Fuwari 上游：https://github.com/saicaca/fuwari