From 935f4781a4de0f888d3579bcd6c5f4f6585bd9d3 Mon Sep 17 00:00:00 2001 From: cat-shark <1716967236@qq.com> Date: Sat, 10 Oct 2026 18:46:01 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E9=87=87=E9=9B=86=20LLM=20token=20?= =?UTF-8?q?=E7=94=A8=E9=87=8F=E5=B9=B6=E4=B8=8A=E6=8A=A5=20lpt-be?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 客户端解析上游 usage(含 DeepSeek 缓存命中/未命中),跨重试累加 - 新增计价表(三档单价 + 峰谷时段),费用在结算时冻结 - 新增用量上报与本地 outbox 重试;4xx 判定为确定性拒绝,不无限重试 - 面板补充 Token/费用/调用次数与计价快照 - 顺带修复面板内联脚本转义错误(模板字面量吃掉 \n 与 \',面板一直空白) --- .env.example | 32 ++++ AGENTS.md | 50 ++++- roles/security-and-degradation.md | 8 +- src/admin/balance.test.ts | 117 ++++++++++++ src/admin/balance.ts | 109 +++++++++++ src/admin/index.ts | 20 +- src/admin/pricing.test.ts | 166 +++++++++++++++++ src/admin/pricing.ts | 231 +++++++++++++++++++++++ src/admin/reporter.test.ts | 290 +++++++++++++++++++++++++++++ src/admin/reporter.ts | 299 ++++++++++++++++++++++++++++++ src/admin/routes.test.ts | 129 +++++++++++++ src/admin/routes.ts | 133 +++++++++++-- src/admin/store.test.ts | 162 ++++++++++++++++ src/admin/store.ts | 145 ++++++++++++--- src/index.ts | 11 ++ src/llm/client.test.ts | 74 ++++++++ src/llm/client.ts | 43 ++++- src/llm/usage.test.ts | 134 +++++++++++++ src/llm/usage.ts | 161 ++++++++++++++++ src/routes/ai.ts | 9 + src/task-queue.test.ts | 151 ++++++++++++++- src/task-queue.ts | 85 ++++++++- src/utils/auth.test.ts | 85 ++++++++- src/utils/auth.ts | 53 +++++- 24 files changed, 2632 insertions(+), 65 deletions(-) create mode 100644 src/admin/balance.test.ts create mode 100644 src/admin/balance.ts create mode 100644 src/admin/pricing.test.ts create mode 100644 src/admin/pricing.ts create mode 100644 src/admin/reporter.test.ts create mode 100644 src/admin/reporter.ts create mode 100644 src/admin/routes.test.ts create mode 100644 src/admin/store.test.ts create mode 100644 src/llm/usage.test.ts create mode 100644 src/llm/usage.ts diff --git a/.env.example b/.env.example index 5be7160..0444898 100644 --- a/.env.example +++ b/.env.example @@ -49,3 +49,35 @@ LPT_AI_RATE_WINDOW_MS=60000 LPT_AI_BODY_LIMIT_BYTES=262144 # 抓取标题允许的额外端口(逗号分隔);默认只允许 80/443 LPT_AI_FETCH_ALLOWED_PORTS= + +# ===== 用量统计 ===== +# 上游余额对账地址;留空时按 LLM_API_URL 的 origin 推导(DeepSeek 为 /user/balance)。 +# 余额只是辅助信息,查询失败不会影响用量面板。 +LLM_BALANCE_URL= +LLM_BALANCE_TIMEOUT_MS=10000 + +# 计价表(USD / 1M tokens,填 DeepSeek 官方 PEAK 一列) +LLM_PRICE_CACHE_HIT_PER_M=0.006 +LLM_PRICE_CACHE_MISS_PER_M=0.3 +LLM_PRICE_OUTPUT_PER_M=1.2 +# 谷时价 = 峰时价 × 该系数;设为 1 即取消峰谷差异 +LLM_PRICE_OFFPEAK_FACTOR=0.5 +# 峰时窗口(UTC,HH:mm-HH:mm,逗号分隔);留空回退到 DeepSeek 公布的 01:00-04:00,06:00-10:00 +LLM_PRICE_PEAK_WINDOWS=01:00-04:00,06:00-10:00 +# 按谷时计价的日期(UTC 的 yyyy-MM-dd,逗号分隔),用于中国法定节假日;每年需要更新 +LLM_PRICE_PEAK_HOLIDAYS= +# 计价表版本;留空时由单价自动派生(改价即变版本,历史账不会被新价格重算) +LLM_PRICE_VERSION= + +# ---- 用量上报(lpt-ai → lpt-be)---- +# lpt-be 基地址;留空表示不上报,用量只保留在本地面板(没有长期账本,Pod 重建即丢) +LPT_AI_REPORT_URL= +# 与 lpt-be 的 lpt.ai-usage.report-token 一致 +LPT_AI_REPORT_TOKEN= +# 定时推送间隔(毫秒);上报失败会留在本地 outbox 里重试,不会丢数据 +LPT_AI_REPORT_INTERVAL_MS=15000 +# 单次推送条数上限 +LPT_AI_REPORT_BATCH_SIZE=50 +# outbox 上限;超过后丢弃最旧的,避免磁盘被写满 +LPT_AI_REPORT_MAX_PENDING=5000 +LPT_AI_REPORT_TIMEOUT_MS=10000 diff --git a/AGENTS.md b/AGENTS.md index 19f30ae..2bde69d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,23 +22,27 @@ ```text lpt-ai/src/ -├── index.ts → 服务入口(加载 .env,启动 Fastify) +├── index.ts → 服务入口(加载 .env,启动 Fastify 与用量上报) ├── routes/ai.ts → AI 路由(health, tasks, fetch-title) ├── llm/ -│ ├── client.ts → LLM 客户端(DeepSeek 接口) +│ ├── client.ts → LLM 客户端(DeepSeek 接口,返回正文 + token 用量) +│ ├── usage.ts → 用量归一化(null 与 0 区分、跨尝试累加) │ ├── thinking.ts → 按 prompt 长度选思考强度(reasoning_effort) │ ├── retry.ts → 退避重试(哪些错误可重试、等多久) -│ ├── prompts.ts → Prompt 模板(3 种任务类型) +│ ├── prompts.ts → Prompt 模板(4 种任务类型) │ └── prompts.test.ts -├── task-queue.ts → 异步任务队列(Worker 池 + 幂等复用) +├── task-queue.ts → 异步任务队列(Worker 池 + 幂等复用 + 用量归集) ├── task-queue.test.ts └── admin/ ├── index.ts → 管理面板路由 ├── routes.ts - └── store.ts → 日志存储 + ├── store.ts → 日志存储(环形缓冲 + 原子落盘) + ├── pricing.ts → 计价(DeepSeek 三档单价 + 峰谷时段) + ├── reporter.ts → 用量上报(lpt-ai → lpt-be,本地 outbox 重试) + └── balance.ts → 上游余额查询(对账用) ``` -## API 端点(5 个) +## API 端点(6 个) | 方法 | 路径 | 说明 | |------|------|------| @@ -46,7 +50,25 @@ lpt-ai/src/ | POST | `/ai/tasks` | 提交异步任务(返回 taskId) | | GET | `/ai/tasks/:taskId` | 轮询任务结果 | | POST | `/fetch-title` | 抓取网页标题 | -| GET | `/admin` | 管理面板(查看最近 200 条日志) | +| GET | `/admin` | 管理面板(最近 500 条日志、用量与计价快照) | +| GET | `/admin/usage/balance` | 上游账户余额(对账用;未配置时 `configured:false`) | + +## 用量统计 + +用量是「任务级」口径,不是「请求级」:一个任务重试 N 次就是 N 次计费。 + +- `llm/usage.ts`:把上游 `usage` 归一成 6 个维度(输入/输出/总计/缓存命中/缓存未命中/推理)。 + **`null` 表示上游未上报,与「明确上报为 0」不同**,面板上必须区分显示。 +- `task-queue.ts`:跨所有尝试累加用量(含失败尝试,如上游 200 但内容为空);`attempts` 是实际发起的调用次数。 +- `admin/pricing.ts`:DeepSeek 三档单价(缓存命中/未命中/输出,USD per 1M)+ 峰谷时段。 + 峰时窗口按 UTC 判定(`01:00-04:00`、`06:00-10:00`,周一至周五),谷时 = 峰时 × 0.5。 + 计价结果在结算时**冻结进日志快照**,改价不会重算历史账。 +- `admin/reporter.ts`:把用量推给 lpt-be(长期账本)。上报失败先落本地 outbox 再重试, + 幂等靠 `record_id` 唯一索引。未配置 `LPT_AI_REPORT_URL` 时为空操作。 +- **权威口径在 lpt-be 的 MySQL**;本地面板只是最近 500 条的调试视图。 + +> `/admin` 用 `?token=…` 首次打开时会换发 `HttpOnly` cookie,否则面板 HTML 与它内部的 +> `fetch` 是两个独立请求,内部请求会全部 401。详见 `roles/security-and-degradation.md`。 ## 支持的任务类型 @@ -55,6 +77,7 @@ lpt-ai/src/ | `aggregate-report` | 残片聚合为学习报告 | 0.3 | 2048 | | `generate-mind-map` | 从报告/残片生成思维导图大纲 | 0.3 | 4096 | | `compare-recall` | 用户回忆 vs 标准导图语义对比 | 0.2 | 4096 | +| `guidance` | 学习引导多轮对话 | 0.7 | 1024 | | `guidance` | 学习引导单轮追问 | 0.7 | 1024 | > 思考强度(`reasoning_effort`)不按任务类型固定,而是按 **prompt 总字符数**(所有 message 正文之和)自适应: @@ -89,6 +112,19 @@ 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) + +# 用量统计(完整注释见 .env.example) +LLM_BALANCE_URL= # 留空按 LLM_API_URL 的 origin 推导 +LLM_PRICE_CACHE_HIT_PER_M=0.006 +LLM_PRICE_CACHE_MISS_PER_M=0.3 +LLM_PRICE_OUTPUT_PER_M=1.2 +LLM_PRICE_OFFPEAK_FACTOR=0.5 +LLM_PRICE_PEAK_WINDOWS=01:00-04:00,06:00-10:00 +LLM_PRICE_PEAK_HOLIDAYS= # 中国法定节假日,每年需要更新 + +# 用量上报(lpt-ai → lpt-be);留空表示不上报,只保留本地面板 +LPT_AI_REPORT_URL= +LPT_AI_REPORT_TOKEN= ``` > 部署侧的变量在 `lpt-infra` 的 `dev/`、`prod/` configmap 里;本服务只读环境变量,默认值写在 `src/llm/client.ts` 与 `loadQueueConfig()` 里。 diff --git a/roles/security-and-degradation.md b/roles/security-and-degradation.md index 10c0b62..49cb1aa 100644 --- a/roles/security-and-degradation.md +++ b/roles/security-and-degradation.md @@ -7,13 +7,19 @@ 本服务是 `ClusterIP` 且未被 Traefik 路由,公网不可达;但集群内任何工作负载都能访问它,因此仍有防护: -- **入站令牌(可选)**:设置 `LPT_AI_TOKEN` 后,`/ai/*` 与 `/admin` 都要求携带(header `x-api-token` 或 query `token`)。 +- **入站令牌(可选)**:设置 `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`)。 > 保留它是为了满足安全条目的验收;如需精简可连同本文件的抓取工具一并删除。 diff --git a/src/admin/balance.test.ts b/src/admin/balance.test.ts new file mode 100644 index 0000000..4d09de8 --- /dev/null +++ b/src/admin/balance.test.ts @@ -0,0 +1,117 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { deriveBalanceUrl, fetchUpstreamBalance, loadBalanceConfig } from "./balance.js"; + +const originalKey = process.env.LLM_API_KEY; +const originalUrl = process.env.LLM_API_URL; +const originalBalanceUrl = process.env.LLM_BALANCE_URL; + +afterEach(() => { + for (const [key, value] of [ + ["LLM_API_KEY", originalKey], + ["LLM_API_URL", originalUrl], + ["LLM_BALANCE_URL", originalBalanceUrl], + ] as const) { + if (value === undefined) { + delete process.env[key]; + } else { + process.env[key] = value; + } + } +}); + +describe("deriveBalanceUrl", () => { + it("从 chat completions 地址推导出同源余额地址", () => { + expect(deriveBalanceUrl("https://api.deepseek.com/v1/chat/completions")).toBe( + "https://api.deepseek.com/user/balance", + ); + }); + + it("地址非法时返回空串,由调用方判定为不可用", () => { + expect(deriveBalanceUrl("not-a-url")).toBe(""); + }); +}); + +describe("loadBalanceConfig", () => { + it("显式配置优先于推导值", () => { + const config = loadBalanceConfig({ + LLM_API_URL: "https://api.deepseek.com/v1/chat/completions", + LLM_BALANCE_URL: "https://proxy.test/balance", + }); + expect(config.url).toBe("https://proxy.test/balance"); + }); + + it("非法超时回退到缺省", () => { + expect(loadBalanceConfig({ LLM_BALANCE_TIMEOUT_MS: "-1" }).timeoutMs).toBe(10_000); + }); +}); + +describe("fetchUpstreamBalance", () => { + it("未配置 API Key 时不发请求,直接返回未配置", async () => { + delete process.env.LLM_API_KEY; + const fetchImpl = vi.fn(); + + await expect( + fetchUpstreamBalance({ fetchImpl: fetchImpl as unknown as typeof fetch }), + ).resolves.toEqual({ configured: false }); + expect(fetchImpl).not.toHaveBeenCalled(); + }); + + it("优先取人民币账户", async () => { + process.env.LLM_API_KEY = "key"; + const fetchImpl = vi.fn().mockResolvedValue({ + ok: true, + json: async () => ({ + balance_infos: [ + { currency: "USD", total_balance: "1.00", granted_balance: "0", topped_up_balance: "1.00" }, + { currency: "CNY", total_balance: "12.34", granted_balance: "0.00", topped_up_balance: "12.34" }, + ], + }), + } as Response); + + const result = await fetchUpstreamBalance({ + fetchImpl: fetchImpl as unknown as typeof fetch, + now: () => Date.parse("2026-10-10T09:00:00Z"), + }); + + expect(result).toEqual({ + configured: true, + currency: "CNY", + totalBalance: "12.34", + grantedBalance: "0.00", + toppedUpBalance: "12.34", + fetchedAt: "2026-10-10T09:00:00.000Z", + }); + }); + + it("没有人民币账户时取第一条,不返回空余额", async () => { + process.env.LLM_API_KEY = "key"; + const fetchImpl = vi.fn().mockResolvedValue({ + ok: true, + json: async () => ({ balance_infos: [{ currency: "USD", total_balance: "1.00" }] }), + } as Response); + + const result = await fetchUpstreamBalance({ fetchImpl: fetchImpl as unknown as typeof fetch }); + expect(result.configured).toBe(true); + expect(result.currency).toBe("USD"); + }); + + it("上游报错或响应缺字段时返回未配置,而不是抛错把面板打挂", async () => { + process.env.LLM_API_KEY = "key"; + + const failing = vi.fn().mockResolvedValue({ ok: false, status: 500 } as Response); + await expect( + fetchUpstreamBalance({ fetchImpl: failing as unknown as typeof fetch }), + ).resolves.toEqual({ configured: false }); + + const empty = vi.fn().mockResolvedValue({ ok: true, json: async () => ({}) } as Response); + await expect( + fetchUpstreamBalance({ fetchImpl: empty as unknown as typeof fetch }), + ).resolves.toEqual({ configured: false }); + + const throwing = vi.fn().mockRejectedValue(new Error("network down")); + await expect( + fetchUpstreamBalance({ fetchImpl: throwing as unknown as typeof fetch }), + ).resolves.toEqual({ configured: false }); + }); +}); diff --git a/src/admin/balance.ts b/src/admin/balance.ts new file mode 100644 index 0000000..a1977d6 --- /dev/null +++ b/src/admin/balance.ts @@ -0,0 +1,109 @@ +/** + * 上游账户余额查询(对账用)。 + * + * 设计要点: + * - 本地算出来的费用只是**估算**:单价表可能过期、峰谷判定可能偏差。 + * 拿上游余额的变化去比对,是唯一能发现「计价表已经不对了」的手段。 + * - 余额接口是供应商特有的(DeepSeek 是 `GET /user/balance`),因此地址可配置, + * 默认按 `LLM_API_URL` 的 origin 推导,换供应商时不必改代码。 + * - 查询失败一律返回 `configured:false` 而不是抛错:余额只是辅助信息, + * 不能因为它把用量面板整体打挂。 + */ + +export interface BalanceSnapshot { + /** false 表示未配置 API Key、供应商不支持或查询失败 */ + configured: boolean; + currency?: string; + totalBalance?: string; + grantedBalance?: string; + toppedUpBalance?: string; + fetchedAt?: string; +} + +export interface BalanceConfig { + url: string; + apiKey: string; + timeoutMs: number; +} + +export interface BalanceDeps { + fetchImpl?: typeof fetch; + now?: () => number; +} + +/** 从 chat completions 地址推导出同源的余额地址;推导不出来时返回空串 */ +export function deriveBalanceUrl(apiUrl: string): string { + try { + return `${new URL(apiUrl).origin}/user/balance`; + } catch { + return ""; + } +} + +export function loadBalanceConfig(env: NodeJS.ProcessEnv = process.env): BalanceConfig { + const apiUrl = env.LLM_API_URL ?? "https://api.deepseek.com/v1/chat/completions"; + const explicit = (env.LLM_BALANCE_URL ?? "").trim(); + const timeoutRaw = Number(env.LLM_BALANCE_TIMEOUT_MS ?? 10_000); + return { + url: explicit.length > 0 ? explicit : deriveBalanceUrl(apiUrl), + apiKey: (env.LLM_API_KEY ?? "").trim(), + timeoutMs: Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 10_000, + }; +} + +interface DeepSeekBalanceResponse { + balance_infos?: Array<{ + currency?: string; + total_balance?: string; + granted_balance?: string; + topped_up_balance?: string; + }>; +} + +/** 优先取人民币账户;找不到就取第一条,避免多币种账户下返回空 */ +function pickBalanceInfo( + infos: DeepSeekBalanceResponse["balance_infos"], +): NonNullable[number] | undefined { + if (!infos || infos.length === 0) return undefined; + return infos.find((info) => info.currency === "CNY") ?? infos[0]; +} + +export async function fetchUpstreamBalance( + deps: BalanceDeps = {}, +): Promise { + const config = loadBalanceConfig(); + if (config.apiKey.length === 0 || config.url.length === 0) { + return { configured: false }; + } + + const fetchImpl = deps.fetchImpl ?? fetch; + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), config.timeoutMs); + try { + const response = await fetchImpl(config.url, { + method: "GET", + headers: { Authorization: `Bearer ${config.apiKey}` }, + signal: controller.signal, + }); + if (!response.ok) { + return { configured: false }; + } + const data = (await response.json()) as DeepSeekBalanceResponse; + const info = pickBalanceInfo(data.balance_infos); + if (!info) { + return { configured: false }; + } + return { + configured: true, + currency: info.currency ?? "", + totalBalance: info.total_balance ?? "", + grantedBalance: info.granted_balance ?? "", + toppedUpBalance: info.topped_up_balance ?? "", + fetchedAt: new Date(deps.now ? deps.now() : Date.now()).toISOString(), + }; + } catch { + return { configured: false }; + } finally { + clearTimeout(timer); + } +} diff --git a/src/admin/index.ts b/src/admin/index.ts index 66bb516..6ebde00 100644 --- a/src/admin/index.ts +++ b/src/admin/index.ts @@ -1,2 +1,20 @@ -export { logStore, type LogEntry, type LogSummary } from "./store.js"; +export { logStore, resetLogStoreForTest, type LogEntry, type LogSummary } from "./store.js"; export { adminRoutes } from "./routes.js"; +export { + UsageReporter, + usageReporter, + loadReporterConfig, + toUsageRecord, + type UsageRecord, + type ReporterConfig, +} from "./reporter.js"; +export { fetchUpstreamBalance, type BalanceSnapshot } from "./balance.js"; +export { + loadPricingConfig, + priceUsage, + isPeak, + parsePeakWindows, + type PricingConfig, + type PricingSnapshot, + type PricedUsage, +} from "./pricing.js"; diff --git a/src/admin/pricing.test.ts b/src/admin/pricing.test.ts new file mode 100644 index 0000000..116858b --- /dev/null +++ b/src/admin/pricing.test.ts @@ -0,0 +1,166 @@ +import { describe, expect, it } from "vitest"; + +import { emptyUsage, type TokenUsage } from "../llm/usage.js"; +import { isPeak, loadPricingConfig, parsePeakWindows, priceUsage } from "./pricing.js"; + +function usage(partial: Partial): TokenUsage { + return { ...emptyUsage(), ...partial }; +} + +/** 2026-10-09 是周五;10-10/10-11 是周末;10-12 是周一 */ +function utc(iso: string): Date { + return new Date(iso); +} + +describe("parsePeakWindows", () => { + it("解析 HH:mm-HH:mm 列表", () => { + expect(parsePeakWindows("01:00-04:00,06:00-10:00")).toEqual([ + { startMinute: 60, endMinute: 240 }, + { startMinute: 360, endMinute: 600 }, + ]); + }); + + it("单条格式写错只跳过这一条,其余窗口仍生效", () => { + expect(parsePeakWindows("01:00-04:00,bad,06:00-10:00")).toEqual([ + { startMinute: 60, endMinute: 240 }, + { startMinute: 360, endMinute: 600 }, + ]); + }); + + it("起止相同的窗口视为无效", () => { + expect(parsePeakWindows("01:00-01:00")).toEqual([]); + }); + + it("不传时回退到 DeepSeek 公布的默认窗口", () => { + expect(parsePeakWindows(undefined)).toHaveLength(2); + }); +}); + +describe("isPeak", () => { + const config = loadPricingConfig({}); + + it("工作日落在峰时窗口内为峰时", () => { + expect(isPeak(utc("2026-10-09T02:00:00Z"), config)).toBe(true); + expect(isPeak(utc("2026-10-09T08:00:00Z"), config)).toBe(true); + }); + + it("工作日落在窗口外为谷时", () => { + expect(isPeak(utc("2026-10-09T00:30:00Z"), config)).toBe(false); + expect(isPeak(utc("2026-10-09T05:00:00Z"), config)).toBe(false); + expect(isPeak(utc("2026-10-09T12:00:00Z"), config)).toBe(false); + }); + + it("窗口右端开区间:04:00 整不算峰时", () => { + expect(isPeak(utc("2026-10-09T04:00:00Z"), config)).toBe(false); + }); + + it("周末一律谷时", () => { + expect(isPeak(utc("2026-10-10T02:00:00Z"), config)).toBe(false); + expect(isPeak(utc("2026-10-11T08:00:00Z"), config)).toBe(false); + }); + + it("配置为法定节假日的日期按谷时计价", () => { + const holiday = loadPricingConfig({ LLM_PRICE_PEAK_HOLIDAYS: "2026-10-12" }); + expect(isPeak(utc("2026-10-12T02:00:00Z"), holiday)).toBe(false); + // 未列入的周一仍按峰时 + expect(isPeak(utc("2026-10-12T02:00:00Z"), config)).toBe(true); + }); + + it("支持跨零点的窗口", () => { + const overnight = loadPricingConfig({ LLM_PRICE_PEAK_WINDOWS: "23:00-02:00" }); + expect(isPeak(utc("2026-10-09T23:30:00Z"), overnight)).toBe(true); + expect(isPeak(utc("2026-10-09T01:00:00Z"), overnight)).toBe(true); + expect(isPeak(utc("2026-10-09T03:00:00Z"), overnight)).toBe(false); + }); +}); + +describe("priceUsage", () => { + const config = loadPricingConfig({}); + + it("按峰时三档单价计价", () => { + const { costUsd, snapshot } = priceUsage( + usage({ cacheHitTokens: 1_000_000, cacheMissTokens: 1_000_000, completionTokens: 1_000_000 }), + utc("2026-10-09T02:00:00Z"), + config, + ); + + expect(snapshot.peak).toBe(true); + expect(costUsd).toBe(1.506); + }); + + it("谷时单价是峰时的一半", () => { + const { costUsd, snapshot } = priceUsage( + usage({ cacheHitTokens: 1_000_000, cacheMissTokens: 1_000_000, completionTokens: 1_000_000 }), + utc("2026-10-09T12:00:00Z"), + config, + ); + + expect(snapshot.peak).toBe(false); + expect(costUsd).toBe(0.753); + expect(snapshot.effectivePrices.cacheMissPerM).toBe(0.15); + expect(snapshot.listPrices.cacheMissPerM).toBe(0.3); + }); + + it("未上报用量时费用为 null,而不是 0", () => { + const { costUsd } = priceUsage(emptyUsage(), utc("2026-10-09T12:00:00Z"), config); + expect(costUsd).toBeNull(); + }); + + it("没有缓存明细时把整个 prompt 按未命中价计,宁可高估也不低估", () => { + const { costUsd } = priceUsage( + usage({ promptTokens: 1_000_000, completionTokens: 0 }), + utc("2026-10-09T02:00:00Z"), + config, + ); + expect(costUsd).toBe(0.3); + }); + + it("只有命中数没有未命中数时用 prompt - hit 兜底", () => { + const { costUsd } = priceUsage( + usage({ promptTokens: 1_000_000, cacheHitTokens: 400_000, completionTokens: 0 }), + utc("2026-10-09T02:00:00Z"), + config, + ); + // 40 万命中 × 0.006 + 60 万未命中 × 0.3 = 0.0024 + 0.18 + expect(costUsd).toBe(0.1824); + }); + + it("费用按 8 位小数收敛,避免浮点噪声写进 DECIMAL(18,8)", () => { + const { costUsd } = priceUsage( + usage({ promptTokens: 3, completionTokens: 7 }), + utc("2026-10-09T02:00:00Z"), + config, + ); + expect(String(costUsd)).toMatch(/^\d+(\.\d{1,8})?$/); + }); +}); + +describe("loadPricingConfig", () => { + it("缺省单价与官方 PEAK 一列一致", () => { + const config = loadPricingConfig({}); + expect(config.cacheHitPerM).toBe(0.006); + expect(config.cacheMissPerM).toBe(0.3); + expect(config.outputPerM).toBe(1.2); + expect(config.offpeakFactor).toBe(0.5); + }); + + it("环境变量可覆盖单价,并让版本号随之变化", () => { + const base = loadPricingConfig({}); + const changed = loadPricingConfig({ LLM_PRICE_OUTPUT_PER_M: "2.4" }); + + expect(changed.outputPerM).toBe(2.4); + // 版本号由单价派生,改价即变版本,避免历史账被新价格重算 + expect(changed.version).not.toBe(base.version); + }); + + it("显式版本号优先于派生值", () => { + const config = loadPricingConfig({ LLM_PRICE_VERSION: "2026-11 调价" }); + expect(config.version).toBe("2026-11 调价"); + }); + + it("非法单价回退到缺省值", () => { + const config = loadPricingConfig({ LLM_PRICE_OUTPUT_PER_M: "abc", LLM_PRICE_CACHE_HIT_PER_M: "-1" }); + expect(config.outputPerM).toBe(1.2); + expect(config.cacheHitPerM).toBe(0.006); + }); +}); diff --git a/src/admin/pricing.ts b/src/admin/pricing.ts new file mode 100644 index 0000000..98e0e67 --- /dev/null +++ b/src/admin/pricing.ts @@ -0,0 +1,231 @@ +/** + * LLM 计价 —— DeepSeek 三档单价 + 峰谷时段。 + * + * 设计要点: + * - **单价按「每百万 token 的美元价」配置**,不引入中转站那套倍率/钱包抽象: + * 本项目是单租户内部服务,没有余额可扣,倍率只会多一层浮点误差面。 + * - **峰谷价差必须算进去**:DeepSeek 谷时价是峰时价的一半,而峰时只占工作日的 7 小时。 + * 忽略它会将近一倍地高估费用(夜间与周末的调用全被按峰时价算)。 + * - **计价结果要冻结**:价格表会变,历史账不能被新价格改写,所以结算时把生效单价与 + * 是否峰时一并写进日志快照,而不是展示时现算。 + * - **中国法定节假日按谷时计价**,但节假日表每年都变,因此做成配置项而不是硬编码日历。 + */ + +import { hasUsage, type TokenUsage } from "../llm/usage.js"; + +/** UTC 分钟数区间;`startMinute > endMinute` 表示跨零点 */ +export interface PeakWindow { + startMinute: number; + endMinute: number; +} + +export interface PricingConfig { + /** 峰时:缓存命中输入 token 单价(USD / 1M tokens) */ + cacheHitPerM: number; + /** 峰时:缓存未命中输入 token 单价 */ + cacheMissPerM: number; + /** 峰时:输出 token 单价 */ + outputPerM: number; + /** 谷时价 = 峰时价 × 该系数;设为 1 即取消峰谷差异 */ + offpeakFactor: number; + peakWindows: PeakWindow[]; + /** 按谷时计价的日期(UTC 的 `yyyy-MM-dd`),用于中国法定节假日 */ + offpeakDates: string[]; + /** 计价表版本;不显式配置时由单价派生,改价即自动变版本 */ + version: string; +} + +export interface PricingSnapshot { + version: string; + peak: boolean; + /** 本次实际生效的单价(已含峰谷系数) */ + effectivePrices: { + cacheHitPerM: number; + cacheMissPerM: number; + outputPerM: number; + }; + /** 峰时标价,便于与账单核对 */ + listPrices: { + cacheHitPerM: number; + cacheMissPerM: number; + outputPerM: number; + }; +} + +export interface PricedUsage { + /** 无法计价(上游完全没上报用量)时为 null,不要用 0 冒充 */ + costUsd: number | null; + snapshot: PricingSnapshot; +} + +/** + * DeepSeek 公布的峰时窗口(UTC,周一至周五): + * 01:00–04:00 与 06:00–10:00,其余时段(含周末与中国法定节假日)为谷时。 + */ +const DEFAULT_PEAK_WINDOWS = "01:00-04:00,06:00-10:00"; + +/** 峰时单价(USD / 1M tokens),取自 DeepSeek 官方 Models & Pricing 的 PEAK 一列 */ +const DEFAULT_CACHE_HIT_PER_M = 0.006; +const DEFAULT_CACHE_MISS_PER_M = 0.3; +const DEFAULT_OUTPUT_PER_M = 1.2; + +/** 谷时 = 峰时 × 0.5 */ +const DEFAULT_OFFPEAK_FACTOR = 0.5; + +/** 费用落到 DECIMAL(18,8) 之前先收敛浮点噪声 */ +const COST_DECIMALS = 8; + +function numberFrom(value: string | undefined, fallback: number): number { + if (value === undefined || value.trim() === "") return fallback; + const parsed = Number(value); + return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback; +} + +/** + * 解析 `HH:mm-HH:mm` 列表。 + * + * 单条格式不对就跳过它而不是整段回退到默认值:运维改了一个窗口写错格式时, + * 其余窗口仍然生效,故障面更小。 + */ +export function parsePeakWindows(raw: string | undefined): PeakWindow[] { + if (raw === undefined) return parsePeakWindows(DEFAULT_PEAK_WINDOWS); + return raw + .split(",") + .map((item) => item.trim()) + .filter((item) => item.length > 0) + .map((item) => { + const match = /^(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})$/.exec(item); + if (!match) return null; + const [, startHour, startMinute, endHour, endMinute] = match; + const start = Number(startHour) * 60 + Number(startMinute); + const end = Number(endHour) * 60 + Number(endMinute); + if (start > 24 * 60 || end > 24 * 60 || start === end) return null; + return { startMinute: start, endMinute: end }; + }) + .filter((window): window is PeakWindow => window !== null); +} + +function parseOffpeakDates(raw: string | undefined): string[] { + if (raw === undefined || raw.trim() === "") return []; + return raw + .split(",") + .map((item) => item.trim()) + .filter((item) => /^\d{4}-\d{2}-\d{2}$/.test(item)); +} + +/** 单价指纹:改价即变版本,无需人工维护版本号 */ +function deriveVersion( + cacheHitPerM: number, + cacheMissPerM: number, + outputPerM: number, + offpeakFactor: number, +): string { + return `hit${cacheHitPerM}|miss${cacheMissPerM}|out${outputPerM}|off${offpeakFactor}`; +} + +export function loadPricingConfig(env: NodeJS.ProcessEnv = process.env): PricingConfig { + const cacheHitPerM = numberFrom(env.LLM_PRICE_CACHE_HIT_PER_M, DEFAULT_CACHE_HIT_PER_M); + const cacheMissPerM = numberFrom(env.LLM_PRICE_CACHE_MISS_PER_M, DEFAULT_CACHE_MISS_PER_M); + const outputPerM = numberFrom(env.LLM_PRICE_OUTPUT_PER_M, DEFAULT_OUTPUT_PER_M); + const offpeakFactor = numberFrom(env.LLM_PRICE_OFFPEAK_FACTOR, DEFAULT_OFFPEAK_FACTOR); + const explicitVersion = (env.LLM_PRICE_VERSION ?? "").trim(); + + return { + cacheHitPerM, + cacheMissPerM, + outputPerM, + offpeakFactor, + peakWindows: parsePeakWindows(env.LLM_PRICE_PEAK_WINDOWS), + offpeakDates: parseOffpeakDates(env.LLM_PRICE_PEAK_HOLIDAYS), + version: + explicitVersion.length > 0 + ? explicitVersion + : deriveVersion(cacheHitPerM, cacheMissPerM, outputPerM, offpeakFactor), + }; +} + +function utcDateKey(at: Date): string { + const year = at.getUTCFullYear(); + const month = String(at.getUTCMonth() + 1).padStart(2, "0"); + const day = String(at.getUTCDate()).padStart(2, "0"); + return `${year}-${month}-${day}`; +} + +function inWindow(minute: number, window: PeakWindow): boolean { + if (window.startMinute < window.endMinute) { + return minute >= window.startMinute && minute < window.endMinute; + } + // 跨零点(如 23:00-02:00) + return minute >= window.startMinute || minute < window.endMinute; +} + +/** + * 判断某一时刻是否按峰时计价。 + * + * 一律按 UTC 判定:DeepSeek 的峰时窗口就是按 UTC 公布的, + * 用服务器本地时区(部署在哪个区不确定)会算错整段。 + */ +export function isPeak(at: Date, config: PricingConfig): boolean { + const weekday = at.getUTCDay(); + if (weekday === 0 || weekday === 6) return false; + if (config.offpeakDates.includes(utcDateKey(at))) return false; + const minute = at.getUTCHours() * 60 + at.getUTCMinutes(); + return config.peakWindows.some((window) => inWindow(minute, window)); +} + +function roundCost(value: number): number { + const factor = 10 ** COST_DECIMALS; + return Math.round(value * factor) / factor; +} + +/** + * 把一次(或累计多次尝试的)用量换算成美元费用。 + * + * 缓存未命中数的兜底顺序:优先用上游给的 `cacheMissTokens`;没给就用 + * `promptTokens - cacheHitTokens`;连命中数都没有则把整个 `promptTokens` + * 按未命中价计——未命中价更高,宁可略微高估也不低估账单。 + */ +export function priceUsage( + usage: TokenUsage, + at: Date, + config: PricingConfig, +): PricedUsage { + const peak = isPeak(at, config); + const multiplier = peak ? 1 : config.offpeakFactor; + const effectivePrices = { + cacheHitPerM: config.cacheHitPerM * multiplier, + cacheMissPerM: config.cacheMissPerM * multiplier, + outputPerM: config.outputPerM * multiplier, + }; + const snapshot: PricingSnapshot = { + version: config.version, + peak, + effectivePrices, + listPrices: { + cacheHitPerM: config.cacheHitPerM, + cacheMissPerM: config.cacheMissPerM, + outputPerM: config.outputPerM, + }, + }; + + if (!hasUsage(usage)) { + return { costUsd: null, snapshot }; + } + + const cacheHitTokens = usage.cacheHitTokens ?? 0; + let cacheMissTokens = usage.cacheMissTokens; + if (cacheMissTokens === null) { + cacheMissTokens = + usage.promptTokens !== null + ? Math.max(0, usage.promptTokens - cacheHitTokens) + : 0; + } + const completionTokens = usage.completionTokens ?? 0; + + const cost = + (cacheHitTokens / 1_000_000) * effectivePrices.cacheHitPerM + + (cacheMissTokens / 1_000_000) * effectivePrices.cacheMissPerM + + (completionTokens / 1_000_000) * effectivePrices.outputPerM; + + return { costUsd: roundCost(cost), snapshot }; +} diff --git a/src/admin/reporter.test.ts b/src/admin/reporter.test.ts new file mode 100644 index 0000000..e1ddf60 --- /dev/null +++ b/src/admin/reporter.test.ts @@ -0,0 +1,290 @@ +import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +import { emptyUsage } from "../llm/usage.js"; +import { UsageReporter, loadReporterConfig, toUsageRecord, type ReporterConfig } from "./reporter.js"; +import type { LogEntry } from "./store.js"; + +let workDir: string; + +beforeEach(() => { + workDir = mkdtempSync(join(tmpdir(), "lpt-ai-reporter-")); +}); + +afterEach(() => { + rmSync(workDir, { recursive: true, force: true }); +}); + +function outboxFile(): string { + return join(workDir, "usage-outbox.json"); +} + +function reporterConfig(overrides: Partial = {}): ReporterConfig { + return { + url: "http://lpt-be.test", + token: "report-token", + intervalMs: 15_000, + batchSize: 50, + maxPending: 5_000, + timeoutMs: 5_000, + ...overrides, + }; +} + +function makeReporter( + config: Partial = {}, + fetchImpl?: typeof fetch, +): UsageReporter { + return new UsageReporter({ + loadConfig: () => reporterConfig(config), + outboxFile: outboxFile(), + ...(fetchImpl ? { fetchImpl } : {}), + }); +} + +function entry(overrides: Partial = {}): LogEntry { + return { + id: 1, + recordId: "rec-1", + timestamp: "2026-10-10T09:38:23.543Z", + endpoint: "/ai/tasks#aggregate-report", + taskType: "aggregate-report", + taskId: "task-1", + model: "deepseek-flash", + attempts: 2, + isLlmCall: true, + usage: { + promptTokens: 1234, + completionTokens: 567, + totalTokens: 1801, + cacheHitTokens: 800, + cacheMissTokens: 434, + reasoningTokens: 0, + }, + usageSource: "upstream", + costUsd: 0.001234, + pricing: { + version: "hit0.006|miss0.3|out1.2|off0.5", + peak: false, + effectivePrices: { cacheHitPerM: 0.003, cacheMissPerM: 0.15, outputPerM: 0.6 }, + listPrices: { cacheHitPerM: 0.006, cacheMissPerM: 0.3, outputPerM: 1.2 }, + }, + durationMs: 7466, + status: 200, + requestBody: {}, + responseBody: {}, + ...overrides, + }; +} + +describe("loadReporterConfig", () => { + it("未配置上报地址时视为关闭", () => { + expect(loadReporterConfig({}).url).toBe(""); + }); + + it("去掉结尾斜杠,避免拼出双斜杠路径", () => { + expect(loadReporterConfig({ LPT_AI_REPORT_URL: "http://be.test/" }).url).toBe("http://be.test"); + }); + + it("非法数值回退到缺省", () => { + const config = loadReporterConfig({ LPT_AI_REPORT_INTERVAL_MS: "-5", LPT_AI_REPORT_BATCH_SIZE: "x" }); + expect(config.intervalMs).toBe(15_000); + expect(config.batchSize).toBe(50); + }); +}); + +describe("toUsageRecord", () => { + it("把日志映射成上报载荷,null 字段显式保留", () => { + const record = toUsageRecord(entry({ usage: emptyUsage(), costUsd: null, usageSource: "missing" })); + + expect(record).toMatchObject({ + recordId: "rec-1", + taskType: "aggregate-report", + attempts: 2, + usageSource: "missing", + promptTokens: null, + completionTokens: null, + cacheHitTokens: null, + costUsd: null, + }); + }); + + it("非 LLM 请求也上报,由 isLlmCall 区分", () => { + const record = toUsageRecord( + entry({ isLlmCall: false, taskType: "fetch-title", model: "", usage: undefined }), + ); + expect(record.isLlmCall).toBe(false); + expect(record.taskType).toBe("fetch-title"); + expect(record.model).toBe(""); + }); + + it("必填字段永远非空,否则 lpt-be 会把整批上报判 400", () => { + // 契约 1 的必填项:lpt-be 侧 @NotBlank 的字段不能是空串,@NotNull 的字段不能缺。 + // 尤其是 /fetch-title 的 model——它合法地是空串,所以 lpt-be 那边用的是 @NotNull。 + const notBlank = ["recordId", "occurredAt", "taskType", "usageSource"] as const; + const notNull = ["model", "attempts", "isLlmCall", "durationMs", "status"] as const; + + const cases = [ + entry(), + entry({ isLlmCall: false, taskType: "fetch-title", model: "", usage: undefined, usageSource: undefined }), + entry({ usage: emptyUsage(), costUsd: null, usageSource: "missing", status: 500, errorCode: "rate_limited" }), + ]; + + for (const logEntry of cases) { + const record = toUsageRecord(logEntry) as unknown as Record; + for (const field of notBlank) { + expect(typeof record[field], field).toBe("string"); + expect(String(record[field]).trim().length, field).toBeGreaterThan(0); + } + for (const field of notNull) { + expect(record[field], field).not.toBeNull(); + expect(record[field], field).not.toBeUndefined(); + } + // lpt-be 用 OffsetDateTime.parse 解析 occurredAt,必须是带时区的 ISO 8601 + expect(record.occurredAt).toMatch(/Z$|[+-]\d{2}:\d{2}$/); + } + }); +}); + +describe("UsageReporter", () => { + it("未配置上报地址时不入队、不落盘", async () => { + const reporter = makeReporter({ url: "" }); + reporter.enqueue(entry()); + + expect(reporter.isConfigured()).toBe(false); + expect(reporter.pendingCount()).toBe(0); + expect(existsSync(outboxFile())).toBe(false); + await expect(reporter.flush()).resolves.toEqual({ sent: 0, remaining: 0 }); + }); + + it("推送成功后清空队列并落盘", async () => { + const fetchImpl = vi.fn().mockResolvedValue({ ok: true, status: 200 } as Response); + const reporter = makeReporter({}, fetchImpl as unknown as typeof fetch); + + reporter.enqueue(entry({ recordId: "rec-1" })); + reporter.enqueue(entry({ recordId: "rec-2" })); + + await expect(reporter.flush()).resolves.toEqual({ sent: 2, remaining: 0 }); + expect(reporter.pendingCount()).toBe(0); + expect(JSON.parse(readFileSync(outboxFile(), "utf-8"))).toEqual([]); + + const [url, init] = fetchImpl.mock.calls[0] as [string, RequestInit]; + expect(url).toBe("http://lpt-be.test/internal/ai-usage/records"); + expect((init.headers as Record)["x-api-token"]).toBe("report-token"); + expect(JSON.parse(String(init.body)).records).toHaveLength(2); + }); + + it("上报失败时保留队列,等下次重试", async () => { + const fetchImpl = vi.fn().mockResolvedValue({ + ok: false, + status: 500, + text: async () => "boom", + } as Response); + const reporter = makeReporter({}, fetchImpl as unknown as typeof fetch); + + reporter.enqueue(entry()); + const result = await reporter.flush(); + + expect(result.sent).toBe(0); + expect(result.remaining).toBe(1); + expect(result.error).toContain("500"); + expect(reporter.pendingCount()).toBe(1); + expect(reporter.dropped).toBe(0); + }); + + it("4xx 是确定性拒绝:丢弃这批而不是无限重试把队列堵死", async () => { + const fetchImpl = vi.fn().mockResolvedValue({ + ok: false, + status: 400, + text: async () => "model 不能为空", + } as Response); + const reporter = makeReporter({}, fetchImpl as unknown as typeof fetch); + + reporter.enqueue(entry({ recordId: "bad" })); + reporter.enqueue(entry({ recordId: "good" })); + const result = await reporter.flush(); + + expect(result.error).toContain("400"); + expect(reporter.pendingCount()).toBe(0); + expect(reporter.dropped).toBe(2); + + // 后续正常记录不受影响,仍然能上报 + fetchImpl.mockResolvedValue({ ok: true, status: 200 } as Response); + reporter.enqueue(entry({ recordId: "later" })); + await expect(reporter.flush()).resolves.toEqual({ sent: 1, remaining: 0 }); + }); + + it("网络异常时不丢队列", async () => { + const fetchImpl = vi.fn().mockRejectedValue(new Error("ECONNREFUSED")); + const reporter = makeReporter({}, fetchImpl as unknown as typeof fetch); + + reporter.enqueue(entry()); + const result = await reporter.flush(); + + expect(result.error).toBe("ECONNREFUSED"); + expect(reporter.pendingCount()).toBe(1); + }); + + it("按 batchSize 分批推送,剩余记录留待下一轮", async () => { + const fetchImpl = vi.fn().mockResolvedValue({ ok: true, status: 200 } as Response); + const reporter = makeReporter({ batchSize: 2 }, fetchImpl as unknown as typeof fetch); + + for (const id of ["a", "b", "c"]) { + reporter.enqueue(entry({ recordId: id })); + } + + await expect(reporter.flush()).resolves.toEqual({ sent: 2, remaining: 1 }); + expect(JSON.parse(String((fetchImpl.mock.calls[0][1] as RequestInit).body)).records.map( + (r: { recordId: string }) => r.recordId, + )).toEqual(["a", "b"]); + }); + + it("超出上限时丢弃最旧的并计数,避免磁盘被写满", () => { + const reporter = makeReporter({ maxPending: 2 }); + for (const id of ["a", "b", "c", "d"]) { + reporter.enqueue(entry({ recordId: id })); + } + + expect(reporter.pendingCount()).toBe(2); + expect(reporter.dropped).toBe(2); + }); + + it("新实例从 outbox 文件恢复未上报的记录", () => { + const first = makeReporter(); + first.enqueue(entry({ recordId: "rec-persisted" })); + expect(first.pendingCount()).toBe(1); + + const second = makeReporter(); + expect(second.pendingCount()).toBe(1); + }); + + it("outbox 文件损坏时从空队列开始,不阻塞后续上报", () => { + const first = makeReporter(); + first.enqueue(entry()); + + const reporter = new UsageReporter({ + loadConfig: () => reporterConfig(), + outboxFile: join(workDir, "corrupt.json"), + }); + expect(reporter.pendingCount()).toBe(0); + }); + + it("并发调用 flush 时第二次直接返回,不重复推送", async () => { + let release!: (value: Response) => void; + const fetchImpl = vi.fn().mockImplementation( + () => new Promise((resolve) => { release = resolve; }), + ); + const reporter = makeReporter({}, fetchImpl as unknown as typeof fetch); + reporter.enqueue(entry()); + + const first = reporter.flush(); + const second = await reporter.flush(); + + expect(second).toEqual({ sent: 0, remaining: 1 }); + release({ ok: true, status: 200 } as Response); + await expect(first).resolves.toEqual({ sent: 1, remaining: 0 }); + expect(fetchImpl).toHaveBeenCalledTimes(1); + }); +}); diff --git a/src/admin/reporter.ts b/src/admin/reporter.ts new file mode 100644 index 0000000..4fe6ddc --- /dev/null +++ b/src/admin/reporter.ts @@ -0,0 +1,299 @@ +/** + * 用量上报(lpt-ai → lpt-be)。 + * + * 设计要点: + * - **lpt-be 的 MySQL 是长期账本**,lpt-ai 本地只有最近若干条的面板缓存, + * 所以上报失败不能丢数据:先落到本地 outbox 文件,再批量推送、成功后删除。 + * - **幂等交给 lpt-be**(`record_id` 唯一索引),因此「推送成功但响应丢失」 + * 导致的重复推送是安全的,不需要在这里做去重协商。 + * - **未配置 `LPT_AI_REPORT_URL` 时整体退化为空操作**:本地开发不必起 lpt-be, + * 面板照常工作,只是没有长期账本。 + * - **配置延迟读取**:ESM 的 import 先于 `index.ts` 里的 .env 加载执行, + * 在模块顶层读环境变量会永远读不到 .env 里的值。 + */ + +import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"; +import { dirname, resolve } from "node:path"; +import type { LogEntry } from "./store.js"; + +// ---- 上报载荷(与 lpt-be 的 /internal/ai-usage/records 契约一致)---- + +export interface UsageRecord { + recordId: string; + occurredAt: string; + taskType: string; + taskId: string | null; + model: string; + attempts: number; + isLlmCall: boolean; + usageSource: string; + promptTokens: number | null; + completionTokens: number | null; + totalTokens: number | null; + cacheHitTokens: number | null; + cacheMissTokens: number | null; + reasoningTokens: number | null; + costUsd: number | null; + pricingVersion: string | null; + peak: boolean | null; + durationMs: number; + status: number; + errorCode: string | null; +} + +export interface ReporterConfig { + /** lpt-be 基地址;为空表示不上报 */ + url: string; + token: string; + intervalMs: number; + batchSize: number; + /** outbox 上限:超过后丢弃最旧的,避免磁盘被写满 */ + maxPending: number; + timeoutMs: number; +} + +export interface ReporterDeps { + loadConfig?: () => ReporterConfig; + fetchImpl?: typeof fetch; + now?: () => number; + /** outbox 文件路径;测试里指向临时目录 */ + outboxFile?: string; +} + +export interface FlushResult { + sent: number; + remaining: number; + error?: string; +} + +function intFrom(value: string | undefined, fallback: number): number { + if (value === undefined || value.trim() === "") return fallback; + const parsed = Number(value); + return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback; +} + +export function loadReporterConfig(env: NodeJS.ProcessEnv = process.env): ReporterConfig { + return { + url: (env.LPT_AI_REPORT_URL ?? "").trim().replace(/\/+$/, ""), + token: (env.LPT_AI_REPORT_TOKEN ?? "").trim(), + intervalMs: intFrom(env.LPT_AI_REPORT_INTERVAL_MS, 15_000), + batchSize: intFrom(env.LPT_AI_REPORT_BATCH_SIZE, 50), + maxPending: intFrom(env.LPT_AI_REPORT_MAX_PENDING, 5_000), + timeoutMs: intFrom(env.LPT_AI_REPORT_TIMEOUT_MS, 10_000), + }; +} + +/** 把面板日志转成上报载荷;缺失字段一律显式写成 null,不要省略键 */ +export function toUsageRecord(entry: LogEntry): UsageRecord { + const usage = entry.usage; + return { + recordId: entry.recordId, + occurredAt: entry.timestamp, + taskType: entry.taskType ?? entry.endpoint, + taskId: entry.taskId ?? null, + model: entry.model, + attempts: entry.attempts ?? 1, + isLlmCall: entry.isLlmCall, + usageSource: entry.usageSource ?? "missing", + promptTokens: usage?.promptTokens ?? null, + completionTokens: usage?.completionTokens ?? null, + totalTokens: usage?.totalTokens ?? null, + cacheHitTokens: usage?.cacheHitTokens ?? null, + cacheMissTokens: usage?.cacheMissTokens ?? null, + reasoningTokens: usage?.reasoningTokens ?? null, + costUsd: entry.costUsd ?? null, + pricingVersion: entry.pricing?.version ?? null, + peak: entry.pricing?.peak ?? null, + durationMs: entry.durationMs, + status: entry.status, + errorCode: entry.errorCode ?? null, + }; +} + +const DEFAULT_OUTBOX_NAME = "usage-outbox.json"; + +/** 与 store.ts 同一口径:可配置且惰性解析,避免测试写进开发者的真实数据目录 */ +/** 取一批记录的幂等键,用于从 outbox 里精确移除已处理的那批 */ +function sentIdsOf(batch: UsageRecord[]): Set { + return new Set(batch.map((record) => record.recordId)); +} + +function defaultOutboxFile(): string { + const configured = (process.env.LPT_AI_DATA_DIR ?? "").trim(); + const dir = configured.length > 0 ? configured : resolve(process.cwd(), "data"); + return resolve(dir, DEFAULT_OUTBOX_NAME); +} + +export class UsageReporter { + private readonly deps: ReporterDeps; + private pending: UsageRecord[] = []; + private loaded = false; + private cachedConfig: ReporterConfig | null = null; + private timer: NodeJS.Timeout | null = null; + private flushing = false; + /** 因超出上限被丢弃的条数,便于发现「长期上报失败」 */ + private droppedCount = 0; + + constructor(deps: ReporterDeps = {}) { + this.deps = deps; + } + + private config(): ReporterConfig { + if (!this.cachedConfig) { + this.cachedConfig = (this.deps.loadConfig ?? loadReporterConfig)(); + } + return this.cachedConfig; + } + + private outboxFile(): string { + return this.deps.outboxFile ?? defaultOutboxFile(); + } + + isConfigured(): boolean { + return this.config().url.length > 0; + } + + pendingCount(): number { + this.ensureLoaded(); + return this.pending.length; + } + + get dropped(): number { + return this.droppedCount; + } + + /** 入队一条日志;未配置上报地址时直接忽略 */ + enqueue(entry: LogEntry): void { + if (!this.isConfigured()) return; + this.ensureLoaded(); + this.pending.push(toUsageRecord(entry)); + const { maxPending } = this.config(); + if (this.pending.length > maxPending) { + const overflow = this.pending.length - maxPending; + this.pending.splice(0, overflow); + this.droppedCount += overflow; + } + this.persist(); + } + + /** 推送一批;成功才从 outbox 删除,失败原样保留等下次 */ + async flush(): Promise { + this.ensureLoaded(); + const config = this.config(); + if (!this.isConfigured() || this.pending.length === 0) { + return { sent: 0, remaining: this.pending.length }; + } + if (this.flushing) { + return { sent: 0, remaining: this.pending.length }; + } + + this.flushing = true; + const batch = this.pending.slice(0, config.batchSize); + try { + const fetchImpl = this.deps.fetchImpl ?? fetch; + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), config.timeoutMs); + let response: Response; + try { + response = await fetchImpl(`${config.url}/internal/ai-usage/records`, { + method: "POST", + headers: { + "Content-Type": "application/json", + "x-api-token": config.token, + }, + body: JSON.stringify({ records: batch }), + signal: controller.signal, + }); + } finally { + clearTimeout(timer); + } + + if (!response.ok) { + const body = await response.text().catch(() => ""); + // 4xx 是确定性拒绝(报文格式不对、令牌不对):重试多少次都一样, + // 继续留在 outbox 只会把队列堵死,把后续正常记录一起饿死。丢弃并计数。 + if (response.status >= 400 && response.status < 500) { + this.pending = this.pending.filter((record) => !sentIdsOf(batch).has(record.recordId)); + this.droppedCount += batch.length; + this.persist(); + return { + sent: 0, + remaining: this.pending.length, + error: `上报被拒绝 (${response.status}),已丢弃这批记录: ${body.slice(0, 200)}`, + }; + } + return { + sent: 0, + remaining: this.pending.length, + error: `上报失败 (${response.status}): ${body.slice(0, 200)}`, + }; + } + + // 只移除本次实际推送的那批;期间新入队的记录不受影响 + const sentIds = sentIdsOf(batch); + this.pending = this.pending.filter((record) => !sentIds.has(record.recordId)); + this.persist(); + return { sent: batch.length, remaining: this.pending.length }; + } catch (err) { + return { + sent: 0, + remaining: this.pending.length, + error: err instanceof Error ? err.message : String(err), + }; + } finally { + this.flushing = false; + } + } + + /** 启动定时推送;未配置上报地址时不做任何事 */ + start(): void { + if (!this.isConfigured() || this.timer) return; + const { intervalMs } = this.config(); + this.timer = setInterval(() => { + void this.flush(); + }, intervalMs); + // 不要因为上报定时器让进程无法退出 + this.timer.unref?.(); + void this.flush(); + } + + stop(): void { + if (this.timer) { + clearInterval(this.timer); + this.timer = null; + } + } + + // ---- outbox 持久化 ---- + + private ensureLoaded(): void { + if (this.loaded) return; + this.loaded = true; + try { + const file = this.outboxFile(); + if (!existsSync(file)) return; + const raw = readFileSync(file, "utf-8"); + const data = JSON.parse(raw) as UsageRecord[]; + this.pending = Array.isArray(data) ? data : []; + } catch { + // 文件损坏时从空队列开始,避免坏数据让上报永久卡死 + this.pending = []; + } + } + + private persist(): void { + try { + const file = this.outboxFile(); + const dir = dirname(file); + if (!existsSync(dir)) mkdirSync(dir, { recursive: true }); + // 原子替换:被中断的直写会留下截断 JSON,重启后整队列丢失 + const tmpFile = `${file}.tmp`; + writeFileSync(tmpFile, JSON.stringify(this.pending), "utf-8"); + renameSync(tmpFile, file); + } catch { + // 写盘失败不阻塞请求,队列仍在内存里 + } + } +} + +export const usageReporter = new UsageReporter(); diff --git a/src/admin/routes.test.ts b/src/admin/routes.test.ts new file mode 100644 index 0000000..81dff1f --- /dev/null +++ b/src/admin/routes.test.ts @@ -0,0 +1,129 @@ +import { mkdtempSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import Fastify from "fastify"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; + +import { adminRoutes } from "./routes.js"; +import { logStore, resetLogStoreForTest } from "./store.js"; + +const originalToken = process.env.LPT_AI_TOKEN; +const originalDataDir = process.env.LPT_AI_DATA_DIR; +let workDir: string; + +// 必须指向临时目录:单例默认写 process.cwd()/data,不隔离会把开发者真实的面板数据清掉 +beforeEach(() => { + workDir = mkdtempSync(join(tmpdir(), "lpt-ai-admin-")); + process.env.LPT_AI_DATA_DIR = workDir; +}); + +afterEach(() => { + if (originalToken === undefined) { + delete process.env.LPT_AI_TOKEN; + } else { + process.env.LPT_AI_TOKEN = originalToken; + } + if (originalDataDir === undefined) { + delete process.env.LPT_AI_DATA_DIR; + } else { + process.env.LPT_AI_DATA_DIR = originalDataDir; + } + rmSync(workDir, { recursive: true, force: true }); +}); + +async function buildApp() { + const app = Fastify(); + await app.register(adminRoutes); + await app.ready(); + return app; +} + +function scriptOf(html: string): string { + const match = /