From 4c58f409e9191185bb4fe908db797fe922e07bc6 Mon Sep 17 00:00:00 2001 From: Marcus <1922576605@qq.com> Date: Sun, 26 Apr 2026 01:13:38 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E8=A1=A5=E5=85=85=E6=B3=A8=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 20 +++++--- server/api/auth/login.post.ts | 15 ++++-- server/api/auth/logout.get.ts | 9 ++++ server/api/auth/me.get.ts | 18 +++++-- server/api/auth/ready.get.ts | 11 +++++ server/api/auth/register.post.ts | 13 +++-- server/api/images/generate.post.ts | 60 ++++++++++++++---------- server/api/images/history.get.ts | 22 ++++----- server/api/images/history/[id].delete.ts | 11 +++++ server/api/images/history/[id].get.ts | 11 +++++ server/api/images/stats.get.ts | 16 ++++--- server/middleware/log.ts | 1 + server/utils/createApiResponse.ts | 35 ++++---------- server/utils/fetch.ts | 1 + server/utils/imageGenerationRecords.ts | 24 ++++++++-- server/utils/index.ts | 1 + server/utils/logging.ts | 3 ++ server/utils/lsky.ts | 17 +++++++ server/utils/newApiAuthCookies.ts | 1 + server/utils/newApiTokens.ts | 1 + server/utils/openai.ts | 2 +- server/utils/prisma.ts | 3 ++ shared/types/openai.ts | 6 +-- 23 files changed, 206 insertions(+), 95 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3113f38..2dae984 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,6 +9,7 @@ - 默认最小改动，优先复用现有工具函数、类型和目录结构。 - 保持单一入口和单一职责，避免同一业务暴露多套路由或重复实现。 - 前端不接触 NewAPI session、完整 API Key、Lsky token 等敏感信息。 +- 所有返回给前端的 `msg` 必须使用本地业务表达，不提及“上游”“NewAPI”“Lsky”“供应商”“token”“key”等内部来源；内部异常统一返回“服务器内部错误”。 - 注释和日志要解释意图、边界和排查信息，不输出密码、cookie、完整 key、token、图片二进制或完整 prompt。 - 已存在的说明性注释不要随意删除，尤其是 `server/utils/openai.ts` 里的模型调用、视觉输入、流式解析等上下文注释。 @@ -60,7 +61,7 @@ - `POST /api/images/generate` 当前同步等待生图完成后返回，不向前端透传流式进度。 - 生图成功后返回： - - `imageUrl`：NewAPI 上游返回的图片 URL，前端当前优先展示。 + - `imageUrl`：生成图片访问地址，前端当前优先展示。 - `hostedImageUrl`：Lsky 图床归档后的 URL，归档失败时为 `null`。 - `revisedPrompt`：流式 chat completions 当前没有等价字段，通常为空。 - Lsky 归档逻辑集中在 `server/utils/lsky.ts`： @@ -68,9 +69,9 @@ - 上传时先下载上游图片，再用 `multipart/form-data` 调 Lsky `/upload`。 - 文件名格式为 `userId_username_timestamp_recordId.ext`。 - tags 固定包含 `AIArtStudio`、`user:{userId}`、`record:{recordId}`、`model:gpt-image-2`。 -- 图床上传失败不影响本次生图成功：接口仍返回上游 `imageUrl`，数据库记录归档失败提示。 +- 图床上传失败不影响本次生图成功：接口仍返回 `imageUrl`，数据库记录归档失败提示；前端可见文案只能说“图片归档失败”等本地描述。 - 数据库不保存图片 base64；不要恢复 `image_base64` 或类似大文本存图方案。 -- 历史列表不返回大体积数据；详情可返回完整上游响应和 Lsky 上传响应。 +- 历史列表和详情都不向前端返回完整上游响应、图床响应或内部错误详情；这些内容可以入库供服务端排查，但 API 响应应固定隐藏或置空。 ## 数据库与 Prisma @@ -92,6 +93,7 @@ - API handler 使用 `server/utils/logging.ts` 的 `createApiLogger` 和 `toSafeLogError`。 - 日志必须包含足够排查信息，例如 `requestId`、阶段、`userId`、`recordId`、分页、耗时、状态。 +- 上游错误、内部响应、图床响应、数据库异常等细节只允许写入服务端日志或数据库排查字段，不允许通过接口 `msg`、`data`、历史详情等返回给前端。 - 生图日志阶段建议保持清晰： - `read_body` - `read_user_id` @@ -108,7 +110,10 @@ - 所有 JSON 接口先校验请求体：只接受 JSON 对象或 `null`，数组、字符串等无效 body 直接返回 400。 - 对上游透传字段必须使用白名单数组过滤，只透传类型正确且文档声明的字段。 - 统一使用 `createSuccessResponse`、`createErrorResponse` 返回结构。 -- 上游异常统一通过 `createUpstreamErrorResponse` 转换。 +- `createSuccessResponse` 的 `msg` 只写本地业务结果，例如“登录成功”“生图完成”“环境已准备”。 +- `createErrorResponse` 的 `msg` 只写本地业务错误，例如“未登录”“请求体必须是 JSON 对象”“生图记录不存在”。 +- 上游或内部异常统一通过 `createUpstreamErrorResponse` 转换，并固定对前端返回“服务器内部错误”；具体异常必须在调用前写入服务端日志。 +- 不把上游 `message`、`statusMessage`、响应体、错误 data、完整响应对象、图床错误信息、数据库错误信息透出给前端。 - 401 或登录态失效时统一清理本地 auth cookie。 - 不在 handler 内重复实现复杂错误解析，通用判断放到 `server/utils`。 @@ -133,6 +138,8 @@ - TypeScript 严格类型优先，避免 `any` 扩散。 - 新增通用逻辑优先抽到 `server/utils`，handler 只负责入参校验、调用和统一响应。 - 修改优先小步快改，不重构无关代码。 +- `server/` 下每个文件顶部必须有 `// server/... - 用途说明` 注释。 +- 复杂 `defineEventHandler` 上方必须写清楚接口流程、鉴权边界、数据是否入库、哪些信息不会返回前端。 - 注释使用中文，描述意图与边界，不写机械解释。 - 不删除已有有价值注释；确需重写文件时，要保留或迁移原注释表达的信息。 @@ -145,8 +152,9 @@ 3. 在 handler 中完成请求体校验、白名单过滤、鉴权和日志。 4. 将可复用业务逻辑抽到 `server/utils`。 5. 涉及数据库时同步修改 Prisma schema、migration、`create_tables.sql`。 -6. 确认敏感信息不进入前端响应、日志或数据库不该保存的字段。 -7. 运行 `pnpm typecheck`；涉及 Prisma schema 时运行 `prisma generate`，必要时同步数据库。 +6. 确认前端响应中的 `msg`、`data`、历史详情不包含上游/internal 细节；内部错误统一显示“服务器内部错误”。 +7. 确认敏感信息不进入前端响应、日志或数据库不该保存的字段。 +8. 运行 `pnpm typecheck`；涉及 Prisma schema 时运行 `prisma generate`，必要时同步数据库。 ## 非目标 diff --git a/server/api/auth/login.post.ts b/server/api/auth/login.post.ts index 16287fd..4cc946e 100644 --- a/server/api/auth/login.post.ts +++ b/server/api/auth/login.post.ts @@ -1,4 +1,4 @@ -// server/api/auth/login.post.ts +// server/api/auth/login.post.ts - 登录接口：代理 NewAPI 登录、保存 httpOnly 登录态并返回基础用户信息。 import type { IUserLoginData, IUserLoginRequest } from "#shared/types"; import { clearNewApiAuthCookies, @@ -40,6 +40,13 @@ const LOGIN_FIELDS = ["username", "password"] as const satisfies ReadonlyArray< /** * POST /api/auth/login + * + * 流程： + * 1. 只接收 JSON 对象，并按 LOGIN_FIELDS 白名单组装上游登录参数。 + * 2. 使用 raw fetch 调用 NewAPI 登录接口，保留 Set-Cookie 响应头。 + * 3. 兼容上游直接返回用户对象或包装响应，提取基础用户信息。 + * 4. 将 NewAPI session 和 userId 写入本站 httpOnly cookie，前端不接触 session 明文。 + * 5. 异步 upsert 用户快照到数据库，失败只记日志，不影响登录成功。 */ export default defineEventHandler(async (event) => { const logger = createApiLogger("auth.login"); @@ -98,7 +105,7 @@ export default defineEventHandler(async (event) => { logger.warn("登录业务失败", { upstreamMessage: normalized.message }); - return createErrorResponse(1, normalized.message, result._data ?? null); + return createErrorResponse(1, "登录失败"); } if (!session) { @@ -132,7 +139,7 @@ export default defineEventHandler(async (event) => { return createSuccessResponse( normalized.user, - normalized.message + "登录成功" ); } catch (error) { clearNewApiAuthCookies(event); @@ -162,7 +169,7 @@ const normalizeLoginResponse = ( } const wrapped = response as INewApiWrappedLoginResponse; - const message = wrapped.message || (wrapped.success ? "登录成功" : "登录失败"); + const message = wrapped.success ? "登录成功" : "登录失败"; if (wrapped.success !== true || !isUser(wrapped.data)) { return { diff --git a/server/api/auth/logout.get.ts b/server/api/auth/logout.get.ts index 74a6ff2..799e870 100644 --- a/server/api/auth/logout.get.ts +++ b/server/api/auth/logout.get.ts @@ -1,3 +1,4 @@ +// server/api/auth/logout.get.ts - 登出接口：尽量通知 NewAPI 销毁 session，并清理本地登录态。 import type { IUserLogoutData } from "#shared/types"; import { clearNewApiAuthCookies, @@ -7,6 +8,14 @@ import { toSafeLogError } from "~~/server/utils"; +/** + * GET /api/auth/logout + * + * 流程： + * 1. 使用本站 httpOnly cookie 中的 NewAPI session 调用上游登出。 + * 2. 无论上游登出是否成功，都清理本站保存的 session/userId cookie。 + * 3. 返回统一成功响应，避免坏 session 残留影响后续登录。 + */ export default defineEventHandler(async (event) => { const logger = createApiLogger("auth.logout"); logger.info("开始"); diff --git a/server/api/auth/me.get.ts b/server/api/auth/me.get.ts index 1fe06e4..d3d209a 100644 --- a/server/api/auth/me.get.ts +++ b/server/api/auth/me.get.ts @@ -1,3 +1,4 @@ +// server/api/auth/me.get.ts - 当前用户接口：用 httpOnly 登录态恢复用户信息并刷新用户快照。 import type { IUserMeData } from "#shared/types"; import { clearNewApiAuthCookies, @@ -25,6 +26,16 @@ interface INewApiSelfUserData extends IUserMeData { [key: string]: unknown; } +/** + * GET /api/auth/me + * + * 流程： + * 1. 从本站 httpOnly cookie 读取 NewAPI session/userId。 + * 2. 带 Cookie 与 New-Api-User 请求 NewAPI /api/user/self。 + * 3. 裁剪上游 self 响应，只返回前端需要的基础用户字段。 + * 4. 异步更新数据库里的用户快照。 + * 5. cookie 缺失、过期或上游鉴权失败时清理本地登录态并返回 401。 + */ export default defineEventHandler(async (event) => { const logger = createApiLogger("auth.me"); logger.info("开始"); @@ -46,7 +57,7 @@ export default defineEventHandler(async (event) => { logger.warn("登录状态无效", { upstreamMessage: normalized.message }); - return createErrorResponse(401, normalized.message); + return createErrorResponse(401, "未登录"); } upsertUserSnapshot(normalized.user).catch((error) => { @@ -64,7 +75,7 @@ export default defineEventHandler(async (event) => { return createSuccessResponse( normalized.user, - normalized.message + "获取用户信息成功" ); } catch (error) { // cookie 缺失或上游鉴权异常时统一视为未登录。 @@ -95,8 +106,7 @@ const normalizeUserResponse = ( } const wrapped = response as INewApiWrappedUserResponse; - const message = - wrapped.message || (wrapped.success ? "获取用户信息成功" : "未登录"); + const message = wrapped.success ? "获取用户信息成功" : "未登录"; if (wrapped.success !== true || !isUser(wrapped.data)) { return { diff --git a/server/api/auth/ready.get.ts b/server/api/auth/ready.get.ts index ce54419..15dd1ad 100644 --- a/server/api/auth/ready.get.ts +++ b/server/api/auth/ready.get.ts @@ -1,3 +1,4 @@ +// server/api/auth/ready.get.ts - 登录后环境准备接口：确保当前用户已有可用的 AIArtStudio Token。 import type { IUserReadyData } from "#shared/types"; import { clearNewApiAuthCookies, @@ -10,6 +11,16 @@ import { toSafeLogError } from "~~/server/utils"; +/** + * GET /api/auth/ready + * + * 流程： + * 1. 读取当前登录用户的 NewAPI session。 + * 2. 检查是否存在启用且未删除的 AIArtStudio Token。 + * 3. 不存在时按固定参数创建 Token。 + * 4. 只返回环境是否准备完成，不返回完整 key 或脱敏 key。 + * 5. 登录态失效时清理本地 cookie 并返回 401。 + */ export default defineEventHandler(async (event) => { const logger = createApiLogger("auth.ready"); logger.info("开始"); diff --git a/server/api/auth/register.post.ts b/server/api/auth/register.post.ts index 3a89fee..ed440e1 100644 --- a/server/api/auth/register.post.ts +++ b/server/api/auth/register.post.ts @@ -1,4 +1,4 @@ -// server/api/auth/register.post.ts +// server/api/auth/register.post.ts - 注册接口：校验并代理 NewAPI 注册请求。 import type { IUserRegisterData, IUserRegisterRequest } from "#shared/types"; import { createApiLogger, @@ -23,6 +23,11 @@ const REGISTER_FIELDS = [ /** * POST /api/auth/register + * + * 流程： + * 1. 只接收 JSON 对象，并按 REGISTER_FIELDS 白名单透传注册字段。 + * 2. 调用 NewAPI 注册接口。 + * 3. 成功时返回统一成功响应；上游失败时转成统一错误响应。 */ export default defineEventHandler(async (event) => { const logger = createApiLogger("auth.register"); @@ -59,7 +64,7 @@ export default defineEventHandler(async (event) => { } try { - const result = await newApiFetch("/api/user/register", { + await newApiFetch("/api/user/register", { method: "POST", body: payload, headers: { @@ -68,10 +73,10 @@ export default defineEventHandler(async (event) => { }); logger.done("成功", { - hasResult: Boolean(result) + registered: true }); - return createSuccessResponse(result, "注册成功"); + return createSuccessResponse(null, "注册成功"); } catch (error) { logger.error("失败", { error: toSafeLogError(error) diff --git a/server/api/images/generate.post.ts b/server/api/images/generate.post.ts index a70fdfc..a3ecd29 100644 --- a/server/api/images/generate.post.ts +++ b/server/api/images/generate.post.ts @@ -1,27 +1,24 @@ +// server/api/images/generate.post.ts - 图片生成接口：创建记录、流式调用上游生图、归档图床并返回图片地址。 import type { IImageGenerateData, IImageGenerateRequest } from "#shared/types/openai"; -import { - askImgStream, - clearNewApiAuthCookies, - createApiLogger, - createErrorResponse, - createRunningImageGeneration, - createSuccessResponse, - createUpstreamErrorResponse, - finishImageGenerationFailed, - finishImageGenerationSuccess, - getAiArtStudioTokenKey, - getNewApiUserIdFromCookie, - getUserArchiveIdentity, - isUnauthorizedError, - toSafeLogError, - uploadImageFromUrl -} from "~~/server/utils"; type ApiLogger = ReturnType; +/** + * POST /api/images/generate + * + * 流程： + * 1. 校验请求体和 prompt，空 prompt 不创建数据库记录。 + * 2. 从 httpOnly cookie 读取当前 NewAPI 用户 ID。 + * 3. 创建 RUNNING 生图记录，并递增全局请求/进行中统计。 + * 4. 在服务端确保并读取 AIArtStudio 完整 key，完整 key 不返回前端。 + * 5. 调用 Chat Completions 流式生图接口，累积 SSE delta content 并提取最终图片 URL。 + * 6. 尝试把上游图片下载后上传到 Lsky 图床；图床失败不阻断本次生图成功。 + * 7. 成功时写入上游 URL、图床 URL、完整上游响应、图床响应和耗时。 + * 8. 失败时把记录标记为 FAILED；鉴权失败会清理本地登录态并返回 401。 + */ export default defineEventHandler(async (event) => { const logger = createApiLogger("images.generate"); let stage = "read_body"; @@ -46,6 +43,7 @@ export default defineEventHandler(async (event) => { return createErrorResponse(400, "请输入图片描述"); } + // 不记录完整 prompt，日志只保留长度，避免把用户输入或潜在敏感内容写进日志。 logger.info("开始", { promptLength: prompt.length }); @@ -54,24 +52,28 @@ export default defineEventHandler(async (event) => { try { stage = "read_user_id"; + // userId 来自服务端 httpOnly cookie，前端不能伪造请求体覆盖用户归属。 const userId = getNewApiUserIdFromCookie(event); logger.info("读取用户成功", { userId }); stage = "create_running_record"; + // 从这里开始才写数据库；参数错误和空 prompt 不会留下无效生图记录。 record = await createRunningImageGeneration(userId, prompt); logger.info("创建生图记录成功", { recordId: record.id.toString() }); stage = "get_api_key"; + // 完整 key 只在服务端内存中短暂使用，不写入响应、不写入日志。 const apiKey = await getAiArtStudioTokenKey(event); logger.info("获取服务端 key 成功", { recordId: record.id.toString() }); stage = "call_image_stream_api"; + // 上游通过 SSE 分段返回进度和最终 Markdown 图片链接，这里同步等待流结束。 const result = await askImgStream({ apiKey, prompt @@ -84,6 +86,7 @@ export default defineEventHandler(async (event) => { }); stage = "upload_lsky"; + // 归档图床用于长期保存；失败时仍继续返回 NewAPI 上游图片 URL。 const archiveResult = await archiveGeneratedImage({ imageUrl: result.imageUrl, userId, @@ -129,14 +132,16 @@ export default defineEventHandler(async (event) => { }); if (record) { - await finishImageGenerationFailed(record.id, record.startedAt, error).catch( - (recordError) => { - logger.error("更新失败记录失败", { - recordId: record?.id.toString() ?? null, - error: toSafeLogError(recordError) - }); - } - ); + await finishImageGenerationFailed( + record.id, + record.startedAt, + error + ).catch((recordError) => { + logger.error("更新失败记录失败", { + recordId: record?.id.toString() ?? null, + error: toSafeLogError(recordError) + }); + }); } if (isUnauthorizedError(error)) { @@ -144,10 +149,12 @@ export default defineEventHandler(async (event) => { return createErrorResponse(401, "未登录"); } + // 统一把上游错误包成前端约定的响应结构，避免泄露 key/cookie。 return createUpstreamErrorResponse(error, "图片生成失败"); } }); +/** 将生成图上传到 Lsky，返回图床地址；归档失败时降级为空结果 */ const archiveGeneratedImage = async ({ imageUrl, userId, @@ -193,7 +200,7 @@ const archiveGeneratedImage = async ({ hostedImageUrl: null, imageMimeType: null, hostedResponse: null, - errorMessage: "图片生成成功，但图床归档失败" + errorMessage: "图片生成成功，但图片归档失败" }; } }; @@ -212,6 +219,7 @@ const getStreamContentLength = (upstreamResponse: unknown) => { return 0; }; +/** 判断流式上游响应里是否包含 usage，用于日志确认上游是否正常结束 */ const hasStreamUsage = (upstreamResponse: unknown) => { return ( upstreamResponse !== null && diff --git a/server/api/images/history.get.ts b/server/api/images/history.get.ts index d865fe0..1c964d5 100644 --- a/server/api/images/history.get.ts +++ b/server/api/images/history.get.ts @@ -1,20 +1,19 @@ +// server/api/images/history.get.ts - 生图历史列表接口：分页返回当前用户未软删除的记录。 import type { IImageHistoryListData } from "#shared/types/openai"; -import { - clearNewApiAuthCookies, - createApiLogger, - createErrorResponse, - createSuccessResponse, - createUpstreamErrorResponse, - getNewApiUserIdFromCookie, - isUnauthorizedError, - listImageGenerationHistory, - toSafeLogError -} from "~~/server/utils"; const DEFAULT_PAGE = 1; const DEFAULT_PAGE_SIZE = 10; const MAX_PAGE_SIZE = 50; +/** + * GET /api/images/history + * + * 流程： + * 1. 从 httpOnly cookie 读取当前用户 ID。 + * 2. 读取 page/size 查询参数，并限制最大 pageSize，避免一次查太多。 + * 3. 只查询当前用户且未软删除的记录，按创建时间倒序返回。 + * 4. 列表不返回完整上游响应或图床响应，详情接口再返回这些调试数据。 + */ export default defineEventHandler(async (event) => { const logger = createApiLogger("images.history.list"); logger.info("开始"); @@ -68,6 +67,7 @@ export default defineEventHandler(async (event) => { } }); +/** 将 query 参数归一化为正整数，非法值回退到默认值 */ const normalizePositiveInt = ( value: unknown, fallbackValue: number diff --git a/server/api/images/history/[id].delete.ts b/server/api/images/history/[id].delete.ts index 8261e3f..b977b88 100644 --- a/server/api/images/history/[id].delete.ts +++ b/server/api/images/history/[id].delete.ts @@ -1,3 +1,4 @@ +// server/api/images/history/[id].delete.ts - 生图历史删除接口：软删除当前用户的单条记录。 import { clearNewApiAuthCookies, createApiLogger, @@ -10,6 +11,15 @@ import { toSafeLogError } from "~~/server/utils"; +/** + * DELETE /api/images/history/:id + * + * 流程： + * 1. 从 httpOnly cookie 读取当前用户 ID。 + * 2. 校验路由参数 id 必须是数字。 + * 3. 只软删除当前用户且未删除的记录，避免越权删除其他用户历史。 + * 4. 找不到记录时返回 404，数据库中保留原始记录和 deletedAt。 + */ export default defineEventHandler(async (event) => { const logger = createApiLogger("images.history.delete"); logger.info("开始"); @@ -55,6 +65,7 @@ export default defineEventHandler(async (event) => { } }); +/** 校验并解析路由里的生图记录 ID */ const parseRecordId = (value: string | undefined): bigint => { if (!value || !/^\d+$/.test(value)) { throw createError({ diff --git a/server/api/images/history/[id].get.ts b/server/api/images/history/[id].get.ts index 71953da..e470c48 100644 --- a/server/api/images/history/[id].get.ts +++ b/server/api/images/history/[id].get.ts @@ -1,3 +1,4 @@ +// server/api/images/history/[id].get.ts - 生图历史详情接口：返回当前用户单条记录和完整响应。 import type { IImageHistoryDetail } from "#shared/types/openai"; import { clearNewApiAuthCookies, @@ -11,6 +12,15 @@ import { toSafeLogError } from "~~/server/utils"; +/** + * GET /api/images/history/:id + * + * 流程： + * 1. 从 httpOnly cookie 读取当前用户 ID。 + * 2. 校验路由参数 id 必须是数字，并转成 BigInt 查询。 + * 3. 只允许读取当前用户、未软删除的记录。 + * 4. 返回详情时包含完整上游响应和 Lsky 响应，便于排查单次生图问题。 + */ export default defineEventHandler(async (event) => { const logger = createApiLogger("images.history.detail"); logger.info("开始"); @@ -61,6 +71,7 @@ export default defineEventHandler(async (event) => { } }); +/** 校验并解析路由里的生图记录 ID */ const parseRecordId = (value: string | undefined): bigint => { if (!value || !/^\d+$/.test(value)) { throw createError({ diff --git a/server/api/images/stats.get.ts b/server/api/images/stats.get.ts index 4ede490..f698a09 100644 --- a/server/api/images/stats.get.ts +++ b/server/api/images/stats.get.ts @@ -1,12 +1,14 @@ +// server/api/images/stats.get.ts - 生图统计接口：返回全局生图请求与成功失败统计。 import type { IImageGenerationStatsData } from "#shared/types/openai"; -import { - createApiLogger, - createSuccessResponse, - createUpstreamErrorResponse, - getGenerationStats, - toSafeLogError -} from "~~/server/utils"; +/** + * GET /api/images/stats + * + * 流程： + * 1. 读取 GenerationStats 的 global 单行统计。 + * 2. 没有统计行时返回全 0，避免前端需要处理空状态。 + * 3. 该接口返回全局统计，不包含用户输入、图片地址或上游响应。 + */ export default defineEventHandler(async () => { const logger = createApiLogger("images.stats"); logger.info("开始"); diff --git a/server/middleware/log.ts b/server/middleware/log.ts index eaf9ba8..0800279 100644 --- a/server/middleware/log.ts +++ b/server/middleware/log.ts @@ -1,3 +1,4 @@ +// server/middleware/log.ts - 全局请求日志中间件：记录 method、path、status 和耗时。 import { consola } from "consola"; /** diff --git a/server/utils/createApiResponse.ts b/server/utils/createApiResponse.ts index eb4d631..effeef3 100644 --- a/server/utils/createApiResponse.ts +++ b/server/utils/createApiResponse.ts @@ -1,5 +1,8 @@ +// server/utils/createApiResponse.ts - 统一封装后端接口成功/失败响应，并把内部异常转换为安全前端文案。 import type { ICommonResponse } from "#shared/types"; +const INTERNAL_SERVER_ERROR_MESSAGE = "服务器内部错误"; + /** * 构造统一成功响应。 * @@ -39,37 +42,17 @@ export const createErrorResponse = ( }; /** - * 将上游请求错误转换为统一响应。 + * 将上游或内部异常转换为统一响应。 * - * @param error ofetch 抛出的错误对象 - * @param fallbackMessage 当上游没有提供可用错误信息时的兜底提示 - * @returns 符合 ICommonResponse 格式的错误响应 + * 调用方必须先在服务端日志中记录 error。这里永远不把上游 message、响应体、 + * statusMessage 或 data 返回给前端，避免暴露内部服务、供应商、token 使用细节。 */ export const createUpstreamErrorResponse = ( error: unknown, - fallbackMessage: string = "请求失败" + _fallbackMessage: string = INTERNAL_SERVER_ERROR_MESSAGE ): ICommonResponse => { - const fetchError = error as { - data?: unknown; - message?: string; - response?: { - _data?: unknown; - status?: number; - }; - statusCode?: number; - }; - - const errorData = fetchError.data ?? fetchError.response?._data ?? null; - const errorMessage = - typeof errorData === "string" - ? errorData - : fetchError.message || fallbackMessage; - - return createErrorResponse( - fetchError.statusCode ?? fetchError.response?.status ?? 500, - errorMessage, - errorData - ); + void error; + return createErrorResponse(500, INTERNAL_SERVER_ERROR_MESSAGE); }; /** 判断上游或本地鉴权错误是否为 401，用于统一清理失效登录态 */ diff --git a/server/utils/fetch.ts b/server/utils/fetch.ts index 3c9dc83..4e14562 100644 --- a/server/utils/fetch.ts +++ b/server/utils/fetch.ts @@ -1,3 +1,4 @@ +// server/utils/fetch.ts - NewAPI 请求封装：集中维护 baseURL、raw fetch 和服务端鉴权请求。 import type { H3Event } from "h3"; import { createError, getCookie } from "h3"; import { diff --git a/server/utils/imageGenerationRecords.ts b/server/utils/imageGenerationRecords.ts index eae5893..65d37ef 100644 --- a/server/utils/imageGenerationRecords.ts +++ b/server/utils/imageGenerationRecords.ts @@ -1,3 +1,4 @@ +// server/utils/imageGenerationRecords.ts - 生图相关数据库操作：用户快照、生成记录、历史查询和统计。 import type { IUserBasicData } from "#shared/types"; import type { IImageGenerationStatsData, @@ -238,8 +239,8 @@ export const getImageGenerationDetail = async ( return { ...mapImageGenerationItem(record), imageMimeType: record.imageMimeType, - upstreamResponse: record.upstreamResponse, - hostedResponse: record.hostedResponse + upstreamResponse: null, + hostedResponse: null }; }; @@ -295,6 +296,7 @@ const upsertGenerationStats = (update: Prisma.GenerationStatsUpdateInput) => { }); }; +/** 更新统计失败不能影响主链路，避免统计表问题导致生图接口失败 */ const safeUpsertGenerationStats = async ( update: Prisma.GenerationStatsUpdateInput ) => { @@ -307,6 +309,7 @@ const safeUpsertGenerationStats = async ( } }; +/** upsert 创建统计行时，把本次 increment 转换为初始计数 */ const buildStatsCreateInput = (update: Prisma.GenerationStatsUpdateInput) => { return { totalRequests: getIncrementValue(update.totalRequests), @@ -318,6 +321,7 @@ const buildStatsCreateInput = (update: Prisma.GenerationStatsUpdateInput) => { }; }; +/** 从 Prisma increment 操作里取出增量；非 increment 操作在创建时按 0 处理 */ const getIncrementValue = (value: unknown): number => { if ( value && @@ -331,6 +335,7 @@ const getIncrementValue = (value: unknown): number => { return 0; }; +/** 将 Prisma 记录转换为前端类型，BigInt/Date 在这里统一序列化 */ const mapImageGenerationItem = (record: { id: bigint; userId: number; @@ -360,17 +365,30 @@ const mapImageGenerationItem = (record: { imageUrl: record.imageUrl, hostedImageUrl: record.hostedImageUrl, revisedPrompt: record.revisedPrompt, - errorMessage: record.errorMessage, + errorMessage: getPublicRecordMessage(record.status, record.errorMessage), createdAt: record.createdAt.toISOString() }; }; +/** 计算耗时并兜底为非负数，避免系统时间抖动导致负值 */ const getDurationMs = (startedAt: Date, endedAt: Date) => { return Math.max(0, endedAt.getTime() - startedAt.getTime()); }; +/** 保存到数据库的错误信息只保留可读摘要，不保存复杂错误对象 */ const getSafeErrorMessage = (error: unknown): string => { if (error instanceof Error) return error.message; if (typeof error === "string") return error; return "图片生成失败"; }; + +/** 返回给前端的记录错误只保留本地泛化文案，具体内部错误留在数据库和服务端日志 */ +const getPublicRecordMessage = ( + status: ImageGenerationStatus, + errorMessage: string | null +): string | null => { + if (!errorMessage) return null; + return status === ImageGenerationStatus.SUCCEEDED + ? "图片归档失败" + : "图片生成失败"; +}; diff --git a/server/utils/index.ts b/server/utils/index.ts index cf313d2..9466f68 100644 --- a/server/utils/index.ts +++ b/server/utils/index.ts @@ -1,3 +1,4 @@ +// server/utils/index.ts - 服务端工具统一导出口，方便 API handler 从同一入口导入。 export * from "./createApiResponse"; export * from "./fetch"; export * from "./imageGenerationRecords"; diff --git a/server/utils/logging.ts b/server/utils/logging.ts index 2b8fb7a..6dd2bda 100644 --- a/server/utils/logging.ts +++ b/server/utils/logging.ts @@ -1,8 +1,10 @@ +// server/utils/logging.ts - API 调试日志工具：为每次请求生成 requestId 并输出安全错误摘要。 import { randomUUID } from "node:crypto"; import { consola } from "consola"; type LogMeta = Record; +/** 创建带 requestId、scope 和耗时统计的接口日志器 */ export const createApiLogger = (scope: string) => { const requestId = randomUUID(); const startedAt = Date.now(); @@ -36,6 +38,7 @@ export const createApiLogger = (scope: string) => { }; }; +/** 将未知错误转换为可写入日志的安全摘要，避免把 cookie/key 等响应体细节打进日志 */ export const toSafeLogError = (error: unknown) => { const maybeError = error as { message?: string; diff --git a/server/utils/lsky.ts b/server/utils/lsky.ts index 7090df5..4cdef38 100644 --- a/server/utils/lsky.ts +++ b/server/utils/lsky.ts @@ -1,3 +1,4 @@ +// server/utils/lsky.ts - Lsky 图床上传工具：下载上游图片、重命名、打标签并上传归档。 import { createError } from "h3"; interface ILskyUploadInput { @@ -29,6 +30,14 @@ export interface ILskyUploadedImage { response: ILskyUploadResponse; } +/** + * 从远程图片 URL 下载图片并上传到 Lsky。 + * + * 注意： + * - Lsky 地址、Token、storage_id 都来自环境变量，代码不写死密钥。 + * - 文件名包含 userId、username、时间戳、recordId，方便图床侧追踪来源。 + * - 返回完整 Lsky 响应供数据库保存，但调用方不要把 token 写入日志。 + */ export const uploadImageFromUrl = async ( input: ILskyUploadInput ): Promise => { @@ -85,6 +94,7 @@ export const uploadImageFromUrl = async ( }; }; +/** 读取并校验 Lsky 环境变量配置 */ const getLskyConfig = () => { const baseUrl = process.env.LSKY_BASE_URL?.replace(/\/+$/, ""); const token = process.env.LSKY_TOKEN; @@ -109,6 +119,7 @@ const getLskyConfig = () => { }; }; +/** 下载上游图片二进制，保留 content-type 供上传和入库使用 */ const downloadImage = async (imageUrl: string) => { const response = await fetch(imageUrl); if (!response.ok) { @@ -121,6 +132,7 @@ const downloadImage = async (imageUrl: string) => { }; }; +/** 构造图床文件名：userId_username_timestamp_recordId.ext */ const buildArchiveFilename = ({ userId, username, @@ -139,6 +151,7 @@ const buildArchiveFilename = ({ return `${userId}_${safeUsername}_${timestamp}_${recordId.toString()}.${extension}`; }; +/** 给图片打固定标签，便于后续在图床里按项目、用户、记录和模型筛选 */ const buildArchiveTags = (userId: number, recordId: bigint) => { return [ "AIArtStudio", @@ -148,6 +161,7 @@ const buildArchiveTags = (userId: number, recordId: bigint) => { ]; }; +/** 清理文件名片段，避免中文/英文/数字/下划线/短横线以外的字符影响上传 */ const sanitizeFilenamePart = (value: string) => { const sanitized = value .trim() @@ -158,10 +172,12 @@ const sanitizeFilenamePart = (value: string) => { return sanitized || "user"; }; +/** 文件名使用紧凑 UTC 时间戳，避免冒号等字符影响跨平台兼容性 */ const formatTimestamp = (date: Date) => { return date.toISOString().replace(/\D/g, "").slice(0, 14); }; +/** 优先按 MIME 推断扩展名，MIME 不认识时再从 URL 路径兜底 */ const getImageExtension = (mimeType: string, imageUrl: string) => { const fromMimeType = mimeType.split(";")[0]?.trim().toLowerCase(); if (fromMimeType === "image/jpeg") return "jpg"; @@ -174,6 +190,7 @@ const getImageExtension = (mimeType: string, imageUrl: string) => { return extension && /^[a-z0-9]+$/.test(extension) ? extension : "png"; }; +/** 兼容 Lsky 可能返回的布尔或字符串成功状态 */ const isSuccessStatus = (status: unknown) => { return status === true || status === "success" || status === "ok"; }; diff --git a/server/utils/newApiAuthCookies.ts b/server/utils/newApiAuthCookies.ts index bcb8fc1..8e1a6c7 100644 --- a/server/utils/newApiAuthCookies.ts +++ b/server/utils/newApiAuthCookies.ts @@ -1,3 +1,4 @@ +// server/utils/newApiAuthCookies.ts - NewAPI 登录态 cookie 工具：提取上游 session 并用 httpOnly 保存。 import type { H3Event } from "h3"; import { createError, deleteCookie, getCookie, setCookie } from "h3"; diff --git a/server/utils/newApiTokens.ts b/server/utils/newApiTokens.ts index c914d83..fe9a589 100644 --- a/server/utils/newApiTokens.ts +++ b/server/utils/newApiTokens.ts @@ -1,3 +1,4 @@ +// server/utils/newApiTokens.ts - NewAPI Token 工具：准备 AIArtStudio Token 并在服务端读取完整 key。 import type { H3Event } from "h3"; import { createError } from "h3"; import type { IUserReadyData } from "#shared/types"; diff --git a/server/utils/openai.ts b/server/utils/openai.ts index 5403687..46b5243 100644 --- a/server/utils/openai.ts +++ b/server/utils/openai.ts @@ -1,4 +1,4 @@ -// server/utils/openai.ts +// server/utils/openai.ts - OpenAI/NewAPI 调用工具：文本、视觉、Responses 流式和 Chat Completions 流式生图。 import OpenAI from "openai"; import type { BaseOptions, IImageGenerateData } from "#shared/types/openai"; diff --git a/server/utils/prisma.ts b/server/utils/prisma.ts index 69aa022..1c884d5 100644 --- a/server/utils/prisma.ts +++ b/server/utils/prisma.ts @@ -1,3 +1,4 @@ +// server/utils/prisma.ts - Prisma 客户端初始化：使用 MariaDB adapter 并在开发热更新中复用连接池。 import { PrismaMariaDb } from "@prisma/adapter-mariadb"; import { PrismaClient } from "~~/app/generated/prisma/client"; @@ -16,6 +17,7 @@ type MariaDbPoolConfig = Exclude< string >; +/** 从 DATABASE_URL 查询参数读取连接池配置，非法值回退到默认值 */ function getNumberParam(url: URL, name: string, fallback: number) { const value = url.searchParams.get(name); if (!value) { @@ -26,6 +28,7 @@ function getNumberParam(url: URL, name: string, fallback: number) { return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback; } +/** 将 DATABASE_URL 拆成 Prisma MariaDB adapter 需要的连接池配置 */ function createMariaDbConfig(urlString: string): MariaDbPoolConfig { const url = new URL(urlString); const database = decodeURIComponent(url.pathname.replace(/^\//, "")); diff --git a/shared/types/openai.ts b/shared/types/openai.ts index 34fb4e7..c16f8e5 100644 --- a/shared/types/openai.ts +++ b/shared/types/openai.ts @@ -64,7 +64,7 @@ export interface IImageHistoryItem { hostedImageUrl: string | null; /** 上游返回的修订提示词，可能为空 */ revisedPrompt: string | null; - /** 失败原因或图床归档提示 */ + /** 面向前端的本地泛化错误提示，不包含上游或内部服务细节 */ errorMessage: string | null; /** 记录创建时间，ISO 字符串 */ createdAt: string; @@ -76,9 +76,9 @@ export interface IImageHistoryItem { export interface IImageHistoryDetail extends IImageHistoryItem { /** 图片 MIME 类型，可能为空 */ imageMimeType: string | null; - /** 完整上游生图接口返回结果 */ + /** 内部响应不向前端透出，当前固定为 null */ upstreamResponse: unknown; - /** 完整 Lsky 图床上传接口返回结果 */ + /** 内部图床响应不向前端透出，当前固定为 null */ hostedResponse: unknown; }