AI Agent故障隔离：fail-closed反向代理与断路器实践

这次我们来看一个面向 AI agent 的基础设施项目：Loopers。它发布于 Hacker News 的 Show HN，核心定位是给 AI agent 调用链加一层可控的"闸门"——一个fail-closed（故障关闭）模式的反向代理，同时内置断路器（circuit breaker）机制。简单说，它解决的不是"怎么让模型生成更好"，而是"当模型服务、API 网关或下游工具出现异常时，你的 agent 系统应该如何优雅地停下来，而不是带着错误继续跑"。

很多人在本地搭过 agent 应用，通常的做法是直接把请求打到 OpenAI、Anthropic 或各类开源模型的 API 上。单机 demo 没问题，但一旦进入多用户、多任务、多 Provider 切换的生产环境，问题就来了：API Key 怎么统一管理？多个上游服务如何做路由？某个模型服务开始超时或返回 5xx 时，怎么避免请求全部堆积导致雪崩？Loopers 这类工具就是为这些问题设计的。

这篇文章会做四件事：先讲清楚 fail-closed 反向代理和断路器在 AI agent 架构里解决什么问题；再给出一套环境准备和部署验证流程；然后重点演示如何测试断路器的三种状态以及 fail-closed 的拦截行为；最后补充接口调用、批量任务、性能观察和常见排错思路。如果你正在做 agent 的工程化，或者负责把 LLM 服务接入公司内部网关，这篇文章可以直接参考落地。

1. 核心能力速览

Loopers 的定位可以从名字和关键词拆出来："Loopers" 指的是 agent 的循环执行过程（LLM 调用链、工具调用链、重试循环），"fail-closed reverse proxy" 和 "circuit breaker" 则是它的两个核心机制。先把这类项目通常具备的能力整理成一张速览表，方便快速判断它适不适合你：

需要说明的是，由于 Loopers 目前公开信息以项目定位为主，文章里涉及具体参数、端口和配置项的地方，我会给出这类组件的通用模板，你需要按实际项目 README 和配置文件调整。这并不影响你理解它的设计思路和验证流程。

2. 适用场景与使用边界

2.1 适合谁

Loopers 适合的是一类比较明确的场景：你已经在用 LLM 做正经业务，而不是只跑实验。具体包括：

• 把 OpenAI、Anthropic、本地 vLLM 等多个上游服务统一收敛到一个入口，方便切换和灰度。
• 在 agent 的工具调用链里加了大量外部 API，担心某个下游服务故障拖垮整个任务。
• 需要在代理层统一管理 API Key、做流控、做审计日志。
• 做故障演练，验证"上游服务挂了之后，agent 系统会不会失控"。

2.2 能解决什么问题

一个典型的 agent 执行循环里，可能会发生这些故障：模型服务超时、返回格式异常、工具调用接口 5xx、API Key 被限流。如果没有代理层保护，agent 可能会无限重试、不断消耗 token、把错误结果继续往下一步传。Loopers 的思路是给这些调用加一道保护层：上游不正常时，代理层直接快速失败（fail fast）或拒绝放行（fail-closed），而不是把错误转发给下游。

2.3 不适合什么场景

• 单机本地跑个 LangChain demo，没必要上代理层。
• 想找一个能提升生成质量或 prompt 编排的框架，这不是它的定位。
• 需要图形化界面做 prompt 调试，这类代理组件通常只有配置文件和 API，没有复杂的 WebUI。

2.4 使用边界与合规提醒

代理层会经过你的全部 LLM 请求。这意味着它能看到 prompt、返回内容以及 API Key。接入使用时需要注意：

• API Key 和敏感配置不要写死在仓库里，用环境变量或密钥管理服务注入。
• 涉及人脸、声音、个人隐私或版权素材的生成与调用，必须确认授权和合规边界。
• 代理日志如果记录完整请求体，要评估数据脱敏策略，避免敏感信息落盘。
• 生产环境部署时，代理管理接口不要暴露到公网，避免被恶意调用。

3. 环境准备与前置条件

Loopers 本身是网络服务组件，不依赖 GPU，也不涉及模型推理，所以环境准备相对轻量。下面是一套通用检查清单：

检查端口占用的通用命令：

# 检查 8080 端口是否被占用 lsof -i :8080 # 或使用 ss ss -tlnp | grep 8080

如果你的环境里没有现成的 LLM 服务，也可以先用一个简单的本地 HTTP 测试服务模拟上游，比如用 Python 起一个返回固定 JSON 的接口，用来验证代理转发和熔断行为。后面会给出具体做法。

4. 安装部署与启动方式

Loopers 的部署方式取决于项目实际提供的产物。通常这类组件会有两种分发形式：Docker 镜像和可直接执行的二进制。下面分别给出通用部署思路。

4.1 Docker 部署模板

如果项目提供 Docker 镜像，典型的启动方式如下，具体镜像名需要按实际项目替换：

docker run -d \ --name looper-proxy \ -p 8080:8080 \ -p 9090:9090 \ -e LOOPERS_LOG_LEVEL=info \ -v $(pwd)/config.yaml:/etc/loopers/config.yaml \ looper-proxy:latest

这里 8080 是代理入口端口，9090 是健康检查/管理端口。挂载配置文件后，代理会按配置读取路由规则和熔断策略。

4.2 二进制启动模板

# 下载对应平台的压缩包并解压后 ./loopers --config config.yaml --port 8080

启动后观察日志，看到类似proxy listening on 0.0.0.0:8080的输出，说明服务已就绪。

4.3 配置文件结构模板

下面是一份通用的 fail-closed 反向代理配置模板，覆盖路由、上游节点、断路器和健康检查。字段名和结构以实际项目为准，这里用于说明配置思路：

proxy: listen: ":8080" fail_closed: true # 关键开关：默认拒绝不放行 routes: - name: llm-openai match: path_prefix: "/v1/chat/completions" upstreams: - url: "https://api.openai.com" weight: 1 circuit_breaker: max_failures: 3 # 连续失败次数阈值 cooldown_seconds: 30 # 熔断后的冷却时间 half_open_max_requests: 1 # 半开状态放行探测请求数 - name: llm-local match: path_prefix: "/v1/models" upstreams: - url: "http://127.0.0.1:8001" weight: 1 circuit_breaker: max_failures: 5 cooldown_seconds: 60 half_open_max_requests: 2 health_check: listen: ":9090" path: "/healthz"

核心概念是三个：

• fail-closed（故障关闭）：请求在没有明确放行规则、或上游健康状态未知时，默认拒绝或返回安全响应，而不是盲目转发。
• circuit breaker（断路器）：维护三种状态——关闭（closed）、打开（open）、半开（half-open）。正常时关闭放行；连续失败达到阈值后打开，直接快速失败；冷却期后进入半开，放行少量探测请求，若成功则恢复关闭。
• 路由：按请求路径或 Header 分发到不同上游服务。

5. 功能测试与效果验证

部署完成后，建议按下面的顺序逐项验证。这是最关键的一部分，直接决定你能不能信任这个代理层。

5.1 验证 1：基础转发

先用最简单的请求验证代理能否正确转发到上游。假设代理监听 8080 端口，上游是本地测试服务：

curl -X POST http://127.0.0.1:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer test-key" \ -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "hello"}]}'

预期结果：代理把请求转发到上游，返回上游的响应体。判断标准：响应状态码 200，且返回内容与直连上游一致。

5.2 验证 2：fail-closed 行为

fail-closed 验证的核心是：当代理无法判断请求是否安全、或上游处于不可用状态时，它应该拒绝放行，而不是"试着转发看看"。

测试方法：在配置里故意把上游地址改成一个不存在的端口，然后发起请求：

curl -i -X POST http://127.0.0.1:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "test", "messages": []}'

预期结果：代理返回 502/503 或自定义错误响应，而不是长时间挂起等待。如果配置了 fail_closed: true，即使没有匹配到任何路由，也应该返回明确的拒绝响应。

另一个测试点是未匹配路由的请求：发送一个不在任何 route 规则里的路径，确认代理默认拒绝，而不是透传到某个默认后端。这是 fail-closed 和普通反向代理的明显区别。

判断标准：

• 请求在几秒内快速失败，没有长时间超时。
• 错误信息里能看出是代理层拦截，而不是上游返回的错误。
• 日志记录了拒绝原因。

5.3 验证 3：断路器熔断

断路器测试建议模拟"上游连续失败"的场景。可以用一个简单的 Python 服务来模拟故障上游：

# fail_server.py - 模拟故障上游 from http.server import HTTPServer, BaseHTTPRequestHandler import time class Handler(BaseHTTPRequestHandler): def do_POST(self): # 先连续返回 500，模拟上游故障 self.send_response(500) self.send_header("Content-Type", "application/json") self.end_headers() self.wfile.write(b'{"error": "upstream failure"}') def log_message(self, format, *args): pass if __name__ == "__main__": server = HTTPServer(("127.0.0.1", 8001), Handler) print("fail server listening on 8001") server.serve_forever()

启动这个故障服务后，连续向代理发送请求：

for i in $(seq 1 10); do curl -s -o /dev/null -w "%{http_code}\n" -X POST \ http://127.0.0.1:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "test", "messages": []}' done

预期观察：

• 前几个请求返回 500（上游故障）。
• 当连续失败次数达到max_failures阈值后，断路器打开，后续请求被代理层直接拦截，返回 503 或快速失败，不再打到上游。
• 观察代理日志，可以看到断路器状态从 closed 变为 open。

5.4 验证 4：半开状态恢复

把故障服务停掉，换成一个正常返回 200 的服务，然后继续发请求。断路器在冷却期结束后会进入半开（half-open）状态，放行少量探测请求。

判断标准：

• 半开状态下，只有部分请求被放行到上游。
• 如果探测请求成功，断路器恢复到 closed 状态，后续流量全部正常转发。
• 如果探测请求仍然失败，断路器再次进入 open 状态并重新计时。

这个测试很关键，它验证了系统"能坏也能恢复"。

5.5 验证 5：长尾请求与超时

在 agent 场景里，LLM 请求通常耗时较长。需要测试代理层对慢请求的处理：

• 配置上游服务在收到请求后 sleep 10 秒再返回。
• 观察代理是否设置了合理的读/写超时。
• 确认超时后代理返回的错误码是否正确，以及是否计入断路器失败次数。

6. 接口 API 与批量任务

6.1 代理接口

Loopers 对外暴露的代理接口，通常直接兼容 OpenAI 或 Anthropic 的请求格式。调用方只需要把 base_url 改成代理地址即可。以 OpenAI SDK 为例：

from openai import OpenAI client = OpenAI( base_url="http://127.0.0.1:8080/v1", # 代理入口 api_key="your-api-key" ) response = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "hello"}] ) print(response.choices[0].message.content)

这在实际部署里非常有价值：你的业务代码不需要大改，只需要换 base_url，就能把流量切到代理层管理之下。

6.2 管理接口与健康检查

代理服务一般还会提供管理接口，用于查看状态和主动触发熔断操作。常见接口包括：

• GET /healthz：存活检查。
• GET /metrics：Prometheus 指标，查看请求数、失败率、断路器状态。
• GET /circuits：查看所有路由的断路器状态。
• POST /circuits/{name}/open：手动打开某条路由的断路器，用于故障演练。

# 查看健康状态 curl http://127.0.0.1:9090/healthz # 查看断路器状态 curl http://127.0.0.1:9090/circuits

6.3 批量任务设计

代理层本身不承担业务批量调度，但可以在代理层之上做批量任务的稳定保障。典型的做法是：

• 批量任务逐个发送请求到代理。
• 代理通过断路器自动隔离故障上游，避免批量任务因为单个上游故障全部失败。
• 调用方需要处理 429（限流）和 503（熔断中），对这两种状态做重试或延迟策略。

import requests import time def send_with_retry(prompt, max_retries=3): url = "http://127.0.0.1:8080/v1/chat/completions" payload = { "model": "gpt-4o-mini", "messages": [{"role": "user", "content": prompt}] } for attempt in range(max_retries): resp = requests.post(url, json=payload, timeout=60) if resp.status_code == 200: return resp.json() elif resp.status_code in (429, 503): # 熔断或限流，退避后重试 wait_time = 2 ** attempt print(f"attempt {attempt + 1} failed: {resp.status_code}, waiting {wait_time}s") time.sleep(wait_time) else: resp.raise_for_status() raise RuntimeError("max retries exceeded") result = send_with_retry("你好，请介绍一下自己") print(result)

这里给调用方的建议是：不要对 5xx 做无限重试，要区分"上游临时错误"和"断路器已打开"。前者可以退避重试，后者应该等待冷却期结束再继续，否则重试只是给代理层增加无效请求负担。

7. 资源占用与性能观察

Loopers 这类代理组件不跑模型，资源占用主要来自网络转发和请求日志，理论上非常轻量。但在生产环境中，仍然需要关注几个性能指标。

7.1 观察指标

建议从四个维度观察：

7.2 影响性能的关键点

• 日志级别：debug 级别会记录完整请求体，高并发下对磁盘和 CPU 都有压力。生产环境建议 error 或 info。
• 上游超时设置：如果代理层超时时间设置得比上游还长，断路器无法及时触发，请求会长时间挂起。超时时间建议比上游 SLA 略短。
• 连接池：如果代理支持 HTTP 连接池配置，需要根据上游服务的并发能力调整。连接池太小会导致请求排队，太大可能打满上游。
• 单条请求体大小：agent 场景里，工具返回结果、历史消息可能很大。如果代理层对请求体大小做了限制，需要按实际场景调整。

7.3 降低资源占用的通用手段

• 关闭访问日志或采用采样日志。
• 开启 gzip 响应压缩（如果代理层支持）。
• 把管理接口和代理接口分开端口暴露，管理接口限内网访问。
• 批量任务在低峰时段运行，控制并发数。

8. 常见问题与排查方法

排查通用思路：先确认上游本身是否正常，再确认代理配置是否生效，最后看断路器状态和日志。大部分问题都能在这三步里定位。

9. 最佳实践与使用建议

9.1 配置管理

• 配置文件纳入版本管理，但密钥用环境变量或密钥管理服务注入，不要写进 YAML。
• 为每个上游服务单独配置路由和断路器参数，不要所有上游共用一套阈值。本地 vLLM 和 OpenAI 的失败率差异很大，统一阈值会导致误熔断或熔断不及时。

9.2 故障演练

• 定期手动触发断路器，验证熔断后业务方的降级表现是否正常。
• 用前面提到的 fail_server.py 模拟上游 500，观察 agent 系统在"上游故障"时的行为是否可控。
• 演练后记录熔断时间、恢复时间、业务影响范围。

9.3 日志与审计

• 代理层只记录必要信息：请求 ID、上游名称、状态码、耗时、断路器状态。
• 如果业务需要 debug 完整请求内容，建议临时开启并在完成后关闭。
• 长期保存的日志要脱敏，Prompt 里的用户数据属于敏感信息。

9.4 安全加固

• 代理管理接口绑定内网地址或加认证。
• 代理入口如果需要公网暴露，前面再叠加一层网关做认证。
• 避免代理层无限转发，设置最大请求体大小和单请求时长上限。
• 对上游 API Key 做最小权限管理，不要使用"万能 Key"。

9.5 Agent 业务侧配合

• agent 的每个 LLM 调用和工具调用都设置独立超时。
• 代理层熔断打开的 503，业务侧要做降级：换上游、走缓存、或终止任务，而不是死循环重试。
• 在 agent 循环里加入"最大失败次数"限制，防止单个故障任务无限消耗资源。
• 善用请求 ID 串联日志，从代理层到业务层形成完整链路追踪。

这最后一点特别值得强调。如果你们的 agent 系统已经出现了"任务卡死、重试风暴、token 费用异常上涨"这类问题，根源往往不是模型能力，而是调用链缺少故障隔离。代理层的价值就在这里：它把"上游可能失败"这件事，变成了一个可预期、可观测、可恢复的工程问题，而不是靠运气。建议先把一个上游服务接入 Loopers 做灰度验证，确认故障切换和熔断恢复都符合预期后，再逐步扩展路由规则。生产环境更换网关类的组件，最忌讳一步到位，小流量验证、观察指标、逐步放量，才是稳妥的路径。