# 服务器命令（server）

> pgBackRest `server` 命令的选项与行为参考。

---

LLMS 索引： [llms.txt](/llms.txt)

---

> 原始页面： [pgBackRest Command Docs: server](https://pgbackrest.org/command.html#command-server)

pgBackRest 服务器允许在不使用 SSH 协议的情况下访问远程主机。

## 命令选项

### TLS 服务器地址选项（`--tls-server-address`）

TLS 服务器地址。

服务器监听客户端请求的 IP 地址。

```yaml
default: localhost
example: --tls-server-address=*
```

### TLS 服务器授权客户端选项（`--tls-server-auth`）

TLS 服务器授权客户端。

服务器通过验证客户端证书，并将其证书 CN（Common Name，通用名称）与 `tls-server-auth` 选项所配置的列表进行比对，来完成对客户端的授权。

可通过向 `tls-server-auth` 选项传入逗号分隔的列表，授权某个客户端 CN 访问多个 stanza（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）；也可通过指定 `tls-server-auth=client-cn=*` 授权其访问所有 stanza。客户端 CN 不支持通配符。

```yaml
example: --tls-server-auth=client-cn=stanza1,stanza2
```

### TLS 服务器证书颁发机构选项（`--tls-server-ca-file`）

TLS 服务器证书颁发机构。

用于验证客户端证书是否由受信任的证书颁发机构签发。

```yaml
example: --tls-server-ca-file=/path/to/server.ca
```

### TLS 服务器证书选项（`--tls-server-cert-file`）

TLS 服务器证书文件。

发送给客户端以证明服务器身份的证书。

```yaml
example: --tls-server-cert-file=/path/to/server.crt
```

### TLS 服务器密钥选项（`--tls-server-key-file`）

TLS 服务器密钥文件。

用于证明服务器证书归属的私钥。

```yaml
example: --tls-server-key-file=/path/to/server.key
```

### TLS 服务器端口选项（`--tls-server-port`）

TLS 服务器端口。

服务器监听客户端请求的端口。

```yaml
default: 8432
allowed: [1, 65535]
example: --tls-server-port=8000
```

## 通用选项

### 允许以 root 用户运行选项（`--allow-root`）

允许命令以 root 用户运行。

默认情况下，仅 `restore` 命令可以由 root 用户运行，因为该命令会谨慎管理文件所有权。以 root 运行其他命令可能创建由 root 所有的文件（例如仓库中的文件），PostgreSQL 用户随后将无法访问这些文件，导致后续命令失败。

启用此选项仍可强制以 root 运行命令。不过，更佳做法是使用仓库和 PostgreSQL 集群的所有者用户运行 pgBackRest。

```yaml
default: n
example: --allow-root
```

### 缓冲区大小选项（`--buffer-size`）

I/O 操作的缓冲区大小。

用于复制、压缩、加密等操作的缓冲区大小。实际使用的缓冲区数量取决于各选项配置，每个操作可能还会额外占用内存，例如 `gz` 压缩可能额外使用 256KiB 内存。

允许的值为：`16KiB`、`32KiB`、`64KiB`、`128KiB`、`256KiB`、`512KiB`、`1MiB`、`2MiB`、`4MiB`、`8MiB` 和 `16MiB`。

```yaml
default: 1MiB
example: --buffer-size=2MiB
```

### 配置文件选项（`--config`）

pgBackRest 配置文件。

指定与默认值不同的配置文件路径。

```yaml
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_FILE
example: --config=/conf/pgbackrest/pgbackrest.conf
```

### 配置包含路径选项（`--config-include-path`）

附加 pgBackRest 配置文件的路径。

该路径下扩展名为 `.conf` 的配置文件将与 pgBackRest 主配置文件合并，最终形成一个完整的配置文件。

```yaml
default: CFGOPTDEF_CONFIG_PATH "/" PROJECT_CONFIG_INCLUDE_PATH
example: --config-include-path=/conf/pgbackrest/conf.d
```

### 配置基础路径选项（`--config-path`）

pgBackRest 配置文件的基础路径。

此选项覆盖 `--config` 和 `--config-include-path` 的默认基础路径，但仅在这两个选项未在命令行中明确指定时生效。

例如，仅传入 `--config-path=/conf/pgbackrest` 时，`--config` 的默认值将变为 `/conf/pgbackrest/pgbackrest.conf`，`--config-include-path` 的默认值将变为 `/conf/pgbackrest/conf.d`。

```yaml
default: CFGOPTDEF_CONFIG_PATH
example: --config-path=/conf/pgbackrest
```

### I/O 超时选项（`--io-timeout`）

I/O 超时时间。

连接及读写操作的超时时间，单位为秒。

注意：整个读写操作不必在此超时时间内完成，但 *必须* 有所进展，哪怕只传输了一个字节。

```yaml
default: 1m
allowed: [100ms, 1h]
example: --io-timeout=120
```

### 进程优先级选项（`--priority`）

设置进程优先级。

定义内核调度器赋予该进程的优先级（即 niceness 值）。正值降低优先级，负值提高优先级。普通进程在大多数情况下无权提高自身优先级。

```yaml
allowed: [-20, 19]
example: --priority=19
```

### 协议超时选项（`--protocol-timeout`）

协议超时时间。

本地或远程进程在协议层等待新消息的超时时间，单位为秒。此设置可防止进程无限期阻塞等待消息。

> **注意：** `protocol-timeout` 选项的值必须大于 `db-timeout` 选项的值。

```yaml
default: 31m
allowed: [100ms, 7d]
example: --protocol-timeout=630
```

### 保活选项（`--sck-keep-alive`）

启用保活。

在 socket 连接上启用保活消息。

```yaml
default: y
example: --no-sck-keep-alive
```

### TCP 保活计数选项（`--tcp-keep-alive-count`）

保活计数。

连接被判定为断开之前，允许丢失的 TCP 保活消息数量。

此选项仅在支持 `TCP_KEEPCNT` socket 选项的系统上可用。

```yaml
allowed: [1, 32]
example: --tcp-keep-alive-count=3
```

### TCP 保活空闲时间选项（`--tcp-keep-alive-idle`）

保活空闲时间。

无网络活动持续多少秒后，操作系统开始发送 TCP 保活消息。

此选项仅在支持 `TCP_KEEPIDLE` socket 选项的系统上可用。

```yaml
allowed: [1, 3600]
example: --tcp-keep-alive-idle=60
```

### TCP 保活间隔选项（`--tcp-keep-alive-interval`）

保活间隔时间。

未被确认的 TCP 保活消息重新发送前的等待秒数。

此选项仅在支持 `TCP_KEEPINTVL` socket 选项的系统上可用。

```yaml
allowed: [1, 900]
example: --tcp-keep-alive-interval=30
```

### TLSv1.2 加密套件选项（`--tls-cipher-12`）

允许使用的 TLSv1.2 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均经过加密，连接到对象存储（如 S3）时默认也会加密。

> **注意：** 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。示例中的配置是合理的选择，除非有特殊安全要求。若未设置（默认），则使用底层 OpenSSL 库的默认值。

```yaml
example: --tls-cipher-12=HIGH:MEDIUM:+3DES:!aNULL
```

### TLSv1.3 加密套件选项（`--tls-cipher-13`）

允许使用的 TLSv1.3 加密套件。

pgBackRest 客户端与服务器之间的所有 TLS 连接均经过加密，连接到对象存储（如 S3）时默认也会加密。

> **注意：** 任何传输连接的最低安全级别为 TLSv1.2。

如有需要，可调整允许使用的加密套件。若未设置（默认），则使用底层 OpenSSL 库的默认值。

```yaml
example: --tls-cipher-13=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
```

## 日志选项

### 控制台日志级别选项（`--log-level-console`）

控制台日志级别。

支持以下日志级别：

- `off` - 不记录任何日志（不推荐）
- `error` - 仅记录错误
- `warn` - 记录警告和错误
- `info` - 记录信息、警告和错误
- `detail` - 记录详情、信息、警告和错误
- `debug` - 记录调试、详情、信息、警告和错误
- `trace` - 记录追踪（非常详细的调试信息）、调试、信息、警告和错误

```yaml
default: warn
example: --log-level-console=error
```

### 文件日志级别选项（`--log-level-file`）

文件日志级别。

支持以下日志级别：

- `off` - 不记录任何日志（不推荐）
- `error` - 仅记录错误
- `warn` - 记录警告和错误
- `info` - 记录信息、警告和错误
- `detail` - 记录详情、信息、警告和错误
- `debug` - 记录调试、详情、信息、警告和错误
- `trace` - 记录追踪（非常详细的调试信息）、调试、信息、警告和错误

```yaml
default: info
example: --log-level-file=debug
```

### 标准错误日志级别选项（`--log-level-stderr`）

stderr 日志级别。

指定哪些日志级别输出到 `stderr` 而非 `stdout`（由 `log-level-console` 控制）。时间戳和进程信息不会输出到 `stderr`。

支持以下日志级别：

- `off` - 不记录任何日志（不推荐）
- `error` - 仅记录错误
- `warn` - 记录警告和错误
- `info` - 记录信息、警告和错误
- `detail` - 记录详情、信息、警告和错误
- `debug` - 记录调试、详情、信息、警告和错误
- `trace` - 记录追踪（非常详细的调试信息）、调试、信息、警告和错误

```yaml
default: off
example: --log-level-stderr=error
```

### 日志路径选项（`--log-path`）

日志文件的存储路径。

pgBackRest 将日志文件写入此路径。若 `log-level-file=off`，则无需配置日志路径。

```yaml
default: /var/log/pgbackrest
example: --log-path=/backup/db/log
```

### 日志时间戳选项（`--log-timestamp`）

在日志中启用时间戳。

在控制台和文件日志中启用时间戳。在某些特殊情况下（如生成文档时），此选项会被禁用。

```yaml
default: y
example: --no-log-timestamp
```