Bifrost

Language: 中文 | English

帮助文档 · English docs · Documentation site

Bifrost 是一个用 Rust 编写的高性能，AI 友好的代理服务器，灵感来源于 Whistle。它提供请求拦截、规则修改、TLS 拦截、脚本扩展、流量查看、请求重放以及 Web UI 管理能力。

快速开始

安装 CLI：

方法一：使用脚本安装

curl -fsSL https://raw.githubusercontent.com/bifrost-proxy/bifrost/main/install-binary.sh | bash

该脚本默认会继续安装并信任 CA 证书、安装所有 Bifrost AI skills，并以后台服务启动 Bifrost；安装完成后可直接访问管理端。 Bash 与 PowerShell 安装脚本都会自动探测 GitHub 直连和内置镜像源，优先使用最快可用的 release 下载地址；受限网络中也可通过 BIFROST_GITHUB_MIRROR 指定优先镜像。

安装指定版本

curl -fsSL https://raw.githubusercontent.com/bifrost-proxy/bifrost/main/install-binary.sh | bash -s -- --version v0.0.48-beta

方法二：使用 npm 安装

npm i -g @bifrost-proxy/bifrost

更多安装方法：docs/getting-started.md

检查代理：

bifrost status

启动后访问管理端：

http://127.0.0.1:9900/_bifrost/

设备可用性检查

手机、平板或另一台电脑配置代理前，优先打开 Web UI 的 Settings -> Certificate -> Availability Check。选择当前电脑的局域网 IP 后生成二维码或链接，用目标设备访问即可自动检查三件事：

• 该设备是否已被 Bifrost 代理访问控制允许。
• 设备是否能访问 Bifrost 的探针端口。
• 当前浏览器是否已经信任 Bifrost CA 签发的 HTTPS 证书。

检查通过后，页面会显示可点击复制的代理地址 <局域网 IP>:<端口>，也可以打开代理二维码继续配置。若检查失败，页面会按 iOS/Android 给出下一步：安装 CA、iOS 进入 设置 > 通用 > 关于本机 > 证书信任设置 开启完全信任，或到管理端批准该设备的代理访问。

和AI集成

bifrost install-skill -y

特性说明

• 高性能代理内核：基于 Tokio + Hyper，支持高并发与连接复用
• 多协议支持：HTTP/1.1、HTTP/2、HTTP/3、HTTPS、SOCKS5、WebSocket、SSE、gRPC
• TLS 拦截能力：支持 CA 证书生成、按域名动态签发证书、按规则选择拦截/透传，并可对单条上游 HTTPS 规则显式允许不安全证书
• 规则引擎：支持路由、请求/响应改写、注入、延迟、限速、Mock、脚本处理
• 管理界面：内置 Web UI，支持规则编辑、流量查看、脚本管理、请求重放
• Breakpoint：支持在 Web UI 中暂停命中 breakpoint://request / breakpoint://response 规则的 HTTP request/response，编辑 headers/body 后继续；详见 docs/breakpoint.md
• 资源风险告警：Performance 页与 /_bifrost/api/system/memory 会显示 body/ws 文件 writer 占用及接近句柄上限的告警状态
• 脚本沙箱：基于 QuickJS，支持 reqScript、resScript、decode

开发初始化

克隆仓库后，先执行一次 Git hook 初始化：

bash scripts/setup-git-hooks.sh
# 或
make setup

这会为当前仓库写入本地 core.hooksPath=.githooks，即使机器上配置了全局 hooksPath，后续 git commit 也会优先执行仓库内的 .githooks/pre-commit。默认 pre-commit 会检查工作区格式、桌面端 Tauri 格式，以及 cargo clippy --workspace --all-targets --all-features -- -D warnings。

用不习惯 CLI？想要使用桌面端 APP？

请直接到releases中下载对应平台的桌面端程序

基本用法摘要

常见命令：

# 查看状态
bifrost status

# 停止服务
bifrost stop

# 管理端远程访问与鉴权（Web UI）
bifrost admin remote status
bifrost admin remote enable
bifrost admin passwd
bifrost admin revoke-all

# 查看流量
bifrost traffic list
bifrost traffic search "keyword" --method POST --host api.openai.com --path /v1/responses
bifrost search "keyword" --req-header
bifrost search "keyword" --res-body

# 添加规则
bifrost rule add local-dev --content "example.com host://127.0.0.1:3000"

搜索命令补充说明：

• bifrost search 与 bifrost traffic search 等价
• 基础过滤支持 --method、--host、--path、--status、--protocol
• 搜索范围支持 --url、--req-header、--res-header、--req-body、--res-body
• 兼容别名：--headers 会同时搜索请求头和响应头，--body 会同时搜索请求体和响应体

规则示例：

example.com host://127.0.0.1:3000
api.example.com reqHeaders://x-debug=1
chatgpt.com http3://
internal-api.example.test https://10.37.102.138:8080 upstreamUnsafeSsl://true

文档索引

• 文档总览：docs/README.md
• 项目概览：docs/overview.md
• 安装与启动：docs/getting-started.md
• CLI 详细命令：docs/cli.md
• 桌面版安装与构建：docs/desktop.md
• 规则语法：docs/rule.md
• 操作符说明：docs/operation.md
• 匹配模式：docs/pattern.md
• 规则协议手册：docs/rules/README.md
• Scripts 模块与脚本开发：docs/scripts.md
• Values 使用说明：docs/values.md
• 请求重放说明：docs/replay.md
• Breakpoint 使用手册：docs/breakpoint.md
• 项目结构与模块说明：docs/architecture.md
• Agent Skill 安装说明：docs/agent-skill.md