技术栈说明：当前 Next.js、Umi 与 FastAPI 架构

这套博客不是一个普通的文章列表，而是一个面向“纪念、整理、长期保存”的内容系统。它既要能安静地展示焦茶相关内容，也要方便后续维护：上传图片、写文章、做分类、调整首页、设置个人简介、发布短记录，都应该能在后台完成。

一、整体架构

项目分成四个主要部分：

这样拆分的好处是：前台可以专心做阅读体验，后台可以专心做编辑效率，服务端只处理数据和权限，部署层负责把它们稳定地拉起来。

二、前台做了什么

前台使用 Next.js 和 React。它的任务不是把内容简单铺出来，而是把纪念型博客需要的氛围、秩序和可读性一起呈现出来。

前台主要实现了这些能力：

1. 首页 Hero 大图：支持大图、头像、简介、站外链接、贴纸、标签和动效。
2. 滚动阈值拦截：首屏不是轻轻一滑就跳走，而是需要明显的滚动意图才进入文章区，避免误触。
3. 置顶横幅：后台设为置顶的文章，会进入首页顶部滚动横幅，最多展示 5 篇。
4. 多内容流：文章、短记录、媒体内容可以分开浏览。
5. 文章详情：支持封面、目录、Markdown、代码高亮、公式、评论、浏览量和推荐文章。
6. 分类、标签、归档：让长期积累的内容可以被重新找到。
7. 个人简介页：后台设置的名称、头像、邮箱、简介、站外链接会同步显示。

它最特别的地方，是首页不是传统博客的“列表开场”，而是先用一个完整的视觉入口承载纪念感，再把文章内容接在后面。

三、后台做了什么

后台使用 Umi 4、React 19 和 Ant Design 6。它负责把内容维护做成可操作的管理系统，并通过 Axios 访问 FastAPI。

后台主要实现了这些能力：

1. 写文章：支持标题、正文、封面、简介、分类、标签、发布时间和状态设置。
2. 写短记录：适合发布更轻量的动态、碎片、图片或补充说明。
3. 草稿：可以先保存，确认后再发布。
4. 文章管理：支持关键词搜索、文章类型筛选、状态筛选、最新排序、总浏览量排序、一周浏览量排序、热度排序和置顶优先排序。
5. 置顶操作：文章列表里可以直接点击插针图标，置顶后进入首页横幅。
6. 批量导入：支持 Markdown 或 JSON 内容导入。
7. 文件管理：支持上传、缩略图显示、目录管理、引用统计和安全删除。
8. Hero 设置：支持大图、移动端图、全息层、贴纸、标签、个人简介模块和毛玻璃/亚克力/液态玻璃效果。
9. 站点设置：支持站名、Logo、副标题、页脚、账号名称、头像、邮箱、简介和站外链接。
10. API Token：为后续扩展和外部工具调用预留入口。

后台值得表扬的地方是，它不是只做“能发布文章”，而是把博客长期维护会遇到的细节都放进去了：筛选、置顶、文件引用、头像同步、封面预览、社交图标和草稿流。

四、服务端做了什么

服务端使用 FastAPI、Python 和 MySQL，负责把前后台的数据真正保存下来。

它主要处理：

1. 登录鉴权：后台接口需要 token，公开阅读接口保持开放。
2. 文章数据：文章、短记录、草稿、状态、置顶、浏览量和评论数。
3. 分类标签：文章与分类、标签的关联关系。
4. 文件存储：上传文件写入文件表，并能通过 /uploads/... 访问。
5. 引用保护：文件管理删除图片前，会检查是否仍被文章或配置引用。
6. 统计数据：记录浏览日志，支持一周浏览量、总浏览量和热度排序。
7. 配置数据：站点信息、主题配置、个人资料都保存在数据库中。

这里的设计很适合纪念型博客，因为内容本身比代码更重要。只要数据库和上传文件在，换机器、换部署方式，都能继续恢复。

五、部署层做了什么

项目提供两种部署方式：

1. Docker Compose 一键部署：同时启动 MySQL、API、前台和后台。
2. 手动部署：适合已经有 MySQL、Python、Node.js、Nginx 环境的服务器。

同时还保留了本地开发脚本：

.\scripts\start-dev.ps1
.\scripts\health-check.ps1
.\scripts\stop-dev.ps1

这对日常维护很方便：需要改样式、改后台、改接口时，可以本地构建并做健康检查。

六、相比普通博客，独特在哪里

普通博客通常从“文章列表”开始，而这套系统更像一个纪念空间：

1. 首页是完整的 Hero 场景，不是单纯信息流。
2. 首屏滚动有阈值拦截，避免轻微滑动破坏大图沉浸感。
3. 贴纸、标签、玻璃效果、紫色光效和封面图都可以从后台调。
4. 站外平台不是写死的，可以选择小红书、抖音、B 站、X、pixiv、Instagram、Discord、Telegram、领英、Facebook、Whatsapp、threads，也支持自定义。
5. 置顶不是简单排到列表最前，而是进入首页横幅，作为重点内容展示。
6. 文件管理知道哪些图片正在被使用，减少误删风险。
7. 后台筛选不是只有“按时间”，还支持浏览量、周浏览量、热度和置顶优先。

七、值得继续保持的方向

这个项目最值得保留的，是“内容优先”的方向。技术栈不是为了堆复杂度，而是为了让焦茶相关内容更好整理、更好观看、更不容易丢。

后续如果继续迭代，可以优先做这些事情：

1. 继续修正多语言文案，让后台显示更完整。
2. 增加备份与恢复脚本，让数据库和上传文件更安全。
3. 给导入导出做更清晰的格式说明。
4. 增加前台搜索结果页，方便查找长期内容。
5. 给重要配置增加版本记录，避免误操作后无法恢复。