从上传到生成：Next.js 图片风格转换工具的服务端链路设计

最近在开发一个图片转动漫工具。最初我以为它只是一个普通的文件上传页面：用户选择图片，服务端调用图像模型，然后把结果返回给浏览器。

真正开始实现后，我发现模型调用只占整个流程的一小部分。一个可以稳定运行的图片生成工具，还要处理文件校验、对象存储、身份认证、任务状态、积分扣除、失败退款和跨域下载等问题。

本文不讨论提示词效果，而是记录我在 Next.js 中组织这条生成链路时采用的方案，以及几个容易被忽略的问题。

一、先把生成过程拆成状态机

如果只用一个 loading 布尔值表示生成状态，界面很快就会变得混乱。上传失败、模型处理中和结果下载失败，都可能被显示成同一种错误。

我将一次生成拆成以下状态：

empty
  ↓
source_selected
  ↓
uploading
  ↓
submitting
  ↓
processing
  ↓
success / failed

其中：

• empty：用户还没有选择图片；
• source_selected：图片已经在浏览器中完成预览；
• uploading：源文件正在上传到对象存储；
• submitting：服务端正在创建生成任务；
• processing：第三方模型已经接收任务；
• success：结果已经写入存储并可以下载；
• failed：上传、提交或模型执行失败。

状态拆开后，按钮禁用、提示文字和异常恢复都会更清晰。例如，上传阶段显示“正在上传图片”，模型执行阶段显示“正在转换图片”，而不是始终显示含义模糊的“处理中”。

二、浏览器只负责选择文件，不直接接触模型密钥

图像模型的 API Key 不能放在客户端环境变量中。即使变量名带有“私有”字样，只要代码被打进浏览器包，就可能被用户读取。

我采用的调用路径如下：

浏览器
  → 请求短期上传凭证
  → 上传源图片到对象存储
  → 向 Next.js 服务端提交生成请求
  → 服务端检查用户和积分
  → 服务端调用图像模型
  → 保存生成记录
  → 浏览器查询结果

浏览器上传前先向服务端申请一个短期有效的预签名地址，然后直接把文件写入对象存储。服务端只接收存储后的文件地址，不需要在应用服务器中转完整图片。

这种方式有两个好处：

1. 减少应用服务器处理大文件的压力；
2. 服务端仍然能够控制文件类型、大小、存储路径和凭证有效期。

不过，预签名上传不能代替服务端校验。客户端的 accept 属性只能改善文件选择体验，不能作为安全边界。

const allowedTypes = new Set([
  "image/jpeg",
  "image/png",
  "image/webp",
]);

if (!allowedTypes.has(file.type)) {
  throw new Error("Unsupported image type");
}

if (file.size > MAX_IMAGE_SIZE) {
  throw new Error("Image is too large");
}

服务端还应该限制上传路径，避免客户端自行指定任意对象 Key。

三、把风格配置与页面组件分离

图片转动漫工具通常会提供多种视觉风格。如果把模型名称、提示词和计费规则直接写在 React 组件中，后续增加风格时会不断修改页面逻辑。

我将风格整理成独立配置：

type StyleConfig = {
  id: string;
  label: string;
  modelId: string;
  pricingOption: string;
  prompt: string;
  referenceImage?: string;
};

页面只负责展示风格和记录用户选择。真正提交时，再根据配置生成请求参数。

这里需要注意，客户端传来的 modelId、清晰度和积分价格都不能直接信任。服务端必须通过自己的配置表重新查询模型，并重新计算本次任务需要消耗的积分。

否则，用户可以绕过页面，手动修改请求中的积分数量或模型名称。

这套配置结构目前已经应用在一个实际的image to anime工具中。页面组件只读取风格名称、预览图和选中状态，不直接保存模型的计费规则。提交任务时，服务端会根据风格标识重新查询对应配置，避免客户端参数被修改后影响模型选择和积分计算。

页面只负责展示风格和记录用户选择。真正提交时，再根据配置生成请求参数。

四、积分扣除必须由服务端完成

为了让界面更快反馈，客户端可以提前检查余额，但它只能作为体验优化，不能作为最终判断。

真正的扣费流程应该放在服务端：

验证登录状态
  → 验证模型和参数
  → 计算积分成本
  → 查询余额
  → 创建生成记录
  → 扣除积分
  → 调用模型

生成记录最好拥有唯一任务编号，并记录以下字段：

user_id
task_id
generation_type
model
credit_cost
status
input_url
output_url
error_message
created_at

如果模型任务失败，需要通过同一条生成记录执行退款。退款操作还要保证幂等性，避免轮询、回调重试或用户刷新页面导致重复返还积分。

一种简单的做法是在记录中增加 refunded_at 字段。只有任务状态为失败并且尚未退款时，才允许写入退款流水。

五、不要让第三方模型状态泄漏到前端

不同模型服务商对任务状态的命名并不一致，例如 queued、running、completed、succeeded 或 error。如果前端直接依赖这些字段，更换服务商时就需要同时修改界面。

我在服务端将它们统一成内部状态：

type GenerationStatus =
  | "pending"
  | "processing"
  | "success"
  | "failed";

适配层负责把服务商响应转换成统一结构：

type GenerationResult = {
  taskId: string;
  status: GenerationStatus;
  outputUrl?: string;
  error?: string;
};

这样，页面只关心任务是否还在执行、是否成功，以及是否需要展示错误。服务商名称、原始错误码和请求结构都保留在服务端。

对于展示给用户的错误，也不应该直接返回第三方接口的完整响应。原始响应可能包含内部地址、请求参数甚至敏感信息。服务端记录详细日志，客户端只接收经过整理的错误提示。

六、下载功能也会遇到跨域问题

生成结果经常存储在第三方域名或对象存储中。直接创建 <a download> 并不总能触发下载，有些浏览器会把图片打开到新页面。

更稳定的方式是由服务端提供受控的文件代理，或者让对象存储返回正确的响应头：

Content-Disposition: attachment; filename="result.png"
Content-Type: image/png

如果使用文件代理，还需要限制允许访问的域名，不能让接口接受任意 URL，否则可能形成服务端请求伪造风险。

七、这次实现中最重要的几个结论

完成整条链路后，我认为图片生成工具最重要的部分并不是“调用一次模型接口”，而是围绕模型建立可靠的业务边界。

我的几个实践结论是：

1. 用明确的状态机描述上传和生成过程；
2. 模型密钥、计费规则和任务适配全部放在服务端；
3. 大文件通过短期预签名地址上传；
4. 客户端检查只用于改善体验，服务端必须重新验证；
5. 扣费、失败记录和退款要围绕同一个任务编号设计；
6. 对前端屏蔽不同模型服务商的状态差异；
7. 下载代理必须限制来源地址并正确设置响应头。

这些工作看起来与图片生成效果没有直接关系，却决定了工具能否从演示页面变成可以持续运行的产品。后续如果继续扩展更多图片工具，我会优先复用上传、任务、计费和结果展示链路，只把模型参数与领域提示词留在具体工具中。