From 1c3168277dbb9cd37567c9584fefad6c94c4b009 Mon Sep 17 00:00:00 2001 From: cat-shark <1716967236@qq.com> Date: Fri, 9 Oct 2026 15:52:25 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E5=AE=89=E5=85=A8?= =?UTF-8?q?=E8=BE=B9=E7=95=8C=E4=B8=8E=E6=96=B0=E5=A2=9E=E7=8E=AF=E5=A2=83?= =?UTF-8?q?=E5=8F=98=E9=87=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 12 ++++++++++++ AGENTS.md | 24 +++++++++++++++++++++++- 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/.env.example b/.env.example index bc05472..acb649e 100644 --- a/.env.example +++ b/.env.example @@ -25,3 +25,15 @@ LPT_AI_TTL_MS=3600000 LPT_AI_RESULT_CACHE_MS=600000 # 过期记录清理间隔(毫秒) LPT_AI_CLEANUP_MS=300000 + +# ===== 安全(安全-03)===== +# 入站令牌:设置后 /ai/* 与 /admin 都要求携带(header x-api-token 或 query token)。 +# 留空表示不校验,开发阶段可以不管;生产往 lpt-secrets 加 lpt-ai-token 即可生效。 +LPT_AI_TOKEN= +# AI 任务限流:每来源在窗口内允许的提交次数(单进程内存计数,粗粒度保护) +LPT_AI_RATE_LIMIT=30 +LPT_AI_RATE_WINDOW_MS=60000 +# 请求体上限(字节) +LPT_AI_BODY_LIMIT_BYTES=262144 +# 抓取标题允许的额外端口(逗号分隔);默认只允许 80/443 +LPT_AI_FETCH_ALLOWED_PORTS= diff --git a/AGENTS.md b/AGENTS.md index 7deeb7f..1baf0dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,15 +89,37 @@ LPT_AI_MAX_ATTEMPTS=3 # 单任务总尝试次数(含首次) LPT_AI_RETRY_BASE_MS=1000 # 退避首次等待,之后 ×2 LPT_AI_RETRY_MAX_MS=20000 # 单次退避上限 LPT_AI_RESULT_CACHE_MS=600000 # 已完成结果可被相同请求复用的窗口 + +# 安全(完整注释见 .env.example) +LPT_AI_TOKEN= # 入站令牌:设置后 /ai/* 与 /admin 都要求携带(留空=不校验) +LPT_AI_RATE_LIMIT=30 # 每来源每窗口允许提交的 AI 任务数 +LPT_AI_RATE_WINDOW_MS=60000 # 限流窗口 +LPT_AI_BODY_LIMIT_BYTES=262144 # 请求体上限 +LPT_AI_FETCH_ALLOWED_PORTS= # 抓取允许的额外端口(默认只有 80/443) ``` > 部署侧的变量在 `lpt-infra` 的 `dev/`、`prod/` configmap 里;本服务只读环境变量,默认值写在 `src/llm/client.ts` 与 `loadQueueConfig()` 里。 +## 安全边界 + +本服务是 `ClusterIP` 且未被 Traefik 路由,公网不可达;但集群内任何工作负载都能访问它,因此仍有防护: + +- **入站令牌(可选)**:设置 `LPT_AI_TOKEN` 后,`/ai/*` 与 `/admin` 都要求携带(header `x-api-token` 或 query `token`)。 + 部署清单用 `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 与学习内容,未设置令牌时会启动告警提示。 + +> `/fetch-title` 当前**全工作区零调用**(`lpt-fe` 走的是 `lpt-be` 的 `/utils/fetch-title`,用 Java 侧 `TitleFetcher`)。 +> 保留它是为了满足安全条目的验收;如需精简可连同本文件的抓取工具一并删除。 + ## 降级策略 - LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`。 - 后端(lpt-be)检测到 AI 不可用 → 自动切换到内置规则引擎(`BuiltinMindMapGenerator`)。 -- Java 后端是唯一调用方;本服务不直接暴露给前端,不做鉴权(部署在内网)。 +- Java 后端是唯一调用方;本服务不直接暴露给前端(Service 是 `ClusterIP`,且 Traefik 未路由本服务)。 ## 启动命令