膳明膳 API

API v1

明膳 CMS API 文档

用于管理明膳官网的账号、内容、媒体和发布状态。后台接口采用安全会话 Cookie 与 CSRF 双重校验,公开读取接口无需登录。

基础地址https://api.mingshanhealth.com

快速开始

登录响应会返回 csrf_token 并设置会话 Cookie。后续写操作必须同时携带 Cookie 和 X-CSRF-Token。

登录取得 Cookie 与 CSRF Token
→
读取仅携带会话 Cookie
→
写入Cookie + X-CSRF-Token
cURL
curl -c cookies.txt \
  -H "Origin: https://admin.mingshanhealth.com" \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}' \
  https://api.mingshanhealth.com/api/auth/login

浏览器前端请求必须使用 credentials: "include"。生产 API 仅允许管理后台域名进行跨域凭证请求。

认证与安全

会话
Secure、HttpOnly、SameSite=Lax Cookie,最长 8 小时。
CSRF
POST、PUT、PATCH、DELETE 请求需要 X-CSRF-Token,登录接口除外。
角色
admin 可管理全部数据;ops 可管理内容、媒体及运营账号。
上传
最大 20MB;允许图片、PDF、文本、Office 文档与 ZIP。

响应与错误

成功
{
  "ok": true,
  "item": { "id": 12 }
}
失败
{
  "ok": false,
  "error": {
    "code": "permission_denied",
    "message": "当前账号没有执行此操作的权限。"
  }
}
状态码含义处理建议
400参数或业务校验失败展示响应中的具体 message
401未登录或会话失效重新登录并刷新 CSRF Token
403权限不足或 CSRF 失败检查角色、Cookie 和请求头
404资源不存在检查资源 ID 或 slug
409用户名或 slug 冲突使用唯一值后重试
429登录尝试过多稍后重试

认证接口

POST/api/auth/login公开

登录后台,返回当前用户与 CSRF Token,并设置会话 Cookie。

{"username":"string","password":"string"}
GET/api/auth/me登录

读取当前用户与最新 CSRF Token。

POST/api/auth/logout登录 + CSRF

退出并清除当前会话。

POST/api/auth/change-password登录 + CSRF

修改自己的密码,新密码 12–128 位,包含字母和数字;修改后所有旧会话失效。

{"current_password":"string","new_password":"string"}

账号接口

GET/api/users登录

超级管理员查看全部账号;运营管理员只看到运营账号。

POST/api/users登录 + CSRF

新增后台账号。运营管理员只能创建 ops。

{"username":"editor_01","password":"MIN_8_CHARS","role":"ops"}
PATCH/api/users/{user_id}admin + CSRF

启停账号,可同时重置密码。

{"is_active":true,"password":"OPTIONAL_NEW_PASSWORD"}

内容接口

GET/api/content?kind=&status=登录

筛选内容。kind:site_info、page、article;status:draft、published、offline。

GET/api/content/{item_id}登录

读取单条完整内容。

POST/api/content登录 + CSRF

新增草稿,slug 只能使用小写字母、数字和连字符。

{"kind":"article","slug":"sample-news","title":"示例标题","summary":"摘要","body":"正文","metadata":{}}
PUT/api/content/{item_id}登录 + CSRF

完整更新内容,使用与新增接口相同的请求体。

POST/api/content/{item_id}/status登录 + CSRF

切换草稿、发布或下线状态。

{"status":"published","version":1}

媒体接口

GET/api/media登录

读取最近 300 个媒体文件。

POST/api/media登录 + CSRF

上传后自动读取宽高、图片比例并判断推荐用途;响应中的 public_url 可直接用于官网内容。

POST/api/media/{media_id}/optimize登录 + CSRF

根据识别用途生成统一桌面 WebP 和 1080×1350 手机适配图,返回 optimized_url 与 mobile_url。

DELETE/api/media/{media_id}登录 + CSRF

归档媒体,保留已有链接;使用 POST /api/media/{media_id}/restore 恢复。

首页模块接口

用于控制首页视频和图片 Banner 的展示状态。隐藏只影响官网展示,原有内容和资源不会删除。

GET/api/homepage-modules登录

读取后台首页模块配置。

PATCH/api/homepage-modules/{module_key}登录 + CSRF

切换模块展示状态。module_key:video_hero 或 static_hero。

{"is_visible":false}
GET/public/homepage-modules公开

官网读取当前模块展示状态,无需登录。

产品管理接口

产品独立保存草稿和上架。首页电脑端一屏展示 4 款,超过 4 款可向右滑动;按已发布的 sort_order 排序,数字越小越靠左。

GET/api/products登录

读取产品列表,支持 status、page、page_size;返回最新 version 和 published_snapshot。

POST/api/products登录 + CSRF

新增草稿。字段为 slug、name、subtitle、summary、body、image_url、sort_order;图片先通过 /api/media 上传。

GET/api/products/{id}登录

读取单个产品及版本。

PUT/api/products/{id}登录 + CSRF

完整保存产品字段并携带 version;不改变线上快照和排列顺序。已发布过的 slug 固定。

POST/api/products/{id}/status登录 + CSRF

上架前需填写简介及有效图片。下架后首页、产品中心及搜索撤回,详情返回 404。版本过期返回 409。

{"version":2,"status":"published"}
GET/public/products公开

仅返回已上架产品,支持 q 搜索和分页。详情使用 /public/products/{slug},官网地址为 /products/{slug}。

审计与统计

GET/api/stats登录

读取内容状态、媒体数量和有效账号数量。

GET/api/auditadmin

读取最近 200 条审计记录。

GET/healthz公开

数据库与 API 健康检查。

公开读取接口

公开接口只返回 published 状态的内容,无需 Cookie 或 CSRF Token。

GET/public/content?kind=article公开

读取已发布内容列表,可按 kind 筛选。列表响应不包含正文 body。

GET/public/content/{slug}公开

通过 slug 读取已发布内容详情。

完整示例

后台 API Demo提供首页素材与文章的真实读写发布;生产版说明与上线检查解释账号、版本冲突及备份恢复。

以下完整脚本会真实创建并发布内容,生产环境请优先使用后台只读 Demo。更新/发布需携带实际 version,缺失返回 428,过期返回 409。初始账号须先修改密码。

POST/api/content/validate登录 + CSRF

校验 ContentWrite,返回清理后的 item 和 dry_run=true;不保存。

GET/api/content/{item_id}/revisions登录

最近 30 个历史版本。列表接口支持 page 和 page_size(1–100),内容列表另支持 q 搜索。

示例包含登录、读取内容、新增草稿、发布和退出的完整流程。请通过环境变量或运行时输入提供凭据。