Files
lpt-ai/roles/security-and-degradation.md
cat-shark 935f4781a4 feat: 采集 LLM token 用量并上报 lpt-be
- 客户端解析上游 usage(含 DeepSeek 缓存命中/未命中),跨重试累加
- 新增计价表(三档单价 + 峰谷时段),费用在结算时冻结
- 新增用量上报与本地 outbox 重试;4xx 判定为确定性拒绝,不无限重试
- 面板补充 Token/费用/调用次数与计价快照
- 顺带修复面板内联脚本转义错误(模板字面量吃掉 \n 与 \',面板一直空白)
2026-10-10 18:46:01 +08:00

2.9 KiB
Raw Permalink Blame History

安全边界与降级策略

  • 功能:说明 lpt-ai 的入站令牌、限流、抓取加固、/admin 暴露边界,以及 LLM 不可用时的降级路径。
  • 何时用:改动鉴权、限流、/fetch-title 抓取逻辑、/admin 暴露范围,或处理 LLM 不可用 / 降级行为时。

安全边界

本服务是 ClusterIP 且未被 Traefik 路由,公网不可达;但集群内任何工作负载都能访问它,因此仍有防护:

  • 入站令牌(可选):设置 LPT_AI_TOKEN 后,/ai/* 与 /admin 都要求携带,按 header x-api-token → query token → cookie lpt_ai_token 的优先级取值。 cookie 这一路是给面板用的:面板 HTML 与它后续的 fetch 是两个独立请求,只在 URL 上带令牌会让 HTML 打得开而内部请求全部 401。 用 /admin?token=… 首次访问时换发一个 HttpOnly; SameSite=Strict; Path=/admin 的 cookie(依赖零新增依赖的手写 set-cookie)。 部署清单用 secretKeyRef.optional: true 引用 lpt-secrets/lpt-ai-token,没设这个 key 也能正常启动(此时不校验)。 lpt-be 侧由 lpt.ai-service.token 提供,部署经 LPT_AI-SERVICE_TOKEN 注入。 开发阶段可以不设,保持零摩擦;生产只需往 secret 加一个 key。
  • 限流:/ai/tasks 按来源限流(默认 30 次/分钟),因为是单进程内存计数,属于粗粒度保护,不是精确配额。
  • 抓取加固:/fetch-title 的目标由调用方给出,抓取前做四层校验 —— 协议白名单、端口白名单、DNS 解析后逐个校验(防解析到内网与 DNS rebinding)、重定向逐跳校验(防「首跳合法、次跳内网」);响应体截断到 512 KiB,且只在网页类型上取标题。
  • /admin 面板会展示完整 prompt 与学习内容,未设置令牌时会启动告警提示。
  • 用量上报出口:POST {lpt-be}/internal/ai-usage/records,用 LPT_AI_REPORT_TOKEN 与 lpt-be 的 lpt.ai-usage.report-token 对接。 上报载荷只含 token 计数、费用与任务元信息,不含 prompt 与学习内容。未配置 LPT_AI_REPORT_URL 时不上报。
  • 面板的用量统计口径是「最近 500 条」(data/logs.json 环形缓冲),长期账本在 lpt-be 的 MySQL。 面板与前端页面数字不一致时,以前端页面为准。

/fetch-title 当前全工作区零调用(lpt-fe 走的是 lpt-be 的 /utils/fetch-title,用 Java 侧 TitleFetcher)。 保留它是为了满足安全条目的验收;如需精简可连同本文件的抓取工具一并删除。

降级策略

  • LLM API Key 未配置 → /health 返回 llmAvailable: false。
  • 后端(lpt-be)检测到 AI 不可用 → 自动切换到内置规则引擎(BuiltinMindMapGenerator)。
  • Java 后端是唯一调用方;本服务不直接暴露给前端(Service 是 ClusterIP,且 Traefik 未路由本服务)。