119 lines
5.8 KiB
Plaintext
119 lines
5.8 KiB
Plaintext
# 轻量级混合架构博客系统 (暂定名：NovaBlog) 需求及开发文档
|
||
|
||
## 1. 项目概述
|
||
|
||
本项目旨在开发一款面向程序员和极客的极轻量级博客系统。针对目前市面上静态博客（如 Hexo）排版能力有限、缺乏动态交互，以及动态博客（如 Halo、WordPress）过度商业化、架构臃肿、资源占用高的问题，本项目提出一种**“静态渲染 + 轻量级微服务”**的解耦架构。
|
||
|
||
**核心目标：**
|
||
|
||
* **极致的排版自由：** 原生支持 MDX，允许在 Markdown 中直接嵌入前端组件（JS/HTML 动效）和 Typst 复杂学术排版。
|
||
* **优雅的动态交互：** 支持用户注册登录、评论、点赞，但核心页面保持纯静态。
|
||
* **低资源占用：** 确保应用能在 2C1G 甚至更低配置的云服务器上稳定运行，杜绝周期性 CPU 满载问题，同时支持 Docker 容器化，方便部署在个人 NAS 上。
|
||
* **现代化的主题系统：** 基于组件化思想构建主题，实现积木式的页面组合，降低主题开发和迁移成本。
|
||
|
||
---
|
||
|
||
## 2. 核心架构设计
|
||
|
||
系统采用前后端完全解耦的架构，前端负责内容解析与预渲染，后端仅作为无状态的数据 API 提供支持。
|
||
|
||
### 2.1 表现层 (前端 / Astro)
|
||
|
||
基于 Astro 框架构建，利用其 Islands Architecture（群岛架构）特性：
|
||
|
||
* **构建时 (Build Time)：** 将 `.md` 和 `.mdx` 文件（包含 Typst 代码块）统一编译为纯静态的 HTML/CSS。
|
||
* **运行时 (Client Side)：** 大部分页面为 Zero-JS，仅在“评论区”、“点赞按钮”等特定“岛屿”组件上挂载 JavaScript 并发起按需 API 请求。
|
||
|
||
### 2.2 交互层 (后端微服务 / Micro API)
|
||
|
||
一个极轻量的后端 API 服务，专门处理动态请求。为了绝对的轻量化，避免 JVM 或臃肿 Node 框架带来的内存和 CPU 开销，采用轻量级语言或极简框架开发，搭配本地文件型数据库（SQLite）。
|
||
|
||
### 2.3 部署形态
|
||
|
||
* **前端产物：** 编译后的纯静态文件可托管于任何 CDN、Nginx 容器或 GitHub Pages。
|
||
* **后端 API：** 打包为轻量级 Docker 镜像，暴露特定端口，通过 Nginx 反向代理提供服务。可轻松接入虚拟局域网作为服务节点。
|
||
|
||
---
|
||
|
||
## 3. 功能需求详细说明
|
||
|
||
### 3.1 内容管理模块 (基于文件系统)
|
||
|
||
* **本地化撰写：** 以 `src/content/blog/` 目录为核心，通过标准 Markdown 和 Frontmatter (YAML) 管理元数据（标题、日期、标签、分类）。
|
||
* **MDX 混合解析：** * 支持标准的 Markdown 语法。
|
||
* 支持直接在文章中 `import` 并使用 Vue/React/原生 JS 组件，实现图表、可交互动画等丰富排版。
|
||
|
||
|
||
* **Typst 渲染支持：** 封装 `<TypstBlock />` 组件，在构建阶段调用 Typst 编译器将数学公式和复杂排版渲染为高质量 SVG 嵌入页面。
|
||
|
||
### 3.2 动态交互模块 (API 驱动)
|
||
|
||
* **用户鉴权：** * 管理员身份认证（用于后台极简面板或特定 API 调用）。
|
||
* 普通用户注册/登录（支持邮箱验证或 OAuth 第三方登录，如 GitHub）。
|
||
* 基于 JWT (JSON Web Token) 的无状态鉴权。
|
||
|
||
|
||
* **评论系统：**
|
||
* 支持文章下的多级嵌套评论。
|
||
* 支持 Markdown 基础语法解析。
|
||
* 前端组件支持 `client:visible` 懒加载，仅当用户滚动到评论区时才加载请求逻辑。
|
||
|
||
|
||
* **点赞系统：**
|
||
* 基于文章 ID 和用户 ID (或访客 IP Hash) 的防刷点赞接口。
|
||
|
||
|
||
|
||
### 3.3 主题与布局系统 (组件化)
|
||
|
||
* **Layout 核心：** 提供基础的 `BaseLayout.astro`，定义全局的 Header、Footer 和 SEO Meta 标签。
|
||
* **CSS 变量换肤：** 样式层全面采用 CSS Variables，通过切换变量配置文件即可实现黑白模式和主题色彩切换。
|
||
* **组件插槽 (Slots)：** 页面主体留白，通过 Astro 的 `<slot />` 机制允许不同文章复用或重写特定的页面布局。
|
||
|
||
---
|
||
|
||
## 4. 技术选型建议
|
||
|
||
### 4.1 前端 (静态生成与渲染)
|
||
|
||
* **核心框架：** Astro (提供极速构建、MDX 支持和内容集合强校验)。
|
||
* **组件库生态：** Vue 3 或 React (仅用于编写需要动态交互的“岛屿”组件，如评论框)。
|
||
* **样式方案：** Tailwind CSS 或纯 CSS 变量 (保持轻量)。
|
||
|
||
### 4.2 后端 (动态 API 提供)
|
||
|
||
为了解决小鸡（如 2C1G 配置）资源受限问题，推荐以下两种方案之一：
|
||
|
||
* **方案 A (性能极致 - 推荐)：** **Go 语言 (Gin/Fiber) + SQLite**。编译为二进制文件运行，内存常驻极低（通常十几 MB），CPU 开销极小，高并发无压力。
|
||
* **方案 B (开发极速)：** **Node.js (Hono 或 Fastify) + SQLite + Prisma (ORM)**。比传统的 NestJS 或 Express 轻量得多，生态契合度高。
|
||
|
||
---
|
||
|
||
## 5. 阶段开发规划 (Roadmap)
|
||
|
||
### Phase 1: 核心静态引擎构建 (MVP)
|
||
|
||
* [ ] 初始化 Astro 项目，配置 Content Collections 数据校验。
|
||
* [ ] 编写基础的博客 Layout (主页、文章列表页、文章详情页)。
|
||
* [ ] 实现 MDX 支持，编写首个包含动态 HTML 交互组件的测试文章。
|
||
* [ ] 封装 Typst 渲染组件，打通构建流。
|
||
|
||
### Phase 2: 轻量 API 服务开发
|
||
|
||
* [ ] 搭建后端服务项目，配置 SQLite 数据库和 ORM 模型 (Users, Posts_Meta, Comments)。
|
||
* [ ] 实现 JWT 登录与鉴权接口。
|
||
* [ ] 实现评论的 CRUD 接口和文章点赞接口。
|
||
* [ ] 后端 Docker 化封装。
|
||
|
||
### Phase 3: 前后端联调与交互组件
|
||
|
||
* [ ] 在 Astro 中使用 UI 框架 (Vue/React) 开发独立于静态页面的评论区组件。
|
||
* [ ] 联调跨域 API，处理 Loading、Error 等异步状态。
|
||
* [ ] 实现文章页的点赞按钮交互。
|
||
|
||
### Phase 4: 部署与测试
|
||
|
||
* [ ] 前端打包测试 (`astro build`)，验证打包后的 JS 产物大小。
|
||
* [ ] 后端部署至云服务器或 NAS 节点，配置 Nginx 反向代理。
|
||
* [ ] 压力测试与 CPU 监控，确保资源占用在合理阈值内。
|