Files
lpt-ai/src/admin/store.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

232 lines
7.9 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 路由的一次完整请求/响应,供 /admin 面板查看,
* 并携带该次请求的 token 用量与计价快照。
*
* 设计要点:
* - 这里只是**最近的调试视图**:真正的长期账本在 lpt-be 的 MySQL(见 reporter.ts)。
* 因此保留条数有限,用量统计的权威口径不在这个文件里。
* - **原子落盘**:直写会在进程被杀时留下截断的 JSON,把连同历史用量在内的
* 整个文件一起毁掉,所以先写临时文件再 rename 替换。
* - `usage` 里的字段可以为 null(上游未上报),**不要用 0 代替**。
*/
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { resolve } from "node:path";
import { randomUUID } from "node:crypto";
import type { TokenUsage, UsageSource } from "../llm/usage.js";
import type { PricingSnapshot } from "./pricing.js";
import { usageReporter } from "./reporter.js";
// ---- 类型 ----
export interface LogEntry {
id: number;
/** 上报幂等键:lpt-be 按它去重,重复推送不会重复入账 */
recordId: string;
timestamp: string; // ISO 8601
endpoint: string; // 如 "/ai/tasks#aggregate-report"
/** 任务类型;`/fetch-title` 这类非任务端点为空 */
taskType?: string;
/** 任务标识,便于把面板上的一条日志对回具体任务 */
taskId?: string;
/** 归属标记(lpt-be 传的用户 id);为空表示调用方没传或为独立调用 */
callerRef?: string;
model: string;
/** 本次请求实际发起的 LLM 调用次数(含失败重试);重试会重复计费 */
attempts?: number;
/** false 表示这次请求没有消耗 LLM(如抓取网页标题) */
isLlmCall: boolean;
usage?: TokenUsage;
usageSource?: UsageSource;
/** 结算时算好并冻结的费用;null 表示用量未上报、无法计价 */
costUsd?: number | null;
pricing?: PricingSnapshot;
durationMs: number;
status: number; // HTTP status code
requestBody: unknown; // Java 端发来的原始请求体
messages?: unknown[]; // 构造后发给 LLM 的 messages(含 system prompt)
params?: Record<string, unknown>; // 模型调用参数(temperature、max_tokens 等)
responseBody: unknown;
error?: string;
/** 失败分类,便于按错误类型聚合(timeout / rate_limited / ...) */
errorCode?: string;
}
export interface LogSummary {
id: number;
timestamp: string;
endpoint: string;
taskType?: string;
callerRef?: string;
model: string;
attempts?: number;
isLlmCall: boolean;
usage?: TokenUsage;
usageSource?: UsageSource;
costUsd?: number | null;
durationMs: number;
status: number;
error?: string;
errorCode?: string;
}
// ---- 存储实现 ----
/** 面板只展示最近若干条;长期账本在 lpt-be,这里不需要留太多 */
const MAX_ENTRIES = 500;
/**
* 数据目录。
*
* 可配置是为了两件事:部署时能挂卷,以及**测试不污染开发者的真实面板数据**——
* 单例默认写在 `process.cwd()/data`,测试里一旦触发落盘就会把真实的 logs.json 清掉。
* 路径惰性解析:ESM 的 import 先于测试里设置环境变量执行,模块顶层解析会读不到。
*/
function dataDir(): string {
const configured = (process.env.LPT_AI_DATA_DIR ?? "").trim();
return configured.length > 0 ? configured : resolve(process.cwd(), "data");
}
function logFile(): string {
return resolve(dataDir(), "logs.json");
}
/**
* 把旧格式的历史日志补齐到当前结构。
*
* 用量字段是这次才加的,旧条目没有 `isLlmCall` 也没有 `recordId`;
* 不补的话它们会被当成「非 LLM 请求」而从用量统计里静默消失(比报错更难发现)。
* 旧条目无法回溯 token,所以用量保持未上报,但 `isLlmCall` 可以从端点推出。
*/
function migrateEntry(entry: LogEntry): LogEntry {
return {
...entry,
recordId: entry.recordId ?? randomUUID(),
isLlmCall: entry.isLlmCall ?? entry.endpoint.startsWith("/ai/tasks"),
};
}
export class LogStore {
private entries: LogEntry[] = [];
private nextId = 1;
private dirty = false;
private loaded = false;
/** 追加一条日志,超出上限时移除最旧的;同时投递到用量上报队列 */
add(entry: Omit<LogEntry, "id" | "recordId"> & { recordId?: string }): LogEntry {
this.ensureLoaded();
const full: LogEntry = { id: this.nextId++, recordId: entry.recordId ?? randomUUID(), ...entry };
this.entries.push(full);
while (this.entries.length > MAX_ENTRIES) {
this.entries.shift();
}
this.dirty = true;
this.flush(); // fire-and-forget
// 上报失败由 reporter 自己持久化重试,这里不阻塞请求
usageReporter.enqueue(full);
return full;
}
/** 列出摘要(不含请求/响应体,减少面板传输量) */
list(endpoint?: string): LogSummary[] {
this.ensureLoaded();
let result = [...this.entries];
if (endpoint) {
result = result.filter((e) => e.endpoint === endpoint);
}
// 倒序:最新在前
result.reverse();
return result.map((entry) => ({
id: entry.id,
timestamp: entry.timestamp,
endpoint: entry.endpoint,
...(entry.taskType !== undefined ? { taskType: entry.taskType } : {}),
...(entry.callerRef !== undefined ? { callerRef: entry.callerRef } : {}),
model: entry.model,
...(entry.attempts !== undefined ? { attempts: entry.attempts } : {}),
isLlmCall: entry.isLlmCall,
...(entry.usage !== undefined ? { usage: entry.usage } : {}),
...(entry.usageSource !== undefined ? { usageSource: entry.usageSource } : {}),
...(entry.costUsd !== undefined ? { costUsd: entry.costUsd } : {}),
durationMs: entry.durationMs,
status: entry.status,
...(entry.error !== undefined ? { error: entry.error } : {}),
...(entry.errorCode !== undefined ? { errorCode: entry.errorCode } : {}),
}));
}
/** 获取单条完整日志 */
get(id: number): LogEntry | undefined {
this.ensureLoaded();
return this.entries.find((e) => e.id === id);
}
/** 清空 */
clear(): void {
this.ensureLoaded();
this.entries = [];
this.dirty = true;
this.flush();
}
/** 端点列表(用于筛选下拉) */
endpoints(): string[] {
this.ensureLoaded();
return [...new Set(this.entries.map((e) => e.endpoint))].sort();
}
// ---- 持久化 ----
private ensureLoaded(): void {
if (this.loaded) return;
this.loaded = true;
this.load();
}
private load(): void {
try {
const file = logFile();
if (existsSync(file)) {
const raw = readFileSync(file, "utf-8");
const data = JSON.parse(raw) as { nextId: number; entries: LogEntry[] };
this.nextId = data.nextId ?? 1;
this.entries = (data.entries ?? []).map((entry) => migrateEntry(entry));
// 裁剪
while (this.entries.length > MAX_ENTRIES) {
this.entries.shift();
}
}
} catch {
// 文件损坏或不存在,使用空存储
}
}
private flush(): void {
if (!this.dirty) return;
this.dirty = false;
try {
const dir = dataDir();
const file = logFile();
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
// 先写临时文件再原子替换:直写被中断会留下截断的 JSON,
// 下次启动读不出来就把历史用量一起丢了
const tmpFile = `${file}.tmp`;
writeFileSync(tmpFile, JSON.stringify({ nextId: this.nextId, entries: this.entries }), "utf-8");
renameSync(tmpFile, file);
} catch {
// 写入失败不阻塞服务
}
}
}
export const logStore = new LogStore();
/** 仅用于测试:重置内部状态,避免用例之间互相污染 */
export function resetLogStoreForTest(): void {
logStore.clear();
}