生产版 1.1
明膳 CMS 上线与对接说明
首页素材、文章、媒体和发布状态的生产接口说明。管理写入需要安全会话与 CSRF 校验,公开读取接口无需登录。
后台 API Demo
登录管理后台的 API Demo,可读取工作统计、内容、媒体、首页模块,并直接试用首页素材和文章的保存、发布、下线接口。写入操作使用当前登录账号并遵循 CSRF 与 version 校验。
账号与会话
新密码为 12–128 字符且同时包含字母和数字。初始密码和管理员重置的临时密码必须先更换。改密、停用或重置会使旧会话失效。运营管理员只能创建运营账号;账号启停、密码重置、系统状态和审计由管理员管理。
内容与发布
新增内容是草稿。更新和状态操作都要携带最新 version;缺失返回 428,过期返回 409。保存不会改变线上快照,设置 published 才会更新公开接口,设置 offline 后详情返回 404。
文章发布后进入 /news、/news/{slug}、站内搜索;首页、产品图片和文章详情由服务器直接读取发布版本。
首页素材直接替换
后台「首页素材」支持首屏视频、手机视频、封面、电脑/手机 Banner、品牌图、四款产品图、二维码和首页文字的独立编辑。保存草稿不影响线上,发布后官网即时读取新版本。
GET /api/site-home:读取 draft、published、version、published_version 和字段定义。PUT /api/site-home:按 version 保存完整首页字段草稿。POST /api/site-home/publish:发布当前草稿。GET /public/site-home:读取线上发布值,不暴露草稿。
视频支持 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。
上线检查
- 完成域名备案与接入核验,用 Safari、微信及不同网络验证 www、admin、api 的 HTTPS。
- 首次登录更换初始密码,并轮换曾通过聊天传递的服务器凭据。
- 每日备份由
mingshan-cms-backup.timer触发,生产建议增加异机备份和故障告警。 - 恢复演练先恢复到独立空库并验证,再执行正式切换。
API 写入示例
先 POST /api/content 获得 item.id 和 item.version,再调用 POST /api/content/{id}/status 设置 published 或 offline。首页素材按“读取 → PUT 保存 → publish 发布”流程操作。所有写入携带会话 Cookie 与 X-CSRF-Token,不要重放旧版本号。