# 配置文件

URL: https://caijiao.org/pingora/configuration
Source: docs/pingora/configuration.md
Description: 了解 Pingora 的配置文件结构、主要参数及其作用，学习如何为不同场景编写高效、清晰的配置。

Pingora 使用灵活的配置系统来控制服务器行为、代理规则和运行参数。  
配置文件通常采用 **YAML** 格式，既简洁又易读。

## 配置文件位置

默认情况下，Pingora 会在以下路径查找配置文件：

```bash
/etc/pingora/config.yaml
````

你也可以通过命令行参数指定配置路径：

```bash
pingora --config /path/to/config.yaml
```

## 基本配置示例

下面是一个最小可用的 Pingora 配置文件示例：

```yaml
server:
  listen: "0.0.0.0:8080"
  workers: 4
  reuse_port: true

proxy:
  upstreams:
    - name: backend
      servers:
        - "127.0.0.1:8000"

logging:
  level: info
  file: /var/log/pingora.log
```

## 核心配置项说明

### 1. `server` 部分

定义服务器运行方式和网络监听行为。

| 参数           | 类型  | 示例               | 说明                       |
| ------------ | --- | ---------------- | ------------------------ |
| `listen`     | 字符串 | `"0.0.0.0:8080"` | 指定监听地址与端口                |
| `workers`    | 数字  | `4`              | 启动的工作进程数量                |
| `reuse_port` | 布尔  | `true`           | 是否启用 SO_REUSEPORT 优化端口复用 |

### 2. `proxy` 部分

定义代理转发规则与上游服务。

| 参数          | 类型  | 示例                   | 说明        |
| ----------- | --- | -------------------- | --------- |
| `upstreams` | 数组  | —                    | 定义上游服务器集群 |
| `name`      | 字符串 | `"backend"`          | 上游名称      |
| `servers`   | 数组  | `["127.0.0.1:8000"]` | 上游服务地址    |

### 3. `logging` 部分

控制日志输出位置与级别。

| 参数      | 类型  | 示例                     | 说明                                    |
| ------- | --- | ---------------------- | ------------------------------------- |
| `level` | 字符串 | `"info"`               | 日志级别，可选 `debug`、`info`、`warn`、`error` |
| `file`  | 字符串 | `/var/log/pingora.log` | 日志文件路径                                |

### 4. `metrics`（可选）

启用 Prometheus 监控导出。

```yaml
metrics:
  enable: true
  listen: "127.0.0.1:9090"
```

### 5. `tls`（可选）

配置 HTTPS 支持（基于 BoringSSL）。

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

## 验证配置文件

运行以下命令检查配置是否正确：

```bash
pingora --check-config /etc/pingora/config.yaml
```

如无错误，命令会输出：

```txt
Configuration OK
```

## 提示与最佳实践

* 使用 **环境变量** 替换敏感配置，如密钥或上游地址；
* 将日志与 PID 文件路径写入 `/var/run` 或 `/var/log`；
* 若部署多实例，建议区分配置文件路径；
* 对性能关键配置（如 worker 数）进行逐步调整测试。

---

Pingora 的配置系统非常灵活，支持从简单的反向代理到复杂的多层代理拓扑。掌握配置语法后，你可以轻松构建高性能、可维护的代理服务。