# 构建 HTTP 代理

URL: https://caijiao.org/pingora/building_http_proxies
Source: docs/pingora/building_http_proxies.md
Description: 学习如何使用 Pingora 构建 HTTP 代理服务，包括基本请求转发、上游配置和自定义过滤器。

Pingora 可以用来构建高性能的 **HTTP/HTTPS 代理**，支持请求转发、连接复用、TLS 加密和自定义过滤器。

## 最小可用代理示例

```rust
use pingora::prelude::*;

#[tokio::main]
async fn main() {
    let mut server = Server::new(None).unwrap();
    server.bootstrap();

    // 构建一个简单 HTTP 代理
    let app = http_proxy_service(None);

    server.run_forever(app).unwrap();
}
````

执行后，你可以访问 `http://127.0.0.1:8080`，Pingora 会将请求转发到默认上游。

## 配置上游服务器

在配置文件中设置上游服务：

```yaml
proxy:
  upstreams:
    - name: backend
      servers:
        - "127.0.0.1:8000"
        - "127.0.0.1:8001"
```

Pingora 会自动进行负载均衡，将请求分发到多个上游。

## 自定义请求过滤器

可以在代理服务中添加自定义过滤器，处理请求和响应：

```rust
use pingora::prelude::*;

fn my_filter(req: &Request, ctx: &mut Context) -> Result<(), Error> {
    println!("请求路径: {}", req.path());
    Ok(())
}

let mut server = Server::new(None).unwrap();
server.bootstrap();
let mut app = http_proxy_service(None);
app.add_filter(my_filter);
server.run_forever(app).unwrap();
```

### 过滤器用途

* 请求验证（如 API Key 或 Token）
* 请求/响应日志记录
* 路由或重写 URL
* 自定义限流或安全策略

## 端口与监听地址

可通过配置文件或命令行参数指定：

```yaml
server:
  listen: "0.0.0.0:8080"
```

* `0.0.0.0` 表示监听所有网络接口
* 端口可以自由指定，例如 8080、80 或 443（需要 root 权限）

## TLS/HTTPS 支持

使用 BoringSSL 或 OpenSSL，可以启用 HTTPS：

```yaml
tls:
  cert: /etc/ssl/certs/server.crt
  key: /etc/ssl/private/server.key
```

Pingora 会自动将 HTTP 请求升级到 HTTPS 并处理加密传输。

---

通过上述步骤，你可以快速搭建一个高性能的 HTTP/HTTPS 代理，并在此基础上添加自定义逻辑，实现复杂的请求处理与转发需求。