Nunchaku-flux-1-dev实战基于Node.js构建图像生成API服务最近在折腾AI图像生成发现很多模型虽然效果惊艳但部署和使用起来对非AI背景的开发者来说门槛还是有点高。特别是想把模型能力集成到自己的应用里比如做个创意工具网站或者给电商平台加个自动作图功能总不能每次都让用户去跑命令行吧。于是我就琢磨着怎么把像Nunchaku-flux-1-dev这样的图像生成模型包装成一个简单易用的Web API服务。这样一来前端开发、移动端应用或者其他后端服务只需要发个HTTP请求就能拿到生成的图片多方便。今天要聊的就是怎么用Node.js和Express一步步搭建一个稳定、好用、还带点企业级功能的图像生成API服务。我们会用到任务队列来管理高并发的生成请求加上身份验证、请求限流这些保障措施最后还会自动生成API文档。整个过程我会尽量用大白话讲清楚即使你Node.js刚入门跟着做也能跑起来。1. 项目蓝图与核心思路在开始敲代码之前我们先盘算一下这个API服务需要具备哪些能力以及背后的技术选型是怎么考虑的。1.1 我们要解决什么问题想象一下你的应用突然有几十上百个用户同时提交了图片生成请求。如果让Node.js主线程直接去调用模型这个耗时操作会立刻把整个服务“卡住”其他用户的请求都得排队等着体验极差。更别提模型本身可能还不稳定偶尔会出错。所以我们的核心思路是“异步解耦”。把接收请求和实际生成图片这两件事分开。用户发来请求我们快速响应“收到啦正在处理”然后把这个生成任务丢到一个“任务队列”里慢慢处理。处理完了再通知用户来取结果。这样API接口的响应速度飞快后台也能从容不迫地处理任务。1.2 技术栈选型基于上面的思路我选了下面这套组合拳它们都是Node.js生态里久经考验的利器Express: Node.js最流行的Web框架用来快速搭建RESTful API的路由和中间件。Bull: 一个基于Redis的快速、可靠的Node.js任务队列库。它负责管理我们的图片生成任务确保每个任务只被执行一次还能重试失败的任务。JSON Web Tokens (JWT): 用来做API的身份验证。用户先登录获取一个令牌Token之后每次请求API都带上这个令牌我们就知道是谁在调用。express-rate-limit: 一个简单的中间件用来给API接口限流防止被恶意刷接口保护后台资源。Swagger UI Express: 用来自动生成和展示漂亮的API交互式文档。前端同事一看就知道怎么调不用你再写文档了。Axios: 用来在Node.js服务内部向真正运行Nunchaku-flux-1-dev模型的后端服务比如用Python Flask搭的发送HTTP请求。当然如果你能把模型直接集成在Node.js进程里这一步可以简化。整个架构的流程我画了个简单的图帮你理解graph TD A[客户端请求] -- B[Express API Server] B -- C{JWT验证 限流} C --|通过| D[接收请求 创建Bull任务] D -- E[Bull任务队列 Redis] E -- F[Worker进程 处理任务] F -- G[调用模型后端服务] G -- H[返回生成结果] H -- F F -- I[更新任务状态] I -- E D -- J[返回任务ID给客户端] J -- K[客户端轮询结果] K -- L[查询任务状态] L -- M{任务完成?} M --|是| N[返回图片URL/数据] M --|否| K简单说用户请求先经过网关验证和限流然后变成任务进队列后台工人慢慢处理用户可以通过任务ID查询进度。2. 从零开始搭建项目基础好了理论说完我们动手把项目架子搭起来。2.1 环境准备与项目初始化首先确保你的机器上安装了Node.js建议版本16和npm。打开终端创建一个新目录并初始化项目# 创建项目文件夹并进入 mkdir nunchaku-flux-api cd nunchaku-flux-api # 初始化npm项目一路回车用默认值就行 npm init -y接下来安装我们需要的核心依赖包npm install express bull redis jsonwebtoken dotenv express-rate-limit swagger-ui-express axios同时安装一些开发时用的工具包比如用nodemon来自动重启服务npm install --save-dev nodemon安装完成后打开package.json文件在scripts部分添加一个启动脚本方便开发{ scripts: { start: node server.js, dev: nodemon server.js, worker: node worker.js } }2.2 项目结构设计一个清晰的项目结构能让代码更好维护。我们的项目大概长这样nunchaku-flux-api/ ├── server.js # Express主服务器入口 ├── worker.js # Bull队列的工作进程入口 ├── .env # 环境变量配置文件不要提交到git ├── package.json ├── src/ │ ├── routes/ # API路由 │ │ └── generate.js │ ├── queues/ # Bull队列定义 │ │ └── imageQueue.js │ ├── middleware/ # 自定义中间件如认证、错误处理 │ │ ├── auth.js │ │ └── errorHandler.js │ ├── utils/ # 工具函数 │ │ └── apiClient.js # 调用模型后端的客户端 │ └── docs/ # Swagger API文档定义 │ └── swaggerDef.js └── README.md你可以先用命令创建这些目录mkdir -p src/{routes,queues,middleware,utils,docs}。2.3 核心配置文件在项目根目录创建一个.env文件用来存放敏感信息和配置。切记把这个文件加到.gitignore里不要上传到公开仓库。# .env 文件示例 NODE_ENVdevelopment PORT3000 # JWT密钥用于签名和验证Token务必用强密码 JWT_SECRETyour_super_secret_jwt_key_change_this # Redis连接信息Bull队列依赖它 REDIS_HOSTlocalhost REDIS_PORT6379 REDIS_PASSWORD # 如果Redis有密码就填上 # 模型后端服务的地址假设你用Python Flask等搭了一个 MODEL_API_BASE_URLhttp://localhost:5000 MODEL_API_KEYyour_model_service_api_key_if_any # API速率限制 RATE_LIMIT_WINDOW_MS900000 # 15分钟 RATE_LIMIT_MAX_REQUESTS100 # 15分钟内最多100次请求然后在server.js的顶部我们加载这些配置// server.js require(dotenv).config(); // 加载.env文件中的环境变量 const express require(express); const app express(); const PORT process.env.PORT || 3000; // 后续中间件和路由...基础打好了接下来我们开始砌墙构建API的核心功能。3. 构建API核心功能模块这一部分我们把身份验证、任务队列、模型调用这些核心功能一个个实现。3.1 用户认证与请求限流首先在src/middleware/auth.js里创建一个简单的JWT验证中间件。这里为了演示我们假设用户已经通过某个登录接口拿到了JWT令牌。// src/middleware/auth.js const jwt require(jsonwebtoken); const authenticateToken (req, res, next) { // 从请求头中获取token const authHeader req.headers[authorization]; const token authHeader authHeader.split( )[1]; // 格式Bearer token if (!token) { return res.status(401).json({ error: 访问被拒绝未提供认证令牌 }); } jwt.verify(token, process.env.JWT_SECRET, (err, user) { if (err) { return res.status(403).json({ error: 令牌无效或已过期 }); } // 把解码后的用户信息挂载到request对象上供后续路由使用 req.user user; next(); // 验证通过继续下一个中间件或路由 }); }; module.exports { authenticateToken };接着在src/middleware/下创建rateLimiter.js设置API调用频率限制// src/middleware/rateLimiter.js const rateLimit require(express-rate-limit); // 创建一个限流器15分钟内最多允许100次请求 const apiLimiter rateLimit({ windowMs: process.env.RATE_LIMIT_WINDOW_MS || 15 * 60 * 1000, // 15分钟 max: process.env.RATE_LIMIT_MAX_REQUESTS || 100, message: { error: 请求过于频繁请在15分钟后再试。 }, standardHeaders: true, // 在RateLimit-* headers中返回速率限制信息 legacyHeaders: false, // 禁用X-RateLimit-* headers }); module.exports { apiLimiter };3.2 创建异步任务队列现在来创建最重要的部分——任务队列。在src/queues/imageQueue.js中定义我们的Bull队列。// src/queues/imageQueue.js const Queue require(bull); const { createBullBoard } require(bull-board/api); const { BullAdapter } require(bull-board/api/bullAdapter); const { ExpressAdapter } require(bull-board/express); // 连接到Redis const imageQueue new Queue(image generation, { redis: { host: process.env.REDIS_HOST || localhost, port: process.env.REDIS_PORT || 6379, password: process.env.REDIS_PASSWORD || undefined, }, defaultJobOptions: { // 任务默认尝试3次每次失败后延迟5秒重试 attempts: 3, backoff: { type: fixed, delay: 5000, }, // 任务最多执行2分钟 timeout: 120000, }, }); // 可选设置Bull Board用于可视化监控队列需要额外安装bull-board包 // const serverAdapter new ExpressAdapter(); // serverAdapter.setBasePath(/admin/queues); // createBullBoard({ // queues: [new BullAdapter(imageQueue)], // serverAdapter: serverAdapter, // }); module.exports imageQueue;这个队列叫“image generation”连接到你本地的Redis。每个任务会尝试3次超时时间是2分钟。3.3 实现模型调用客户端队列里的任务需要有人Worker来处理处理的核心就是调用真正的图像生成模型。我们在src/utils/apiClient.js里封装一个调用模型后端服务的客户端。// src/utils/apiClient.js const axios require(axios); // 创建axios实例配置模型后端的基础地址和认证信息 const modelApiClient axios.create({ baseURL: process.env.MODEL_API_BASE_URL, timeout: 60000, // 60秒超时 headers: { Content-Type: application/json, // 如果模型服务需要API Key可以在这里或每个请求中添加 // Authorization: Bearer ${process.env.MODEL_API_KEY} }, }); /** * 调用Nunchaku-flux-1-dev模型生成图片 * param {Object} params - 生成参数如prompt, negative_prompt, steps等 * returns {PromiseObject} - 返回模型服务的响应数据 */ async function generateImage(params) { try { // 这里需要根据你实际模型后端的API接口来调整 const response await modelApiClient.post(/generate, params); return response.data; } catch (error) { console.error(调用模型API失败:, error.message); // 可以根据错误类型抛出更具体的错误供Worker处理 if (error.response) { // 请求已发出服务器返回了错误状态码 throw new Error(模型服务错误: ${error.response.status} - ${JSON.stringify(error.response.data)}); } else if (error.request) { // 请求发出但没有收到响应 throw new Error(无法连接到模型服务请检查服务是否运行); } else { // 其他错误 throw new Error(请求配置错误: ${error.message}); } } } module.exports { generateImage };这个函数就是Worker工作的核心它负责与真正的AI模型“对话”。4. 组装与运行让服务活起来模块都准备好了现在我们把它们组装起来并让Worker开始工作。4.1 编写Worker处理进程创建worker.js它的职责就是从imageQueue里取出任务调用上面的generateImage函数然后更新任务状态。// worker.js require(dotenv).config(); const imageQueue require(./src/queues/imageQueue); const { generateImage } require(./src/utils/apiClient); console.log(图像生成Worker已启动等待任务...); // 处理队列中的任务 imageQueue.process(async (job) { console.log(开始处理任务 ID: ${job.id}); const { prompt, negative_prompt, steps, cfg_scale, width, height } job.data; try { // 1. 调用模型生成图片 const result await generateImage({ prompt, negative_prompt, steps: steps || 20, cfg_scale: cfg_scale || 7.5, width: width || 512, height: height || 512, }); console.log(任务 ${job.id} 处理成功); // 2. 返回成功结果。这里假设模型返回了图片的URL或Base64数据 // 实际应根据你的模型后端返回的数据结构调整 return { success: true, jobId: job.id, imageUrl: result.image_url, // 或者 imageData: result.image_base64 metadata: { prompt, ...result.metadata, // 可能包含生成用时、种子等信息 }, }; } catch (error) { console.error(处理任务 ${job.id} 时出错:, error.message); // 抛出错误Bull会根据配置进行重试 throw error; } }); // 监听任务完成事件 imageQueue.on(completed, (job, result) { console.log(任务 ${job.id} 已完成结果:, result.success); }); // 监听任务失败事件 imageQueue.on(failed, (job, err) { console.error(任务 ${job.id} 失败错误:, err.message); });4.2 构建Express API路由现在来创建API接口本身。在src/routes/generate.js中// src/routes/generate.js const express require(express); const router express.Router(); const imageQueue require(../queues/imageQueue); const { authenticateToken } require(../middleware/auth); const { apiLimiter } require(../middleware/rateLimiter); /** * route POST /api/generate * desc 提交一个图像生成任务 * access Private (需要JWT认证) */ router.post(/generate, authenticateToken, apiLimiter, async (req, res) { const { prompt, negative_prompt, steps, cfg_scale, width, height } req.body; // 简单的请求体验证 if (!prompt || typeof prompt ! string) { return res.status(400).json({ error: 必须提供有效的提示词(prompt) }); } try { // 将生成任务添加到队列 const job await imageQueue.add({ prompt, negative_prompt, steps, cfg_scale, width, height, userId: req.user.id, // 从JWT中获取的用户ID }); // 立即返回任务ID客户端可以用它来查询状态 res.status(202).json({ // 202 Accepted 表示请求已接受正在处理 message: 图像生成任务已提交, jobId: job.id, statusUrl: /api/job/${job.id}, }); } catch (error) { console.error(提交任务到队列失败:, error); res.status(500).json({ error: 服务器内部错误无法提交任务 }); } }); /** * route GET /api/job/:jobId * desc 查询指定任务的状态和结果 * access Private (需要JWT认证) */ router.get(/job/:jobId, authenticateToken, async (req, res) { const { jobId } req.params; try { const job await imageQueue.getJob(jobId); if (!job) { return res.status(404).json({ error: 未找到该任务 }); } // 检查任务是否属于当前用户简单权限控制 if (job.data.userId ! req.user.id) { return res.status(403).json({ error: 无权查看此任务 }); } const state await job.getState(); const result job.returnvalue; const response { jobId, status: state, progress: job.progress(), // 如果有设置进度的话 data: job.data, }; if (state completed) { response.result result; } else if (state failed) { response.error job.failedReason; } res.json(response); } catch (error) { console.error(查询任务状态失败:, error); res.status(500).json({ error: 查询任务状态时发生错误 }); } }); module.exports router;4.3 集成Swagger API文档为了让API更友好我们集成Swagger。先创建文档定义src/docs/swaggerDef.js// src/docs/swaggerDef.js const swaggerJSDoc require(swagger-jsdoc); const options { definition: { openapi: 3.0.0, info: { title: Nunchaku-flux-1-dev 图像生成API, version: 1.0.0, description: 一个基于Node.js和Bull队列的异步图像生成RESTful API服务, }, servers: [ { url: http://localhost:${process.env.PORT || 3000}, description: 开发服务器, }, ], components: { securitySchemes: { bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT, }, }, }, security: [{ bearerAuth: [] }], }, apis: [./src/routes/*.js], // 指定包含注释的路由文件 }; const swaggerSpec swaggerJSDoc(options); module.exports swaggerSpec;然后在server.js中引入并设置Swagger UI// server.js (部分代码) const swaggerUi require(swagger-ui-express); const swaggerSpec require(./src/docs/swaggerDef); const generateRoutes require(./src/routes/generate); // ... 其他引入 const app express(); // 中间件 app.use(express.json()); // 解析JSON请求体 app.use(express.urlencoded({ extended: true })); // 静态文件服务如果需要托管生成的图片 app.use(/output, express.static(public/output)); // API路由 app.use(/api, generateRoutes); // Swagger API文档路由 app.use(/api-docs, swaggerUi.serve, swaggerUi.setup(swaggerSpec)); // 一个简单的根路由 app.get(/, (req, res) { res.send(h1Nunchaku-flux-1-dev 图像生成API服务/h1p访问 a href/api-docs/api-docs/a 查看API文档。/p); }); // 全局错误处理中间件放在所有路由之后 app.use((err, req, res, next) { console.error(err.stack); res.status(500).json({ error: 服务器内部错误 }); }); app.listen(PORT, () { console.log(API服务器运行在 http://localhost:${PORT}); console.log(API文档地址: http://localhost:${PORT}/api-docs); });4.4 启动与测试一切就绪你需要打开三个终端窗口启动Redis服务如果你本地没装Redis可以用Docker快速启动一个docker run -d -p 6379:6379 redis:alpine启动Express API服务器npm run dev启动Worker进程npm run worker现在打开浏览器访问http://localhost:3000/api-docs你应该能看到自动生成的Swagger UI界面。你可以在这里直接尝试调用/api/generate接口需要先在Headers里设置Authorization: Bearer 你的JWT令牌。5. 总结与后续优化方向走完这一趟一个具备基本生产可用性的图像生成API服务就搭建起来了。它解决了同步处理卡顿的问题通过任务队列实现了异步化并且加上了身份认证和限流这两道安全锁。Swagger文档也让接口调用变得一目了然。实际用起来你会发现这个基础版本还有不少可以打磨的地方。比如图片生成后是返回一个URL链接还是直接Base64数据流需要根据你的存储方案来定。你可以把图片存到本地文件夹然后用express.static提供访问或者上传到云存储如AWS S3、阿里云OSS返回一个临时访问链接。对于更复杂的场景可能还需要考虑任务优先级、多个Worker负载均衡、更细致的用户配额管理以及一个更漂亮的前端界面来展示任务历史和结果。不过这个项目最重要的价值是提供了一个清晰、可扩展的架构思路。它把复杂的AI模型能力封装成了任何开发者都能轻松调用的HTTP接口。你可以基于这个骨架根据自己的业务需求轻松地添砖加瓦。下次当你需要把某个AI能力集成到自己的产品中时不妨试试这个“异步任务队列Web API”的模式它会让你和你的用户都轻松不少。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
Nunchaku-flux-1-dev实战：基于Node.js构建图像生成API服务
发布时间：2026/7/29 23:32:50
Nunchaku-flux-1-dev实战基于Node.js构建图像生成API服务最近在折腾AI图像生成发现很多模型虽然效果惊艳但部署和使用起来对非AI背景的开发者来说门槛还是有点高。特别是想把模型能力集成到自己的应用里比如做个创意工具网站或者给电商平台加个自动作图功能总不能每次都让用户去跑命令行吧。于是我就琢磨着怎么把像Nunchaku-flux-1-dev这样的图像生成模型包装成一个简单易用的Web API服务。这样一来前端开发、移动端应用或者其他后端服务只需要发个HTTP请求就能拿到生成的图片多方便。今天要聊的就是怎么用Node.js和Express一步步搭建一个稳定、好用、还带点企业级功能的图像生成API服务。我们会用到任务队列来管理高并发的生成请求加上身份验证、请求限流这些保障措施最后还会自动生成API文档。整个过程我会尽量用大白话讲清楚即使你Node.js刚入门跟着做也能跑起来。1. 项目蓝图与核心思路在开始敲代码之前我们先盘算一下这个API服务需要具备哪些能力以及背后的技术选型是怎么考虑的。1.1 我们要解决什么问题想象一下你的应用突然有几十上百个用户同时提交了图片生成请求。如果让Node.js主线程直接去调用模型这个耗时操作会立刻把整个服务“卡住”其他用户的请求都得排队等着体验极差。更别提模型本身可能还不稳定偶尔会出错。所以我们的核心思路是“异步解耦”。把接收请求和实际生成图片这两件事分开。用户发来请求我们快速响应“收到啦正在处理”然后把这个生成任务丢到一个“任务队列”里慢慢处理。处理完了再通知用户来取结果。这样API接口的响应速度飞快后台也能从容不迫地处理任务。1.2 技术栈选型基于上面的思路我选了下面这套组合拳它们都是Node.js生态里久经考验的利器Express: Node.js最流行的Web框架用来快速搭建RESTful API的路由和中间件。Bull: 一个基于Redis的快速、可靠的Node.js任务队列库。它负责管理我们的图片生成任务确保每个任务只被执行一次还能重试失败的任务。JSON Web Tokens (JWT): 用来做API的身份验证。用户先登录获取一个令牌Token之后每次请求API都带上这个令牌我们就知道是谁在调用。express-rate-limit: 一个简单的中间件用来给API接口限流防止被恶意刷接口保护后台资源。Swagger UI Express: 用来自动生成和展示漂亮的API交互式文档。前端同事一看就知道怎么调不用你再写文档了。Axios: 用来在Node.js服务内部向真正运行Nunchaku-flux-1-dev模型的后端服务比如用Python Flask搭的发送HTTP请求。当然如果你能把模型直接集成在Node.js进程里这一步可以简化。整个架构的流程我画了个简单的图帮你理解graph TD A[客户端请求] -- B[Express API Server] B -- C{JWT验证 限流} C --|通过| D[接收请求 创建Bull任务] D -- E[Bull任务队列 Redis] E -- F[Worker进程 处理任务] F -- G[调用模型后端服务] G -- H[返回生成结果] H -- F F -- I[更新任务状态] I -- E D -- J[返回任务ID给客户端] J -- K[客户端轮询结果] K -- L[查询任务状态] L -- M{任务完成?} M --|是| N[返回图片URL/数据] M --|否| K简单说用户请求先经过网关验证和限流然后变成任务进队列后台工人慢慢处理用户可以通过任务ID查询进度。2. 从零开始搭建项目基础好了理论说完我们动手把项目架子搭起来。2.1 环境准备与项目初始化首先确保你的机器上安装了Node.js建议版本16和npm。打开终端创建一个新目录并初始化项目# 创建项目文件夹并进入 mkdir nunchaku-flux-api cd nunchaku-flux-api # 初始化npm项目一路回车用默认值就行 npm init -y接下来安装我们需要的核心依赖包npm install express bull redis jsonwebtoken dotenv express-rate-limit swagger-ui-express axios同时安装一些开发时用的工具包比如用nodemon来自动重启服务npm install --save-dev nodemon安装完成后打开package.json文件在scripts部分添加一个启动脚本方便开发{ scripts: { start: node server.js, dev: nodemon server.js, worker: node worker.js } }2.2 项目结构设计一个清晰的项目结构能让代码更好维护。我们的项目大概长这样nunchaku-flux-api/ ├── server.js # Express主服务器入口 ├── worker.js # Bull队列的工作进程入口 ├── .env # 环境变量配置文件不要提交到git ├── package.json ├── src/ │ ├── routes/ # API路由 │ │ └── generate.js │ ├── queues/ # Bull队列定义 │ │ └── imageQueue.js │ ├── middleware/ # 自定义中间件如认证、错误处理 │ │ ├── auth.js │ │ └── errorHandler.js │ ├── utils/ # 工具函数 │ │ └── apiClient.js # 调用模型后端的客户端 │ └── docs/ # Swagger API文档定义 │ └── swaggerDef.js └── README.md你可以先用命令创建这些目录mkdir -p src/{routes,queues,middleware,utils,docs}。2.3 核心配置文件在项目根目录创建一个.env文件用来存放敏感信息和配置。切记把这个文件加到.gitignore里不要上传到公开仓库。# .env 文件示例 NODE_ENVdevelopment PORT3000 # JWT密钥用于签名和验证Token务必用强密码 JWT_SECRETyour_super_secret_jwt_key_change_this # Redis连接信息Bull队列依赖它 REDIS_HOSTlocalhost REDIS_PORT6379 REDIS_PASSWORD # 如果Redis有密码就填上 # 模型后端服务的地址假设你用Python Flask等搭了一个 MODEL_API_BASE_URLhttp://localhost:5000 MODEL_API_KEYyour_model_service_api_key_if_any # API速率限制 RATE_LIMIT_WINDOW_MS900000 # 15分钟 RATE_LIMIT_MAX_REQUESTS100 # 15分钟内最多100次请求然后在server.js的顶部我们加载这些配置// server.js require(dotenv).config(); // 加载.env文件中的环境变量 const express require(express); const app express(); const PORT process.env.PORT || 3000; // 后续中间件和路由...基础打好了接下来我们开始砌墙构建API的核心功能。3. 构建API核心功能模块这一部分我们把身份验证、任务队列、模型调用这些核心功能一个个实现。3.1 用户认证与请求限流首先在src/middleware/auth.js里创建一个简单的JWT验证中间件。这里为了演示我们假设用户已经通过某个登录接口拿到了JWT令牌。// src/middleware/auth.js const jwt require(jsonwebtoken); const authenticateToken (req, res, next) { // 从请求头中获取token const authHeader req.headers[authorization]; const token authHeader authHeader.split( )[1]; // 格式Bearer token if (!token) { return res.status(401).json({ error: 访问被拒绝未提供认证令牌 }); } jwt.verify(token, process.env.JWT_SECRET, (err, user) { if (err) { return res.status(403).json({ error: 令牌无效或已过期 }); } // 把解码后的用户信息挂载到request对象上供后续路由使用 req.user user; next(); // 验证通过继续下一个中间件或路由 }); }; module.exports { authenticateToken };接着在src/middleware/下创建rateLimiter.js设置API调用频率限制// src/middleware/rateLimiter.js const rateLimit require(express-rate-limit); // 创建一个限流器15分钟内最多允许100次请求 const apiLimiter rateLimit({ windowMs: process.env.RATE_LIMIT_WINDOW_MS || 15 * 60 * 1000, // 15分钟 max: process.env.RATE_LIMIT_MAX_REQUESTS || 100, message: { error: 请求过于频繁请在15分钟后再试。 }, standardHeaders: true, // 在RateLimit-* headers中返回速率限制信息 legacyHeaders: false, // 禁用X-RateLimit-* headers }); module.exports { apiLimiter };3.2 创建异步任务队列现在来创建最重要的部分——任务队列。在src/queues/imageQueue.js中定义我们的Bull队列。// src/queues/imageQueue.js const Queue require(bull); const { createBullBoard } require(bull-board/api); const { BullAdapter } require(bull-board/api/bullAdapter); const { ExpressAdapter } require(bull-board/express); // 连接到Redis const imageQueue new Queue(image generation, { redis: { host: process.env.REDIS_HOST || localhost, port: process.env.REDIS_PORT || 6379, password: process.env.REDIS_PASSWORD || undefined, }, defaultJobOptions: { // 任务默认尝试3次每次失败后延迟5秒重试 attempts: 3, backoff: { type: fixed, delay: 5000, }, // 任务最多执行2分钟 timeout: 120000, }, }); // 可选设置Bull Board用于可视化监控队列需要额外安装bull-board包 // const serverAdapter new ExpressAdapter(); // serverAdapter.setBasePath(/admin/queues); // createBullBoard({ // queues: [new BullAdapter(imageQueue)], // serverAdapter: serverAdapter, // }); module.exports imageQueue;这个队列叫“image generation”连接到你本地的Redis。每个任务会尝试3次超时时间是2分钟。3.3 实现模型调用客户端队列里的任务需要有人Worker来处理处理的核心就是调用真正的图像生成模型。我们在src/utils/apiClient.js里封装一个调用模型后端服务的客户端。// src/utils/apiClient.js const axios require(axios); // 创建axios实例配置模型后端的基础地址和认证信息 const modelApiClient axios.create({ baseURL: process.env.MODEL_API_BASE_URL, timeout: 60000, // 60秒超时 headers: { Content-Type: application/json, // 如果模型服务需要API Key可以在这里或每个请求中添加 // Authorization: Bearer ${process.env.MODEL_API_KEY} }, }); /** * 调用Nunchaku-flux-1-dev模型生成图片 * param {Object} params - 生成参数如prompt, negative_prompt, steps等 * returns {PromiseObject} - 返回模型服务的响应数据 */ async function generateImage(params) { try { // 这里需要根据你实际模型后端的API接口来调整 const response await modelApiClient.post(/generate, params); return response.data; } catch (error) { console.error(调用模型API失败:, error.message); // 可以根据错误类型抛出更具体的错误供Worker处理 if (error.response) { // 请求已发出服务器返回了错误状态码 throw new Error(模型服务错误: ${error.response.status} - ${JSON.stringify(error.response.data)}); } else if (error.request) { // 请求发出但没有收到响应 throw new Error(无法连接到模型服务请检查服务是否运行); } else { // 其他错误 throw new Error(请求配置错误: ${error.message}); } } } module.exports { generateImage };这个函数就是Worker工作的核心它负责与真正的AI模型“对话”。4. 组装与运行让服务活起来模块都准备好了现在我们把它们组装起来并让Worker开始工作。4.1 编写Worker处理进程创建worker.js它的职责就是从imageQueue里取出任务调用上面的generateImage函数然后更新任务状态。// worker.js require(dotenv).config(); const imageQueue require(./src/queues/imageQueue); const { generateImage } require(./src/utils/apiClient); console.log(图像生成Worker已启动等待任务...); // 处理队列中的任务 imageQueue.process(async (job) { console.log(开始处理任务 ID: ${job.id}); const { prompt, negative_prompt, steps, cfg_scale, width, height } job.data; try { // 1. 调用模型生成图片 const result await generateImage({ prompt, negative_prompt, steps: steps || 20, cfg_scale: cfg_scale || 7.5, width: width || 512, height: height || 512, }); console.log(任务 ${job.id} 处理成功); // 2. 返回成功结果。这里假设模型返回了图片的URL或Base64数据 // 实际应根据你的模型后端返回的数据结构调整 return { success: true, jobId: job.id, imageUrl: result.image_url, // 或者 imageData: result.image_base64 metadata: { prompt, ...result.metadata, // 可能包含生成用时、种子等信息 }, }; } catch (error) { console.error(处理任务 ${job.id} 时出错:, error.message); // 抛出错误Bull会根据配置进行重试 throw error; } }); // 监听任务完成事件 imageQueue.on(completed, (job, result) { console.log(任务 ${job.id} 已完成结果:, result.success); }); // 监听任务失败事件 imageQueue.on(failed, (job, err) { console.error(任务 ${job.id} 失败错误:, err.message); });4.2 构建Express API路由现在来创建API接口本身。在src/routes/generate.js中// src/routes/generate.js const express require(express); const router express.Router(); const imageQueue require(../queues/imageQueue); const { authenticateToken } require(../middleware/auth); const { apiLimiter } require(../middleware/rateLimiter); /** * route POST /api/generate * desc 提交一个图像生成任务 * access Private (需要JWT认证) */ router.post(/generate, authenticateToken, apiLimiter, async (req, res) { const { prompt, negative_prompt, steps, cfg_scale, width, height } req.body; // 简单的请求体验证 if (!prompt || typeof prompt ! string) { return res.status(400).json({ error: 必须提供有效的提示词(prompt) }); } try { // 将生成任务添加到队列 const job await imageQueue.add({ prompt, negative_prompt, steps, cfg_scale, width, height, userId: req.user.id, // 从JWT中获取的用户ID }); // 立即返回任务ID客户端可以用它来查询状态 res.status(202).json({ // 202 Accepted 表示请求已接受正在处理 message: 图像生成任务已提交, jobId: job.id, statusUrl: /api/job/${job.id}, }); } catch (error) { console.error(提交任务到队列失败:, error); res.status(500).json({ error: 服务器内部错误无法提交任务 }); } }); /** * route GET /api/job/:jobId * desc 查询指定任务的状态和结果 * access Private (需要JWT认证) */ router.get(/job/:jobId, authenticateToken, async (req, res) { const { jobId } req.params; try { const job await imageQueue.getJob(jobId); if (!job) { return res.status(404).json({ error: 未找到该任务 }); } // 检查任务是否属于当前用户简单权限控制 if (job.data.userId ! req.user.id) { return res.status(403).json({ error: 无权查看此任务 }); } const state await job.getState(); const result job.returnvalue; const response { jobId, status: state, progress: job.progress(), // 如果有设置进度的话 data: job.data, }; if (state completed) { response.result result; } else if (state failed) { response.error job.failedReason; } res.json(response); } catch (error) { console.error(查询任务状态失败:, error); res.status(500).json({ error: 查询任务状态时发生错误 }); } }); module.exports router;4.3 集成Swagger API文档为了让API更友好我们集成Swagger。先创建文档定义src/docs/swaggerDef.js// src/docs/swaggerDef.js const swaggerJSDoc require(swagger-jsdoc); const options { definition: { openapi: 3.0.0, info: { title: Nunchaku-flux-1-dev 图像生成API, version: 1.0.0, description: 一个基于Node.js和Bull队列的异步图像生成RESTful API服务, }, servers: [ { url: http://localhost:${process.env.PORT || 3000}, description: 开发服务器, }, ], components: { securitySchemes: { bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT, }, }, }, security: [{ bearerAuth: [] }], }, apis: [./src/routes/*.js], // 指定包含注释的路由文件 }; const swaggerSpec swaggerJSDoc(options); module.exports swaggerSpec;然后在server.js中引入并设置Swagger UI// server.js (部分代码) const swaggerUi require(swagger-ui-express); const swaggerSpec require(./src/docs/swaggerDef); const generateRoutes require(./src/routes/generate); // ... 其他引入 const app express(); // 中间件 app.use(express.json()); // 解析JSON请求体 app.use(express.urlencoded({ extended: true })); // 静态文件服务如果需要托管生成的图片 app.use(/output, express.static(public/output)); // API路由 app.use(/api, generateRoutes); // Swagger API文档路由 app.use(/api-docs, swaggerUi.serve, swaggerUi.setup(swaggerSpec)); // 一个简单的根路由 app.get(/, (req, res) { res.send(h1Nunchaku-flux-1-dev 图像生成API服务/h1p访问 a href/api-docs/api-docs/a 查看API文档。/p); }); // 全局错误处理中间件放在所有路由之后 app.use((err, req, res, next) { console.error(err.stack); res.status(500).json({ error: 服务器内部错误 }); }); app.listen(PORT, () { console.log(API服务器运行在 http://localhost:${PORT}); console.log(API文档地址: http://localhost:${PORT}/api-docs); });4.4 启动与测试一切就绪你需要打开三个终端窗口启动Redis服务如果你本地没装Redis可以用Docker快速启动一个docker run -d -p 6379:6379 redis:alpine启动Express API服务器npm run dev启动Worker进程npm run worker现在打开浏览器访问http://localhost:3000/api-docs你应该能看到自动生成的Swagger UI界面。你可以在这里直接尝试调用/api/generate接口需要先在Headers里设置Authorization: Bearer 你的JWT令牌。5. 总结与后续优化方向走完这一趟一个具备基本生产可用性的图像生成API服务就搭建起来了。它解决了同步处理卡顿的问题通过任务队列实现了异步化并且加上了身份认证和限流这两道安全锁。Swagger文档也让接口调用变得一目了然。实际用起来你会发现这个基础版本还有不少可以打磨的地方。比如图片生成后是返回一个URL链接还是直接Base64数据流需要根据你的存储方案来定。你可以把图片存到本地文件夹然后用express.static提供访问或者上传到云存储如AWS S3、阿里云OSS返回一个临时访问链接。对于更复杂的场景可能还需要考虑任务优先级、多个Worker负载均衡、更细致的用户配额管理以及一个更漂亮的前端界面来展示任务历史和结果。不过这个项目最重要的价值是提供了一个清晰、可扩展的架构思路。它把复杂的AI模型能力封装成了任何开发者都能轻松调用的HTTP接口。你可以基于这个骨架根据自己的业务需求轻松地添砖加瓦。下次当你需要把某个AI能力集成到自己的产品中时不妨试试这个“异步任务队列Web API”的模式它会让你和你的用户都轻松不少。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
：进入正题)
