膳明膳 API

生产版 1.1

明膳 CMS 上线与对接说明

首页素材、文章、媒体和发布状态的生产接口说明。管理写入需要安全会话与 CSRF 校验,公开读取接口无需登录。

后台 API Demo

登录管理后台的 API Demo,可读取工作统计、内容、媒体、首页模块,并直接试用首页素材和文章的保存、发布、下线接口。写入操作使用当前登录账号并遵循 CSRF 与 version 校验。

账号与会话

新密码为 12–128 字符且同时包含字母和数字。初始密码和管理员重置的临时密码必须先更换。改密、停用或重置会使旧会话失效。运营管理员只能创建运营账号;账号启停、密码重置、系统状态和审计由管理员管理。

内容与发布

新增内容是草稿。更新和状态操作都要携带最新 version;缺失返回 428,过期返回 409。保存不会改变线上快照,设置 published 才会更新公开接口,设置 offline 后详情返回 404。

文章发布后进入 /news、/news/{slug}、站内搜索;首页、产品图片和文章详情由服务器直接读取发布版本。

首页素材直接替换

后台「首页素材」支持首屏视频、手机视频、封面、电脑/手机 Banner、品牌图、四款产品图、二维码和首页文字的独立编辑。保存草稿不影响线上,发布后官网即时读取新版本。

视频支持 H.264 / yuv420p MP4,最长 120 秒、最大 100MB、最大 4K;图片和常用文件最大 20MB。

文件与媒体

POST /api/media 上传素材,服务器校验真实格式、尺寸和视频兼容性。删除操作归档记录并保留已有链接;可通过恢复接口重新启用。尺寸优化会生成桌面/手机版适配版本,不会把低清原图变成真实高清细节。

分页与错误

/api/content、/api/media、/public/content 支持 page 和 page_size(1–100)。错误响应包含 ok、error.code、error.message、request_id,响应头含 X-Request-ID。

上线检查

  1. 完成域名备案与接入核验,用 Safari、微信及不同网络验证 www、admin、api 的 HTTPS。
  2. 首次登录更换初始密码,并轮换曾通过聊天传递的服务器凭据。
  3. 每日备份由 mingshan-cms-backup.timer 触发,生产建议增加异机备份和故障告警。
  4. 恢复演练先恢复到独立空库并验证,再执行正式切换。

API 写入示例

先 POST /api/content 获得 item.id 和 item.version,再调用 POST /api/content/{id}/status 设置 published 或 offline。首页素材按“读取 → PUT 保存 → publish 发布”流程操作。所有写入携带会话 Cookie 与 X-CSRF-Token,不要重放旧版本号。