cwd/docs/api/admin/comments.md

评论管理相关

评论管理接口用于查看、编辑、删除评论以及管理 IP 和邮箱黑名单。

所有接口都需要在请求头中携带 Bearer Token。

Authorization: Bearer <token>

1.1 获取评论列表

GET /admin/comments/list

获取评论列表，用于后台管理页面展示。

• 方法：GET
• 路径：/admin/comments/list
• 鉴权：需要（Bearer Token）

查询参数

名称	位置	类型	必填	说明
page	query	integer	否	页码，默认 1
siteId	query	string	否	按站点 ID 筛选评论，如 blog、docs

说明：

• 当前实现中每页固定大小为 10，暂不支持 pageSize 或状态过滤；
• 当提供 siteId 参数且不为 default 时，仅返回该站点下的评论。

成功响应

• 状态码：200

{
	"data": [
		{
			"id": 1,
			"created": 1736762400000,
			"name": "张三",
			"email": "zhangsan@example.com",
			"postSlug": "/blog/hello-world",
			"postUrl": "https://your-blog.example.com/blog/hello-world",
			"url": "https://zhangsan.me",
			"ipAddress": "127.0.0.1",
			"contentText": "很棒的文章！",
			"contentHtml": "很棒的文章！",
			"status": "approved",
			"priority": 2,
			"ua": "Mozilla/5.0 ...",
			"avatar": "https://gravatar.com/avatar/..."
		}
	],
	"pagination": {
		"page": 1,
		"limit": 10,
		"total": 1
	}
}

返回字段说明：

字段名	类型	说明
id	number	评论 ID
created	number	创建时间戳
name	string	评论者昵称
email	string	评论者邮箱
postSlug	string	文章 slug
postUrl	string	null)
url	string	null)
ipAddress	string	评论者 IP 地址
contentText	string	评论内容（纯文本）
contentHtml	string	评论内容（渲染后的 HTML）
status	string	评论状态
priority	number	置顶权重
ua	string	用户代理
avatar	string	头像 URL（Gravatar）

鉴权错误

• 未携带 Token 或 Token 失效：

  • 状态码：401

  {
  	"message": "Unauthorized"
  }
  

1.2 更新评论状态

PUT /admin/comments/status

更新评论状态（例如通过 / 拒绝）。

注意：此接口仅用于更新评论状态，如需修改评论内容、置顶权重等，请使用 /admin/comments/update 接口。

• 方法：PUT
• 路径：/admin/comments/status
• 鉴权：需要（Bearer Token）

查询参数

名称	位置	类型	必填	说明
id	query	number	是	评论 ID
status	query	string	是	评论状态，例如 approved、rejected

当前实现中未对 status 值进行枚举校验，但推荐仅使用：

• approved：已通过
• rejected：已拒绝

成功响应

• 状态码：200

{
	"message": "Comment status updated, id: 1, status: approved."
}

错误响应

• 缺少参数：

  • 状态码：400

  {
  	"message": "Missing id or status"
  }
  

• 更新失败：

  • 状态码：500

  {
  	"message": "Update failed"
  }
  

1.3 更新评论内容

PUT /admin/comments/update

更新评论的详细信息，包括昵称、邮箱、网址、评论地址、内容、状态和置顶权重等。

• 方法：PUT
• 路径：/admin/comments/update
• 鉴权：需要（Bearer Token）

请求头

名称	必填	示例
Content-Type	是	application/json

请求体

{
  "id": 1,
  "name": "张三",
  "email": "zhangsan@example.com",
  "url": "https://zhangsan.me",
  "postSlug": "/blog/hello-world",
  "postUrl": "https://example.com/blog/hello-world",
  "contentText": "更新后的评论内容",
  "status": "approved",
  "priority": 2
}

字段说明：

字段名	类型	必填	说明
id	number	是	评论 ID
name	string	是	评论者昵称
email	string	是	评论者邮箱
url	string	否	评论者个人主页或站点地址
postSlug	string	否	文章 slug，不传则保持原值，支持 postSlug 或 post_slug
postUrl	string	否	文章完整 URL，不传则保持原值，支持 postUrl 或 post_url
content	string	是*	评论内容（Markdown 或纯文本），与 contentText 二选一
contentText	string	是*	评论内容（纯文本），与 content 二选一
status	string	否	评论状态，可选 approved、pending、rejected
priority	number	否	置顶权重，默认为 1，数值越大越靠前，必须 >= 1

置顶权重说明：

• 1：不置顶（默认值）
• 2 或更高：数值越大，该评论在列表中排序越靠前
• 公开 API 获取评论时，会按照 priority DESC 进行排序

成功响应

• 状态码：200

{
  "message": "Comment updated, id: 1."
}

错误响应

• ID 无效：

  • 状态码：400 或 404

  {
    "message": "Missing or invalid id"
  }
  

  或

  {
    "message": "Comment not found"
  }
  

• 必填字段为空：

  • 状态码：400

  {
    "message": "昵称不能为空"
  }
  

• 更新失败：

  • 状态码：500

  {
    "message": "Update failed"
  }
  

1.4 删除指定评论

DELETE /admin/comments/delete

删除指定评论。

• 方法：DELETE
• 路径：/admin/comments/delete
• 鉴权：需要（Bearer Token）

查询参数

名称	位置	类型	必填	说明
id	query	number	是	评论 ID

成功响应

• 状态码：200

{
	"message": "Comment deleted, id: 1."
}

错误响应

• 缺少 ID：

  • 状态码：400

  {
  	"message": "Missing id"
  }
  

• 删除失败：

  • 状态码：500

  {
  	"message": "Delete operation failed"
  }
  

1.5 将指定 IP 加入评论黑名单

POST /admin/comments/block-ip

通过接口将指定 IP 地址加入评论黑名单，后续该 IP 提交评论将被拒绝。

• 方法：POST
• 路径：/admin/comments/block-ip
• 鉴权：需要（Bearer Token）

请求头

名称	必填	示例
Content-Type	是	application/json

请求体

{
	"ip": "1.1.1.1"
}

字段说明：

字段名	类型	必填	说明
ip	string	是	要加入黑名单的 IP 地址，多个 IP 用逗号或换行分隔

成功响应

• 状态码：200

{
	"message": "已加入 IP 黑名单"
}

错误响应

• IP 为空：

  • 状态码：400

  {
  	"message": "IP 地址不能为空"
  }
  

• 内部错误：

  • 状态码：500

  {
  	"message": "操作失败"
  }
  

1.6 将指定邮箱加入评论黑名单

POST /admin/comments/block-email

通过接口将指定邮箱地址加入评论黑名单，后续该邮箱提交评论将被拒绝。

• 方法：POST
• 路径：/admin/comments/block-email
• 鉴权：需要（Bearer Token）

请求头

名称	必填	示例
Content-Type	是	application/json

请求体

{
	"email": "spam@example.com"
}

字段说明：

字段名	类型	必填	说明
email	string	是	要加入黑名单的邮箱地址，多个邮箱用逗号或换行分隔

成功响应

• 状态码：200

{
	"message": "已加入邮箱黑名单"
}

错误响应

• 邮箱为空：

  • 状态码：400

  {
  	"message": "邮箱不能为空"
  }
  

• 邮箱格式不正确：

  • 状态码：400

  {
  	"message": "邮箱格式不正确"
  }
  

• 内部错误：

  • 状态码：500

  {
  	"message": "操作失败"
  }