主题
八、接口与协议
本章速览:读完后你会知道 —— ① 四类 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 博客 | 21 | 95 | /api/admin/blog/*、/api/portal/blog/* |
module_memory 记忆 | 6 | 71 | /api/admin/hindsight*、/api/admin/life、/api/admin/memory/open-loops、/api/admin/ai/care |
module_system 系统 | 12 | 67 | /api/admin/auth、/api/admin/system*、/api/portal/{site,layout,captcha,subscriber}、/api/health |
module_ai AI | 8 | 59 | /api/admin/ai/{chat,kb,digest,avatar,writing,prompt,image}、/api/portal/ai/avatar |
platform 扩展 | 4 | 58 | /api/admin/extensions、/api/extensions、/api/internal/agent-capability* |
module_daily 日程 | 6 | 35 | /api/admin/daily*、/api/portal/daily |
module_ops 运维 | 7 | 27 | /api/admin/system/ops*、/api/admin/ops*、/api/admin/system/{export,import} |
module_agent 助手 | 7 | 21 | /api/admin/ai/{profile,agent-prompt,assistant-metrics}、/api/admin/agent/token、/api/agent、/api/agent/mcp |
module_note 笔记 | 2 | 20 | /api/admin/note、/api/admin/note/notebook |
module_conversation 会话采集 | 5 | 11 | /api/admin/agent/sessions、/api/agent/{ingest,heartbeat,chat/attachments}、/api/admin/chat/attachments |
module_llm 模型 | 1 | 5 | /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 条控制台报错 |