博客系统 API 使用说明

本文档详细介绍了博客系统的所有 API 端点，包括请求方法、参数、响应格式和使用示例。

认证 API

1. 用户登录

端点: POST /api/auth/login

描述: 管理员登录接口

请求体:

{
  "username": "admin",
  "password": "your_password"
}

响应:

{
  "success": true,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin"
    }
  }
}

示例:

curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}'

2. 用户登出

端点: POST /api/auth/logout

描述: 管理员登出接口

需要认证: 是

响应:

{
  "success": true,
  "message": "登出成功"
}

公开 API

1. 获取文章列表

端点: GET /api/posts

描述: 获取已发布的文章列表，支持分页和搜索

查询参数:

page (可选): 页码，默认 1
limit (可选): 每页数量，默认 10
search (可选): 搜索关键词

响应:

{
  "success": true,
  "message": "获取文章列表成功",
  "data": {
    "posts": [
      {
        "id": 1,
        "title": "文章标题",
        "slug": "article-slug",
        "excerpt": "文章摘要",
        "author": "作者名",
        "category": "技术",
        "tags": "Next.js,React",
        "cover_image_url": "https://...",
        "status": "published",
        "views": 100,
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

示例:

# 获取第一页
curl https://your-domain.com/api/posts?page=1&limit=10

# 搜索文章
curl https://your-domain.com/api/posts?search=Next.js

2. 获取单篇文章

端点: GET /api/posts/[slug]

描述: 通过 slug 获取单篇已发布文章的详细内容

路径参数:

slug: 文章的 URL slug

响应:

{
  "success": true,
  "message": "获取文章成功",
  "data": {
    "id": 1,
    "title": "文章标题",
    "slug": "article-slug",
    "content": "# 文章内容\n\n这是文章的 Markdown 内容...",
    "excerpt": "文章摘要",
    "author": "作者名",
    "category": "技术",
    "tags": "Next.js,React",
    "cover_image_url": "https://...",
    "status": "published",
    "views": 100,
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}

示例:

curl https://your-domain.com/api/posts/my-first-article

3. 更新文章浏览量

端点: POST /api/posts/[slug]/views

描述: 异步更新文章浏览量（客户端自动调用）

路径参数:

slug: 文章的 URL slug

响应:

{
  "success": true
}

示例:

curl -X POST https://your-domain.com/api/posts/my-article/views

4. 获取网站设置

端点: GET /api/settings

描述: 获取网站的公开设置信息

响应:

{
  "success": true,
  "message": "获取设置成功",
  "data": {
    "siteBrand": "JLONG",
    "siteSlogan": "探索技术，分享生活",
    "homeBgImage": "https://images.unsplash.com/..."
  }
}

5. 获取网站统计

端点: GET /api/stats

描述: 获取网站的统计数据

响应:

{
  "success": true,
  "message": "获取统计数据成功",
  "data": {
    "totalPosts": 50,
    "totalViews": 5000,
    "totalCategories": 5
  }
}

管理后台 API

注意: 所有管理后台 API 都需要认证。请在请求头中包含认证 token。

认证方式:

Authorization: Bearer YOUR_TOKEN

或使用 Cookie:

Cookie: auth-token=YOUR_TOKEN

1. 获取仪表盘数据

端点: GET /api/admin/dashboard

描述: 获取管理后台仪表盘统计数据

需要认证: 是

响应:

{
  "success": true,
  "message": "获取仪表盘数据成功",
  "data": {
    "totalPosts": 50,
    "publishedPosts": 45,
    "draftPosts": 5,
    "totalViews": 5000,
    "totalCategories": 5,
    "recentPosts": [...]
  }
}

2. 管理文章

获取所有文章（包括草稿）

端点: GET /api/admin/posts

描述: 获取所有文章，包括草稿和归档，支持搜索和排序

查询参数:

page: 页码
limit: 每页数量
search: 搜索关键词
sortBy: 排序字段 (created_at, updated_at, views, title, status)
sortOrder: 排序顺序 (ASC, DESC)

响应:

{
  "success": true,
  "message": "获取文章列表成功",
  "data": {
    "posts": [...],
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

创建文章

端点: POST /api/admin/posts

请求体:

{
  "title": "文章标题",
  "slug": "article-slug",
  "content": "# 文章内容",
  "excerpt": "文章摘要",
  "author": "作者名",
  "category": "技术",
  "tags": "Next.js,React",
  "cover_image_url": "https://...",
  "status": "draft"
}

响应:

{
  "success": true,
  "message": "创建文章成功",
  "data": {
    "id": 1,
    ...
  }
}

示例:

curl -X POST https://your-domain.com/api/admin/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "我的第一篇文章",
    "content": "# Hello World",
    "status": "published"
  }'

获取单篇文章

端点: GET /api/admin/posts/[id]

路径参数:

id: 文章 ID

响应:

{
  "success": true,
  "message": "获取文章成功",
  "data": {
    "id": 1,
    "title": "文章标题",
    ...
  }
}

更新文章

端点: PUT /api/admin/posts/[id]

请求体: 与创建文章相同，所有字段可选

响应:

{
  "success": true,
  "message": "更新文章成功"
}

示例:

curl -X PUT https://your-domain.com/api/admin/posts/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "published"}'

删除文章

端点: DELETE /api/admin/posts/[id]

响应:

{
  "success": true,
  "message": "删除文章成功"
}

3. 文件管理

端点: GET /api/admin/files

描述: 获取已上传的文件列表

响应:

{
  "success": true,
  "data": [
    {
      "url": "https://...",
      "pathname": "image.jpg",
      "size": 102400,
      "uploadedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}

4. 分类管理

端点: GET /api/admin/categories

描述: 获取所有分类及文章数量

响应:

{
  "success": true,
  "data": [
    {
      "category": "技术",
      "count": 25
    }
  ]
}

5. 设置管理

获取设置

端点: GET /api/admin/settings

响应:

{
  "success": true,
  "data": {
    "siteBrand": "JLONG",
    "siteSlogan": "探索技术，分享生活",
    "homeBgImage": "https://..."
  }
}

更新设置

端点: POST /api/admin/settings

请求体:

{
  "siteBrand": "新的网站名",
  "siteSlogan": "新的标语",
  "homeBgImage": "https://new-image.jpg"
}

响应:

{
  "success": true,
  "message": "设置更新成功"
}

6. 修改密码

端点: POST /api/admin/change-password

请求体:

{
  "oldPassword": "old_password",
  "newPassword": "new_password"
}

响应:

{
  "success": true,
  "message": "密码修改成功"
}

工具 API

1. 图片上传

端点: POST /api/upload

描述: 上传图片到 Vercel Blob 存储

需要认证: 是

请求: multipart/form-data

file: 图片文件 (支持 JPG, PNG, GIF, WebP, SVG)
最大 5MB

响应:

{
  "success": true,
  "message": "上传成功",
  "data": {
    "url": "https://...",
    "pathname": "image.jpg",
    "contentType": "image/jpeg",
    "size": 102400
  }
}

示例:

curl -X POST https://your-domain.com/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@image.jpg"

2. Webhook - n8n 集成

端点: POST /api/webhook/posts

描述: 接收来自 n8n 的文章发布请求

安全: 需要在环境变量中设置 WEBHOOK_SECRET

请求头:

X-Webhook-Secret: YOUR_WEBHOOK_SECRET

请求体:

{
  "title": "文章标题",
  "content": "文章内容",
  "author": "作者",
  "category": "分类",
  "tags": "标签1,标签2"
}

响应:

{
  "success": true,
  "message": "文章创建成功",
  "data": {
    "id": 1,
    "slug": "auto-generated-slug"
  }
}

错误处理

所有 API 在发生错误时返回统一格式：

{
  "success": false,
  "message": "错误描述",
  "statusCode": 400
}

常见状态码:

200 - 成功
201 - 创建成功
400 - 请求参数错误
401 - 未认证
403 - 无权限
404 - 资源不存在
500 - 服务器错误

认证令牌

获取令牌

通过 /api/auth/login 登录后获得 JWT token

使用令牌

方法 1: 请求头

Authorization: Bearer YOUR_TOKEN

方法 2: Cookie（登录后自动设置）

Cookie: auth-token=YOUR_TOKEN

令牌过期

默认 7 天过期，需要重新登录

示例：完整工作流

创建并发布一篇文章

# 1. 登录获取 token
TOKEN=$(curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}' \
  | jq -r '.data.token')

# 2. 上传封面图片
COVER_URL=$(curl -X POST https://your-domain.com/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@cover.jpg" \
  | jq -r '.data.url')

# 3. 创建文章
curl -X POST https://your-domain.com/api/admin/posts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"我的新文章\",
    \"content\": \"# Hello World\n\n这是我的第一篇文章\",
    \"excerpt\": \"文章摘要\",
    \"author\": \"张三\",
    \"category\": \"技术\",
    \"tags\": \"Next.js,博客\",
    \"cover_image_url\": \"$COVER_URL\",
    \"status\": \"published\"
  }"

# 4. 登出
curl -X POST https://your-domain.com/api/auth/logout \
  -H "Authorization: Bearer $TOKEN"

性能优化

缓存

公开 API 启用了 60 秒 ISR 缓存
静态文章页面预生成（SSG）
图片自动优化和懒加载

限流

建议在生产环境中添加 API 限流：

登录接口: 5次/分钟
创建接口: 10次/分钟
查询接口: 100次/分钟

安全建议

HTTPS: 生产环境必须使用 HTTPS
环境变量: 妥善保管数据库连接字符串和 JWT 密钥
密码强度: 使用强密码
定期备份: 定期备份数据库
监控: 启用错误日志和性能监控

更新日志

v1.0.0 (2024-01-01)

初始版本发布
支持文章 CRUD
支持图片上传
支持 n8n webhook 集成
性能优化（ISR、SSG、图片优化）

技术支持

如有问题，请：

查看本文档
查看 PERFORMANCE.md 性能优化指南
提交 GitHub Issue

API 基础 URL: https://your-domain.com/api 当前版本: v1.0.0 最后更新: 2024-01-01

博客系统 API 使用说明

博客系统 API 使用说明

目录

认证 API

1. 用户登录

2. 用户登出

公开 API

1. 获取文章列表

2. 获取单篇文章

3. 更新文章浏览量

4. 获取网站设置

5. 获取网站统计

管理后台 API

1. 获取仪表盘数据

2. 管理文章

获取所有文章（包括草稿）

创建文章

获取单篇文章

更新文章

删除文章

3. 文件管理

4. 分类管理

5. 设置管理

获取设置

更新设置

6. 修改密码

工具 API

1. 图片上传

2. Webhook - n8n 集成

错误处理

认证令牌

获取令牌

使用令牌

令牌过期

示例：完整工作流

创建并发布一篇文章

性能优化

缓存

限流

安全建议

更新日志

v1.0.0 (2024-01-01)

技术支持