Server 接口
按源码整理 Nitro 服务端接口、鉴权规则和路由映射
本页按 imqi1-cms/server 当前源码整理接口。接口实现位于 server/api，不带 /api 前缀的固定端点位于 server/routes。本文档仅供参考，请求参数、返回字段和错误文案以对应的 .ts handler 为最终准则；表格用于快速定位，不替代源码中的参数校验。
路由规则
文件路径会转换为 URL，HTTP 方法由文件名后缀决定：
| 源码文件 | HTTP 路径 | 方法 |
|---|---|---|
server/api/home-data.get.ts | /api/home-data | GET |
server/api/comments.post.ts | /api/comments | POST |
server/api/contents/[category]/[slug].get.ts | /api/contents/:category/:slug | GET |
server/api/mini/[...].options.ts | /api/mini/* | OPTIONS |
方括号表示动态参数：[id] 对应 :id，[slug] 对应 :slug，[...path] 表示剩余路径。查询字符串不体现在文件名中，例如 /api/search?q=nuxt&page=1 仍由 server/api/search.get.ts 处理。少数旧接口使用不带方法后缀的文件名，例如 server/api/links/patch.ts 对应 PATCH /api/links/patch，server/api/amap/config.ts 对应地图配置读取接口。
鉴权和安全规则
普通 API
生产环境中，server/middleware/referer-check.ts 会检查 /api/* 请求的 Referer 是否属于 site.config.ts 的允许域名。SSR 内部请求可使用 SSR_INTERNAL_REQUEST_SECRET 对应的 X-SSR-Internal-Request 标识；/api/mini/* 和 /api/_nuxt_icon（含其子路径）不走 Referer 校验，前者使用下面的小程序签名。
会话和后台 API
后台接口通过登录后的 session Cookie 识别当前用户。没有有效会话时返回 401。后台 GET 通常只检查登录；POST、PUT、PATCH、DELETE 等写请求还需要 CSRF token，token 可以放在请求体的 csrfToken 字段或 x-csrf-token 请求头。前端先请求 GET /api/csrf/token 获取 token。
公开写接口也遵循 CSRF 规则：评论提交、友链申请和友链修改请求都需要 token；评论还可能需要图形验证码，具体由站点设置决定。常见错误状态码为 400（参数错误）、401（未登录）、403（CSRF/Referer/签名失败）、404（资源不存在）和 500（服务端错误）。
小程序 API
生产环境的 /api/mini/* 由 server/middleware/mini-auth.ts 统一检查 HMAC-SHA256 签名。请求需要 X-Mini-Timestamp、X-Mini-Nonce 和 X-Mini-Sign，时间戳与服务器相差不能超过 300 秒，nonce 在有效窗口内不能重复。OPTIONS 预检请求不需要签名；开发环境会跳过签名校验。
公开接口
以下接口面向主站前台或公开页面，默认不要求登录。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/site | 返回站点基础信息、版本和前台运行时配置。 |
| GET | /api/home-data | 返回首页文章、图片、友链等聚合数据。 |
| GET | /api/archiving | 返回归档页按时间组织的文章数据。 |
| GET | /api/categories | 返回启用的分类列表。 |
| GET | /api/category/:slug | 返回分类信息。 |
| GET | /api/category/:slug/contents | 分页读取指定分类下的文章。 |
| GET | /api/tags | 返回标签列表。 |
| GET | /api/tag/:slug/contents | 分页读取指定标签下的文章。 |
| GET | /api/contents/:category/:slug | 返回文章详情及正文、元信息、评论相关数据。 |
| GET | /api/page/:slug | 返回自定义页面详情。 |
| GET | /api/related-contents/:cid | 根据文章 ID 返回相关文章。 |
| GET | /api/random-content | 返回随机文章或随机内容。 |
| GET | /api/recent-comments | 返回最近评论。 |
| GET | /api/comments | 按文章 ID 分页读取已审核评论及回复。 |
| POST | /api/comments | 提交评论；游客需要验证码，所有写入都需要 CSRF。 |
| GET | /api/changelogs | 返回公开更新日志。 |
| GET | /api/contents/likes/:cid | 返回当前访客对指定文章的点赞状态与计数。 |
| POST | /api/contents/likes/:cid | 给指定文章点赞；同 IP+UA 指纹已存在时为幂等操作；接口级与通用限流中间件双重限速。 |
| GET | /api/likes/counts | 批量返回指定 cid 列表的点赞数，列表页一次性调用；CDN 缓存 5 分钟。 |
| GET | /api/links | 返回已启用的友链。 |
| POST | /api/links | 提交新友链申请；是否自动通过由设置决定。 |
| PATCH | /api/links/patch | 提交已有友链的修改申请。 |
| GET | /api/subscribes | 返回订阅源及其缓存文章。 |
| GET | /api/travels | 返回启用的旅行地点和关联文章。 |
| GET | /api/footprint | 返回地图足迹和访客统计数据。 |
| GET | /api/heatmap | 返回热力图数据。 |
| GET | /api/blog-network | 解析友链/订阅站点的博客网络信息。 |
| GET | /api/search | 按关键词搜索文章、页面或标签；生产环境可使用 Redis 缓存。 |
| GET | /api/stats | 返回公开统计数据。 |
| GET | /api/sitemap | 返回 HTML 站点地图所需的数据。 |
| GET | /api/check-link | 检查指定友链 URL 的可访问性。 |
| GET | /api/messages/config | 返回留言板是否开启、评论层级和验证码等配置。 |
| GET | /api/meting | 代理音乐平台元数据，供音乐播放器使用。 |
| GET | /api/amap/config | 返回高德地图客户端配置；服务端代理模式下不向浏览器下发密钥。 |
| GET | /api/captcha/image | 生成图形验证码图片和验证码标识。 |
| GET | /api/csrf/token | 创建或返回当前浏览器会话使用的 CSRF token。 |
| GET | /api/qr | 根据 text 参数生成通用二维码图片。 |
| GET | /api/qrcode | 根据 cid 生成文章对应的微信小程序码图片；未配置小程序凭据时返回 404。 |
附件接口
附件接口用于文章编辑器和后台附件管理；它们需要登录，上传和删除还需要 CSRF。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/attachments/list | 按 cid 返回当前文章或页面关联的附件。 |
| POST | /api/attachments/upload | 上传普通附件或实况照片，可通过 cid 关联到内容。 |
| DELETE | /api/attachments/:id | 删除附件；带 cid 时可只取消单篇内容的关联。 |
MCP 端点
/mcp 位于根级 URL，不走 /api/* 前缀（AI 客户端无浏览器 Referer，且端点自带限速与只读白名单；运维工具组另受 MCP_OPS_TOKEN 令牌门禁）。site.config.ts 的 features.mcp 关闭时该路由保持注册但一律 404。
| 方法 | 路径 | 用途 |
|---|---|---|
| POST | /mcp | 以 Model Context Protocol（JSON-RPC）暴露十九个只读检索工具，配置 MCP_OPS_TOKEN 后追加五个运维工具，单 IP 每分钟 60 次；详见 MCP Server |
认证接口
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/auth/login-config | 返回当前客户端是否需要图形验证码（captchaRequired）。 |
| POST | /api/auth/login | 使用用户名、密码和可选的 TOTP/信任设备信息登录。需要 CSRF。 |
| POST | /api/auth/logout | 删除当前会话 Cookie 和服务端会话。 |
| GET | /api/auth/me | 返回当前登录用户；未登录时返回 401 Unauthorized。 |
| GET | /api/auth/verify | 验证当前会话是否仍然有效。 |
| GET | /api/auth/2fa/status | 返回当前账户两步验证启用状态。需要登录。 |
| POST | /api/auth/2fa/setup | 生成 TOTP 密钥、二维码和 otpauth 信息。需要登录和 CSRF。 |
| POST | /api/auth/2fa/enable | 校验动态码并正式启用两步验证。需要登录和 CSRF。 |
| POST | /api/auth/2fa/disable | 使用动态码或密码停用两步验证并清理信任设备 Cookie。需要登录和 CSRF。 |
| POST | /api/auth/2fa/verify | 在登录流程中验证 TOTP 或信任设备挑战。 |
后台接口 /api/admin/*
所有后台接口都需要有效的 session 会话。除 GET 只读接口外，写操作还需要 CSRF token。后台接口的返回字段通常直接对应页面需要的数据，新增或修改字段时应同步更新 app/types/apis/admin 中的类型。
仪表盘和系统
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/admin/stats | 后台首页统计。 |
| GET | /api/admin/detailed-stats | 详细统计数据。 |
| GET | /api/admin/recent-contents | 最近文章。 |
| GET | /api/admin/popular-contents | 热门文章。 |
| GET | /api/admin/recent-comments | 最近评论。 |
| GET | /api/admin/system-info | 服务端版本、运行环境和系统信息。 |
| GET | /api/admin/pages | 后台自定义页面列表。 |
| GET | /api/admin/settings | 读取系统设置和字段元数据。 |
| POST | /api/admin/settings | 保存系统设置。 |
| POST | /api/admin/settings/init | 初始化默认设置。 |
| POST | /api/admin/mail/test | 发送测试邮件，验证 SMTP 配置。 |
| POST | /api/admin/cache/clear | 清理全部、预设或指定 Redis 缓存。 |
文章、页面、分类和标签
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/admin/contents | 分页读取后台文章列表。 |
| POST | /api/admin/contents | 创建文章或页面内容记录。 |
| GET | /api/admin/contents/:cid | 读取文章/页面详情。 |
| PUT | /api/admin/contents/:cid | 更新文章正文、标题、封面、状态等字段。 |
| DELETE | /api/admin/contents/:cid | 删除文章或页面。 |
| PATCH | /api/admin/contents/:cid/autosave | 草稿云端自动同步：仅写正文与 update_time，不动元数据；草稿保存见 撰写文章 |
| POST | /api/admin/contents/batch-delete | 批量删除内容。 |
| GET | /api/admin/content-categories/:id | 读取内容关联的分类。 |
| PUT | /api/admin/content-categories/:id | 更新内容与分类的关联。 |
| GET | /api/admin/content-tags/:id | 读取内容关联的标签。 |
| PUT | /api/admin/content-tags/:id | 更新内容与标签的关联。 |
| GET | /api/admin/categories | 读取全部分类。 |
| POST | /api/admin/categories/create | 创建分类。 |
| PUT | /api/admin/categories/:id | 更新分类。 |
| DELETE | /api/admin/categories/:id | 删除分类。 |
| GET | /api/admin/tags | 读取全部标签。 |
| POST | /api/admin/tags | 创建标签。 |
| PUT | /api/admin/tags/:id | 更新标签。 |
| DELETE | /api/admin/tags/:id | 删除标签。 |
附件、评论和更新日志
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/admin/attachments/all | 分页读取全部附件，支持类型和文件名筛选。 |
| GET | /api/admin/attachments/:id | 读取附件详情、元数据和关联内容。 |
| PATCH | /api/admin/attachments/:id | 修改附件标题或调整关联内容。 |
| GET | /api/admin/comments | 按文章、状态和分页读取评论。 |
| PATCH | /api/admin/comments/:id | 修改评论内容、状态或审核结果。 |
| DELETE | /api/admin/comments/:id | 删除评论。 |
| POST | /api/admin/comments/batch-delete | 批量删除评论。 |
| GET | /api/admin/changelogs | 读取后台更新日志。 |
| POST | /api/admin/changelogs | 新增更新日志记录。 |
| PUT | /api/admin/changelogs/:id | 修改更新日志记录。 |
| DELETE | /api/admin/changelogs/:id | 删除更新日志记录。 |
| POST | /api/admin/changelogs/batch-delete | 批量删除更新日志。 |
| POST | /api/admin/changelogs/import | 事务性导入 JSON 更新日志。 |
点赞管理
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/admin/likes/:cid | 分页读取指定文章的点赞列表，含 IP、User-Agent 摘要、指纹前 8 位与时间。 |
| DELETE | /api/admin/likes/:cid/:id | 单条删除点赞记录，用于清理刷量；CSRF 从 header 读取。 |
友链、订阅和旅行地图
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/admin/links | 读取友链和待审核修改。 |
| POST | /api/admin/links | 在后台新增友链。 |
| PATCH | /api/admin/links/:id | 修改友链。 |
| PATCH | /api/admin/links/:id/toggle | 启用或停用友链。 |
| DELETE | /api/admin/links/:id | 删除友链。 |
| PATCH | /api/admin/links/:id/approve-modification | 通过或拒绝友链修改申请。 |
| GET | /api/admin/subscribes | 读取订阅源列表。 |
| POST | /api/admin/subscribes | 新增订阅源。 |
| PUT | /api/admin/subscribes/:id | 修改订阅源。 |
| DELETE | /api/admin/subscribes/:id | 删除订阅源。 |
| GET | /api/admin/subscribes/stats | 返回订阅源更新统计。 |
| POST | /api/admin/subscribes/update | 立即刷新订阅源。 |
| GET | /api/admin/travels | 读取旅行地点。 |
| POST | /api/admin/travels | 创建旅行地点。 |
| PUT | /api/admin/travels/:id | 更新旅行地点和文章关联。 |
| DELETE | /api/admin/travels/:id | 删除旅行地点。 |
数据备份、用户和信任设备
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/admin/data/export | 流式导出业务数据备份，不包含用户和会话表。 |
| POST | /api/admin/data/import | 在事务中清空并恢复业务数据，要求备份版本和表结构完整。 |
| GET | /api/admin/users/:id | 读取当前登录用户本人的用户信息；访问其他 uid 返回 403。 |
| PUT | /api/admin/users/:id | 修改当前登录用户本人的资料或密码；访问其他 uid 返回 403。 |
| GET | /api/admin/2fa/devices | 列出信任设备，并根据 IP 动态解析位置和运营商。 |
| PUT | /api/admin/2fa/devices/:id | 修改信任设备名称。 |
| DELETE | /api/admin/2fa/devices/:id | 撤回信任设备。 |
小程序接口 /api/mini/*
这些接口为小程序页面提供与主站对应的轻量数据。生产环境统一经过 HMAC 中间件；接口本身不使用主站后台 session。
| 方法 | 路径 | 用途 |
|---|---|---|
| OPTIONS | /api/mini/* | CORS 预检，返回小程序接口允许的跨域响应头。 |
| GET | /api/mini/archive | 小程序归档数据。 |
| GET | /api/mini/categories | 小程序分类列表。 |
| GET | /api/mini/category/:slug/contents | 小程序分类文章分页。 |
| GET | /api/mini/changelogs | 小程序更新日志。 |
| GET | /api/mini/comments | 小程序评论列表。 |
| POST | /api/mini/comments | 小程序提交评论。 |
| GET | /api/mini/content/:id | 小程序文章详情。 |
| GET | /api/mini/latest-contents | 小程序首页最新文章。 |
| GET | /api/mini/links | 小程序友链和订阅站点。 |
| GET | /api/mini/messages-config | 小程序留言/评论配置。 |
| GET | /api/mini/music | 小程序音乐数据。 |
| GET | /api/mini/repo | 小程序仓库卡片数据。 |
| GET | /api/mini/travels | 小程序旅行地点和地图数据。 |
非 API 路由
这些路由位于 server/routes，因此路径不带 /api：
| 方法 | 路径 | 源码文件 | 用途 |
|---|---|---|---|
| GET | /feed | server/routes/feed.get.ts | RSS 订阅源。 |
| GET | /sitemap.xml | server/routes/sitemap.xml.get.ts | XML 站点地图。 |
| GET | /uploads/* | server/routes/uploads/[...path].get.ts | UPLOADS_DIR 位于 public 外时的本地附件回源。 |
| ALL | /_AMapService/* | server/routes/_AMapService/[...path].ts | 高德地图服务端代理。 |
新增接口时，应先确认它属于公开、认证、后台还是 mini 域，再选择对应目录；后台写接口必须做会话和 CSRF 校验，公开查询接口应使用字段白名单，避免把数据库内部字段直接返回给客户端。