总览
字段说明
title 文章标题。
content_markdown 正文 Markdown，发布时必填。
slug 可选，不传时会按标题自动生成。
excerpt 可选，不传时会根据正文自动提取摘要。
cover_image_url 封面地址字段，可直接传本站已上传图片 URL。
publish_mode 只支持 draft 或 publish，默认 draft。
行为定义
draft 只在后台创建草稿，不出现在前台 News。
publish 创建后立即上线，需要 news:create + news:publish。
article.id 创建成功后返回文章 ID，后续更新和发布都基于这个 ID。
鉴权与安全
鉴权约定
Authorization 仅支持 Bearer Token，不接受 x-api-key。
401 令牌不存在、已吊销、已过期，或 Authorization 格式不正确。
403 令牌存在，但 scope 不足，无法访问当前接口。
令牌管理约定
plain_token 明文令牌只在创建成功时返回一次，之后不可找回。
revoke 吊销后立刻失效，后续请求全部按未授权处理。
article.id 第三方系统应保存创建返回的 article.id，后续操作均基于此值。
快速开始
- 先准备 Bearer 令牌，并确认该令牌具备所需 scope。
- 如果有封面图，先调用 upload-image 拿到本站图片 URL。
- 调用 POST /news，创建草稿或直接发布。
- 如果创建的是草稿，再调用 /news/:id/publish 上线。
curl -X POST 'https://gate-rank.com/api/v1/publish/news' \
-H 'Authorization: Bearer <publish_token>' \
-H 'Content-Type: application/json' \
-d '{
"title":"新文章",
"content_markdown":"# Hello\n\n正文内容",
"publish_mode":"draft"
}'状态流转
创建草稿后，内容只在后台存在，前台 News 页面不会展示。适合由第三方系统先写入，再由你在后台复核。
调用 publish 或在创建时直接使用 publish_mode=publish 后，文章会进入前台已发布集合。
归档后文章不再作为前台已发布新闻展示，但数据仍保留在后台系统中，便于追溯和再次处理。
创建文章
/api/v1/publish/news
创建一篇新闻草稿，或直接创建并发布。
{
"title": "新文章",
"slug": "new-article",
"excerpt": "可选摘要",
"cover_image_url": "/uploads/news/1743240000000-cover.webp",
"content_markdown": "# Hello\n\n正文内容",
"publish_mode": "draft"
}返回要点
返回完整 article 对象，其中包含 article.id。
如果 slug 冲突，会返回 NEWS_SLUG_CONFLICT。
未传 excerpt 时，会按正文自动提取摘要。
{
"article": {
"id": 123,
"title": "新文章",
"slug": "new-article",
"status": "draft",
"cover_image_url": "/uploads/news/1743240000000-cover.webp",
"published_at": null
}
}Request Body
Key Response Fields
上传封面
/api/v1/publish/news/upload-image
上传正文图片或封面图片；如果 mode=cover，会按封面规则压缩处理。
curl -X POST 'https://gate-rank.com/api/v1/publish/news/upload-image' \
-H 'Authorization: Bearer <publish_token>' \
-F 'mode=cover' \
-F 'file=@/path/to/cover.png'{"url":"/uploads/news/1743240000000-cover.webp"}Multipart Fields
Response
后续操作
/api/v1/publish/news/:id
更新已存在的文章内容。
/api/v1/publish/news/:id/publish
将草稿正式发布到前台。
/api/v1/publish/news/:id/archive
归档文章，使其不再作为前台已发布新闻展示。
# 更新文章
curl -X PATCH 'https://gate-rank.com/api/v1/publish/news/123' \
-H 'Authorization: Bearer <publish_token>' \
-H 'Content-Type: application/json' \
-d '{"title":"更新后的标题","content_markdown":"# Updated"}'
# 发布草稿
curl -X POST 'https://gate-rank.com/api/v1/publish/news/123/publish' \
-H 'Authorization: Bearer <publish_token>' \
-H 'Content-Type: application/json' \
-d '{}'
# 归档文章
curl -X POST 'https://gate-rank.com/api/v1/publish/news/123/archive' \
-H 'Authorization: Bearer <publish_token>'更新文章
适用于修正文案、摘要、slug、正文和封面。
建议只提交需要变更的字段，但 title 与 content_markdown 通常应保持完整。
发布草稿
发布成功后，article.status 会切换为 published。
如果文章不存在，会返回 NEWS_NOT_FOUND。
归档文章
归档后不会作为前台已发布新闻展示。
适合处理误发、过期活动或内容撤回场景。
错误码
{
"code": "FORBIDDEN",
"message": "Publish token scope not allowed",
"request_id": "..."
}排查顺序
401 先检查 Authorization 格式、令牌是否已吊销、是否已过期。
403 再检查该 token 是否具备当前接口所需 scope。
BAD_REQUEST 最后检查 JSON 字段、multipart 参数和文章 ID 是否正确。
接入建议
request_id 建议在调用失败时记录返回中的 request_id 便于排查。
retry 仅对网络错误或明确可重试场景做有限重试，不要对 401/403 盲目重放。
slug 若系统自行生成 slug，需处理 NEWS_SLUG_CONFLICT 回退逻辑。