-
Notifications
You must be signed in to change notification settings - Fork 56
API Reference
Monolith 后端为纯 REST + JSON，全部路径以 /api 前缀。前端 Pages Functions 已在生产环境同源代理。
后台路由需在请求头携带 JWT：
Authorization: Bearer <token>Token 通过 POST /api/auth/login 获取，默认有效期 8 小时。
Content-Type: application/json文件上传使用 multipart/form-data。
// 成功
200/201 OK
{ "data": ... } 或直接对象
// 错误
4xx/5xx
{ "error": "message" }GET /api/posts?page=1&pageSize=10返回包含 total / page / pageSize 字段。
公开。返回服务状态。
{ "status": "ok", "timestamp": "2026-04-25T00:00:00Z" }公开。限流 5 次/15 分钟。
// Request
{ "password": "your-admin-password" }
// Response
{ "token": "eyJhbGciOi...", "expiresAt": "2026-04-25T08:00:00Z" }需鉴权。撤销当前 token（加入黑名单直到过期）。
需鉴权。返回当前会话信息。
列表。支持过滤参数：
| 参数 | 类型 | 说明 |
|---|---|---|
page |
int | 页码，默认 1 |
pageSize |
int | 每页数量，默认 10，最大 50 |
category |
string | 按分类 slug 过滤 |
tag |
string | 按标签过滤 |
series |
string | 按系列 slug 过滤 |
q |
string | 全文搜索 |
文章详情。自动递增 viewCount（异步）。
相关文章推荐（基于分类/标签）。
提交反应。限流，使用 IP+UA+REACTION_SALT 指纹去重。
{ "type": "heart" } // heart / like / wow / sad / angry获取反应统计。
{ "heart": 12, "like": 5, "wow": 2 }文章评论列表（已审核）。
提交评论。限流。匿名邮箱后台不可见（隐私加固）。
{
"author": "匿名",
"email": "optional@example.com",
"content": "**Markdown** 支持"
}全部分类。
分类详情含文章列表。
全部系列（合集）。
系列详情含按顺序排列的文章。
静态页（如 /about、/privacy）。
RSS 2.0 订阅源。边缘缓存 5 分钟。
站点地图。包含全部已发布文章 + 静态页。
全部需
Authorization: Bearer <token>。
管理后台文章列表（含草稿/计划发布）。
创建文章。
{
"slug": "hello-world",
"title": "你好世界",
"content": "Markdown 内容",
"status": "draft", // draft | scheduled | published
"publishAt": null, // ISO 8601, 仅 scheduled
"categoryIds": [1, 2],
"tagIds": [3],
"seriesId": null,
"isPinned": false
}含完整字段（草稿/计划/统计数据）。
更新。自动创建版本快照（用于历史回滚）。
软删除。
从软删除恢复。
历史版本列表。
恢复到指定版本。
抓取文章中的远程图片，下载到 R2 并替换 URL（防外链失效）。
{
"action": "publish", // publish | unpublish | delete | pin | unpin
"slugs": ["hello", "world"]
}批量导入。Body 为统一的 ImportPayload 格式（前端 importer 输出）。
{
"posts": [...],
"categories": [...],
"tags": [...],
"attachments": [...]
}支持来源: WordPress / Ghost / Hexo / Hugo / Jekyll / Halo。
分类 CRUD。
标签 CRUD。
系列 CRUD。
待审核 + 已审核列表。
通过 / 拒绝。
{ "status": "approved" } // approved | rejected | pending删除。
R2 文件列表。
上传。multipart/form-data。
POST /api/admin/media/upload
Content-Type: multipart/form-data
file: <binary>返回:
{ "key": "uploads/...", "url": "/cdn/uploads/..." }删除文件。
CRUD 操作。publish 字段控制是否对公开 /api/pages/:slug 暴露。
导出全站数据 + 媒体清单为 JSON，并写入 R2 backups/。
{ "key": "backups/2026-04-25.json", "size": 123456 }从备份 JSON 恢复（覆盖现有数据，谨慎）。
仅从 R2 备份重新导入媒体清单（不动数据库）。
总览：浏览量 / 评论 / 反应趋势。
文章维度统计（按 viewCount 排序）。
引荐源 Top N。
站点配置（标题、描述、社交链接、Logo 等）。
R2 反向代理。1 年强缓存。immutable。
需鉴权。备份文件下载。
| 状态 | 含义 | 常见原因 |
|---|---|---|
| 400 | Bad Request | 参数缺失/格式错 |
| 401 | Unauthorized | 缺 token / token 过期 |
| 403 | Forbidden | 权限不足 |
| 404 | Not Found | 资源不存在 |
| 409 | Conflict | slug 重复 |
| 413 | Payload Too Large | 上传文件超限 |
| 429 | Too Many Requests | 触发限流 |
| 500 | Internal Server Error | 服务器异常 |
Monolith · 边缘原生全栈博客 · MIT License · 文档以 main 分支 代码为准