安装与启动

此页面由 docs/getting-started.md 自动同步生成。

安装与启动

本文档汇总 Bifrost 的安装、启动、管理端入口与卸载方式。

安装 CLI

一键安装

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

可选参数：

# 指定安装目录
curl -fsSL https://raw.githubusercontent.com/bifrost-proxy/bifrost/main/install-binary.sh | bash -s -- --dir /usr/local/bin

# 安装指定版本
curl -fsSL https://raw.githubusercontent.com/bifrost-proxy/bifrost/main/install-binary.sh | bash -s -- --version v0.2.0

Homebrew（macOS）

brew tap bifrost-proxy/bifrost
brew install bifrost

使用 npm 安装

npm i @bifrost-proxy/bifrost

从源码构建

环境要求：

Rust 1.70+
Cargo
Node.js 22+
pnpm

构建步骤：

git clone https://github.com/bifrost-proxy/bifrost.git
cd bifrost

./install.sh

# 或手动构建
cd web && pnpm install && pnpm build && cd ..
cargo build --release

手动下载

可直接从 Releases 下载预编译二进制。

检查安装

command -v bifrost
bifrost --version

如果尚未加入 PATH，也可以在源码仓库中执行：

cargo run -p bifrost-cli -- --version

启动代理

# 默认监听 0.0.0.0:9900
bifrost start

# 自定义端口和监听地址
bifrost -p 9000 -H 127.0.0.1 start

# 启用 HTTP + SOCKS5
bifrost -p 9900 --socks5-port 1080 start

# 按域名启用 TLS 抓包
bifrost start --intercept-include "*.api.local"

# 按应用启用 TLS 抓包
bifrost start --app-intercept-include "*Chrome,*curl"

# 守护进程模式
bifrost start --daemon

bifrost start 默认会启用系统代理，浏览器和桌面应用通常无需额外配置就会进入 Bifrost。TLS 抓包按需开启，不建议默认全局 --intercept；优先使用域名白名单、应用白名单或规则级 tlsIntercept://。遇到 SSL pinning 应用时，应使用 --app-intercept-exclude、--intercept-exclude 或规则级 tlsPassthrough:// 排除。需要 TLS 抓包时，启动流程会自动生成并安装 Bifrost CA；bifrost ca generate / bifrost ca install 主要用于手动修复或诊断证书状态。默认访问控制模式为 interactive：本机 loopback 直接允许，非本机地址需要管理端审批、白名单或显式 --allow-lan / --access-mode 放行。只有在 CI、沙箱或明确不想影响系统网络时，才使用 --no-system-proxy。

管理端入口

服务启动后，在浏览器访问：

http://127.0.0.1:<port>/_bifrost/

默认端口示例：

http://127.0.0.1:9900/_bifrost/

常用入口：

路径	说明
`/_bifrost/`	Web UI
`/_bifrost/api/rules/*`	规则管理 API
`/_bifrost/api/values/*`	Values API
`/_bifrost/api/traffic/*`	流量 API
`/_bifrost/api/scripts/*`	Scripts API
`/_bifrost/api/replay/*`	请求重放 API

说明：

管理端默认仅允许通过 127.0.0.1 或 localhost 访问
SSE 增量订阅接口为 /_bifrost/api/traffic/{id}/sse/stream?from=begin

环境变量

环境变量	说明	默认值
`BIFROST_DATA_DIR`	数据目录路径	`~/.bifrost`
`RUST_LOG`	日志级别和过滤器	`info`
`WEB_PORT`	Web UI 开发服务端口	`3000`

示例：

RUST_LOG=debug bifrost start
RUST_LOG=bifrost_proxy=debug,info bifrost start

日常使用不建议为了临时排障创建新的 BIFROST_DATA_DIR。优先启动一次主服务，再使用 bifrost port bind ... 创建独立调试端口；只有自动化测试、并发实验或破坏性配置验证需要完全隔离状态时，才设置临时数据目录。

卸载

# 卸载 CLI 和桌面应用
./uninstall.sh

# 连同数据一起清理
./uninstall.sh --purge