Breakpoint 使用手册

此页面由 docs/breakpoint.md 自动同步生成。

Breakpoint 使用手册

Breakpoint 用于在 Bifrost 转发 HTTP 流量时暂停指定 request 或 response。暂停后可以查看并修改 headers/body，再继续放行。它适合临时调试接口、验证上游入参、模拟下游响应、排查鉴权/header 问题，或在不改业务代码的情况下验证请求和响应改写效果。

适用场景

查看某个接口真正发往上游的 request headers/body。
临时修改 request body、query、headers 后再发送给上游。
在 response 返回客户端前修改 headers/body，验证客户端兼容性。
模拟异常响应、特殊 header 或边界数据。
只针对某个域名、端口或路径调试，避免影响其他网络请求。

不建议把 Breakpoint 长期开在宽泛规则上。Breakpoint 是交互式调试能力，命中的流量会等待用户 Resume 或等待超时自动放行；规则越宽，越容易造成请求等待、连接堆积和额外 CPU/内存开销。

工作方式

Breakpoint 有双重门禁：

Traffic Toolbar 中的 Breakpoint 开关必须打开。
请求必须命中包含 breakpoint://request 或 breakpoint://response 的规则。

只打开 Toolbar 开关不会暂停任何流量。只有全局开关打开，并且规则明确授权了 request 或 response 阶段，流量才会暂停。

在 WebUI 中使用

打开 WebUI，进入 Traffic 页面。
在 Toolbar 中打开 Breakpoint 开关。
进入 Rules 页面，为目标流量增加一条尽量精确的规则。
发送命中该规则的请求。
回到 Traffic 页面，打开对应请求的 TrafficDetail。
在暂停面板中查看或修改 headers/body。
点击 Resume 继续 request 或 response。

Breakpoint 关闭后，新流量不会再暂停；已经 pending 的 breakpoint 会被释放。

规则配置

使用 breakpoint 协议选择暂停阶段：

api.example.com/v1/users breakpoint://request
api.example.com/v1/users breakpoint://response
api.example.com/v1/users breakpoint://request,response

支持的 value：

request 或 req：在 request 发往上游前暂停。
response 或 res：在 response 返回客户端前暂停。
request,response、req,res、both 或 all：request 和 response 两个阶段都会暂停。

建议把规则 pattern 收窄到明确域名、端口、路径或方法。例如只调试登录接口时，优先写登录路径，不要写整个域名。空 value 或无法识别的 value 不会触发 Breakpoint。

Request Breakpoint

breakpoint://request 会在请求发往上游前暂停。适合：

检查真实 request headers/body。
临时添加、删除或修改请求 header。
修改 body 后再发送给上游。
验证客户端请求是否符合预期。

Resume 后，上游会收到修改后的 request。若 body 因过大、非文本或流式内容无法编辑，页面会提示 body 被省略，此时只能修改 headers，Resume 时不会替换原始 body。

Response Breakpoint

breakpoint://response 会在上游返回后、客户端收到前暂停。适合：

查看上游真实响应。
临时修改响应 header。
修改响应 body，验证客户端展示或错误处理。
模拟特殊状态或特殊响应内容。

Resume 后，客户端会收到修改后的 response。对未知长度的流式响应或过大的 body，Bifrost 会尽量保持原始 streaming 行为，避免为了调试而完整缓存大响应。

Timeout 配置

Breakpoint Auto-Resume Timeout 位于 Settings -> Performance。

默认值：30 秒。
可配置范围：5 秒到 5 分钟。
超时后：Bifrost 自动继续原始 request/response，不应用未提交的编辑。

这个配置用于避免用户忘记点击 Resume 时请求无限等待。较低值能降低网络延迟和连接堆积风险；较高值适合需要较长时间手动检查 headers/body 的场景。超过 5 分钟会带来明显的连接占用和性能风险，因此不允许配置。

性能与安全建议

默认保持 Breakpoint 关闭，只在需要调试时打开。
使用精确规则，避免把整个域名或所有流量都纳入 breakpoint。
优先只暂停需要的阶段：只看请求就用 breakpoint://request，只看响应就用 breakpoint://response。
调试完成后关闭 Breakpoint 或禁用对应规则。
对大 body、二进制 body、未知长度 streaming body，Bifrost 会限制编辑能力，避免额外复制和缓存造成明显性能开销。
如果发现请求等待变长，降低 Auto-Resume Timeout 或收窄规则范围。

API 自动化

日常使用建议通过 WebUI 操作。需要和外部工具、脚本或团队自动化集成时，可以使用 Admin API。

启用或关闭全局 Breakpoint 门禁：

curl -sS -X POST http://127.0.0.1:8800/_bifrost/api/breakpoint/settings \
  -H 'Content-Type: application/json' \
  --data '{"enabled":true,"max_body_bytes":1048576}'

修改 Auto-Resume Timeout：

curl -sS -X PUT http://127.0.0.1:8800/_bifrost/api/config/performance \
  -H 'Content-Type: application/json' \
  --data '{"breakpoint_timeout_ms":30000}'

恢复一个暂停项：

curl -sS -X POST http://127.0.0.1:8800/_bifrost/api/breakpoint/resume \
  -H 'Content-Type: application/json' \
  --data '{
    "request_id": "REQ-xxxx",
    "phase": "request",
    "headers": [["X-Debug", "1"]],
    "body": "edited body"
  }'

完整 API 描述可在 WebUI 的 Swagger 页面查看，或通过 /_bifrost/api/openapi.json 获取。

常见问题

打开 Breakpoint 后为什么没有暂停？

确认目标流量命中了包含 breakpoint://request 或 breakpoint://response 的规则。Toolbar 开关只是全局门禁，不会单独暂停流量。

为什么 body 不能编辑？

通常是 body 超过上限、不是 UTF-8 文本、属于二进制内容，或是未知长度 streaming body。此时 Bifrost 会保护性能，只允许 header-only pause 或直接保持 streaming。

请求一直等待怎么办？

点击 Resume，或等待 Auto-Resume Timeout 自动放行。也可以在 Settings -> Performance 降低 timeout，并收窄 breakpoint 规则范围。

如何避免影响其他应用？

使用更精确的规则，例如域名 + 路径 + 方法；调试结束后关闭 Breakpoint 或禁用规则。