IC咖啡胡运旺先交代一下背景：我在本地跑 ReActor 换脸流程的时候，遇到过几次挺让人恼火的报错，样子非常直接——
text复制HTTP Error 502: Bad Gateway
unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572
看到这条提示，第一反应是“怎么本地服务还给我整出个 502”。如果你也卡在这一步，别急着怀疑人生，这基本不是逻辑代码写错了，而是 ReActor 背后的辅助服务、模型进程或者依赖环境出了问题。这篇文章就把我从报错出现到排查、修复、再到稳定使用的完整过程拆开讲，重点说明这个 502 在换脸插件场景里到底意味着什么，以及每一步怎么处理。
1. 先搞清楚 502 是从哪一层冒出来的：ReActor 的调用链
1.1 一个看似本地却走 HTTP 的换脸插件
ReActor 是目前社区里比较常用的换脸（face swap）插件，很多人在 ComfyUI、SD WebUI 这类图形界面里直接调用它。很多人误以为 ReActor 就是一个纯本地函数库，靠 Python 代码直接跑——它确实最终是在本机做推理，但实际架构里通常有一层独立服务在待命。当你在界面上发起一次换脸请求时，主程序会先向本地某个端口发起 HTTP 请求，等服务把模型加载、推理结果算完，再返回给主程序。
http://127.0.0.1:1572 这个地址就是那个本地服务入口。502 是网关类错误，本质是“我（客户端）请求了某个代理/网关，但网关背后的真正服务没有给出合法响应”。在 ReActor 这里，相当于：
- 主 UI 进程（客户端）去请求本地 ReActor 服务；
- 本地服务可能没起来、正在加载模型、或者已经崩了；
- 于是返回了一个 502，而不是正常的图片数据。
1.2 502 在 ReActor 场景下的真实含义
我最初以为 502 是网络代理问题，毕竟这类报错在浏览器里太常见了。但在 ReActor 的调用上下文里，不完全是这么回事。它更多表示：服务进程存在，但没有成功处理这次请求。常见情况有几种：
- 服务进程启动过程中被中断，端口没有真正监听；
- 服务进程还活着，但模型加载没有完成，请求直接超时；
- 请求进入之后，推理过程中显存爆掉，进程被杀，连接被重置；
- 多个实例抢同一个端口，实际响应你的不是 ReActor，而是另一个不认识的进程。
这就是为什么单看报错解决不了问题——你得先判断 502 是在哪个阶段出现的。这里我建议排查时先按“端口能否连通 → 服务日志有没有报错 → 模型是否加载完整 → 配置有没有冲突”的顺序走，下面每一节都对应一个具体检查点。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 最常见的元凶：内存、显存与模型加载的前后顺序
2.1 模型没有完整加载就请求，服务端直接拒了
ReActor 换脸依赖的模型文件一般体积不小，比如用于人脸检测、特征提取的多个模型加起来动辄几百 MB 到几个 GB。首次启动时需要把模型读入内存或显存，这个阶段如果立刻发送请求，服务端往往直接返回连接异常或 502。
我实际遇到的情况是：ReActor 服务在后台静默启动，但是模型加载需要二十多秒，而 UI 层已经认为服务“可用了”，于是马上发请求。这时候本地服务还卡在模型加载，根本来不及处理，最终表现为 502。
复现路径大概是：
- 启动 ComfyUI 或 WebUI；
- 加载 ReActor 插件，后台服务开始预热；
- 立刻在界面上传一张图，点击生成；
- 控制台抛出
HTTP Error 502: Bad Gateway。
这类问题最容易出现在“服务热启动 + 用户手速快”的组合下。解决方式很朴素：启动完成后等几秒再发第一次请求。如果你用脚本调用，可以在请求前轮询端口连通性，确认服务真正就绪。
提示：端口能连通不等于服务就绪。连通只能说明有 socket 在监听，不代表模型已经加载到显存里。要等日志出现类似“model loaded”的标记后再进入任务队列。
2.2 显存和内存双双顶满，进程假死或被杀
另一个高频原因是推理过程中显存或内存超限。换脸任务看起来不复杂，但组件链条长：人脸检测、对齐、特征提取、特征融合、图像生成，每一个环节都可能吃显存。如果你同时跑着 SD 生成任务，再叠加 ReActor 推理，显存很容易被挤爆。
当进程因为 OOM（Out Of Memory）被杀时，服务端的表现不是优雅报错，而是连接被中断。客户端收到的就是 502 Bad Gateway，因为请求发过去后连一个正常的 HTTP 响应都没等到。
我当时排查时用 nvidia-smi -l 1 盯实时显存，发现一个有意思的现象：服务启动时显存占用很低，但只要第一次换脸请求进入，显存直接冲上 90% 以上，然后在任务执行到一半时掉到接近 0——那不是任务完成了，是进程崩了。
解决思路分两层：
- 推理前关闭其他占用显存的任务，避免并发抢显存；
- 给 ReActor 进程设置合理的显存上限，或者强制使用 CPU 推理验证前后端链路是否正常。
这里有一个实用命令，Linux 下可以用环境变量限制显存可见性：
bash复制CUDA_VISIBLE_DEVICES=0 python main.py
Windows 下可以临时改用 CPU 模式跑一次，如果 502 消失，基本可以坐实是显存/资源问题。CPU 模式速度慢，但能帮你快速区分方向。
3. 端口占用和 API 地址不匹配：报错里的 127.0.0.1:1572 说明什么
3.1 端口冲突排查
1572 这个端口是 ReActor 本地服务默认监听端口。如果你同时开了两个项目、或者上一次运行没有彻底关闭，端口被抢占，就会出现一个很隐蔽的情况：请求确实到达了某个进程，但那个进程并不是 ReActor 服务，于是返回的响应格式完全不对，最终表现为 502。
排查方法非常直接，直接在终端里查端口占用：
Windows PowerShell：
powershell复制netstat -ano | findstr 1572
Linux/macOS：
bash复制lsof -i :1572
如果发现占用 1572 的 PID 对应的进程不是你预期的 ReActor 进程，就需要结束冲突进程，或者修改 ReActor 的端口配置。
我遇到过一次比较有意思的情况：之前一次运行没有正常退出，导致残留了一个僵尸进程占着 1572，新启动的 ReActor 只能监听别的端口，但 UI 配置仍然指向 1572，于是所有请求都打到了僵尸进程上。那进程既不会正常响应，也不会退出，最后只能手动杀掉。
3.2 多实例冲突
如果你习惯同时开多个 WebUI 窗口，或者用了某些启动器，也可能出现多实例共用同一个端口。这种情况下，A 实例启动后占用了 1572，B 实例再启动时默认端口弹窗报错，但如果你忽略了提示或强制覆盖，后续请求就会落到不确定的实例上。
这类问题处理起来不难，但很考验排查耐心。我建议：
- 每个 WebUI 工作目录只允许一个 ReActor 实例；
- 如果确实要多开，显式给不同实例分配不同端口；
- 启动日志里确认本实例实际监听的端口号，再与 UI 配置里的地址比对。
注意：端口配置修改后需要完全重启进程才生效，不能只刷新页面。个别情况下浏览器缓存里还留着旧的 API 地址，会继续往旧端口发请求。
4. 依赖环境问题：insightface、onnxruntime 版本不匹配
4.1 Python 环境混乱导致服务启动不完整
ReActor 的底层依赖比较多，尤其是 insightface、onnxruntime、filterpy、numba 这几个。如果你用 Conda、系统 Python 混着装，或者用一键整合包后又在外部安装了一些包，很容易把版本搞乱。
版本不匹配的典型表现在：服务启动时没有报致命错误，但某些模型加载接口返回异常。主程序去调用时，服务端没法正常返回结果，502 就出现了。
这类问题有一个很明显的特征：命令行启动时能看到 import 阶段的 warning，但没有 traceback。比如 onnxruntime 的 Provider 之一初始化失败，系统会自动回退到 CPU，速度变慢但还能跑；而如果 insightface 依赖的某个动态库缺失，可能直接导致推理接口不可用。
我的处理习惯是把依赖固定在一个稳定的组合上，避免盲目升级最新版：
| 依赖包 | 建议版本区间 | 说明 |
|---|---|---|
| Python | 3.10 / 3.11 | 3.12 部分依赖兼容性一般，不建议首选 |
| insightface | 0.7.3 | 社区实测较多，稳定 |
| onnxruntime-gpu | 1.16.x 或 1.17.x | 需要和 CUDA 版本匹配 |
| numpy | 1.24.x 上下 | 过高版本可能导致部分包不兼容 |
| opencv-python | 4.8.x 以上 | 过低版本会出现人脸检测异常 |
如果你用的是 ComfyUI 加 ReActor 的组合，建议优先使用整合包作者锁定的依赖版本，不要自己手痒全部升级。很多 502 和疑难杂症就是这么来的。
4.2 CUDA 与 onnxruntime-gpu 的配合问题
GPU 版的 onnxruntime 对 CUDA 版本有严格要求。如果你本机 CUDA 版本和 onnxruntime 编译时的版本不匹配，它会在初始化时静默失败，然后回退到 CPU 推理。
回退本身不致命，但如果你设置了比较短的请求超时时间，CPU 推理速度跟不上，服务端还是会判定请求失败。极端情况下，onnxruntime 初始化 CUDA 失败会直接导致服务线程崩溃，返回 502。
判断方法不复杂。在 Python 环境里执行：
python复制import onnxruntime as ort
print(ort.get_available_providers())
如果输出里只有 CPUExecutionProvider，没有 CUDAExecutionProvider，说明 GPU 加速没生效。原因可能是：
- CUDA 版本过高或过低；
- cuDNN 缺失；
- onnxruntime-gpu 没装对。
不要一看 502 就觉得是网络问题，先确认推理后端是不是真的跑起来了。我实际踩过这个坑：安装时图省事用了 pip install onnxruntime，结果装的是 CPU 版，推理请求一多，服务就半死不活，时不时返回 502。
5. 解决 502 的完整排查清单与实操步骤
5.1 分阶段排查，快速定位问题层
在这里我给出一套可以直接照做的排查流程。按顺序执行，不用跳步，基本能覆盖 95% 的 502 场景。
-
确认服务进程是否在运行
打开任务管理器或进程列表，搜索python或ReActor相关进程。如果服务根本没有起来，直接跳到第 3 步看日志。
如果进程存在，执行端口检查命令，确认监听地址确实是127.0.0.1:1572。 -
确认端口监听和请求可达
Windows 下用netstat -ano | findstr 1572，Linux 下用ss -lntp | grep 1572。
如果没有任何监听输出，说明 ReActor 服务没有正常启动，需要重新启动或查看日志。 -
查看服务端日志
启动 WebUI 时，终端窗口会打印 ReActor 插件的日志。重点搜索error、traceback、failed、assert等关键词。
如果日志里出现“Model not found”或“cannot load”，说明模型文件缺失或路径错误。 -
用浏览器直接访问 API 地址
在浏览器打开http://127.0.0.1:1572（或加上你的实际路径），如果返回 404 或者空响应，说明服务在线但 API 路径不对；如果直接拒绝连接，说明服务没起来。
这一步能帮你区分“服务没起”和“服务起但没有正确响应”。 -
检查模型文件是否完整
找到 ReActor 的模型缓存目录，检查模型文件大小是否正常。模型文件如果下载不完整，加载时不会报错，但推理时会全线失败，导致请求被中断。
5.2 修改端口与配置的实操示例
如果你决定换端口，以 ReActor 在 ComfyUI 中的配置为例，一般是在插件设置或环境变量里指定端口。假设改成 1573，启动时保持 UI 设置里 API 地址也同步修改。
Linux 环境下临时指定端口：
bash复制export REACTOR_PORT=1573
python main.py
Windows PowerShell：
powershell复制$env:REACTOR_PORT = "1573"
python main.py
修改后再次检查端口监听：
powershell复制netstat -ano | findstr 1573
如果能看到你启动的 Python 进程 PID，说明监听成功。
5.3 快速恢复的兜底方案
如果以上排查太耗时，有一个相对快的兜底方案：清掉所有残留进程后重启。
Linux/macOS：
bash复制pkill -f python
Windows：
powershell复制taskkill /F /IM python.exe
然后重新启动 WebUI。这个方法能解决一半以上因为僵尸进程或残留状态导致的 502。当然，它会把其他正在跑的 Python 任务也一起杀掉，执行前确认当前环境里没有重要任务。
6. 个人踩坑经验：容易被忽略的超时、队列和缓存问题
6.1 服务端处理超时被当成 502
这个问题我在排查后期才发现。ReActor 服务本身有请求处理超时配置，当一张图特别大、人脸数量多、或者机器性能不足时，处理时间超过了服务端设定的超时阈值，连接会被主动断开，客户端同样收到 502。
如果你发现小图能正常处理，大图容易 502，优先怀疑超时。解决方法不是盲目调大超时，而是先做图像预处理，把输入尺寸压到合理范围。比如 800x800 以内的图通常几秒内就能完成推理，超过 2000x2000 的图耗时成倍增长。
有些场景下你并不想损失画质，这时可以在预处理阶段先做缩放，推理完成后再把换脸结果贴回原图。ReActor 本身提供了类似输出分辨率控制的选项，不需要自己写图像融合代码。
6.2 请求排队导致的连锁 502
ReActor 在并发请求场景下也有坑。如果你在 ComfyUI 的批量生成队列里连续提交多个任务，而服务端不是并发安全的，后面的请求会因为前一个任务还没结束而直接失败。
这跟 Web 服务里的请求排队不一样，ReActor 的接口往往没有完善的队列管理。我遇到的情况是：批量处理 20 张图，前 5 张正常，第 6 张开始陆续出现 502。不是资源不够，而是前一个请求的处理结果还没有完全释放，新请求到的连接被短暂拒绝。
解决办法也不复杂：
- 批量任务之间加一点间隔，比如 0.5 秒；
- 如果是调用 API 脚本，做失败重试，间隔 1~2 秒；
- 不要同时向多个接口发起并发换脸请求。
如果你的批处理脚本是自己写的，可以在每次请求之间 sleep 一下，或者在失败时捕获异常后重试几次。不要一看到 502 就中断整个流程。
6.3 浏览器缓存和旧 API 地址残留
这个坑听起来很蠢，但实际遇到过两次。ComfyUI 页面可能在浏览器里缓存了旧的 API 地址，当你修改了 ReActor 端口后，页面仍在请求旧地址，导致 502。刷新页面不行，必须强制刷新或清缓存：
text复制Ctrl + Shift + R
如果你在调用时用了自定义的 Python 脚本，还需要检查代码里有没有写死端口号。我见过有人在配置里改了 1573，但脚本里还是 http://127.0.0.1:1572，排查半天才发现。
6.4 模型文件路径包含中文或空格时的异常
这一个是我最想提醒的。ReActor 的模型加载在某些版本里对路径中的非 ASCII 字符支持不好。如果你把模型放在 D:\下载\模型\ 这种带中文的路径下，可能服务启动正常，但一加载模型就异常退出，请求自然变成 502。
解决方案很简单：把所有模型、工作区路径改成纯英文目录，例如：
text复制D:\AI\Models\ReActor\
不要带空格，也不要用中文。Linux 用户也要留意挂载路径中是否有特殊符号。
7. 验证问题是否解决：从日志到端到端的完整测试
7.1 正常成功时应该看到什么
排查完一轮，怎么确认 502 真正解决了？我建议不要只看“这次没有报错”，而是做一次比较完整的验证。
正常流程下，你至少应该在服务端日志里看到：
- 模型加载完成的时间点；
- 请求进入的时间点；
- 推理完成的返回状态码（比如 200）；
- 输出文件成功生成的路径。
如果日志里没有这几条，只是客户端没报错，说明可能只是请求被吞了或者走了缓存，并不是真的成功处理。
我个人的习惯是生成一张包含单个人脸的测试图，跑一次换脸，确认输出图像有变化，再进入正式使用。不要拿一个完全没有人脸的图测试，这样即使服务是好的，也可能因为检测不到人脸而返回空结果，容易被误判成问题。
7.2 端到端测试脚本示例
如果你是用脚本调 ReActor 服务，可以用下面这个思路写一个简单的连通性测试：
python复制import time
import requests
url = "http://127.0.0.1:1572"
max_retries = 5
for i in range(max_retries):
try:
resp = requests.get(url, timeout=3)
print(f"尝试 {i+1}: HTTP {resp.status_code}")
if resp.status_code < 500:
print("服务正常响应")
break
except requests.exceptions.RequestException as e:
print(f"尝试 {i+1}: 连接失败 - {e}")
time.sleep(2)
注意这只是连通性测试，不等同于完整推理成功。真实推理测试需要准备一张测试图片，调用换脸接口，确认返回文件可读且内容正确。
8. 最后的稳定性建议：让 502 不再反复出现
8.1 服务运行习惯上的改进
我踩过足够多的坑之后，总结出几个能明显减少 502 出现频率的习惯：
- 启动后不要急着跑第一个任务，等模型完全加载；
- 大批量任务之间留出合理间隔；
- 不在同一时间运行多个吃显存的工作流；
- 使用固定版本的依赖，不随意升级；
- 定期清理残留的 Python 进程。
这些习惯不需要额外工具，但能帮你省掉大量排错时间。
8.2 日志是最终的说服者
很多人在排查 502 时，习惯性地反复重试请求，期望某一次能碰巧成功。这种思路比较浪费时间。我建议每轮操作都看日志输出，让日志告诉你服务端到底发生了什么。
如果你看到下面这类信息：
text复制RuntimeError: CUDA out of memory
那 502 的来源就非常明确：显存不足。你反复重试只是让问题更快出现。
如果你看到：
text复制ConnectionRefusedError: [Errno 111] Connection refused
说明服务没起来，去查启动日志才是正路。
8.3 保留一套稳定的运行环境快照
这一点送给所有把 ReActor 用在生产或者长期项目中的朋友。当你终于调好一套能稳定运行的依赖环境后，建议记录下关键包版本和配置项。条件允许的话，可以直接做一份虚拟环境快照或者打包好整合包，下次遇到问题至少能快速恢复到可运行状态。
我自己的做法是写了一个 requirements-lock.txt，把每个依赖包的版本精确锁定，同时在项目目录里保留一份 ReActor 模型文件的备用副本。这样即使主环境出问题，也能在半小时内恢复到一个能用的状态。
502 本身只是一个症状，背后原因因环境而异。如果你能按“端口 → 日志 → 模型 → 资源 → 依赖”这条链路去排查，大概率能定位到真正的问题点。希望这篇内容能让你少走一些弯路。