# 用户指南

URL: https://caijiao.org/pingora/user_guide
Source: docs/pingora/user_guide.md
Description: 本节介绍 Pingora 的基本概念、主要特性与使用方式，帮助你快速了解和上手这个高性能代理框架。

Pingora 是一个基于 **Rust** 构建的高性能代理框架，由 **Cloudflare** 开发并开源。  
它被用于替代 Nginx，在高并发场景下展现出更好的性能与资源效率。

## 什么是 Pingora

Pingora 是一个 **网络代理框架（proxy framework）**，它并不是单一应用程序，而是可被用来构建自定义代理、负载均衡器或服务网关的 **框架**。  
通过模块化设计和异步运行模型，你可以在 Pingora 基础上构建：

- 反向代理（Reverse Proxy）
- 正向代理（Forward Proxy）
- 负载均衡（Load Balancer）
- 服务网关（Service Gateway）
- 内部流量路由与过滤器系统

## Pingora 的特点

| 特性 | 描述 |
|------|------|
| 🚀 高性能 | 基于 Rust 异步模型，比 Nginx 更快的连接复用与内存安全 |
| 🔐 内存安全 | Rust 的所有权系统杜绝内存泄漏与数据竞争 |
| ⚙️ 模块化 | 按阶段拆分请求生命周期，可自定义过滤器与中间层 |
| 📊 可观测性 | 内置 Tracing 与 Prometheus 支持 |
| 🧠 灵活扩展 | 提供 CTX 上下文共享机制，可在多个阶段共享状态 |

## 基础组件

Pingora 的主要组成部分包括：

- **pingora-core**：核心运行库，提供事件循环、IO、多线程调度；
- **pingora-proxy**：构建 HTTP 代理的核心模块；
- **pingora-limiter**：提供限流与速率控制；
- **pingora-runtime**：异步运行时层，管理线程与任务；
- **pingora-openssl / pingora-boringssl**：SSL/TLS 支持；
- **pingora-tools**：辅助开发与调试工具。

## 快速上手流程

1. **安装 Rust 环境**

   ```bash
   curl https://sh.rustup.rs -sSf | sh
   ````

2. **创建 Pingora 项目**

   ```bash
   cargo new pingora-demo
   cd pingora-demo
   cargo add pingora-proxy
   ```

3. **编写最小代理示例**

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

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

4. **运行项目**

   ```bash
   cargo run
   ```

   打开浏览器访问 `http://127.0.0.1:8080`，即可看到代理服务启动成功。

## 下一步

接下来，我们将学习如何 **运行 Pingora 服务器**、实现 **优雅重启**、**配置管理** 等关键功能。
👉 继续阅读：[运行 Pingora 服务器](/pingora/running_pingora_servers)