Fooocus 从下载安装到运行：Node.js 项目部署教程，附配置参数和测试方法

部署前先理解架构

Fooocus 是面向本地 AI 图像生成的工具，核心运行依赖 Python 环境、显卡驱动和模型文件；Node.js 项目通常不直接替代 Fooocus 的推理能力，而是作为管理层使用，例如提供 Web 页面、统一接口、任务队列、参数预设、日志记录和访问控制。比较稳妥的部署方式是：先让 Fooocus 在本机或服务器上独立跑通，再用 Node.js 项目调用它的本地服务或管理启动脚本。

这种组合适合三类场景：个人工作站希望把常用参数做成固定模板；小团队需要把图像生成能力接入内部系统；开发者希望在已有 Node.js 应用中增加 AI 工具入口。若只是偶尔体验，直接运行 Fooocus 即可；若要长期使用、多人访问或接入业务流程，再考虑 Node.js 部署层。

环境准备与版本建议

硬件方面，建议使用支持 CUDA 的独立显卡，显存越大可承载的分辨率和批量任务越高。低显存设备也能尝试，但需要降低分辨率、批次数和性能档位。系统方面，Windows、Linux、macOS 均可部署，其中 Linux 更适合长期服务化运行。软件方面建议准备 Git、Python 3.10.x、Node.js 18 或 20 LTS、npm 或 pnpm，以及对应显卡驱动。

部署目录建议分清三层：fooocus 目录存放主程序；models 目录存放模型与扩展资源；node-app 目录存放 Node.js 管理项目。不要把模型文件、临时图像、日志全部混在源码目录中，否则后期升级、备份和排错都会变复杂。

安装 Fooocus 主程序

第一步，获取 Fooocus 项目文件。可通过 Git 克隆官方仓库，也可以下载压缩包后解压到固定目录。目录路径尽量使用英文和数字，避免空格与特殊符号，减少脚本识别异常。

第二步，安装 Python 依赖。进入 Fooocus 目录后，按项目说明执行启动脚本。首次运行通常会自动创建虚拟环境并安装依赖，也可能自动下载基础模型。若下载较慢，可提前把模型文件放到指定目录，再启动程序识别。模型来源要选择可信渠道，避免使用来历不明的文件。

第三步，确认 Fooocus 能独立启动。启动后浏览器访问本地地址，例如 127.0.0.1:7865，能打开页面并完成一次低分辨率生成，说明后端基本可用。首次测试建议使用较小尺寸、单张输出、默认采样参数，先验证流程，不要一上来就拉高配置。

准备 Node.js 项目

Node.js 部署层可以是 Express、Fastify、NestJS 或已有前端项目。最小可用思路是：Node.js 提供一个管理页面，保存用户输入的提示词和参数；后端将请求转发给 Fooocus 的服务接口，或通过进程管理方式启动 Fooocus；生成完成后把结果路径返回给页面展示。

初始化项目时，建议使用 Node.js LTS 版本，执行 npm install 安装依赖。常见依赖包括 express、axios、dotenv、cors、pm2 等。dotenv 用于管理环境变量，axios 用于调用 Fooocus 服务，pm2 用于守护 Node.js 进程。若项目需要上传参考图，还要配置文件大小限制、临时目录和清理策略。

关键配置参数

Fooocus 侧常见参数包括监听地址、端口、模型路径、输出目录、性能模式、最大分辨率和是否启用远程访问。个人本机使用时，监听 127.0.0.1 更安全；若 Node.js 与 Fooocus 在同一台机器，也优先使用本地回环地址。只有确有需要时才绑定到内网地址，并配合访问限制。

Node.js 侧建议使用环境变量集中管理，例如 FOOOCUS_HOST=127.0.0.1、FOOOCUS_PORT=7865、APP_PORT=3000、OUTPUT_DIR=/data/fooocus/outputs、MAX_UPLOAD_MB=10、REQUEST_TIMEOUT=600000。超时时间要按生成耗时设置，AI 图像任务可能持续几十秒到数分钟，过短会导致前端误判失败。

如果 Node.js 负责启动 Fooocus，还需要配置 FOOOCUS_COMMAND、FOOOCUS_WORKDIR 和 LOG_DIR。启动命令应写绝对路径，避免服务化运行时找不到 Python 或脚本。日志要分为 Node.js 日志和 Fooocus 日志，便于判断问题发生在接口层还是推理层。

运行与服务化部署

开发环境中，可以先分别启动 Fooocus 和 Node.js 项目。确认 Fooocus 页面可访问后，再启动 Node.js，并访问 Node.js 提供的页面或接口。不要在尚未验证 Fooocus 的情况下直接排查 Node.js，否则容易把模型缺失、显存不足等问题误认为接口错误。

生产或长期运行场景，Node.js 可用 pm2 托管，例如设置应用名、入口文件、环境变量和自动重启策略。Fooocus 可通过系统服务、任务计划或进程管理工具托管。建议把两个服务拆开管理，避免 Node.js 重启时强制中断正在生成的任务。若确实要由 Node.js 控制 Fooocus 启停，要加入状态检测，防止重复启动多个实例占满显存。

测试方法：从基础到完整链路

第一项测试是端口连通。浏览器访问 Fooocus 地址，确认页面可打开；访问 Node.js 地址，确认首页或健康检查接口返回正常。若页面打不开，先检查端口是否被占用、防护规则是否允许本机访问、进程是否真正启动。

第二项测试是最小生成。使用默认模型、默认风格、较低分辨率生成一张图片，观察是否报错、是否输出到指定目录、耗时是否合理。若显存不足，降低分辨率、关闭高质量选项或减少并发任务。

第三项测试是 Node.js 调用链路。通过页面提交提示词，由 Node.js 转发给 Fooocus，再返回任务状态和结果地址。测试时记录请求参数、响应内容、日志时间点和输出文件名。若 Node.js 返回超时但 Fooocus 仍在生成，应调整超时、改成异步任务模式，避免长连接不稳定。

第四项测试是异常输入。包括空提示词、超长提示词、过大上传文件、重复点击提交、服务重启中提交任务等。成熟的部署不只看成功案例，更要看异常时是否有清晰提示、是否会产生残留文件、是否会让进程崩溃。

常见问题与处理思路

启动后提示找不到 Python，多数是环境变量未生效或版本不匹配。建议在终端执行 python --version 或 py --version 确认版本，并使用项目推荐的 Python 版本。若依赖安装失败，可清理虚拟环境后重新安装，或更换可靠的软件源。

模型加载失败通常与路径、文件名或文件完整性有关。检查模型是否放在 Fooocus 指定目录，文件是否下载完整，权限是否可读。不要频繁改动模型目录结构，Node.js 中也不要硬编码临时路径。

生成很慢或中途失败，常见原因是显存不足、分辨率过高、同时任务太多或驱动不兼容。解决方式是降低生成尺寸，限制并发数，关闭不必要的后台程序，并保持驱动与运行库匹配。服务器部署时应设置任务队列，不建议让多个用户同时直接触发高负载任务。

Node.js 能启动但无法访问 Fooocus，要检查地址是否写成了 0.0.0.0、localhost 或 127.0.0.1 的混用问题。容器或跨主机部署时，本地回环地址只代表当前容器或当前机器，不能直接指向另一台服务。

安全边界与实用建议

AI 图像服务不建议直接公开到公网。若必须多人使用，应至少加入账号校验、访问频率限制、上传类型校验和日志审计。上传文件要限制格式与大小，输出目录不要允许任意路径读取，避免把服务器上的其他文件暴露出去。

提示词和生成结果可能包含敏感业务信息，团队使用时应明确保存周期和清理规则。临时文件、失败任务残留、旧日志都要定期清理，防止磁盘被占满。模型和插件要从可信位置获取，升级前先备份配置文件、参数预设和关键依赖版本。

升级时建议采用“先复制一份新目录测试，再切换服务”的方式，不要在正在使用的目录中直接覆盖。若新版本出现接口变化、参数失效或生成效果异常，可以快速回退到旧目录。Node.js 项目也应锁定依赖版本，避免一次 npm install 后出现不可预期的兼容问题。

总体来看，Fooocus 负责图像生成，Node.js 负责工程化封装。只要按“先跑通后集成、先本地后服务化、先单任务后并发”的顺序推进，就能降低部署难度，并为后续扩展参数模板、任务记录和团队协作打好基础。