Files
lpt-ai/src/routes/ai.ts
T
cat-shark 4aff5c03fe feat: 用量归属支持 callerRef 透传
- POST /ai/tasks 接受顶层可选 callerRef(限 64 字符),不进入 params、不参与幂等键、不进 prompt
- 结算时写进用量记录,lpt-be 据此做用户维度报表
- 复用已有任务时沿用原归属:那次 LLM 调用只发生一次,账算在原调用方头上
2026-10-10 20:08:51 +08:00

177 lines
6.4 KiB
TypeScript
Raw 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.
/**
* AI 能力路由(仅异步任务模式,旧同步端点已移除)
*/
import type { FastifyInstance } from "fastify";
import { isAvailable, loadConfig } from "../llm/client.js";
import { createTask, getTask, type TaskType } from "../task-queue.js";
import { logStore } from "../admin/store.js";
import { safeFetchText, UnsafeUrlError } from "../utils/ssrf-guard.js";
import { RateLimiter, intFromEnv } from "../utils/rate-limit.js";
import { checkToken } from "../utils/auth.js";
/**
* 归属标记的最大长度。
*
* 它会落进日志与 lpt-be 的 `ai_usage_records.user_id`(VARCHAR(255)),
* 在入口限长比让数据库截断更安全。
*/
const MAX_CALLER_REF_LENGTH = 64;
export async function aiRoutes(app: FastifyInstance): Promise<void> {
const config = loadConfig();
// 安全-03:AI 任务会消耗 LLM 额度,按来源限流(单进程粗粒度保护)
const taskLimiter = new RateLimiter({
limit: intFromEnv("LPT_AI_RATE_LIMIT", 30),
windowMs: intFromEnv("LPT_AI_RATE_WINDOW_MS", 60_000),
});
// 安全-03:可选的入站令牌。设置了 LPT_AI_TOKEN 时,所有 /ai/* 请求都必须携带
app.addHook("preHandler", async (request, reply) => {
if (!request.url.startsWith("/ai/")) return;
if (!checkToken(request, reply)) {
return reply;
}
return undefined;
});
/** 取限流用的来源标识:优先真实客户端 IP(后面有反代时取 X-Forwarded-For 首段) */
const clientKey = (request: { ip?: string; headers: Record<string, unknown> }): string => {
const forwarded = request.headers["x-forwarded-for"];
if (typeof forwarded === "string" && forwarded.trim()) {
return forwarded.split(",")[0].trim();
}
return request.ip ?? "unknown";
};
app.get("/health", async () => ({
status: "ok",
llmAvailable: isAvailable(config),
model: config.model,
}));
/** 提交 AI 任务,立即返回 taskId */
app.post<{
Body: {
type: string;
params: Record<string, unknown>;
/** 可选:显式幂等键,用于跨请求去重 */
idempotencyKey?: string;
/** 可选:跳过结果复用,强制重新生成 */
force?: boolean;
/** 可选:归属标记(lpt-be 传用户 id),原样写进用量记录;不参与幂等键 */
callerRef?: string;
};
}>("/ai/tasks", async (request, reply) => {
const { type, params, idempotencyKey, force, callerRef } = request.body ?? {};
const decision = taskLimiter.check(clientKey(request));
if (!decision.allowed) {
app.log.warn({ key: clientKey(request) }, "AI 任务提交被限流");
return reply
.status(429)
.header("retry-after", String(Math.ceil(decision.retryAfterMs / 1000)))
.send({ error: "提交太频繁了,请稍后再试" });
}
if (!type || !["aggregate-report", "generate-mind-map", "compare-recall", "guidance"].includes(type)) {
return reply.status(400).send({ error: "无效的 type,允许: aggregate-report, generate-mind-map, compare-recall, guidance" });
}
if (!params || typeof params !== "object") {
return reply.status(400).send({ error: "params 必须为非空对象" });
}
// 归属标记是 opaque 字符串,但必须限长:它会落进日志与数据库列(VARCHAR(64))
if (callerRef !== undefined && callerRef !== null) {
if (typeof callerRef !== "string" || callerRef.length > MAX_CALLER_REF_LENGTH) {
return reply
.status(400)
.send({ error: `callerRef 必须是不超过 ${MAX_CALLER_REF_LENGTH} 字符的字符串` });
}
}
const created = createTask(type as TaskType, params as Record<string, unknown>, {
...(typeof idempotencyKey === "string" && idempotencyKey.trim().length > 0
? { idempotencyKey }
: {}),
...(force === true ? { force: true } : {}),
...(typeof callerRef === "string" && callerRef.trim().length > 0
? { callerRef: callerRef.trim() }
: {}),
});
// 固定返回 201:Java 端 AiServiceClient 把非 201 当作提交失败,
// 所以不能改用 200 表达「复用」。复用信息放在响应体里。
return reply.status(201).send(created);
});
/** 查询任务状态与结果 */
app.get<{ Params: { taskId: string } }>("/ai/tasks/:taskId", async (request, reply) => {
const { taskId } = request.params;
const task = getTask(taskId);
if (!task) {
return reply.status(404).send({ error: "任务不存在" });
}
return task;
});
/**
* 抓取网页标题。
*
* <p>安全-03:目标由调用方给出,因此在抓取前做协议、端口、DNS 解析与逐跳重定向校验,
* 避免被当成探测内网与云元数据的跳板,同时对响应体做截断。</p>
*/
app.post<{ Body: { url: string } }>("/fetch-title", async (request, reply) => {
const { url } = request.body ?? {};
const t0 = Date.now();
if (!url || typeof url !== "string") {
return reply.status(400).send({ error: "无效的 URL" });
}
try {
const { body } = await safeFetchText(url);
const match = body.match(/<title[^>]*>([^<]+)<\/title>/i);
const title = match ? match[1].trim() : null;
logStore.add({
timestamp: new Date().toISOString(),
endpoint: "/fetch-title",
taskType: "fetch-title",
model: "",
attempts: 1,
// 抓标题不过 LLM,不计入用量统计
isLlmCall: false,
durationMs: Date.now() - t0,
status: 200,
requestBody: { url },
responseBody: { url, title },
});
return { url, title };
} catch (err) {
// 被安全校验拦下时返回 400(调用方的问题),其余按抓取失败处理
const blocked = err instanceof UnsafeUrlError;
const message = err instanceof Error ? err.message : String(err);
logStore.add({
timestamp: new Date().toISOString(),
endpoint: "/fetch-title",
taskType: "fetch-title",
model: "",
attempts: 1,
// 抓标题不过 LLM,不计入用量统计
isLlmCall: false,
durationMs: Date.now() - t0,
status: blocked ? 400 : 502,
requestBody: { url },
responseBody: { url, title: null },
error: message,
errorCode: blocked ? "unsafe_url" : "fetch_failed",
});
if (blocked) {
return reply.status(400).send({ error: message });
}
return { url, title: null };
}
});
}