# 安装与启动

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

## 安装 CLI

### 一键安装

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

默认安装完成后，脚本会自动完成一键体验初始化：

- 安装并信任 Bifrost CA 证书。
- 安装所有支持 AI 工具的 Bifrost skills。
- 以后台服务启动 Bifrost。

Bash 与 PowerShell 安装脚本都会自动探测 GitHub 直连和内置镜像源，优先使用最快可用的 release 下载地址；受限网络中可以设置 `BIFROST_GITHUB_MIRROR` 指定优先镜像，也可以用 `BIFROST_MIRROR_PROBE_TIMEOUT` 调整镜像探测超时。

可选参数：

```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

# 仅安装二进制，不自动安装证书、skills 或启动服务
curl -fsSL https://raw.githubusercontent.com/bifrost-proxy/bifrost/main/install-binary.sh | bash -s -- --no-post-install
```

### Homebrew（macOS）

```bash
brew tap bifrost-proxy/bifrost
brew install bifrost
```

### 使用 npm 安装

```bash
npm i @bifrost-proxy/bifrost
```

### 从源码构建

环境要求：

- Rust 1.70+
- Cargo
- Node.js 22+
- pnpm

构建步骤：

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

./install.sh

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

### 手动下载

可直接从 [Releases](https://github.com/bifrost-proxy/bifrost/releases) 下载预编译二进制。

## 检查安装

```bash
command -v bifrost
bifrost --version
```

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

```bash
cargo run -p bifrost-cli -- --version
```

## 启动代理

```bash
# 默认监听 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`。

## 管理端入口

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

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

默认端口示例：

```text
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 后仍然无法抓包时，优先使用 `Settings -> Certificate -> Availability Check`，不要先猜是证书问题还是代理授权问题。

使用步骤：

1. 在 Certificate 页面顶部的 `Availability Check` 中选择当前电脑的局域网 IP。
2. 点击 `Generate Availability Check`，把页面展示的链接发给目标设备，或让目标设备扫码。
3. 目标设备打开检测页后会自动检查代理访问授权、探针端口可达性，以及 Bifrost CA 的 HTTPS 信任状态。
4. 如果代理访问显示待批准，回到 Bifrost 管理端批准该设备，或调整访问控制/局域网访问配置。
5. 如果 HTTPS 信任失败，先安装 Bifrost CA；iOS 还必须进入 `设置 > 通用 > 关于本机 > 证书信任设置`，打开 Bifrost CA 的完全信任。
6. 检查成功后，点击页面上的代理地址复制 `<局域网 IP>:<端口>`，或打开代理二维码继续配置。

这个检查验证的是“当前设备当前浏览器能否真实完成 Bifrost CA 签发证书的 HTTPS 握手”。它不能保证所有 App 都能被解密，因为个别 App 可能使用证书固定、自定义 TLS 栈，Android App 也可能默认不信任用户安装的 CA。

## 环境变量

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

示例：

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

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

## 卸载

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

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