# 故障与自动切换

URL: https://caijiao.org/pingora/handling_failures_and_failover
Source: docs/pingora/handling_failures_and_failover.md
Description: 学习如何在 Pingora 中处理上游故障，实现自动切换（Failover）和高可用服务。

在代理场景中，上游服务器可能出现故障或不可用。  
Pingora 提供 **自动故障检测与切换机制**，确保服务稳定性。

## 故障检测

Pingora 会监控上游连接状态：

- 请求失败或超时  
- TCP/TLS 连接断开  
- HTTP 错误响应（如 5xx）

出现上述情况时，Peer 会将该上游标记为不可用。

## 自动切换（Failover）

当上游不可用时：

1. Pingora 会自动选择其他可用上游进行请求转发  
2. 可配置重试次数和回退策略  
3. 失败连接会被短暂隔离，避免频繁尝试

### 配置示例

```yaml
proxy:
  upstreams:
    - name: backend
      servers:
        - "127.0.0.1:8000"
        - "127.0.0.1:8001"
      max_connections: 50
      retry_policy:
        retries: 3
        backoff: 100ms
````

* `retries`：失败重试次数
* `backoff`：重试间隔，防止瞬间过载

## 高可用策略

* **多上游备份**：至少配置两个或以上上游
* **动态权重**：根据响应速度动态调整负载分配
* **健康检查**：定期检测上游状态，自动恢复已标记不可用的服务器

## 编程示例

```rust
fn handle_request(req: &Request, ctx: &mut Context) -> Result<Response, Error> {
    let peer = Peer::select("backend")?;
    
    match peer.send_request(req) {
        Ok(resp) => Ok(resp),
        Err(err) => {
            error!("请求上游失败: {:?}", err);
            // 尝试切换到备用上游
            let backup_peer = Peer::select_backup("backend")?;
            backup_peer.send_request(req)
        }
    }
}
```

---

通过合理配置故障检测和自动切换，Pingora 能够在上游服务器出现故障时继续提供服务，提高代理系统的可用性和稳定性。