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

32 lines
2.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 安全边界与降级策略
- **功能**:说明 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 未路由本服务)。