API v1
明膳 CMS API 文档
用于管理明膳官网的账号、内容、媒体和发布状态。后台接口采用安全会话 Cookie 与 CSRF 双重校验,公开读取接口无需登录。
https://api.mingshanhealth.com快速开始
登录响应会返回 csrf_token 并设置会话 Cookie。后续写操作必须同时携带 Cookie 和 X-CSRF-Token。
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 | 登录尝试过多 | 稍后重试 |
认证接口
/api/auth/login公开登录后台,返回当前用户与 CSRF Token,并设置会话 Cookie。
{"username":"string","password":"string"}/api/auth/me登录读取当前用户与最新 CSRF Token。
/api/auth/logout登录 + CSRF退出并清除当前会话。
/api/auth/change-password登录 + CSRF修改自己的密码,新密码 12–128 位,包含字母和数字;修改后所有旧会话失效。
{"current_password":"string","new_password":"string"}账号接口
/api/users登录超级管理员查看全部账号;运营管理员只看到运营账号。
/api/users登录 + CSRF新增后台账号。运营管理员只能创建 ops。
{"username":"editor_01","password":"MIN_8_CHARS","role":"ops"}/api/users/{user_id}admin + CSRF启停账号,可同时重置密码。
{"is_active":true,"password":"OPTIONAL_NEW_PASSWORD"}内容接口
/api/content?kind=&status=登录筛选内容。kind:site_info、page、article;status:draft、published、offline。
/api/content/{item_id}登录读取单条完整内容。
/api/content登录 + CSRF新增草稿,slug 只能使用小写字母、数字和连字符。
{"kind":"article","slug":"sample-news","title":"示例标题","summary":"摘要","body":"正文","metadata":{}}/api/content/{item_id}登录 + CSRF完整更新内容,使用与新增接口相同的请求体。
/api/content/{item_id}/status登录 + CSRF切换草稿、发布或下线状态。
{"status":"published","version":1}媒体接口
/api/media登录读取最近 300 个媒体文件。
/api/media登录 + CSRF上传后自动读取宽高、图片比例并判断推荐用途;响应中的 public_url 可直接用于官网内容。
/api/media/{media_id}/optimize登录 + CSRF根据识别用途生成统一桌面 WebP 和 1080×1350 手机适配图,返回 optimized_url 与 mobile_url。
/api/media/{media_id}登录 + CSRF归档媒体,保留已有链接;使用 POST /api/media/{media_id}/restore 恢复。
首页模块接口
用于控制首页视频和图片 Banner 的展示状态。隐藏只影响官网展示,原有内容和资源不会删除。
/api/homepage-modules登录读取后台首页模块配置。
/api/homepage-modules/{module_key}登录 + CSRF切换模块展示状态。module_key:video_hero 或 static_hero。
{"is_visible":false}/public/homepage-modules公开官网读取当前模块展示状态,无需登录。
产品管理接口
产品独立保存草稿和上架。首页电脑端一屏展示 4 款,超过 4 款可向右滑动;按已发布的 sort_order 排序,数字越小越靠左。
/api/products登录读取产品列表,支持 status、page、page_size;返回最新 version 和 published_snapshot。
/api/products登录 + CSRF新增草稿。字段为 slug、name、subtitle、summary、body、image_url、sort_order;图片先通过 /api/media 上传。
/api/products/{id}登录读取单个产品及版本。
/api/products/{id}登录 + CSRF完整保存产品字段并携带 version;不改变线上快照和排列顺序。已发布过的 slug 固定。
/api/products/{id}/status登录 + CSRF上架前需填写简介及有效图片。下架后首页、产品中心及搜索撤回,详情返回 404。版本过期返回 409。
{"version":2,"status":"published"}/public/products公开仅返回已上架产品,支持 q 搜索和分页。详情使用 /public/products/{slug},官网地址为 /products/{slug}。
审计与统计
/api/stats登录读取内容状态、媒体数量和有效账号数量。
/api/auditadmin读取最近 200 条审计记录。
/healthz公开数据库与 API 健康检查。
公开读取接口
公开接口只返回 published 状态的内容,无需 Cookie 或 CSRF Token。
/public/content?kind=article公开读取已发布内容列表,可按 kind 筛选。列表响应不包含正文 body。
/public/content/{slug}公开通过 slug 读取已发布内容详情。
完整示例
后台 API Demo提供首页素材与文章的真实读写发布;生产版说明与上线检查解释账号、版本冲突及备份恢复。
以下完整脚本会真实创建并发布内容,生产环境请优先使用后台只读 Demo。更新/发布需携带实际 version,缺失返回 428,过期返回 409。初始账号须先修改密码。
/api/content/validate登录 + CSRF校验 ContentWrite,返回清理后的 item 和 dry_run=true;不保存。
/api/content/{item_id}/revisions登录最近 30 个历史版本。列表接口支持 page 和 page_size(1–100),内容列表另支持 q 搜索。
示例包含登录、读取内容、新增草稿、发布和退出的完整流程。请通过环境变量或运行时输入提供凭据。