轻博客系统需求文档

1. 项目概述

开发一个轻量级的个人博客系统，通过 Markdown 文件管理内容，使用图片URL链接，无需数据库，易于部署和维护。

前端：

Next.js（React 框架）
TailwindCSS（样式）
React-Query（数据获取）
next-mdx-remote（Markdown 渲染）
prism.js（代码高亮）

后端：

Express.js（后端框架）
gray-matter（解析 Markdown 元数据）
express-rate-limit（限流）
jsonwebtoken（认证）

2. 核心功能

2.1 前端界面

主内容区
- 文章列表（支持分页）
- 文章详情页面
- Markdown 文章渲染
- 代码高亮
侧边栏组件
- 搜索框
- 标签云
- 分类导航
- 最近文章
- 个人简介

2.2 后台管理

简单的登录验证
文章管理
- 在线 Markdown 编辑器
  - 实时预览功能
  - 工具栏快捷操作
  - 图片URL快速插入
  - 自动保存草稿
  - 快捷键支持
- 文章预览
- 文章发布/草稿切换
- 文章分类和标签管理
- 图片URL链接管理
分类管理
- 创建/编辑/删除分类
- 分类描述
- 分类排序
- 分类统计
标签管理
- 创建/编辑/删除标签
- 标签描述
- 标签颜色设置
- 标签使用统计
侧边栏管理
- 组件显示/隐藏
- 组件顺序调整
- 个人简介编辑
系统设置
- 基础设置
  - 网站标题
  - 网站描述
  - 网站关键词
  - 网站图标
  - 版权信息
- 个性化设置
  - 主题颜色
  - 字体设置
  - 布局选择
  - 代码高亮主题
- 文章设置
  - 每页显示文章数
  - 文章URL格式
  - 默认分类
  - 默认标签
- SEO设置
  - Meta描述
  - Meta关键词
  - 站点地图
  - robots.txt
- 评论设置
  - 是否开启评论
  - 评论系统选择
  - 评论审核
- 安全设置
  - 密码修改
  - 登录IP限制
  - API访问限制
  - 图片URL域名白名单
- 备份设置
  - 自动备份
  - 备份周期
  - 备份保留数量

2.3 文章功能

基于文件的全文搜索
标签筛选
分类筛选
文章目录导航
基础统计信息

3. 技术方案

3.1 后端技术栈

框架：Express.js
语言：JavaScript
存储：文件系统
缓存：内存缓存
API：RESTful

3.2 文件存储

使用 Markdown 文件存储文章
文章元数据存储在文件头部
图片采用外部URL链接
简单的文件目录组织

分类和标签配置文件：

// content/config/categories.json
{
  "categories": [
    {
      "id": "tech",
      "name": "技术",
      "description": "技术相关文章",
      "order": 1,
      "count": 10
    },
    {
      "id": "life",
      "name": "生活",
      "description": "生活随笔",
      "order": 2,
      "count": 5
    }
  ]
}

// content/config/tags.json
{
  "tags": [
    {
      "id": "javascript",
      "name": "JavaScript",
      "description": "JavaScript相关",
      "color": "#f7df1e",
      "count": 8
    },
    {
      "id": "react",
      "name": "React",
      "description": "React框架",
      "color": "#61dafb",
      "count": 5
    }
  ]
}

3.3 性能优化

文件缓存
静态文件优化
按需加载

4. 目录结构

├─src                     # 源代码目录
│  ├─articles            # 文章相关功能
│  │  ├─dto            # 数据传输对象
│  │  ├─services       # 业务逻辑
│  │  └─controllers    # 控制器
│  │
│  ├─sidebar            # 侧边栏相关
│  │  ├─dto           # 数据传输对象
│  │  └─services      # 侧边栏服务
│  │
│  ├─auth               # 认证相关
│  │  ├─guards         # 认证守卫
│  │  └─services       # 认证服务
│  │
│  ├─common             # 公共功能
│  │  ├─filters        # 异常过滤器
│  │  └─utils          # 工具函数
│  │
│  ├─config             # 配置文件
│  │  └─app.config.ts  # 应用配置
│  │
│  └─main.ts            # 入口文件
│
├─content               # 内容目录
│  ├─posts             # 文章
│  ├─drafts            # 草稿
│  └─sidebar           # 侧边栏配置
│
├─public               # 静态资源
│  └─uploads           # 上传文件

5. 文章格式和编写指南

5.1 文章目录结构

content/
  ├─posts/                    # 已发布文章
  │  ├─2024/                 # 按年份归档
  │  │  ├─03/               # 按月份归档
  │  │  │  └─article-1.md   # 文章文件
  │  │  └─04/
  │  └─2023/
  └─drafts/                  # 草稿文章
     └─draft-1.md

5.2 文章元数据格式

---
title: 文章标题
date: 2024-03-20
update_date: 2024-03-21    # 可选，更新日期
category: 技术
tags: [web, blog]
status: published          # published/draft
excerpt: 文章摘要
coverImage: https://example.com/image.jpg  # 封面图片URL
slug: my-first-post        # URL友好的文章标识
author: 作者名称           # 可选
---

文章正文...

5.3 文章编写规范

图片引用

![图片描述](https://example.com/image.jpg "图片标题")

代码块

```python
def hello():
    print("Hello World")

链接引用

[链接文字](https://example.com "链接标题")

文章结构

# 文章标题

## 1. 一级标题
正文内容...

### 1.1 二级标题
- 列表项1
- 列表项2

## 2. 下一个一级标题

5.4 发布流程

创建文章
- 点击"新建文章"按钮
- 在在线编辑器中：
  - 填写文章标题
  - 选择分类和标签
  - 上传或输入封面图片URL
  - 编写文章内容
- 系统自动保存为草稿
编辑文章
- 使用在线 Markdown 编辑器
- 左侧编辑，右侧实时预览
- 工具栏提供常用功能：
  - 标题
  - 加粗/斜体
  - 列表
  - 链接
  - 图片
  - 代码块
- 图片URL管理面板：
  - 历史图片URL快速插入
  - 新增图片URL
  - URL有效性检查
预览文章
- 实时预览窗口查看效果
- 模拟实际显示效果
- 响应式预览（桌面/平板/手机）
- 检查图片显示
- 确认代码高亮
发布文章
- 点击"发布"按钮
- 确认文章信息
- 选择立即发布或定时发布
- 系统自动：
  - 生成 slug（如未指定）
  - 创建对应年月目录
  - 更新文章索引
更新文章
- 在文章列表中选择要编辑的文章
- 进入在线编辑器
- 修改内容后点击"更新"
- 系统自动添加更新时间

5.5 在线编辑器快捷键

Ctrl + S  : 保存草稿
Ctrl + P  : 预览文章
Ctrl + B  : 加粗
Ctrl + I  : 斜体
Ctrl + K  : 插入链接
Ctrl + L  : 插入图片
Ctrl + 1-6: 插入对应级别标题
Ctrl + M  : 插入代码块

5.6 工具栏功能

文本格式化
- 标题（H1-H6）
- 加粗/斜体/删除线
- 引用
- 代码块
插入功能
- 图片URL
- 链接
- 分割线
- 表格
列表功能
- 无序列表
- 有序列表
- 任务列表
其他功能
- 撤销/重做
- 全屏编辑
- 预览切换
- 帮助文档

6. API 设计

6.1 文章接口

GET /api/articles - 获取文章列表
GET /api/articles/:id - 获取文章详情
POST /api/articles - 创建文章
PUT /api/articles/:id - 更新文章
DELETE /api/articles/:id - 删除文章
POST /api/articles/draft - 保存草稿
GET /api/articles/draft/:id - 获取草稿
POST /api/articles/:id/publish - 发布文章
POST /api/articles/preview - 预览文章内容

6.2 分类接口

GET /api/categories - 获取分类列表
POST /api/categories - 创建分类
PUT /api/categories/:id - 更新分类
DELETE /api/categories/:id - 删除分类
GET /api/categories/:id/articles - 获取分类下的文章
PUT /api/categories/order - 更新分类排序
GET /api/categories/stats - 获取分类统计信息

6.3 标签接口

GET /api/tags - 获取标签列表
POST /api/tags - 创建标签
PUT /api/tags/:id - 更新标签
DELETE /api/tags/:id - 删除标签
GET /api/tags/:id/articles - 获取标签下的文章
GET /api/tags/stats - 获取标签使用统计
PUT /api/tags/batch - 批量更新标签

6.4 图片URL接口

GET /api/images - 获取图片URL列表
POST /api/images - 添加图片URL
DELETE /api/images/:id - 删除图片URL
GET /api/images/validate - 验证图片URL有效性
GET /api/images/search - 搜索图片URL
POST /api/images/batch - 批量添加图片URL
GET /api/images/recent - 获取最近使用的图片URL

6.5 侧边栏接口

GET /api/sidebar/config - 获取侧边栏配置
PUT /api/sidebar/config - 更新侧边栏配置
GET /api/sidebar/tags - 获取标签云数据
GET /api/sidebar/categories - 获取分类数据
GET /api/sidebar/recent - 获取最近文章

6.6 系统接口

POST /api/auth/login - 登录
GET /api/system/info - 系统信息
PUT /api/system/settings - 更新设置
GET /api/system/settings - 获取设置
POST /api/system/backup - 创建备份
GET /api/system/backups - 获取备份列表
POST /api/system/restore - 恢复备份
PUT /api/system/password - 修改密码
GET /api/system/stats - 系统统计信息

6.7 系统配置文件格式

// content/config/system.json
{
  "site": {
    "title": "我的博客",
    "description": "个人技术博客",
    "keywords": ["博客", "技术", "生活"],
    "favicon": "https://example.com/favicon.ico",
    "copyright": "© 2024 我的博客"
  },
  "theme": {
    "primaryColor": "#4a90e2",
    "fontFamily": "Microsoft YaHei",
    "layout": "sidebar-right",
    "codeTheme": "github-dark"
  },
  "article": {
    "pageSize": 10,
    "urlFormat": "YYYY/MM/slug",
    "defaultCategory": "未分类",
    "defaultTags": []
  },
  "seo": {
    "metaDescription": "个人技术博客，分享技术文章和生活感悟",
    "metaKeywords": ["博客", "技术博客"],
    "generateSitemap": true,
    "robotsTxt": "User-agent: *\nAllow: /"
  },
  "comment": {
    "enable": true,
    "system": "giscus",
    "needAudit": false
  },
  "security": {
    "loginIpWhitelist": [],
    "apiRateLimit": 100,
    "allowedImageDomains": [
      "imgur.com",
      "cloudinary.com"
    ]
  },
  "backup": {
    "autoBackup": true,
    "backupInterval": "7d",
    "keepBackups": 5
  }
}

7. 安全要求

基础的身份认证
XSS 防护
URL验证和过滤
图片URL安全检查

菜单

”新建”轻量博客

轻博客系统需求文档

1. 项目概述

2. 核心功能

2.1 前端界面

2.2 后台管理

2.3 文章功能

3. 技术方案

3.1 后端技术栈

3.2 文件存储

3.3 性能优化

4. 目录结构

5. 文章格式和编写指南

5.1 文章目录结构

5.2 文章元数据格式

5.3 文章编写规范

5.4 发布流程

5.5 在线编辑器快捷键

5.6 工具栏功能

6. API 设计

6.1 文章接口

6.2 分类接口

6.3 标签接口

6.4 图片URL接口

6.5 侧边栏接口

6.6 系统接口

6.7 系统配置文件格式

7. 安全要求

评论