Skip to content

八、接口与协议 ​

本章速览:读完后你会知道 —— ① 四类 HTTP 面(后台/门户/Agent/健康)分别怎么鉴权;② 响应、分页、错误码、时间与大整数的统一约定;③ 哪些端点故意没有 UI 入口;④ 完整端点表在附录 L(参考层,按需检索)。

后端暴露四类 HTTP 面:后台管理(JWT)、门户公开(只读+访客写)、Agent(专用令牌)、 健康检查(公开最小信息)。全部端点的逐条清单在 附录 L;这里讲鉴权、协议约定与 "没有 UI 入口的端点"为什么存在。

8.0 读这一章最该记住的三件事 ​

  • 响应永远可判断:code=0/200 成功;其余按附录 D 错误码表解释,success 是派生字段。
  • 协议层错误用状态码:401 未登录、403 无权限/IP 限制、404 资源不存在、405 方法不对、 409 课程冲突、413 上传超限;业务错误一律 200 + code。
  • 分页与时间统一:pageNum/pageSize → {records,total,current,size};时间字符串按 Asia/Shanghai 输出,大整数 ID 输出为字符串。

接口清单是参考部分:路径、方法、鉴权由 check-doc-coverage.mjs 从控制器注解逐条扫描核对。 设计相关的内容只在 §5.1(鉴权矩阵)、§5.1.1(渲染安全边界)、§5.5(协议约定)三处。

8.1 鉴权矩阵 ​

路径前缀鉴权方式实现谁在用
/api/admin后台 JWT(Authorization: Bearer)AuthInterceptor + JwtUtil后台前端
/api/agent采集令牌(Authorization: Bearer cosmos_agent_…)AgentAuthInterceptor本机采集器、DSH 工具
/api/portal公开;写操作按类型设防(见下表)—门户前端、访客
/api/internal一次性 run token(X-Run-Token + runId 绑定)ExtensionRunTokenService扩展运行时/沙箱回调
/api/health公开—探针、监控

访客写操作的防护(不是验证码一刀切):

操作防护
提交评论按 IP 限流:60 秒 1 条(comment:ip:*)
提交留言按 IP 限流:60 秒 1 条 且 每天 20 条(message:ip:* / message:ip:day:*)
订阅/取消订阅验证码(CaptchaService,唯一使用验证码的访客写接口)
访客 AI 分身每会话每日限额(site.ai.avatar.daily-limit,0=不限)

8.1.1 渲染安全边界(2026-11-17 审查 #20 逐项实测) ​

为什么单列一节:门户把 服务端渲染好的 HTML 直接 v-html 输出, 这条链路一旦"往可信卫生区里塞了访客可控内容",就是存储型 XSS。 当前的做法是按来源分区,而不是对所有内容统一消毒:

内容渲染方式安全性由什么保证
文章正文 / 自定义页面 / widget 的 text_html服务端 Markdown → HTML → v-html只有博主可写;MarkdownRenderer 有意 escapeHtml=false(保留 iframe/video 嵌入能力),但开了 sanitizeUrls(true)(javascript:/data: 链接被清空);MarkdownRendererTest 锁定该取舍
第三方 Markdown 导入(Hexo/WordPress)先 escapeHtmlForImport() 把 < 转义再渲染导入内容来自外部,不当作可信输入;有测试覆盖
评论 / 留言 / 友链 / 说说纯文本插值(Vue 自动转义)从不进 v-html;实测 CommentSection 的正文是文本插值(不是 v-html)
AI 分身回答(共享/访客)纯文本插值(SSE 逐 token 追加,最后按文本插值输出)不进 Markdown 渲染器 → 提示词注入最多改措辞,不能变成 HTML
搜索高亮highlightKeyword():先按命中词切分、每段先转义再拼 <mark>src/utils/highlight.ts 注释与实现一致
上传图片白名单 jpg/jpeg/png/gif/webp/avif(SVG 已显式移除,理由写在代码注释:SVG 是可执行文档)+ magic-bytes 校验实测把 txt/exe 改名 .png 上传会被拒
/uploads/** 响应nginx 静态直出 + 继承 CSP / X-Content-Type-Options: nosniff / X-Frame-Options实测响应头齐全(CSP script-src 'self')
门户 Service Worker只接管门户;/admin 直接放行不接管;导航请求网络优先;版本号构建期注入public/sw.js;避免"发版后用户永远看旧壳"与"后台壳被门户覆盖"

结论:访客可控的每一个入口(评论/留言/友链/说说/AI 回答)都是纯文本插值, 不存在"把访客字符串喂给 HTML 渲染器"的路径;唯一允许原始 HTML 的正文来源被限定为博主本人。

附加保护:

  • IP 白名单:后台可配 site.security.admin-ip-whitelist,非白名单 IP 打后台接口被拒(AdminIpGuardInterceptor)。
  • 登录限流:按 IP,600 秒内最多 20 次(超限 code 20014)。
  • 失败锁定:连续失败达阈值锁定账号一段时间,写 sys_login_log。
  • 两步验证:开启后登录需 totpCode(6 位 TOTP 或 10 位恢复码)。

8.2 端点总览(79 控制器 / 468 个 verb·path 组合) ​

模块控制器端点主要基础路径
module_blog 博客2195/api/admin/blog/*、/api/portal/blog/*
module_memory 记忆671/api/admin/hindsight*、/api/admin/life、/api/admin/memory/open-loops、/api/admin/ai/care
module_system 系统1267/api/admin/auth、/api/admin/system*、/api/portal/{site,layout,captcha,subscriber}、/api/health
module_ai AI859/api/admin/ai/{chat,kb,digest,avatar,writing,prompt,image}、/api/portal/ai/avatar
platform 扩展458/api/admin/extensions、/api/extensions、/api/internal/agent-capability*
module_daily 日程635/api/admin/daily*、/api/portal/daily
module_ops 运维727/api/admin/system/ops*、/api/admin/ops*、/api/admin/system/{export,import}
module_agent 助手721/api/admin/ai/{profile,agent-prompt,assistant-metrics}、/api/admin/agent/token、/api/agent、/api/agent/mcp
module_note 笔记220/api/admin/note、/api/admin/note/notebook
module_conversation 会话采集511/api/admin/agent/sessions、/api/agent/{ingest,heartbeat,chat/attachments}、/api/admin/chat/attachments
module_llm 模型15/api/admin/ai/provider

8.3 无 UI 入口的端点(运维 / 通道 / 调试 / 旧路径) ​

后端有 415 个 admin 端点,其中 11 个前端不调用。逐个核对源码后的分类如下 —— 写在这里是为了避免以后误判"少了页面"或"没人用可以删"。 (判定方法见 docs/tools/check-api-wiring.mjs:前端 332 条路径 ↔ 后端 415 个 admin 端点双向比对。)

A. 通道/运维专用(保留,不接 UI 是设计)

端点用途
GET /api/admin/ai/care关怀记录列表(供 MCP / 运维排查;后台无"关怀"页面)
GET /api/admin/ai/care/{id}单条关怀详情(回溯"凭什么发这条")
POST /api/admin/ai/care/{id}/reply通道侧落点:微信/网页把博主回复交进来,服务推导类型并写长期记忆(MCP care_reply 同源)
GET /api/admin/daily/holiday/status节假日数据源状态(运维诊断)
GET /api/admin/daily/holiday/judge单日节假日判定(排查"为什么今天判成工作日")
GET /api/admin/system/security/status安全中心状态(登录告警/白名单/IP 统计)—— 后台安全页用的是别的组合端点
GET /api/admin/system/storage/status存储状态(磁盘/上传目录)—— 运维诊断用
POST /api/admin/hindsight/knowledge-nodes知识页节点创建(控制台只读,写入口留给运维脚本)
GET /api/admin/ai/digest总结列表(旧入口;后台已改用 /ai/digest/list)
GET /api/admin/daily/reminder提醒列表(旧入口;后台提醒数据随日程概览一起返回)

B. 调试用(保留)

端点用途
POST /api/admin/ai/chat/send同步(非流式)对话,供调试/内部调用;前端只用 SSE 的 /stream

兼容别名 system/config/nav*(4 个路径)已删除(2026-11-18 审查 #74): 全仓库 grep(前端/部署脚本/文档/测试)无调用方,仅 Java 映射里还留着别名; 保留的是 GET/POST /api/admin/system/nav 与 /nav/mobile-tabs(前端在用)。

8.4 协议与约定 ​

项约定
响应体{ code, message, data, success };code=0 或 200 为成功。success 由 R.isSuccess() getter 派生(不是独立字段),Jackson 自动序列化
分页入参 pageNum/pageSize;出参 { records, total, current, size }
流式AI 对话/写作走 text/event-stream;前端 fetch + ReadableStream 解析
幂等对话按 requestId;采集按 (sessionId, lineNo);主动消息按 dedupKey
时间格式yyyy-MM-dd HH:mm:ss(Jackson 统一配置)
大整数雪花 ID 以字符串返回(JacksonConfig 序列化 Long 为 String)
鉴权失败HTTP 401 + code 10002(前端据此跳登录);参数错误 code 10001(HTTP 200)
文件上传multipart/form-data;后端校验类型/大小(图片可选压缩水印)→ 落 sys_file,返回相对 URL
Markdown 编辑器后台 md-editor-v3;其代码高亮/公式/图表扩展依赖外部 CDN,而站点 CSP 禁止外链,故已关闭(no-highlight/no-katex/no-mermaid/no-echarts),避免每页 6 条控制台报错

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。