PostgreSQL 社区组件 on PIG.CENTER

pgBadger 13.x 版本记录

Mon, 01 Jan 0001 00:00:00 +0000

本页按从新到旧的顺序保留 pgBadger 13.x 的完整上游变更记录。为确保版本、参数、提交者致谢和兼容性描述不被转述改变，正文保留英文原文。

v13.2 · 2025-12-29

This is a maintenance release of pgBadger that fixes issues and applied patches reported by users since last release.

注解命令（annotate）

Mon, 01 Jan 0001 00:00:00 +0000

backup 命令执行时附加的注解，可在事后通过 annotate 命令进行添加、修改或删除。

命令选项

备份注解选项（`--annotation`）

为备份添加用户自定义键值对注解。

动态配置

Mon, 01 Jan 0001 00:00:00 +0000

动态配置存储在 DCS（分布式配置存储）中，并应用于集群的所有节点。

如需修改动态配置，可使用 patronictl edit-config 工具或 Patroni REST API 。

loop_wait：主循环每轮的休眠秒数。默认值：10，最小值：1。
ttl：获取领导者锁的 TTL（秒）。可以理解为触发自动故障转移前的等待时长。默认值：30，最小值：20。
retry_timeout：DCS 和 PostgreSQL 操作的重试超时时间（秒）。若 DCS 或网络故障时长短于此值，Patroni 不会对主库执行降级。默认值：10，最小值：3。

警告

修改 loop_wait、retry_timeout 或 ttl 时，必须遵守以下约束：

简介

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 是一个基于 Python 构建的高可用 PostgreSQL 解决方案模板框架。它最初 fork 自 Compose 公司的 Governor 项目，并在此基础上引入了大量新特性。

更多背景资料，请参阅：

PostgreSQL HA with Kubernetes and Patroni ——Josh Berkus 在 KubeCon 2016 上的演讲（视频）
2016 年 2 月 Zalando 技术博客文章

开发状态

Patroni 正处于活跃开发阶段，欢迎社区贡献。详情请参阅下方的 贡献指南 章节。

入门指南

Mon, 01 Jan 0001 00:00:00 +0000

特性

Mon, 01 Jan 0001 00:00:00 +0000

连接轮换时，按激进程度分为以下几种策略：

会话池化

最温和的方式。当客户端连接时，将为其分配一个服务端连接，并在客户端保持连接期间始终持有。当客户端断开时，服务端连接将放回连接池。此模式支持所有 PostgreSQL 特性。

事务池化

仅在事务期间为客户端分配服务端连接。当 PgBouncer 检测到事务结束时，服务端连接将放回连接池。此模式会破坏 PostgreSQL 的部分会话级特性，只有在应用程序配合、不使用不兼容特性的情况下才可使用。不兼容特性详见下表。

语句池化

最激进的方式。这是事务池化的变体：禁止多语句事务。这是为了在客户端强制执行“自动提交”（autocommit）模式，主要面向 PL/Proxy。
内存占用极低（默认每连接仅需 2 kB）。这是因为 PgBouncer 无需一次性看到完整的数据包。

新闻

Mon, 01 Jan 0001 00:00:00 +0000

pgBackRest 2.59.1 正式发布

2026 年 8 月 17 日

pgBackRest 社区很高兴地宣布 pgBackRest 2.59.1 正式发布。pgBackRest 是一款可靠、易用的备份与恢复解决方案，可无缝扩展以应对超大规模数据库和工作负载。

pgBadger 12.x 版本记录

Mon, 01 Jan 0001 00:00:00 +0000

本页按从新到旧的顺序保留 pgBadger 12.x 的完整上游变更记录。为确保版本、参数、提交者致谢和兼容性描述不被转述改变，正文保留英文原文。

v12.4 · 2023-12-25

This is a maintenance release of pgBadger that fixes issues reported by users since last release.

归档获取命令（archive-get）

Mon, 01 Jan 0001 00:00:00 +0000

PostgreSQL 通过此命令执行备份恢复、PITR，或将其作为流复制的替代方式来维持副本同步。WAL 段是 PostgreSQL 执行恢复或维护副本的必要条件。

配置多个仓库时，pgBackRest 按优先级顺序（如 repo1、repo2 等）依次从各仓库获取 WAL。速度更快或成本更低的存储应配置更高的优先级。若通过 --repo 选项指定了某个仓库，则仅从该仓库中查找。

YAML 配置参数

Mon, 01 Jan 0001 00:00:00 +0000

全局/通用

name：主机名称，在集群中必须唯一。
namespace：Patroni 在配置存储中保存集群信息的路径，默认值为 /service。
scope：集群名称。

安装

Mon, 01 Jan 0001 00:00:00 +0000

Mac OS 前置依赖

在 Mac 上安装依赖，执行以下命令：

brew install postgresql etcd haproxy libyaml python

Psycopg

从 psycopg2-2.8 开始，psycopg2 的二进制版本不再默认安装。从源码编译安装需要 C 编译器以及 postgres 和 python 的开发包。由于 Python 生态中无法将依赖声明为 psycopg2 OR psycopg2-binary，您需要自行选择安装方式。

负载均衡基础

Mon, 01 Jan 0001 00:00:00 +0000

本文旨在向所有尚未了解 HAProxy 的用户以及希望重新认识该软件（尤其是熟悉旧版本的用户）提供入门引导。本文主要目的在于为用户提供充分信息，以判断 HAProxy 是否符合其需求。高级用户可能在此发现某些解决方案的片段，仅因此前未意识到某项新功能的存在。此外，本文还提供了部分容量规划信息，说明了产品的生命周期，并对部分功能重叠的产品进行了对比。

配置：pgbouncer.ini

Mon, 01 Jan 0001 00:00:00 +0000

描述

配置文件采用 “ini” 格式。节名称位于 [ 和 ] 之间。以 ; 或 # 开头的行被视为注释并忽略。当 ; 和 # 出现在行中间时，不会被识别为特殊字符。

下载与安装

Mon, 01 Jan 0001 00:00:00 +0000

选择分发渠道

渠道	适用场景	地址
官方发布	源码归档与版本说明	GitHub Releases
RPM 软件包	基于 RPM 的 Linux 发行版	PostgreSQL Yum 仓库
Debian/Ubuntu 软件包	基于 APT 的 Linux 发行版	PostgreSQL Apt 仓库
开发源码	尚未正式发布的最新代码	darold/pgbadger

本站文档快照基于 13.2 源码树。下载前始终应查看发布页面：本地快照为了可复现而固定，上游版本仍会继续更新。

用户指南（Debian/Ubuntu）

Mon, 01 Jan 0001 00:00:00 +0000

简介

本用户指南适合从头到尾顺序阅读——每章内容均依赖前一章的配置基础。例如，恢复章节依赖 快速开始 章节中已完成的配置。pgBackRest 运行起来之后，跳章阅读也无妨，但建议初次阅读时按顺序跟随本指南。

pgBadger 11.x 版本记录

Mon, 01 Jan 0001 00:00:00 +0000

本页按从新到旧的顺序保留 pgBadger 11.x 的完整上游变更记录。为确保版本、参数、提交者致谢和兼容性描述不被转述改变，正文保留英文原文。

v11.8 · 2022-04-08

This release of pgBadger fix some issues reported by users since past three months and especially two fixes on new log entries detection in incremental mode.

归档推送命令（archive-push）

Mon, 01 Jan 0001 00:00:00 +0000

接收来自 PostgreSQL 的 WAL 段，并将其归档到各个仓库中（仓库路径由带索引的 repo-path 选项定义，详见 仓库选项 章节）。WAL 段可以立即推送到归档，也可以根据 archive-async 的值先暂存在本地。配置了多个仓库时，archive-push 会尽量向所有仓库推送。

环境变量

Mon, 01 Jan 0001 00:00:00 +0000

可以使用系统环境变量覆盖 Patroni 配置文件中定义的部分配置参数。本文档列出了 Patroni 处理的所有环境变量。通过环境变量设置的值始终优先于配置文件中的值。

全局/通用

PATRONI_CONFIGURATION：可通过 PATRONI_CONFIGURATION 环境变量为 Patroni 提供完整配置。设置此变量后，其他所有环境变量将被忽略！
PATRONI_NAME：运行当前 Patroni 实例的节点名称，在集群内必须唯一。
PATRONI_NAMESPACE：Patroni 在配置存储中保存集群信息的路径。默认值："/service"。
PATRONI_SCOPE：集群名称。

日志

PATRONI_LOG_TYPE：日志格式，可为 plain 或 json。使用 json 格式需要安装 jsonlogger 。默认值为 plain。
PATRONI_LOG_LEVEL：全局日志级别。默认值为 INFO（参见 Python logging 文档）。
PATRONI_LOG_TRACEBACK_LEVEL：显示 traceback 的日志级别。默认值为 ERROR。若希望仅在 PATRONI_LOG_LEVEL=DEBUG 时才显示 traceback，可将其设置为 DEBUG。
PATRONI_LOG_FORMAT：日志格式化字符串。若日志类型为 plain，格式应为字符串，可用属性参见 LogRecord 属性文档。若日志类型为 json，格式除字符串外还可以是列表，每个列表项对应一个 LogRecord 属性，只需填写字段名，省略 %( 和 )。若希望以不同键名输出某个字段，可使用字典，键为日志字段名，值为希望在日志中显示的字段名。默认值为 %(asctime)s %(levelname)s: %(message)s。
PATRONI_LOG_DATEFORMAT：日期时间格式化字符串（参见 formatTime() 文档）。
PATRONI_LOG_STATIC_FIELDS：为日志添加额外字段，仅在日志类型为 json 时可用。示例：PATRONI_LOG_STATIC_FIELDS="{app: patroni}"。
PATRONI_LOG_MAX_QUEUE_SIZE：Patroni 采用两步日志记录机制。日志记录先写入内存队列，由独立线程从队列中取出后写入 stderr 或文件。内存队列容量默认限制为 1000 条，足以保留过去约 1 小时 20 分钟的日志。
PATRONI_LOG_DIR：应用程序日志的写入目录。该目录必须已存在且对运行 Patroni 的用户可写。设置此变量后，默认保留 4 个 25MB 的日志文件，可通过 PATRONI_LOG_FILE_NUM 和 PATRONI_LOG_FILE_SIZE 调整（见下文）。
PATRONI_LOG_MODE：日志文件权限（例如 0644）。若未指定，将基于当前 umask 值设置。
PATRONI_LOG_FILE_NUM：保留的应用程序日志文件数量。
PATRONI_LOG_FILE_SIZE：触发日志滚动的 patroni.log 文件大小（字节）。
PATRONI_LOG_LOGGERS：按 Python 模块重新定义日志级别。示例：PATRONI_LOG_LOGGERS="{patroni.postmaster: WARNING, urllib3: DEBUG}"。
PATRONI_LOG_DEDUPLICATE_HEARTBEAT_LOGS：设置为 true 时，连续且内容相同的心跳日志不再重复输出。默认值为 false。

警告

HA 循环的执行时间是诊断资源耗尽等问题所致故障转移的重要信息。将 PATRONI_LOG_DEDUPLICATE_HEARTBEAT_LOGS 设置为 true 后，HA 循环执行将不产生日志（除非领导者发生变化），导致这些潜在有用的信息无法从日志中获取。

HAProxy 是什么及其实现原理

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 用于指代产品，而 HAProxy 用于指代可执行程序、软件包或进程。然而，两者常被互换使用，且均发音为 H-A-Proxy。早期，“HAProxy”曾代表“高可用性代理”，名称以两个独立单词书写，但如今其含义已仅限于“HAProxy”。

命令行参考

Mon, 01 Jan 0001 00:00:00 +0000

本页保留固定上游源码生成的完整命令参考。为了能与 pgbadger --help 逐项核对，参数名、帮助文字和命令示例均保留英文原文。

用法与选项

Usage: pgbadger [options] logfile […]

pgbouncer 命令用法

Mon, 01 Jan 0001 00:00:00 +0000

语法

pgbouncer [-d][-R][-v][-u user] <pgbouncer.ini>
pgbouncer -V|-h

在 Windows 系统上，选项如下：

pgbouncer.exe [-v][-u user] <pgbouncer.ini>
pgbouncer.exe -V|-h

用于设置 Windows 服务的附加选项：

pgbouncer.exe --regservice <pgbouncer.ini>
pgbouncer.exe --unregservice <pgbouncer.ini>

描述

pgbouncer 是一个 PostgreSQL 连接池。任何目标应用程序都可以像连接 PostgreSQL 服务器一样连接到 pgbouncer，pgbouncer 会创建一个到实际服务器的连接，或者复用已有连接。

用户指南（RHEL/Rocky/CentOS）

Mon, 01 Jan 0001 00:00:00 +0000

简介

本用户指南设计为从头到尾顺序阅读——每个章节都依赖前一章节的内容。例如，恢复章节依赖 快速开始 章节中完成的配置。熟悉 pgBackRest 之后可以跳章查阅，但初次阅读建议按顺序跟随。

pgBadger 10.x 版本记录

Mon, 01 Jan 0001 00:00:00 +0000

本页按从新到旧的顺序保留 pgBadger 10.x 的完整上游变更记录。为确保版本、参数、提交者致谢和兼容性描述不被转述改变，正文保留英文原文。

v10.3 · 2019-02-14

This release of pgBadger is a maintenance release that fixes some log format autodetection issues another pgBouncer log parsing issue reported by users. There is also a new feature:

备份命令（backup）

Mon, 01 Jan 0001 00:00:00 +0000

配置多个仓库时，pgBackRest 默认备份到优先级最高的仓库（如 repo1），除非通过 --repo 选项明确指定目标仓库。

pgBackRest 本身不内置调度器，建议通过 cron 或其他调度机制触发备份。

Patroni REST API

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 提供了丰富的 REST API，供 Patroni 自身在主库竞选期间调用，也供 patronictl 工具执行故障转移、主从切换、重新初始化、重启和重载等操作，还可供 HAProxy 或其他负载均衡器执行 HTTP 健康检查，以及用于监控目的。以下是 Patroni REST API 端点的完整列表。

PostgreSQL 日志配置

Mon, 01 Jan 0001 00:00:00 +0000

pgBadger 只能报告 PostgreSQL 实际写入日志的信息。应先确定可解析的日志前缀与清晰的语句记录策略，再按需要加入检查点、锁、临时文件和自动清理等运行事件。

最小查询日志配置

若报告需要查询文本与执行耗时，请启用按时长记录语句：

PgBouncer 编译与安装

Mon, 01 Jan 0001 00:00:00 +0000

编译

PgBouncer 的编译依赖以下组件：

GNU Make 3.81+
Libevent 2.0+
pkg-config
OpenSSL 1.0.1+（TLS 支持）
（可选）c-ares ，作为 Libevent 内置 evdns 的替代方案
（可选）LDAP 库
（可选）PAM 库

安装依赖后，执行以下命令：

基本功能

Mon, 01 Jan 0001 00:00:00 +0000

本段将列举 HAProxy 实现的若干功能，其中部分功能是现代负载均衡器普遍具备的特性，另一些则是 HAProxy 架构带来的直接优势。更高级的功能将在下一节中详细说明。

pgBadger 9.x 版本记录

Mon, 01 Jan 0001 00:00:00 +0000

本页按从新到旧的顺序保留 pgBadger 9.x 的完整上游变更记录。为确保版本、参数、提交者致谢和兼容性描述不被转述改变，正文保留英文原文。

v9.2 · 2017-07-27

This release of pgBadger is a maintenance release that adds some new features.

检查命令（check）

Mon, 01 Jan 0001 00:00:00 +0000

check 命令用于验证 pgBackRest 及 archive_command 的配置是否正确，确保指定 stanza（stanza 是 pgBackRest 中用于标识 PostgreSQL 集群备份配置的逻辑名称）的归档与备份能够正常运作。该命令会对当前主机上为该 stanza 配置的所有仓库和数据库逐一检查，可检测出配置错误——尤其是归档配置问题，此类问题会导致所需的 WAL 段无法进入归档，从而造成备份不完整。此命令可在 PostgreSQL 主机或仓库主机上运行；也可在备库主机上运行，但由于备库无法执行 pg_switch_xlog()/pg_switch_wal()，命令仅会测试仓库配置。

patronictl 命令行

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 提供了 patronictl 命令行工具，用于与 Patroni 的 REST API 和 DCS 交互，旨在简化集群操作，适合人工操作或脚本调用。

配置

patronictl 使用以下 3 个配置节：

标准功能

Mon, 01 Jan 0001 00:00:00 +0000

在本段中，列举了一些在 HAProxy 中非常常见但未必存在于其他负载均衡器上的功能。

3.4.1. 标准功能：采样与信息转换

HAProxy 支持使用多种“样本提取函数”进行信息采样。其原理是提取称为样本的信息片段，以供即时使用。该机制用于实现会话粘性、构建条件判断、生成日志信息或丰富 HTTP 头。

并行处理

Mon, 01 Jan 0001 00:00:00 +0000

pgBadger 提供两种互补的多进程模式。选择时应关注输入日志的形态，而不只是 CPU 数量。

选项	并行单位	最适合	主要限制
`-j N` / `--jobs N`	一个日志文件的多个分块	单个可定位的大日志	分块边界可能重复或漏掉少量查询
`-J N` / `--Jobs N`	完整日志文件	大量相互独立的日志	只有文件数量足以填满工作进程时才有明显收益

使用 `-j` 拆分单个大文件

$ pgbadger -j 8 /var/log/postgresql/postgresql.log

上游算法把每个文件分成 N 个字节区间，为每个区间 fork 一个解析进程，把统计结果写入临时二进制文件，最后合并生成报告。

配置参考

Mon, 01 Jan 0001 00:00:00 +0000

简介

pgBackRest 可以完全通过命令行参数使用，但当配置较为复杂或需要设置大量选项时，使用配置文件更为实用。配置文件的默认路径为 /etc/pgbackrest/pgbackrest.conf。若该路径下不存在配置文件，则会检查旧的默认路径 /etc/pgbackrest.conf。

源码发布版下载

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer 1.25

File	Date	Size	SHA256
pgbouncer-1.25.2.tar.gz	2026-05-08	865371 bytes	sha256
pgbouncer-1.25.1.tar.gz	2025-12-03	864801 bytes	sha256
pgbouncer-1.25.0.tar.gz	2025-11-09	863322 bytes	sha256

PgBouncer 1.24

File	Date	Size	SHA256
pgbouncer-1.24.1.tar.gz	2025-04-16	717796 bytes	sha256
pgbouncer-1.24.0.tar.gz	2025-01-10	706573 bytes	sha256

PgBouncer 1.23

File	Date	Size	SHA256
pgbouncer-1.23.1.tar.gz	2024-08-02	700025 bytes	sha256
pgbouncer-1.23.0.tar.gz	2024-07-03	694845 bytes	sha256

PgBouncer 1.22

File	Date	Size	SHA256
pgbouncer-1.22.1.tar.gz	2024-03-04	677351 bytes	sha256
pgbouncer-1.22.0.tar.gz	2024-01-31	670589 bytes	sha256

PgBouncer 1.21

File	Date	Size	SHA256
pgbouncer-1.21.0.tar.gz	2023-10-16	668211 bytes	sha256

PgBouncer 1.20

File	Date	Size	SHA256
pgbouncer-1.20.1.tar.gz	2023-08-09	638844 bytes	sha256
pgbouncer-1.20.0.tar.gz	2023-07-20	638020 bytes	sha256

PgBouncer 1.19

File	Date	Size	SHA256
pgbouncer-1.19.1.tar.gz	2023-05-31	623569 bytes	sha256
pgbouncer-1.19.0.tar.gz	2023-05-04	616947 bytes	sha256

PgBouncer 1.18

File	Date	Size	SHA256
pgbouncer-1.18.0.tar.gz	2022-12-12	600825 bytes	sha256

PgBouncer 1.17

File	Date	Size	SHA256
pgbouncer-1.17.0.tar.gz	2022-03-23	598294 bytes	sha256

PgBouncer 1.16

File	Date	Size	SHA256
pgbouncer-1.16.1.tar.gz	2021-11-11	591450 bytes	sha256
pgbouncer-1.16.0.tar.gz	2021-08-09	592136 bytes	sha256

PgBouncer 1.15

File	Date	Size	SHA256
pgbouncer-1.15.0.tar.gz	2020-11-19	588042 bytes	sha256

PgBouncer 1.14

File	Date	Size	SHA256
pgbouncer-1.14.0.tar.gz	2020-06-11	578955 bytes	sha256

PgBouncer 1.13

File	Date	Size	SHA256
pgbouncer-1.13.0.tar.gz	2020-04-27	574955 bytes	sha256

PgBouncer 1.12

File	Date	Size	SHA256
pgbouncer-1.12.0.tar.gz	2019-10-17	567465 bytes	sha256

PgBouncer 1.11

File	Date	Size	SHA256
pgbouncer-1.11.0.tar.gz	2019-08-27	571414 bytes	sha256

PgBouncer 1.10

File	Date	Size	SHA256
pgbouncer-1.10.0.tar.gz	2019-07-01	480571 bytes	sha256

PgBouncer 1.9

File	Date	Size	SHA256
pgbouncer-1.9.0.tar.gz	2018-08-13	469300 bytes	sha256

PgBouncer 1.8

File	Date	Size	SHA256
pgbouncer-1.8.1.tar.gz	2017-12-20	465930 bytes	sha256
pgbouncer-1.8.tar.gz	2017-12-19	465612 bytes	sha256

PgBouncer 1.7

File	Date	Size	SHA256
pgbouncer-1.7.2.tar.gz	2016-02-26	462374 bytes	sha256
pgbouncer-1.7.1.tar.gz	2016-02-18	461903 bytes	sha256
pgbouncer-1.7.tar.gz	2015-12-18	459080 bytes	sha256

PgBouncer 1.6

File	Date	Size	SHA256
pgbouncer-1.6.1.tar.gz	2015-09-03	431076 bytes	sha256
pgbouncer-1.6.tar.gz	2015-08-01	412700 bytes	sha256

PgBouncer 1.5

File	Date	Size	SHA256
pgbouncer-1.5.5.tar.gz	2015-04-09	336145 bytes	sha256
pgbouncer-1.5.4.tar.gz	2012-11-28	339610 bytes	sha256
pgbouncer-1.5.3.tar.gz	2012-09-12	339013 bytes	sha256
pgbouncer-1.5.2.tar.gz	2012-05-29	335338 bytes	sha256
pgbouncer-1.5.1.tar.gz	2012-04-17	334413 bytes	sha256
pgbouncer-1.5.tar.gz	2012-01-05	411488 bytes	sha256

PgBouncer 1.4

File	Date	Size	SHA256
pgbouncer-1.4.2.tgz	2011-06-16	283204 bytes	sha256
pgbouncer-1.4.1.tgz	2011-04-01	282728 bytes	sha256
pgbouncer-1.4.tgz	2011-01-11	231691 bytes	sha256

PgBouncer 1.3

File	Date	Size	SHA256
pgbouncer-1.3.4.tgz	2010-09-09	167957 bytes	sha256
pgbouncer-1.3.3.tgz	2010-05-10	167476 bytes	sha256
pgbouncer-1.3.2.tgz	2010-03-15	166756 bytes	sha256
pgbouncer-1.3.1.tgz	2009-07-06	161518 bytes	sha256
pgbouncer-1.3.tgz	2009-02-18	160154 bytes	sha256

PgBouncer 1.2

File	Date	Size	SHA256
pgbouncer-1.2.3.tgz	2008-08-08	145372 bytes	sha256
pgbouncer-1.2.2.tgz	2008-08-06	145017 bytes	sha256
pgbouncer-1.2.1.tgz	2008-08-04	144903 bytes	sha256
pgbouncer-1.2.tgz	2008-07-29	143915 bytes	sha256

PgBouncer 1.1

File	Date	Size	SHA256
pgbouncer-1.1.2.tgz	2007-12-10	122054 bytes	sha256
pgbouncer-1.1.1.tgz	2007-10-26	121042 bytes	sha256
pgbouncer-1.1.tgz	2007-10-09	120462 bytes	sha256

PgBouncer 1.0

File	Date	Size	SHA256
pgbouncer-1.0.8.tgz	2007-06-18	93636 bytes	sha256
pgbouncer-1.0.7.tgz	2007-04-19	93086 bytes	sha256
pgbouncer-1.0.6.tgz	2007-04-12	92244 bytes	sha256
pgbouncer-1.0.5.tgz	2007-04-11	91934 bytes	sha256
pgbouncer-1.0.4.tgz	2007-04-11	91889 bytes	sha256
pgbouncer-1.0.3.tgz	2007-04-11	91489 bytes	sha256
pgbouncer-1.0.2.tgz	2007-03-28	90555 bytes	sha256
pgbouncer-1.0.1.tgz	2007-03-15	89609 bytes	sha256
pgbouncer-1.0.tgz	2007-03-13	88587 bytes	sha256

二进制软件包

许多操作系统发行版提供了 PgBouncer 的原生软件包/移植版本，建议首先检查您的系统中是否已有可用的版本。

过期命令（expire）

Mon, 01 Jan 0001 00:00:00 +0000

pgBackRest 基于保留策略对全量备份进行轮换，策略可按数量或时间段定义。按数量保留时，过期操作只关注需要保留的备份数量，不考虑备份的创建时间。差异备份按数量进行保留，但当其依赖的全量备份过期时，差异备份也会随之过期。增量备份没有独立的保留策略——它们始终随关联的全量备份或差异备份一同过期。详情及示例请参见 全量备份保留策略 和 差异备份保留策略 章节。

版本发布说明

Mon, 01 Jan 0001 00:00:00 +0000

简介

pgBackRest 的版本号由主版本号和次版本号两部分组成。主版本升级可能破坏与上一主版本的兼容性，但 v2 版本与 v1 仓库完全兼容，且接受所有 v1 选项。次版本可包含漏洞修复和新功能，但不会更改仓库格式，并尽量避免修改选项和命名约定。v1 版本的文档可在此处查阅。版本说明中还可能包含"附加说明"，此部分变更仅涉及文档或测试套件，不直接影响 pgBackRest 代码库。

高级功能

Mon, 01 Jan 0001 00:00:00 +0000

3.5.1. 高级功能：系统管理

HAProxy 旨在在常规生产环境中保持极高的稳定性与安全性。它以单个可执行文件的形式提供，无需任何安装过程。多个版本可轻松共存，因此建议按重要性顺序逐步升级实例，而非一次性全部迁移。配置文件易于版本化。配置检查可在离线状态下完成，无需重启可能失败的服务。在配置检查过程中，可检测到多种高级错误（例如规则相互隐藏，或无法生效的会话粘性），并提供详细的警告信息与配置建议以修复问题。配置文件的向后兼容性极为持久，版本 1.5 仍完全支持 13 年前为版本 1.1 编写的配置，而 1.6 仅移除了几乎不再使用、已过时的关键词，这些功能可通过其他方式实现。配置与软件升级机制平滑且无中断，允许旧版与新版进程在系统中共存，各自处理自身的连接。启动时会报告系统状态、构建选项及库兼容性信息。

从库镜像与引导

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 支持自定义新从库的创建方式，也支持定义全新空集群在引导时的行为。两者有明确区别：只有当 DCS 中存在 initialize 键时，Patroni 才会创建从库。若不存在该键，Patroni 将在第一个抢到初始化锁的节点上独占执行引导流程。

增量报告

Mon, 01 Jan 0001 00:00:00 +0000

增量模式先以二进制形式保存解析统计，再生成每日 HTML 报告、每周累计报告，以及把它们组织起来的日历式索引。它适合反复处理轮转日志，同时避免重复统计相同记录。

帮助命令（help）

Mon, 01 Jan 0001 00:00:00 +0000

help 命令提供三个层级的帮助信息：未指定命令时显示通用帮助；指定命令（例如 pgbackrest help backup）时显示该命令的完整说明及有效选项列表；在命令之外还指定了某个选项（例如 pgbackrest help backup type）时显示该选项在此命令下的完整说明。

版本变更日志

Mon, 01 Jan 0001 00:00:00 +0000

PgBouncer 1.25.x

2026-05-08 - PgBouncer 1.25.2 - “Human touch with fresh twist in title race full of uncertainties（充满不确定性的冠军争夺战中，人情味带来新意）”

常见问题解答

Mon, 01 Jan 0001 00:00:00 +0000

简介

常见问题解答旨在针对一些具体问题提供详细说明，这些问题可能未在用户指南、配置参考或命令参考中涵盖。如果在此处找不到您的问题，pgBackRest 在 GitHub 上的 Issues List 也是一个宝贵的资源。

复制模式

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 使用 PostgreSQL 流复制。关于流复制的更多信息，请参阅 Postgres 文档。默认情况下，Patroni 将 PostgreSQL 配置为异步复制。选择哪种复制方案取决于你的业务需求。建议同时研究异步和同步复制，以及其他高可用方案，以确定最适合自己的解决方案。

性能与容量规划

Mon, 01 Jan 0001 00:00:00 +0000

典型 CPU 使用率数据显示，在 TCP 或 HTTP 关闭模式下，HAProxy 占用约 15% 的处理时间，内核占用约 85%；在 HTTP 持久连接模式下，HAProxy 占用约 30%，内核占用约 70%。这表明操作系统及其调优对整体性能有显著影响。

输出格式

Mon, 01 Jan 0001 00:00:00 +0000

pgBadger 会根据输出文件扩展名，或 -x / --extension 选项选择格式。同一次解析可多次使用 -o / --outfile，同时生成多种格式。

格式	常用扩展名	最适合
HTML	`.html`	带图表的交互式人类可读报告
文本	`.txt`	终端查看与纯文本归档
二进制	`.bin`	可合并的中间统计数据与报告重建
JSON	`.json`	与其他软件集成；需要 `JSON::XS`
原始 CSV	自选输出文件	使用 `--dump-raw-csv` 导出逐行数据

HTML 与文本

默认输出为 out.html：

Info 命令（info）

Mon, 01 Jan 0001 00:00:00 +0000

info 命令可查询单个 stanza（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）或所有 stanza 的信息。默认输出为文本格式，以人类可读的摘要展示所请求 stanza 的备份信息。该格式可能随版本更新而变化。

报告示例

Mon, 01 Jan 0001 00:00:00 +0000

示例内容由 pgBadger 11.8 于 2022 年 5 月生成。原始示例已与本站一起保存，因此即使无法访问上游服务器，也能继续使用报告导航、图表、样式与脚本。

示例	展示内容	本地副本
完整报告	PostgreSQL 活动与 PgBouncer 统计	打开完整报告
增量报告	日历索引、每周累计与每日页面	打开增量索引
错误与事件	仅包含错误和运行事件的报告	打开错误报告

完整报告

完整报告是一份自包含 HTML 文档。可通过顶部导航查看全局统计、查询、会话、连接、临时文件、检查点、自动清理、锁，以及 PgBouncer 专用图表。

备用集群

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 还支持通过"备用集群"功能向远程数据中心（Region）运行级联复制。这类集群具有以下特点：

备用领导者（standby leader）：行为与普通集群领导者基本相同，区别在于它从远程节点进行复制。
级联从库：从备用领导者进行复制。

备用领导者在 DCS 中持有并更新领导者锁。若领导者锁过期，级联从库将通过选举从备用节点中选出新的领导者。

发布、软件包与升级

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 是一个采用 GPLv2 许可证的开源项目，这意味着只要在请求时提供源代码，任何人都可以自由分发该软件，尤其是当进行了任何修改时。

HAProxy 以名为“master”或“mainline”的主开发分支持续演进，当代码被认为稳定后，便会从该分支衍生出新的分支。许多网站自愿在生产环境中运行开发分支，或为参与项目，或因需要前沿功能，其反馈对修复缺陷、评估所开发版本的整体质量与稳定性具有极高价值。

社区

Mon, 01 Jan 0001 00:00:00 +0000

教程

为 Postgres Plus Standard Server 配置 PgBouncer

对 PgBouncer 概念的精彩概述。
连接池究竟有什么意义？

讨论各种池化模式之间的差异。

支持

项目主页 （GitHub）

项目指标

Mon, 01 Jan 0001 00:00:00 +0000

代码覆盖率

pgBackRest 致力于对 /src 目录下的核心 C 代码实现完整的函数、分支和行覆盖。

函数覆盖率和行覆盖率均已达到 100%，无任何例外。

常见问题解答

Mon, 01 Jan 0001 00:00:00 +0000

如何连接到 PgBouncer？

PgBouncer 扮演 PostgreSQL 服务器的角色，只需将客户端指向 PgBouncer 端口即可。

如何在多个服务器之间实现查询负载均衡？

PgBouncer 没有内置的多主机配置功能，但可以通过外部工具实现：

仓库获取命令（repo-get）

Mon, 01 Jan 0001 00:00:00 +0000

repo-get 命令类似于 Unix 的 cat 命令，但支持所有仓库类型。使用此命令需要提供完整的文件名，主要用于管理、排查和测试目的，不是常规 pgBackRest 使用流程中的必需命令。

若仓库已加密，repo-get 将自动解密文件。文件不会自动解压，但可将输出通过管道传递给相应的解压命令，例如 gzip -d。

Watchdog 支持

Mon, 01 Jan 0001 00:00:00 +0000

同时存在多个以主库身份运行的 PostgreSQL 实例，可能因时间线分叉而导致事务丢失，这种情况也称为脑裂（split-brain）问题。为了避免脑裂，Patroni 需要确保在 DCS 中的领导者键过期后，PostgreSQL 不再接受任何事务提交。正常情况下，Patroni 会在领导者锁更新失败时尝试停止 PostgreSQL 来实现这一目标。然而，以下各种原因可能导致该机制失效：

仓库列表命令（repo-ls）

Mon, 01 Jan 0001 00:00:00 +0000

repo-ls 类似于 Unix 的 ls 命令，但支持所有 pgBackRest 仓库类型。该命令接受一个路径参数，可以是绝对路径，也可以是相对于 --repo-path 所定义的仓库根路径的相对路径。此命令主要用于管理、排查和测试场景，并非常规部署的必要命令。

如何搭建演示集群

Mon, 01 Jan 0001 00:00:00 +0000

在每个 etcd 节点上，指定集群成员：

TOKEN=token-01
CLUSTER_STATE=new
NAME_1=machine-1
NAME_2=machine-2
NAME_3=machine-3
HOST_1=10.240.0.17
HOST_2=10.240.0.18
HOST_3=10.240.0.19
CLUSTER=${NAME_1}=http://${HOST_1}:2380,${NAME_2}=http://${HOST_2}:2380,${NAME_3}=http://${HOST_3}:2380

在每台机器上运行以下命令：

# For machine 1
THIS_NAME=${NAME_1}
THIS_IP=${HOST_1}
etcd --data-dir=data.etcd --name ${THIS_NAME} \
	--initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
	--advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
	--initial-cluster ${CLUSTER} \
	--initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}

# For machine 2
THIS_NAME=${NAME_2}
THIS_IP=${HOST_2}
etcd --data-dir=data.etcd --name ${THIS_NAME} \
	--initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
	--advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
	--initial-cluster ${CLUSTER} \
	--initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}

# For machine 3
THIS_NAME=${NAME_3}
THIS_IP=${HOST_3}
etcd --data-dir=data.etcd --name ${THIS_NAME} \
	--initial-advertise-peer-urls http://${THIS_IP}:2380 --listen-peer-urls http://${THIS_IP}:2380 \
	--advertise-client-urls http://${THIS_IP}:2379 --listen-client-urls http://${THIS_IP}:2379 \
	--initial-cluster ${CLUSTER} \
	--initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}

或使用我们的公开发现服务：

集群的暂停/恢复模式

Mon, 01 Jan 0001 00:00:00 +0000

目标

在某些特殊情况下，Patroni 需要临时退出对集群的管理，同时仍在 DCS 中保留集群状态。典型使用场景包括对集群执行一些不常见的操作，例如大版本升级或数据损坏恢复。在此类操作期间，节点往往会因 Patroni 未知的原因频繁启停，某些节点甚至可能被临时提升为主库，从而打破"同一时间只能有一个主库"的假设。为此，Patroni 需要具备从运行中的集群"脱离"的能力，实现类似 Pacemaker 维护模式的效果。

支持与贡献

Mon, 01 Jan 0001 00:00:00 +0000

pgBadger 是一个开放维护的项目。缺陷报告、功能建议、文档修复与代码补丁都通过上游 GitHub 仓库处理。

缺陷与功能需求

升级到最新正式版本，确认问题仍然存在。
搜索开放问题与已关闭问题，查看是否已有答案。
把问题缩减为仍能复现的最小安全日志样本与命令行。
删除凭据、敏感 SQL、绑定值、主机名、地址与业务数据。
创建新问题，写明 pgBadger 版本、操作系统、输入格式、完整选项、实际结果与预期结果。

对于崩溃或解析错误，只应附上复现边界所需的最少脱敏日志。完整生产日志或生成报告通常不适合放在公开问题中。

文档与社区

Mon, 01 Jan 0001 00:00:00 +0000

1. 可用文档

HAProxy 的完整文档由以下文件组成。请先查阅与问题相关的文档，以节省时间并获得最准确的答案。如果这些文档已经给出答案，请勿再向邮件列表重复提问。

DCS 故障安全模式

Mon, 01 Jan 0001 00:00:00 +0000

问题背景

Patroni 高度依赖分布式配置存储（DCS）来完成领导者选举和检测网络分区。具体而言，节点只有在能够成功更新 DCS 中的领导者锁时，才被允许以主库身份运行 PostgreSQL。一旦领导者锁更新失败，PostgreSQL 将立即被降级并以只读模式启动。触发该"问题"的概率因所使用的 DCS 而异——例如，当 Etcd 专用于 Patroni 时，发生概率接近于零；而当使用以 Etcd 为后端的 Kubernetes API 时，则可能更为频繁。

恢复命令（restore）

Mon, 01 Jan 0001 00:00:00 +0000

restore 命令默认从第一个存有备份的仓库中自动选取最新备份（参见 快速开始 - 恢复备份 ）。仓库的检查顺序由 pgbackrest.conf 决定（例如先检查 repo1，再检查 repo2）。若要从特定仓库恢复，可使用 --repo 选项（例如 --repo=1）。若需恢复非最新的备份，可传入 --set 选项。

配置手册

Mon, 01 Jan 0001 00:00:00 +0000

许可证与致谢

Mon, 01 Jan 0001 00:00:00 +0000

pgBadger 是以 PostgreSQL License 发布的自由开源软件。只要保留版权与许可证声明，就可以免费使用、复制、修改与分发。

PostgreSQL License 原文

1. 快速 HTTP 提示

Mon, 01 Jan 0001 00:00:00 +0000

本文涵盖上述指定版本中实现的配置语言。本文不提供任何提示、示例或建议。如需此类文档，请参阅参考手册或架构手册。编号章节在 HAProxy 扁平侧边栏中按顺序排列，支持直接导航。

服务器命令（server）

Mon, 01 Jan 0001 00:00:00 +0000

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

命令选项

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

TLS 服务器地址。

在 Kubernetes 中使用 Patroni

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 可以利用 Kubernetes 对象来存储集群状态并管理领导者键，从而无需任何额外的一致性存储即可在 Kubernetes 环境中运行 PostgreSQL——也就是说，不需要单独部署 Etcd。Patroni 支持两种不同类型的 Kubernetes 对象来存储领导者键和配置键，通过 kubernetes.use_endpoints 配置项或 PATRONI_KUBERNETES_USE_ENDPOINTS 环境变量进行选择。

2. 配置 HAProxy

Mon, 01 Jan 0001 00:00:00 +0000

2.1. 配置文件格式

HAProxy 的配置过程涉及三个主要参数来源：

命令行参数，始终具有最高优先级
配置文件，其格式在此处描述
运行进程的环境，若显式引用了某些环境变量

配置文件采用一种相对简单的分层格式，遵循若干基本规则：

Citus 支持

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 使部署多节点 Citus 集群变得极为简单。

TL;DR

只需遵循以下几条简单规则：

所有节点上必须安装 Citus 数据库扩展。最低支持的 Citus 版本为 10.0，但为了充分利用工作节点透明主从切换和重启的特性，建议使用至少 Citus 11.2。
集群名称（scope）在所有 Citus 节点上必须相同！
超级用户凭据在协调节点和所有工作节点上必须相同，且 pg_hba.conf 应允许所有节点之间的超级用户访问。
工作节点到协调节点的 REST API 访问必须被允许。例如，凭据应相同，如果配置了客户端证书，工作节点的客户端证书必须被协调节点接受。
在 patroni.yaml 中添加以下配置节：

citus:
 group: X  # 0 表示协调节点，工作节点使用 1、2、3 等
 database: citus  # 所有节点上必须相同

之后只需启动 Patroni，它会处理其余的一切：

服务器心跳命令（server-ping）

Mon, 01 Jan 0001 00:00:00 +0000

向 pgBackRest TLS 服务器发送 ping，确认其正在接受连接。此命令仅作为存活性检查，不进行身份验证。

若命令行中未指定主机，则使用 tls-server-host 选项的值。

命令选项

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

TLS 服务器地址。

3. 全局段

Mon, 01 Jan 0001 00:00:00 +0000

“global” 段中的参数为进程级配置，通常与操作系统相关。这些参数通常只需一次性设置，一旦配置正确便无需再修改。部分参数在命令行中也有对应选项。

Stanza 创建命令（stanza-create）

Mon, 01 Jan 0001 00:00:00 +0000

stanza-create 命令须在 pgbackrest.conf 中完成 stanza 配置后再执行（stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称）。若配置了多个仓库，stanza-create 会在每个仓库上分别建立 stanza。已创建的 stanza 会被跳过，因此即便新增了仓库，也可以随时安全地重复执行 stanza-create。

将独立实例转换为 Patroni 集群

Mon, 01 Jan 0001 00:00:00 +0000

本节介绍将独立 PostgreSQL 实例转换为 Patroni 集群的操作流程。

如需从零开始部署 Patroni 集群（不使用已有 PostgreSQL 实例），请参阅 运行与配置 。

操作步骤

以下是将现有 PostgreSQL 集群转换为 Patroni 托管集群的步骤概览。本步骤假设现有集群的所有节点当前均在运行，并且您 不打算 在迁移过程中修改 PostgreSQL 配置。具体步骤如下：

4. 代理

Mon, 01 Jan 0001 00:00:00 +0000

代理配置可位于一组段中：

defaults [<name>] [ from <defaults_name> ]
frontend <name> [ from <defaults_name> ]
backend <name> [ from <defaults_name> ]
listen <name> [ from <defaults_name> ]

前端段描述了一组用于接收客户端连接的监听套接字。

后端段描述了一组代理将连接以转发传入连接的服务器。

Stanza 删除命令（stanza-delete）

Mon, 01 Jan 0001 00:00:00 +0000

stanza-delete 命令用于删除仓库中与指定 stanza 关联的所有数据。stanza 是 pgBackRest 中用于标识一个 PostgreSQL 集群备份配置的逻辑名称。

警告：

此命令会永久删除指定 stanza 在 pgBackRest 仓库中的所有备份和归档数据，请谨慎使用。

与其他工具的集成

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 能够与技术栈中的其他工具集成。本节列举了一些集成示例，并不详尽，但希望能为您提供参考和启发。

Barman

Patroni 提供了一个名为 patroni_barman 的应用程序，内含与 pg-backup-api 通信的逻辑，可用于远程执行 Barman 操作。

5. 绑定与服务器选项

Mon, 01 Jan 0001 00:00:00 +0000

“bind”、“server” 和 “default-server” 关键字支持多种设置，具体取决于构建选项以及 HAProxy 所基于的系统。这些设置通常由一个单词组成，有时后接一个值，与 “bind” 或 “server” 语句位于同一行。所有这些选项均在本节中描述。

Stanza 升级命令（stanza-upgrade）

Mon, 01 Jan 0001 00:00:00 +0000

将 PostgreSQL 升级到新的主版本后，必须立即将所有 pgBackRest 配置中的 pg-path 更新为新的数据库位置，然后运行 stanza-upgrade 命令。若主机上配置了多个仓库，每个仓库都会执行 stanza 升级。若数据库处于离线状态，请使用 --no-online 选项。

安全注意事项

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 集群有两个需要防范未授权访问的接口：分布式配置存储（DCS）和 Patroni REST API。

保护 DCS

Patroni 和 patronictl 都会向 DCS 读写数据。

尽管 DCS 本身不包含任何敏感信息，但它允许修改部分 Patroni/PostgreSQL 配置，因此首要保护对象就是 DCS 本身。

6. 缓存

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 提供一个缓存，专为小型对象（如 favicon、CSS 等）的缓存而设计。这是一个极简且低维护成本的缓存，运行于内存中。

缓存基于所有线程共享的内存区域，并划分为 1kB 的块。

启动命令（start）

Mon, 01 Jan 0001 00:00:00 +0000

如果 pgBackRest 进程之前已通过 stop 命令停止，可使用 start 命令重新允许它们运行。注意，此命令不会立即启动任何 pgBackRest 进程，只是解除运行限制。详情与示例请参见 启动与停止 。

通用选项

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

允许命令以 root 用户运行。

多数据中心高可用

Mon, 01 Jan 0001 00:00:00 +0000

部署在多个数据中心的 PostgreSQL 集群，其高可用基于复制实现，复制可以是同步的，也可以是异步的（参见 复制模式 ）。

无论哪种模式，都需要明确以下概念：

PostgreSQL 仅在持有领导者键且能够更新领导者键时，才能以主库或备用领导者身份运行。
etcd、ZooKeeper 或 Consul 节点的数量应为奇数：3 个或 5 个！

同步复制

要构建能够自动容忍单区域故障的多数据中心集群，至少需要 3 个数据中心。

7. ACL 与样本提取

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 可从请求或响应流、客户端或服务器信息、表格、环境信息等来源提取数据。提取此类数据的动作称为获取样本。获取后，这些样本可用于多种用途，例如作为粘性表的键，但最常见的用法是将其与称为模式的预定义常量数据进行匹配。

停止命令（stop）

Mon, 01 Jan 0001 00:00:00 +0000

禁止任何新的 pgBackRest 进程运行。默认情况下，正在运行的进程将被允许正常完成。使用 --force 选项可强制终止正在运行的进程。

stop 命令执行完成后，此后尝试运行的 pgBackRest 进程将返回错误。详情与示例请参见 启动与停止 。

常见问题

Mon, 01 Jan 0001 00:00:00 +0000

本节收录了关于 Patroni 最常见问题的解答，各子节聚焦于不同类别的问题。

希望这些内容能帮你解答大多数疑问。如果仍有疑问或遇到意外问题，请参阅 chatting 和 reporting_bugs ，了解如何获取帮助或提交问题报告。

8. 日志记录

Mon, 01 Jan 0001 00:00:00 +0000

本文的强项之一无疑是其精确的日志记录。它可能为这类产品提供了最详尽的信息级别，这对排查复杂环境中的问题至关重要。日志中提供的标准信息包括客户端端口、TCP/HTTP 状态定时器、流在终止时的精确状态以及精确的终止原因，关于将流量导向服务器的决策信息，当然还包括捕获任意头字段的能力。

验证命令（verify）

Mon, 01 Jan 0001 00:00:00 +0000

verify 用于验证仓库中的备份和归档是否有效。

命令选项

输出格式选项（`--output`）

输出类型。

支持以下输出类型：

版本历史

Mon, 01 Jan 0001 00:00:00 +0000

Version 4.1.5

发布于 2026-08-12

兼容性改进

兼容 PostgreSQL 14.24、15.19、16.15、17.11 与 18.6（Alexander Kukushkin）

9. 支持的过滤器

Mon, 01 Jan 0001 00:00:00 +0000

以下是官方支持的过滤器及其所接受的参数列表。根据编译选项的不同，部分过滤器可能不可用。可用过滤器的列表将在 HAProxy -vv. 中报告。

另请参见：“过滤器”

版本命令（version）

Mon, 01 Jan 0001 00:00:00 +0000

显示已安装的 pgBackRest 版本。

命令选项

输出格式选项（`--output`）

输出类型。

支持以下输出类型：

text — 以文本形式显示已安装的 pgBackRest 版本。
num — 以整数形式显示已安装的 pgBackRest 版本。

default: text
example: --output=num

从 etcd 中读取

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

安装 etcdctl

步骤

使用 get 子命令从 etcd 读取：

$ etcdctl --endpoints=$ENDPOINTS get foo
foo
Hello World!
$

其中：

贡献指南

Mon, 01 Jan 0001 00:00:00 +0000

在线交流

如有疑问、需要互动式故障排查帮助，或希望与其他 Patroni 用户交流，欢迎加入 PostgreSQL Slack 的 #patroni 频道。

报告缺陷

提交缺陷报告前，请务必 在最新版 Patroni 上复现该问题！同时请检查 Issues Tracker 中是否已存在相同问题。

10. FastCGI 应用程序

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 可以向 Responder FastCGI 应用发送 HTTP 请求。此功能自 HAProxy 2.1 版本起引入。为此，必须将服务器配置为使用 FastCGI 协议（在服务器行中使用关键字 “proto fcgi”），且后端管理这些服务器时，必须配置并使用一个 FastCGI 应用（在代理段中使用关键字 “use-fcgi-app”）。可以定义多个 FastCGI 应用，但每个后端在同一时间只能使用其中一个。

11. 粘性表与对等节点

Mon, 01 Jan 0001 00:00:00 +0000

在 HAProxy 中，stick-table 是一种机制，允许将一定数量的信息和指标与特定类型的键关联，并在最后一次更新后持续一定时间。这可视为表格中的一行多列数据，其中行号由键值决定，各列代表不同的衡量标准。

12. 其他配置段

Mon, 01 Jan 0001 00:00:00 +0000

以下所述段落使用频率较低，通常仅支持少量参数。它们之间不存在隐式关联。所有段均通过单一关键字启动。在 “global” 段之前禁止出现任何此类段。部分段的支持可能受构建选项限制（例如与 SSL 相关的任何功能）。

管理指南

Mon, 01 Jan 0001 00:00:00 +0000

1. 先决条件

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍如何启动、停止、管理 HAProxy 及排查其故障，也会说明一些已知限制和应避免的陷阱。本文不涉及 HAProxy 的配置方法；相关内容请参阅 configuration.txt 。

本文假定读者具备类 Unix 操作系统的管理能力，日常使用 shell，并熟悉 strace、tcpdump 等故障排查工具。

向 etcd 写入

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

安装 etcdctl

步骤

使用 put 子命令写入键值对：

etcdctl --endpoints=$ENDPOINTS put foo "Hello World!"

其中：

foo 为键名称
"Hello World!" 为用引号括起的值

2. HAProxy 架构

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 是一个多线程、事件驱动、非阻塞的守护进程。它使用事件多路复用机制调度所有活动，而不依赖系统在多项活动之间切换调度。大多数情况下，HAProxy 只运行一个进程，因此在系统上执行 “ps aux” 时通常只会看到一个 “haproxy” 进程；平滑重载期间是例外，此时旧进程会与新进程并行完成剩余工作。因此，使用 strace 始终可以轻松跟踪其活动。为利用多个处理器，HAProxy 默认会为每个允许使用的处理器启动一个工作线程。除非另有明确配置，传入流量会均匀分配给所有线程，每个线程运行相同的事件循环。HAProxy 将线程间依赖严格控制在最低水平，以实现近乎线性的扩展能力。这也意味着每条连接只由一个线程处理。因此，要充分利用全部处理能力，连接数至少应与线程数相当；实际环境几乎总能满足这一条件。

3. 启动 HAProxy

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 通过在命令行中传入若干参数来调用 “haproxy” 程序启动。实际语法如下：

$ haproxy [<options>]*

其中 [<options>]* 为任意数量的选项。每个选项均以 ‘-’ 开头，后接一个或多个字母，可选地跟随一个或多个额外参数。若未指定任何选项，HAProxy 将显示帮助页面，并提示支持的选项。可用选项可能因操作系统略有差异。其中相当一部分选项与 “global” 段中的等效选项重叠。在此情况下，命令行选项始终优先于配置文件，以便可通过命令行快速强制设置，而无需修改配置文件。当前选项列表如下：

4. 停止与重启 HAProxy

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 支持优雅停止和强制停止。强制停止操作简单：当向 HAProxy 进程发送 SIGTERM 信号时，进程立即退出，所有已建立的连接将被关闭。优雅停止通过向 HAProxy 进程发送 SIGUSR1 信号触发，其操作仅包括解除对监听端口的绑定，但会继续处理现有连接，直至所有连接关闭。当最后一个连接关闭后，进程退出。

5. 文件描述符限制

Mon, 01 Jan 0001 00:00:00 +0000

为确保所有传入连接均能成功处理，HAProxy 在加载时会计算进程生命周期内所需的文件描述符总数。常规 Unix 进程默认被授予 1024 个文件描述符，特权进程可自行提升该限制。这是以 root 身份启动 HAProxy 并由其自行调整限制的原因之一。默认的 1024 个文件描述符大致可支持约 500 个并发连接的处理。该计算基于全局 maxconn 参数，该参数限制每个进程的总连接数，同时考虑监听器数量、启用健康检查的服务器数量、代理检查、对等节点、日志记录器以及可能的其他技术需求。对该数值的粗略估算方法为：将 maxconn 值翻倍，并额外增加数十个，即可得到所需的文件描述符近似数量。

6. 内存管理

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 采用简单、快速的池式内存管理。由于 HAProxy 只使用少量不同的对象类型，从已经包含适当大小对象的内存池中获取新对象，远比针对每种大小分别调用 malloc() 高效。内存池按栈或 LIFO 方式组织，新分配的对象会优先取自刚刚释放、仍在 CPU 缓存中的对象。大小相近的内存池会合并，以减少内存碎片。

如何根据前缀获取键

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

按前缀获取键

$ etcdctl --endpoints=$ENDPOINTS get PREFIX --prefix

全局选项

--endpoints=[127.0.0.1:2379], gRPC endpoints

选项

--prefix, get a range of keys with matching prefix

示例

etcdctl --endpoints=$ENDPOINTS put web1 value1
etcdctl --endpoints=$ENDPOINTS put web2 value2
etcdctl --endpoints=$ENDPOINTS put web3 value3

etcdctl --endpoints=$ENDPOINTS get web --prefix

7. CPU 使用率

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 通常大部分时间运行在系统空间，仅小部分时间运行在用户空间。经过精细调优的 3.5 GHz CPU 在单核满载 100% 时，每秒可维持约 80000 次端到端连接的建立与关闭。当单核达到饱和时，典型数值为：

8. 日志记录

Mon, 01 Jan 0001 00:00:00 +0000

对于日志记录，HAProxy 始终依赖 syslog 服务器，因为它不执行任何文件系统访问。标准用法是通过 UDP 将日志发送至日志服务器（默认端口为 514）。通常情况下，该配置会指向 127.0.0.1，即本地 syslog 守护进程运行的位置，但也常通过网络将日志发送至集中式服务器。在主动-主动场景中，集中式服务器尤其具有优势，可确保日志按到达顺序合并。HAProxy 也可使用 Unix 套接字将日志发送至本地 syslog 守护进程，但强烈不建议使用，因为当 syslog 服务器重启而 haproxy 仍在运行时，套接字将被替换，新日志将丢失。由于 HAProxy 将被隔离在 chroot 环境中，它将无法重新连接至新的套接字。现场观察表明，Unix 套接字使用的日志缓冲区非常小，即使在极轻负载下也可能导致消息丢失。不过，这在测试环境中可以接受。

9. 统计信息与监控

Mon, 01 Jan 0001 00:00:00 +0000

可以查询 HAProxy 的运行状态。最常用的机制是 HTTP 统计信息页面。该页面还提供了一种用于监控工具的替代 CSV 输出格式。相同的格式也通过 Unix 套接字提供。

10. 简化配置管理

Mon, 01 Jan 0001 00:00:00 +0000

组成集群的两个 HAProxy 节点通常使用完全相同的配置，只有少数地址不同。与其为每个节点分别维护一份最终必然产生差异的重复配置，不如在配置中引用环境变量。这样，多个配置实例便可共用同一个文件，只需在系统级环境变量中保留少量差异。此功能始于 1.5 版，当时只有地址可以包含环境变量；1.6 版进一步支持在所有位置使用环境变量。其语法与 UNIX shell 相同：变量以美元符号（’$’）开头，后接左花括号（’{’）、变量名和右花括号（’}’）。除地址外，环境变量只在双引号包围的参数中解析；这是为了避免破坏使用含美元符号正则表达式的现有配置。

11. 应避免的常见陷阱

Mon, 01 Jan 0001 00:00:00 +0000

有时会有人报告：系统重启后 HAProxy 服务没有启动，但手动启动又能正常工作。这通常出现在使用 keepalived 等集群 IP 地址机制、只把服务 IP 分配给主节点的环境中。HAProxy 绑定 0.0.0.0 时一切正常，改为绑定虚拟 IP 后却无法启动。原因是服务启动时，本地节点尚未持有该虚拟 IP；HAProxy 尝试绑定时，系统会因其不是本地 IP 地址而拒绝操作。正确的解决办法不是推迟 HAProxy 服务启动——这无法应对服务重启——而是把系统配置为允许绑定非本地地址。在 Linux 上，将 net.ipv4.ip_nonlocal_bind sysctl 设为 1 即可。如果需要透明截获经 HAProxy 转发到特定目标地址的 IP 流量，也必须启用此设置。

12. 调试与性能问题

Mon, 01 Jan 0001 00:00:00 +0000

当 HAProxy 以 “-d” 选项启动时，它将以前台模式运行，并为每个事件打印一行输出，例如接收到的连接、连接结束，以及每个请求或响应头行。此调试输出在内容被处理前发出，因此不会考虑本地修改。主要用途是无需运行网络嗅探器即可查看请求和响应。当多个连接并行处理时，输出可读性会降低，但位于 examples/ 目录中的 “debug2ansi” 和 “debug2html” 脚本可显著改善此问题，通过为输出着色提升可读性。

13. 安全注意事项

Mon, 01 Jan 0001 00:00:00 +0000

HAProxy 旨在以极低的权限运行。使用它的标准方式是将其隔离到 chroot 环境中，并将其权限降级为非 root 用户，且该用户在该环境内没有任何权限，从而确保未来若发现任何漏洞，其被攻破也不会影响系统其余部分。

如何删除键

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

安装 etcd 和 etcdctl

添加或删除键

del 用于删除指定的键或键范围：

etcdctl del $KEY [$END_KEY]

选项

--prefix[=false]: delete keys with matching prefix
--prev-kv[=false]: return deleted key-value pairs
--from-key[=false]: delete keys that are greater than or equal to the given key using byte compare
--range[=false]: delete range of keys without delay

继承自父命令的选项

--endpoints="127.0.0.1:2379": gRPC endpoints

示例

etcdctl --endpoints=$ENDPOINTS put key myvalue
etcdctl --endpoints=$ENDPOINTS del key

etcdctl --endpoints=$ENDPOINTS put k1 value1
etcdctl --endpoints=$ENDPOINTS put k2 value2
etcdctl --endpoints=$ENDPOINTS del k --prefix

如何在事务中进行多次写操作

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

安装 etcd 和 etcdctl 。
运行中的 etcd 集群。

术语

以下是本文中使用的部分关键术语的定义，这些术语将在 Example 示例中出现。

如何监听键值变化

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

安装 etcd 和 etcdctl

监听键

watch 以接收后续变更的通知：

etcdctl watch $KEY [$END_KEY]

选项

-i, --interactive[=false]: interactive mode
--prefix[=false]: watch on a prefix if prefix is set
--rev=0: Revision to start watching
--prev-kv[=false]: get the previous key-value pair before the event happens
--progress-notify[=false]: get periodic watch progress notification from server

继承自父命令的选项

--endpoints="127.0.0.1:2379": gRPC endpoints

示例

etcdctl --endpoints=$ENDPOINTS watch stock1
etcdctl --endpoints=$ENDPOINTS put stock1 1000

etcdctl --endpoints=$ENDPOINTS watch stock --prefix
etcdctl --endpoints=$ENDPOINTS put stock1 10
etcdctl --endpoints=$ENDPOINTS put stock2 20

如何创建租约

Mon, 01 Jan 0001 00:00:00 +0000

lease 以 TTL 写入：

etcdctl --endpoints=$ENDPOINTS lease grant 300
# lease 2be7547fbc6a5afa granted with TTL(300s)

etcdctl --endpoints=$ENDPOINTS put sample value --lease=2be7547fbc6a5afa
etcdctl --endpoints=$ENDPOINTS get sample

etcdctl --endpoints=$ENDPOINTS lease keep-alive 2be7547fbc6a5afa
etcdctl --endpoints=$ENDPOINTS lease revoke 2be7547fbc6a5afa
# or after 300 seconds
etcdctl --endpoints=$ENDPOINTS get sample

如何创建锁

Mon, 01 Jan 0001 00:00:00 +0000

LOCK 使用指定名称获取一个分布式互斥锁。锁获取成功后，将一直持有，直至 etcdctl 终止。

先决条件

安装 etcd 和 etcdctl

创建锁

lock 用于分布式锁：

快速入门

Mon, 01 Jan 0001 00:00:00 +0000

按照以下步骤本地安装、运行并测试单成员 etcd 集群：

从预构建的二进制文件或源码安装 etcd。详情请参见 [安装][]。

警告

重要：务必完成安装说明的最后一步，确认可执行文件搜索路径中包含 etcd。

如何在 etcd 集群中进行领导者选举

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

确保已安装 etcd 和 etcdctl 。
检查 etcd 集群是否处于活跃状态。

进行领导者选举

etcdctl 命令用于在 etcd 集群中执行选举操作。该命令确保同一时间仅有一个客户端可成为领导者。

如何检查集群状态

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

安装 etcd 和 etcdctl

检查整体状态

使用 endpoint status 检查 --endpoints 标志中指定的每个端点的总体状态：

etcdctl endpoint status (--endpoints=$ENDPOINTS|--cluster)

选项

--cluster[=false]: use all endpoints from the cluster member list

检查健康状况

使用 endpoint health 检查 --endpoints 标志中指定的每个端点的健康状态：

如何保存数据库

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

快照数据库

snapshot 用于保存 etcd 数据库的指定时间点快照：

etcdctl --endpoints=$ENDPOINT snapshot save DB_NAME

全局选项

etcdctl

--endpoints=[127.0.0.1:2379], gRPC endpoints

快照只能从一个 etcd 节点请求，因此 --endpoints 标志中应仅包含一个端点。

示例

Mon, 01 Jan 0001 00:00:00 +0000

本系列示例展示了操作 etcd 集群的基本流程。

认证

auth、user、role 用于身份认证：

export ETCDCTL_API=3
ENDPOINTS=localhost:2379

etcdctl --endpoints=${ENDPOINTS} role add root
etcdctl --endpoints=${ENDPOINTS} role get root

etcdctl --endpoints=${ENDPOINTS} user add root
etcdctl --endpoints=${ENDPOINTS} user grant-role root root
etcdctl --endpoints=${ENDPOINTS} user get root

etcdctl --endpoints=${ENDPOINTS} role add role0
etcdctl --endpoints=${ENDPOINTS} role grant-permission role0 readwrite foo
etcdctl --endpoints=${ENDPOINTS} user add user0
etcdctl --endpoints=${ENDPOINTS} user grant-role user0 role0

etcdctl --endpoints=${ENDPOINTS} auth enable
# now all client requests go through auth

etcdctl --endpoints=${ENDPOINTS} --user=user0:123 put foo bar
etcdctl --endpoints=${ENDPOINTS} get foo
# permission denied, user name is empty because the request does not issue an authentication request
etcdctl --endpoints=${ENDPOINTS} --user=user0:123 get foo
# user0 can read the key foo
etcdctl --endpoints=${ENDPOINTS} --user=user0:123 get foo1

安装

Mon, 01 Jan 0001 00:00:00 +0000

先决条件

安装 etcd 之前，请参阅以下页面：

[支持的平台][]
[硬件建议][]

安装预构建二进制文件

安装 etcd 最简便的方式是使用预构建的二进制文件：

功能门控

Mon, 01 Jan 0001 00:00:00 +0000

本文概述了管理员可在 etcd 中指定的各种功能门控。

请参阅 feature stages 了解功能各阶段的说明。

概述

功能门控是一组描述 etcd 特性的 key=value 键值对。可使用 etcd 的 --feature-gates 命令行标志来开启或关闭这些特性。

常见问题

Mon, 01 Jan 0001 00:00:00 +0000

etcd，通用

etcd 是什么？

etcd 是一个一致性的分布式键值存储。主要用于分布式系统中的独立协调服务，专为存储可完全容纳在内存中的少量数据而设计。

库和工具

Mon, 01 Jan 0001 00:00:00 +0000

请注意，以下第三方库和工具未托管在 https://github.com/etcd-io 下，也未经 etcd 团队测试或维护。使用前应自行阅读相关资料并评估其可靠性。

工具

etcdctl - etcd 的命令行客户端
etcd-dump - 用于导出/恢复 etcd 的命令行工具
etcd-fs - etcd 的 FUSE 文件系统
etcddir - 实时同步 etcd 与本地目录的工具，支持 Windows 和 Linux
etcd-browser - 基于 AngularJS 的 Web 端键值编辑器，用于 etcd
etcd-lock - 基于 etcd 实现的领导者选举与分布式读写锁，支持 v2 版本
etcd-console - 基于 PHP 的 Web 端键值编辑器，用于 etcd
etcd-viewer - 使用 Java 编写的 etcd 键值存储编辑器/查看器
etcdtool - 将 etcd 目录导出/导入/编辑为 JSON/YAML/TOML 格式，并使用 JSON Schema 验证目录
etcdloadtest - 用于 etcd 3.0 及以上版本的命令行负载测试客户端
etcd-tui - 用于与 etcd 数据库交互的现代终端用户界面（TUI），可在终端中导航键、查看值、过滤数据，并直接管理 etcd 集群
etcdfinder - 一款快速、现代的 Web UI，支持 etcd v2 和 v3，具备即时搜索功能
lucas - 用于 Kubernetes etcd 3.0+ 集群的 Web 端键值查看器
etcd-manager - 一款现代、高效、跨平台且免费的 etcd 3.x 图形界面与客户端工具，支持 Windows、Linux 和 Mac
etcd-backup-restore - 用于定期且增量备份与恢复 etcd 的工具
etcd-druid - 用于部署 etcd 集群并管理日常运维操作的 Kubernetes Operator
etcdadm - 用于操作 etcd 集群的命令行工具
etcd-defrag - 更易用且智能的 etcd 碎片整理工具
etcdhelper - 适用于 IntelliJ 平台的 etcd 插件

库

以下各节按语言列出了 etcd 客户端库。

如何添加和删除成员

Mon, 01 Jan 0001 00:00:00 +0000

member 用于添加、删除或更新成员关系：

# For each machine
TOKEN=my-etcd-token-1
CLUSTER_STATE=new
NAME_1=etcd-node-1
NAME_2=etcd-node-2
NAME_3=etcd-node-3
HOST_1=10.240.0.13
HOST_2=10.240.0.14
HOST_3=10.240.0.15
CLUSTER=${NAME_1}=http://${HOST_1}:2380,${NAME_2}=http://${HOST_2}:2380,${NAME_3}=http://${HOST_3}:2380

# For node 1
THIS_NAME=${NAME_1}
THIS_IP=${HOST_1}
etcd --data-dir=data.etcd --name ${THIS_NAME} \
	--initial-advertise-peer-urls http://${THIS_IP}:2380 \
	--listen-peer-urls http://${THIS_IP}:2380 \
	--advertise-client-urls http://${THIS_IP}:2379 \
	--listen-client-urls http://${THIS_IP}:2379 \
	--initial-cluster ${CLUSTER} \
	--initial-cluster-state ${CLUSTER_STATE} \
	--initial-cluster-token ${TOKEN}

# For node 2
THIS_NAME=${NAME_2}
THIS_IP=${HOST_2}
etcd --data-dir=data.etcd --name ${THIS_NAME} \
	--initial-advertise-peer-urls http://${THIS_IP}:2380 \
	--listen-peer-urls http://${THIS_IP}:2380 \
	--advertise-client-urls http://${THIS_IP}:2379 \
	--listen-client-urls http://${THIS_IP}:2379 \
	--initial-cluster ${CLUSTER} \
	--initial-cluster-state ${CLUSTER_STATE} \
	--initial-cluster-token ${TOKEN}

# For node 3
THIS_NAME=${NAME_3}
THIS_IP=${HOST_3}
etcd --data-dir=data.etcd --name ${THIS_NAME} \
	--initial-advertise-peer-urls http://${THIS_IP}:2380 \
	--listen-peer-urls http://${THIS_IP}:2380 \
	--advertise-client-urls http://${THIS_IP}:2379 \
	--listen-client-urls http://${THIS_IP}:2379 \
	--initial-cluster ${CLUSTER} \
	--initial-cluster-state ${CLUSTER_STATE} \
	--initial-cluster-token ${TOKEN}

然后使用 member remove 和 member add 命令替换成员：

报告缺陷

Mon, 01 Jan 0001 00:00:00 +0000

如果 etcd 项目任何部分存在缺陷或文档错误，请通过打开问题告知我们。我们高度重视缺陷和错误，认为任何问题都不算太小。创建缺陷报告前，请确认尚未存在报告相同问题的议题。

调优

Mon, 01 Jan 0001 00:00:00 +0000

默认情况下，etcd 的配置在平均网络延迟较低的本地网络环境中应能良好运行。然而，当在多个数据中心之间或高延迟网络上使用 etcd 时，可能需要调整心跳间隔和选举超时设置。

发现服务协议

Mon, 01 Jan 0001 00:00:00 +0000

发现服务协议有助于新 etcd 成员在集群引导阶段通过共享的发现 URL 发现集群中的所有其他成员。

发现服务协议仅在集群引导阶段使用，不可用于运行时重配置或集群监控。

发现服务协议

Mon, 01 Jan 0001 00:00:00 +0000

发现服务协议有助于新 etcd 成员在集群引导阶段，通过共享的发现令牌和端点列表，发现集群中的所有其他成员。

发现服务协议仅在集群引导阶段使用，不可用于运行时重配置或集群监控。

日志记录约定

Mon, 01 Jan 0001 00:00:00 +0000

etcd 使用 zap 库记录应用程序输出，输出按级别进行分类。日志消息的级别依据以下约定确定：

DebugLevel 日志通常非常庞大，通常在生产环境中禁用。
- 示例：
  - 向远程对等成员发送一条普通消息
  - 将日志条目写入磁盘
InfoLevel 为默认的日志优先级。

Go 模块

Mon, 01 Jan 0001 00:00:00 +0000

etcd 项目（自版本 3.5 起）采用多个 golang 模块，托管于单个仓库中。

以下是各个模块：

go.etcd.io/etcd/api/v3 - 包含 API 定义（如 protos 与 proto 生成的库），定义了 etcd 客户端与服务器之间的通信协议。
go.etcd.io/etcd/pkg/v3 - etcd 使用的通用工具包集合，不针对 etcd 本身。仅当某个包未来可能被移出至独立仓库时，才应归入此处。请避免在此处添加依赖关系复杂的代码，因为这些依赖会自动成为客户端库的依赖（我们希望客户端库保持轻量）。

数据模型

Mon, 01 Jan 0001 00:00:00 +0000

etcd 旨在可靠地存储更新频率较低的数据，并提供可靠的监听查询。etcd 通过暴露键值对的旧版本，支持低成本的快照和监听历史事件（“时间旅行查询”）。持久化、多版本、并发控制的数据模型非常适合这些应用场景。

etcd 客户端设计

Mon, 01 Jan 0001 00:00:00 +0000

etcd 客户端设计

Gyuho Lee (github.com/gyuho, Amazon Web Services, Inc.), Joe Betz (github.com/jpbetz, Google Inc.)

简介

etcd 服务器通过多年的故障注入测试验证了其稳健性。大多数复杂的应用逻辑已由 etcd 服务器及其数据存储处理（例如，集群成员关系对客户端透明，提案通过 Raft 层转发至领导者）。尽管服务器组件本身正确，但其与客户端的组合需采用一组复杂的协议，以确保在故障条件下仍能保证正确性和高可用性。理想情况下，etcd 服务器为多台物理机器提供单一逻辑集群视图，客户端则实现副本间的自动故障转移。本文档描述客户端的架构决策及其具体实现细节。

etcd 学习者成员设计

Mon, 01 Jan 0001 00:00:00 +0000

etcd 学习者成员

Gyuho Lee (github.com/gyuho, Amazon Web Services, Inc.), Joe Betz (github.com/jpbetz, Google Inc.)

背景

成员变更配置一直是运维中最大的挑战之一。回顾常见问题。

etcd v3 身份认证设计

Mon, 01 Jan 0001 00:00:00 +0000

为什么不重用 v2 认证系统？

v3 协议使用 gRPC 作为传输机制，而非 v2 所采用的 RESTful 接口。这一新协议为迭代和改进 v2 设计提供了机会。例如，v3 身份认证采用基于连接的身份认证，而非 v2 每请求身份认证的较慢方式。此外，v2 身份认证在实际应用中关于一致性推理的语义往往难以处理，这一点将在后续章节中详述。对于 v3，身份认证机制具有明确定义的描述和实现，解决了 v2 身份认证系统中的缺陷。

etcd API

Mon, 01 Jan 0001 00:00:00 +0000

本文旨在概述 v3 版 etcd API 的核心设计。切勿将本指南与已弃用的 etcd v2 API 混淆，后者已于 etcd v3.5 中弃用。本文并非全面涵盖所有内容，而是聚焦于理解 etcd 所需的基本概念，避免被较少使用的 API 调用分散注意力。所有 etcd API 均定义在 [gRPC services][grpc-service] 中，这些服务对 etcd 服务器所理解的远程过程调用（RPC）进行了分类。所有 etcd RPC 的完整列表已在 [gRPC API listing][grpc-api] 的 Markdown 文档中记录。

etcd 持久化存储文件

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍了 etcd 持久化存储格式：命名规则、内容结构以及可供开发者用于检查存储内容的工具。后续应随着存储模型的变更持续扩展本文内容。本文面向 etcd 开发者，旨在帮助其满足数据恢复需求。

etcd API 保证

Mon, 01 Jan 0001 00:00:00 +0000

etcd 是一个一致且持久的键值存储系统。键值存储通过 gRPC Services 暴露。etcd 为分布式系统提供最强的一致性和持久性保证。本文规范列出了 etcd 所提供的 API 保证。

值得考虑的 API

KV API
- 范围
- 范围流
- 写入
- 删除
- 事务
监听 API
- 监听
租约 API
- 授予
- [撤销]
- 保活

KV API 支持对键值存储进行直接读取和操作。监听 API 支持订阅键值存储的变更。租约 API 支持为键指定生存时间（TTL）。

etcd 与其它键值存储系统比较

Mon, 01 Jan 0001 00:00:00 +0000

etcd 这个名称源自两个理念：Unix 系统中的“/etc”目录和“d”istributed（分布式）系统。其中，“/etc”目录是用于存储单个系统配置数据的路径，而 etcd 则用于存储大规模分布式系统的配置信息。因此，“d”istributed “/etc”即为 etcd。

术语表

Mon, 01 Jan 0001 00:00:00 +0000

本文定义了 etcd 文档、命令行和源代码中使用的各种术语。

告警

当集群需要操作员干预以保持可靠性时，etcd 服务器会触发告警。

配置本地集群

Mon, 01 Jan 0001 00:00:00 +0000

对于测试和开发部署，最快捷简便的方式是配置本地集群。对于生产部署，请参考 clustering 章节。

本地独立集群

启动集群

运行以下命令以将 etcd 集群部署为独立集群：

与 etcd 交互

Mon, 01 Jan 0001 00:00:00 +0000

用户通常通过设置或获取键的值来与 etcd 交互。本节介绍如何使用 etcdctl（用于与 etcd 服务器交互的命令行工具）实现这一操作。此处描述的概念同样适用于 gRPC API 或客户端库 API。

为什么使用 gRPC 网关

Mon, 01 Jan 0001 00:00:00 +0000

etcd v3 使用 gRPC 作为其消息协议。etcd 项目包含一个基于 gRPC 的 Go 客户端，以及一个命令行工具 etcdctl ，用于通过 gRPC 与 etcd 集群通信。对于不支持 gRPC 的语言，etcd 提供一个 JSON gRPC 网关。该网关提供一个 RESTful 代理，可将 HTTP/JSON 请求转换为 gRPC 消息。

gRPC 命名与发现

Mon, 01 Jan 0001 00:00:00 +0000

etcd 提供了一个 gRPC 解析器，用于支持一种替代名称系统，该系统从 etcd 获取端点以发现 gRPC 服务。其底层机制基于监听以服务名称为前缀的键的更新。

请注意，此功能为实验性功能，因为它依赖于 google.golang.org/grpc/resolver 包，而该包在 grpc-go 中仍处于实验阶段。

将 etcd 集成到 Go 应用中

Mon, 01 Jan 0001 00:00:00 +0000

etcd embed go 包提供了一种简便方式，可将 etcd 服务器直接嵌入应用程序。

有关详细信息，请参见 embed 包文档。

系统限制

Mon, 01 Jan 0001 00:00:00 +0000

请求大小限制

etcd 专为处理典型的元数据类小规模键值对而设计。虽然较大请求也能正常工作，但可能增加其他请求的延迟。默认情况下，任何请求的最大大小为 1.5 MiB。此限制可通过 etcd 服务器的 --max-request-bytes 标志进行配置。

etcd 功能

Mon, 01 Jan 0001 00:00:00 +0000

本文概述了 etcd 的各项功能，旨在帮助用户更好地理解这些功能及其相关弃用流程。若想了解 etcd 功能的开发方式，请参阅开发指南。

etcd 功能分为三个阶段：实验性、稳定和不安全。可通过运行 etcd --help 获取功能列表。

API 参考

Mon, 01 Jan 0001 00:00:00 +0000

本文 API 参考由命名的 .proto 文件自动生成。

服务 `Auth` (api/etcdserverpb/rpc.proto)

方法	请求类型	响应类型	描述
AuthEnable	AuthEnableRequest	AuthEnableResponse	AuthEnable 启用身份认证。
AuthDisable	AuthDisableRequest	AuthDisableResponse	AuthDisable 禁用身份认证。
AuthStatus	AuthStatusRequest	AuthStatusResponse	AuthStatus 显示身份认证状态。
Authenticate	AuthenticateRequest	AuthenticateResponse	Authenticate 处理身份认证请求。
UserAdd	AuthUserAddRequest	AuthUserAddResponse	UserAdd 添加新用户。用户名不能为空。
UserGet	AuthUserGetRequest	AuthUserGetResponse	UserGet 获取用户详细信息。
UserList	AuthUserListRequest	AuthUserListResponse	UserList 获取所有用户的列表。
UserDelete	AuthUserDeleteRequest	AuthUserDeleteResponse	UserDelete 删除指定用户。
UserChangePassword	AuthUserChangePasswordRequest	AuthUserChangePasswordResponse	UserChangePassword 更改指定用户的密码。
UserGrantRole	AuthUserGrantRoleRequest	AuthUserGrantRoleResponse	UserGrant 为指定用户授予角色。
UserRevokeRole	AuthUserRevokeRoleRequest	AuthUserRevokeRoleResponse	UserRevokeRole 撤销指定用户的指定角色。
RoleAdd	AuthRoleAddRequest	AuthRoleAddResponse	RoleAdd 添加新角色。角色名不能为空。
RoleGet	AuthRoleGetRequest	AuthRoleGetResponse	RoleGet 获取角色详细信息。
RoleList	AuthRoleListRequest	AuthRoleListResponse	RoleList 获取所有角色的列表。
RoleDelete	AuthRoleDeleteRequest	AuthRoleDeleteResponse	RoleDelete 删除指定角色。
RoleGrantPermission	AuthRoleGrantPermissionRequest	AuthRoleGrantPermissionResponse	RoleGrantPermission 为指定角色授予指定键或范围的权限。
RoleRevokePermission	AuthRoleRevokePermissionRequest	AuthRoleRevokePermissionResponse	RoleRevokePermission 撤销指定角色的指定键或范围的权限。

服务 `Cluster` (api/etcdserverpb/rpc.proto)

方法	请求类型	响应类型	描述
MemberAdd	MemberAddRequest	MemberAddResponse	MemberAdd 将成员添加至集群。
MemberRemove	MemberRemoveRequest	MemberRemoveResponse	MemberRemove 从集群中移除现有成员。
MemberUpdate	MemberUpdateRequest	MemberUpdateResponse	MemberUpdate 更新成员配置。
MemberList	MemberListRequest	MemberListResponse	MemberList 列出集群中的所有成员。
MemberPromote	MemberPromoteRequest	MemberPromoteResponse	MemberPromote 将学习者成员（非投票成员）提升为 Raft 投票成员。

服务 `KV` (api/etcdserverpb/rpc.proto)

方法	请求类型	响应类型	描述
Range	RangeRequest	RangeResponse	Range 从键值存储中获取指定范围内的键。
Put	PutRequest	PutResponse	Put 将指定键写入键值存储。Put 请求会递增键值存储的修订版本，并在事件历史中生成一个事件。
DeleteRange	DeleteRangeRequest	DeleteRangeResponse	DeleteRange 从键值存储中删除指定范围内的键。删除请求会递增键值存储的修订版本，并为每个被删除的键在事件历史中生成一个删除事件。
Txn	TxnRequest	TxnResponse	Txn 在单个事务中处理多个请求。事务请求会递增键值存储的修订版本，并为每个完成的请求生成具有相同修订版本的事件。不允许在同一个事务中多次修改同一键。
Compact	CompactionRequest	CompactionResponse	Compact 对 etcd 键值存储中的事件历史进行压缩。键值存储应定期执行压缩，否则事件历史将无限增长。

服务 `Lease` (api/etcdserverpb/rpc.proto)

方法	请求类型	响应类型	描述
LeaseGrant	LeaseGrantRequest	LeaseGrantResponse	LeaseGrant 创建一个租约，若服务器在指定的生存时间（TTL）内未收到保活请求，则该租约将过期。若租约过期，所有关联该租约的键将被过期并删除。每个过期的键都会在事件历史中生成一个删除事件。
LeaseRevoke	LeaseRevokeRequest	LeaseRevokeResponse	LeaseRevoke 撤销一个租约。所有关联该租约的键将过期并被删除。
LeaseKeepAlive	LeaseKeepAliveRequest	LeaseKeepAliveResponse	LeaseKeepAlive 通过客户端向服务器流式发送保活请求，并从服务器流式接收保活响应，以维持租约的活跃状态。
LeaseTimeToLive	LeaseTimeToLiveRequest	LeaseTimeToLiveResponse	LeaseTimeToLive 获取租约信息。
LeaseLeases	LeaseLeasesRequest	LeaseLeasesResponse	LeaseLeases 列出所有现有的租约。

服务 `Maintenance` (api/etcdserverpb/rpc.proto)

方法	请求类型	响应类型	描述
Alarm	AlarmRequest	AlarmResponse	告警用于激活、停用和查询与集群健康状态相关的告警。
Status	StatusRequest	StatusResponse	状态用于获取成员的状态。
Defragment	DefragmentRequest	DefragmentResponse	碎片整理用于对成员的后端数据库进行碎片整理，以恢复存储空间。
Hash	HashRequest	HashResponse	哈希用于计算整个后端键空间的哈希值，包括存储中的键、租约及其他桶。此功能仅用于测试！请勿在存在持续事务的生产环境中依赖此操作，因为哈希操作不持有 MVCC 锁。如需对“键”桶进行一致性检查，请改用“HashKV” API。
HashKV	HashKVRequest	HashKVResponse	哈希键用于计算指定修订版本之前所有 MVCC 键的哈希值。它仅遍历后端存储中的“键”桶。
Snapshot	SnapshotRequest	SnapshotResponse	快照通过流将成员的整个后端数据发送给客户端。
MoveLeader	MoveLeaderRequest	MoveLeaderResponse	转移领导者用于请求当前领导者将其领导权转移给指定接收节点。
Downgrade	DowngradeRequest	DowngradeResponse	降级用于请求降级、验证可行性或取消集群版本的降级操作。自 etcd 3.5 起支持。

服务 `Watch` (api/etcdserverpb/rpc.proto)

方法	请求类型	响应类型	描述
Watch	WatchRequest	WatchResponse	Watch 用于监听发生的事件或已发生的事件。输入和输出均为流；输入流用于创建和取消监听器，输出流用于发送事件。一个 Watch RPC 可以同时监听多个键范围，一次性流式传输多个监听的事件。可以从最后一次压缩的修订版本开始，监听完整的事件历史。

消息 `AlarmMember` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
memberID	memberID 是与触发告警相关的成员的 ID。	uint64
alarm	alarm 是已触发的告警类型。	AlarmType

消息 `AlarmRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
action	action 表示要发出的告警请求类型。action 可以是获取告警状态、激活告警，或停用已触发的告警。	AlarmAction
memberID	memberID 表示与告警关联的成员 ID。如果 memberID 为 0，则该告警请求涵盖所有成员。	uint64
alarm	alarm 表示本次请求所考虑的告警类型。	AlarmType

消息 `AlarmResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader
alarms	alarms 是与告警请求相关联的告警列表。	(slice of) AlarmMember

消息 `AuthDisableRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option

消息 `AuthDisableResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthEnableRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option

消息 `AuthEnableResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthRoleAddRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
name	name 是要添加到身份认证系统中的角色名称。	string

消息 `AuthRoleAddResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthRoleDeleteRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
role		string

消息 `AuthRoleDeleteResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthRoleGetRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
role		string

消息 `AuthRoleGetResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
header		ResponseHeader
perm		(切片) authpb.Permission

消息 `AuthRoleGrantPermissionRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
name	name 是将被授予权限的角色名称。	string
perm	perm 是要授予角色的权限。	authpb.Permission

消息 `AuthRoleGrantPermissionResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthRoleListRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option

消息 `AuthRoleListResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader
roles		(slice of) string

消息 `AuthRoleRevokePermissionRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
role		string
key		bytes
range_end		bytes

消息 `AuthRoleRevokePermissionResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthStatusRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option

消息 `AuthStatusResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader
enabled		bool
authRevision	authRevision 是认证存储系统的当前修订版本	uint64

消息 `AuthUserAddRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
name		string
password		string
options		authpb.UserAddOptions
hashedPassword		string

消息 `AuthUserAddResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthUserChangePasswordRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
name	name 是要更改密码的用户的名称。	string
password	password 是用户的新密码。请注意，该字段将在 API 层被移除。	string
hashedPassword	hashedPassword 是用户的新的哈希密码。请注意，该字段将在 API 层被初始化。	string

消息 `AuthUserChangePasswordResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthUserDeleteRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
name	name 是要删除的用户名称。	string

消息 `AuthUserDeleteResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthUserGetRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
name		string

消息 `AuthUserGetResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader
roles		(slice of) string

消息 `AuthUserGrantRoleRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
user	user 是应被授予指定角色的用户名。	string
role	role 是应授予用户的角色名称。	string

消息 `AuthUserGrantRoleResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthUserListRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option

消息 `AuthUserListResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader
users		(slice of) string

消息 `AuthUserRevokeRoleRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
name		string
role		string

消息 `AuthUserRevokeRoleResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader

消息 `AuthenticateRequest` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
name		string
password		string

消息 `AuthenticateResponse` (api/etcdserverpb/rpc.proto)

字段	描述	类型
(versionpb.etcd_version_msg)		option
header		ResponseHeader
token	token 是可用于后续 RPC 的授权令牌	string

消息 `CompactionRequest` (api/etcdserverpb/rpc.proto)

CompactionRequest 对键值存储执行压缩，直至指定的修订版本。所有修订版本小于压缩修订版本的已覆盖键将被移除。

API 参考：并发

Mon, 01 Jan 0001 00:00:00 +0000

本文 API 参考由命名的 .proto 文件自动生成。

服务 `Lock` (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

锁服务将客户端锁功能以 gRPC 接口的形式暴露。

方法	请求类型	响应类型	描述
Lock	LockRequest	LockResponse	Lock 在指定名称的锁上获取分布式共享锁。成功时，将返回一个唯一键，该键在调用方持有锁期间持续存在。该键可与事务配合使用，以确保对 etcd 的更新仅在持有锁所有权时发生。锁将持续持有，直至对键调用 Unlock，或与所有者关联的租约到期。
Unlock	UnlockRequest	UnlockResponse	Unlock 接收 Lock 返回的键，并释放对锁的持有。等待获取锁的下一个 Lock 调用者将被唤醒，并获得锁的所有权。

消息 `LockRequest` (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

字段	描述	类型
name	name 是要获取的分布式共享锁的标识符。	bytes
lease	lease 是将附加到锁所有权的租约 ID。如果该租约到期或被撤销且当前持有锁，则锁会自动释放。使用相同租约调用 Lock 将被视为一次获取；使用相同租约两次锁定为无操作。	int64

消息 `LockResponse` (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

字段	描述	类型
header		etcdserverpb.ResponseHeader
key	键是在锁持有者持有锁期间存在于 etcd 中的键。用户不应修改此键，否则锁可能表现出未定义行为。	bytes

消息 `UnlockRequest` (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

字段	描述	类型
key	key 是由 Lock 分配的锁所有权键。	bytes

消息 `UnlockResponse` (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

字段	描述	类型
header		etcdserverpb.ResponseHeader

服务 `Election` (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

选举服务通过 gRPC 接口向客户端暴露选举功能。

配置选项

Mon, 01 Jan 0001 00:00:00 +0000

可以通过以下方式配置 etcd：

命令行标志
环境变量：每个标志都有一个对应的环境变量，其名称与标志相同，但前缀为 ETCD_，并以全大写和 [蛇形命名法][] 格式化。例如，--some-flag 对应 ETCD_SOME_FLAG。
配置文件

警告

请注意：如果混合使用配置选项，则以下规则适用。

身份认证

Mon, 01 Jan 0001 00:00:00 +0000

auth、user、role 用于身份认证：

export ETCDCTL_API=3
ENDPOINTS=localhost:2379

etcdctl --endpoints=${ENDPOINTS} role add root
etcdctl --endpoints=${ENDPOINTS} role get root

etcdctl --endpoints=${ENDPOINTS} user add root
etcdctl --endpoints=${ENDPOINTS} user grant-role root root
etcdctl --endpoints=${ENDPOINTS} user get root

etcdctl --endpoints=${ENDPOINTS} role add role0
etcdctl --endpoints=${ENDPOINTS} role grant-permission role0 readwrite foo
etcdctl --endpoints=${ENDPOINTS} user add user0
etcdctl --endpoints=${ENDPOINTS} user grant-role user0 role0

etcdctl --endpoints=${ENDPOINTS} auth enable
# now all client requests go through auth

etcdctl --endpoints=${ENDPOINTS} --user=user0:123 put foo bar
etcdctl --endpoints=${ENDPOINTS} get foo
# permission denied, user name is empty because the request does not issue an authentication request
etcdctl --endpoints=${ENDPOINTS} --user=user0:123 get foo
# user0 can read the key foo
etcdctl --endpoints=${ENDPOINTS} --user=user0:123 get foo1

注意：

本文仅为示例，需补充并更新关于身份认证的更多信息。上述文本仅为代码示例。

基于角色的访问控制

Mon, 01 Jan 0001 00:00:00 +0000

概述

身份认证功能自 etcd 2.1 版本起引入。etcd v3 API 对身份认证功能的 API 和用户界面进行了轻微调整，以更好地适配新的数据模型。本文旨在帮助用户在 etcd v3 中设置基本的身份认证和基于角色的访问控制。

传输安全模型

Mon, 01 Jan 0001 00:00:00 +0000

etcd 支持自动 TLS，以及通过客户端证书实现的客户端到服务器和对等成员（服务器到服务器 / 集群）通信的身份认证。请注意，etcd 默认不启用基于 RBAC 的身份认证或传输层的身份认证功能，以降低用户入门时的使用门槛。此外，更改此默认设置将对该项目造成破坏性变更，该项目自 2013 年确立以来一直保持该设定。未启用安全功能的 etcd 集群可能使数据暴露于任意客户端。

集群指南

Mon, 01 Jan 0001 00:00:00 +0000

概述

静态启动 etcd 集群要求每个成员均知晓集群中的其他成员。在某些情况下，集群成员的 IP 地址可能无法提前确定。在这些情况下，可以借助发现服务来引导启动 etcd 集群。

以 Kubernetes StatefulSet 运行 etcd 集群

Mon, 01 Jan 0001 00:00:00 +0000

以下演示如何作为 Kubernetes StatefulSet 执行静态引导过程。

示例 Manifest

本文档包含用于在 Kubernetes 中部署静态 etcd 集群的服务和有状态集（StatefulSet）配置。

在容器中运行 etcd 集群

Mon, 01 Jan 0001 00:00:00 +0000

本文指南展示了如何使用 Docker 以静态引导过程运行 etcd。

Docker

为使 Docker 主机外部的客户端能够访问 etcd API，请使用容器的主机 IP 地址。有关获取 IP 地址的详细信息，请参见 docker inspect 。或者，可向 docker run 命令指定 --net=host 标志，以跳过将容器置于独立网络栈中的操作。

故障模式

Mon, 01 Jan 0001 00:00:00 +0000

在大规模机器部署中，故障是常见现象。当硬件或软件发生故障时，机器会失效。若出现断电或网络问题，多台机器可能同时失效。多种类型的故障也可能同时发生；几乎无法穷举所有可能的故障场景。

灾难恢复

Mon, 01 Jan 0001 00:00:00 +0000

etcd 设计用于抵御机器故障。etcd 集群可自动从临时故障（例如机器重启）中恢复，并能容忍最多 (N−1)/2 个成员的永久性故障，适用于由 N 个成员组成的集群。当某个成员发生永久性故障（无论是硬件故障还是磁盘损坏）时，该成员将失去对集群的访问权限。若集群永久性丢失超过 (N−1)/2 个成员，则将发生灾难性故障，法定人数不可逆地丢失。一旦法定人数丢失，集群将无法达成共识，因而无法继续接受更新。

etcd 网关

Mon, 01 Jan 0001 00:00:00 +0000

etcd 网关是什么

etcd 网关是一个简单的 TCP 代理，负责将网络数据转发至 etcd 集群。网关为无状态且透明的；它既不检查客户端请求，也不干扰集群响应。网关不会终止 TLS 连接，不会代表客户端执行 TLS 握手，也不会验证连接是否已加密。

gRPC 代理

Mon, 01 Jan 0001 00:00:00 +0000

gRPC 代理是运行在 gRPC 层（L7）的无状态 etcd 反向代理。该代理旨在降低核心 etcd 集群的总体处理负载。为实现横向扩展，代理会合并监听和租约 API 请求。为防止恶意客户端对集群造成影响，代理会缓存键范围请求。

硬件推荐

Mon, 01 Jan 0001 00:00:00 +0000

etcd 在资源有限的开发或测试环境中通常运行良好；在笔记本电脑或廉价云主机上开发 etcd 是常见做法。然而，在生产环境中运行 etcd 集群时，遵循一些硬件建议有助于实现有效的系统管理。这些建议并非硬性规定，而是构建稳健生产部署的良好起点。和往常一样，部署前应使用模拟工作负载进行测试。

维护

Mon, 01 Jan 0001 00:00:00 +0000

概述

etcd 集群需要定期维护以保持可靠性。根据 etcd 应用的需求，此类维护通常可以自动化执行，且无需停机或显著降低性能。

监控 etcd

Mon, 01 Jan 0001 00:00:00 +0000

每个 etcd 服务器通过其客户端端口上的 HTTP 端点提供本地监控信息。监控数据对于系统健康检查和集群调试均具有实用价值。

调试端点

若设置 --log-level=debug，etcd 服务器将在其客户端端口的 /debug 路径下导出调试信息。设置 --log-level=debug 时需谨慎，因为会导致性能下降和日志输出过于 verbose。

性能

Mon, 01 Jan 0001 00:00:00 +0000

理解性能

etcd 提供稳定、持续的高性能。性能由两个因素决定：延迟和吞吐量。延迟是指完成操作所需的时间。吞吐量是指在一定时间周期内完成的总操作数。通常情况下，当 etcd 接受并发客户端请求时，平均延迟会随着整体吞吐量的增加而上升。在常见的云环境（如 Google Compute Engine (GCE) 上的标准 n-4 实例，或 AWS 上相当的机器类型）中，三成员 etcd 集群在轻负载下请求完成时间小于 1 毫秒，重负载下每秒可完成超过 30,000 次请求。

运行时重配置设计

Mon, 01 Jan 0001 00:00:00 +0000

运行时重配置是分布式系统中最为复杂且最容易出错的功能之一，尤其是在基于共识的系统（如 etcd）中。

继续阅读以了解 etcd 运行时重配置命令的设计原理，以及我们如何解决这些问题。

运行时重配置

Mon, 01 Jan 0001 00:00:00 +0000

etcd 支持增量式运行时重配置，允许用户在运行时更新集群成员。

重新配置请求仅在集群多数成员正常运行时才能处理。生产环境中强烈建议始终将集群规模设置为大于二。从两成员集群中移除成员是不安全的。两成员集群的多数为两个。若在移除过程中发生故障，集群可能无法继续推进，需从多数故障中重启。

支持的平台

Mon, 01 Jan 0001 00:00:00 +0000

支持层级

etcd 可在不同平台上运行，但其提供的保证取决于平台的支持级别：

Tier 1：由 [etcd 维护者][] 完全支持；etcd 保证通过所有测试，包括功能测试和健壮性测试。
Tier 2：etcd 保证通过集成测试和端到端测试，但不保证通过功能测试或健壮性测试。
Tier 3：etcd 保证可构建，可能仅进行轻度测试（或未测试），因此应视为 不稳定。

当前支持

下表列出了当前支持的平台及其对应的 etcd 支持级别：

版本管理

Mon, 01 Jan 0001 00:00:00 +0000

本文描述了 etcd 项目所支持的版本。

服务版本管理与支持版本

etcd 版本号采用 x.y.z 格式，其中 x 表示主版本号，y 表示次版本号，z 表示补丁版本号，遵循语义化版本控制规范。新次版本号可能向 API 添加额外功能。

数据损坏

Mon, 01 Jan 0001 00:00:00 +0000

etcd 内置了自动数据损坏检测机制，以防止成员状态发生不一致。

启用数据损坏检测

数据损坏检测可通过以下方式执行：

初始检查，通过 --experimental-initial-corrupt-check 标志启用。
定期检查包括：
- 已压缩的修订版本哈希，通过 --experimental-compact-hash-check-enabled 标志启用。
- 最新修订版本哈希，通过 --experimental-corrupt-check-time 标志启用。

引导过程中将执行初始检查。成员将比较其持久化状态与其他成员的状态，若发现不匹配则退出。

存储内存使用量基准测试

Mon, 01 Jan 0001 00:00:00 +0000

etcd 存储的两个组件会占用物理内存。etcd 进程分配了一个 内存索引，用于加速键的查找。进程的 页缓存 由操作系统管理，用于存储从磁盘读取的最近访问数据，以便快速重用。

监听内存使用量基准测试

Mon, 01 Jan 0001 00:00:00 +0000

说明

监听功能正处于积极开发中，其内存使用量可能随开发进展而变化。我们预计其内存使用量不会显著超过以下所述数值。

etcd 的一个核心目标是支持大量客户端执行海量监听操作。etcd 旨在支持 O(10k) 个客户端、O(100K) 个监听流（每个客户端约 O(10) 个监听流）以及 O(10M) 个总监听操作（每个监听流约 O(100) 个监听）。每个单独监听操作所消耗的内存占 etcd 整体内存使用量的最大部分，因此成为当前及未来优化的重点。

etcd v3 基准测试

Mon, 01 Jan 0001 00:00:00 +0000

物理机

GCE n1-highcpu-2 机器类型

1x 专用本地 SSD，挂载于 /var/lib/etcd
1x 专用慢速磁盘，用于操作系统
1.8 GB 内存
2x CPU
etcd 版本 2.2.0

etcd 集群

1 以 v3 演示模式运行的 etcd 成员

etcd v2.2.0-rc 内存基准测试

Mon, 01 Jan 0001 00:00:00 +0000

物理机

GCE n1-standard-2 机器类型

1 个专用本地 SSD，挂载于 /var/lib/etcd
1 个专用慢速磁盘，用于操作系统
7.5 GB 内存
2 个 CPU

etcd

etcd Version: 2.2.0-rc.0+git
Git SHA: 103cb5c
Go Version: go1.5
Go OS/Arch: linux/amd64

测试

启动一个由 3 个成员组成的 etcd 集群，每个成员使用 2 个核心。

etcd v2.2.0-rc 基准测试

Mon, 01 Jan 0001 00:00:00 +0000

物理机

GCE n1-highcpu-2 机器类型

1 个专用本地 SSD，挂载于 /var/lib/etcd
1 个专用慢速磁盘，用于操作系统
1.8 GB 内存
2 个 CPU

etcd 集群

3 etcd 2.2.0-rc 成员，每个成员运行在单台机器上。

etcd v2.2.0 基准测试

Mon, 01 Jan 0001 00:00:00 +0000

物理机

GCE n1-highcpu-2 机器类型

1 块专用本地 SSD，挂载为 etcd 数据目录
1 块专用慢速磁盘，用于操作系统
1.8 GB 内存
2 个 CPU

etcd 集群

3 etcd 2.2.0 成员，每个成员运行在单台机器上。

etcd v2.1.0 基准测试

Mon, 01 Jan 0001 00:00:00 +0000

物理机

GCE n1-highcpu-2 机器类型

1 块专用本地 SSD，挂载于 /var/lib/etcd
1 块专用慢速磁盘，用于操作系统
1.8 GB 内存
2 个 CPU
etcd 版本 2.1.0 alpha

etcd 集群

3 个 etcd 成员，每个成员运行在单台机器上

降级 etcd 集群与应用程序

Mon, 01 Jan 0001 00:00:00 +0000

本节包含与降级 etcd 集群及应用程序相关的文档。

降级 etcd v3.x 集群

升级 etcd 集群与应用程序

Mon, 01 Jan 0001 00:00:00 +0000

本节包含与升级 etcd 集群及应用程序相关的特定文档。

升级策略

升级前请注意，etcd 仅支持以下两种升级场景：

补丁升级：在同一小版本内升级补丁版本（例如 3.7.0 至 3.7.1）。
小版本升级：每次仅升级一个次版本（例如 3.6 至 3.7）。不支持跳过次版本的升级，此类操作很可能失败。请在升级至下一个次版本前，先更新至最新补丁版本。

升级 etcd v3.x 集群

升级至 etcd v2.3

将 v2.3 集群升级至 v3.0

将 etcd 从 v3.5 升级到 v3.6

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd v3.5 升级到 v3.6 可以实现零停机时间的滚动升级：

逐一停止 etcd v3.5 进程，并替换为 etcd v3.6 进程
所有 v3.6 进程运行后，集群即可使用 v3.6 中的新特性

在开始升级之前，请通读本指南其余部分以做好准备。

将 etcd 从 v3.7 降级到 v3.6

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd v3.7 降级到 v3.6 可以实现零停机、滚动降级：

逐一停止 etcd v3.7 进程，并替换为 etcd v3.6 进程
启用降级后，集群将不再支持 v3.7 中的新特性

开始降级前，请阅读本指南其余内容并做好准备。

将 etcd 从 3.4 升级到 3.5

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd 3.4 升级到 3.5 可以实现零停机滚动升级：

逐一停止 etcd v3.4 进程，并替换为 etcd v3.5 进程
在所有 v3.5 进程运行后，集群即可使用 v3.5 的新特性

在开始升级之前，请通读本指南其余部分以做好准备。

将 etcd 从 3.5 降级到 3.4

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd 3.5 降级到 3.4 可以实现零停机、滚动降级：

逐一停止 etcd 3.5 进程，并替换为 etcd 3.4 进程
启动任意 3.4 进程后，集群将不再支持 3.5 中的新特性

开始降级前，请阅读本指南其余内容并做好准备。

将 etcd 从 v3.6 降级到 v3.5

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd v3.6 降级到 v3.5 可以实现零停机、滚动降级：

逐一停止 etcd v3.6 进程，并替换为 etcd v3.5 进程
启用降级后，集群将不再支持 v3.6 中的新特性

开始降级前，请阅读本指南其余内容并做好准备。

将 etcd 从 3.3 升级到 3.4

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd 3.3 升级到 3.4 可以实现零停机滚动升级：

逐一停止 etcd v3.3 进程，并替换为 etcd v3.4 进程
在所有 v3.4 进程运行后，集群即可使用 v3.4 的新特性

在开始升级之前，请通读本指南其余部分以做好准备。

将 etcd 从 v3.6 升级到 v3.7

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd v3.6 升级到 v3.7 可以实现零停机滚动升级：

逐一停止 etcd v3.6 进程，并替换为 etcd v3.7 进程
在所有 v3.7 进程运行后，集群即可使用 v3.7 中的新特性

在开始升级之前，请通读本指南其余部分以做好准备。

将 etcd 从 3.2 升级到 3.3

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd 3.2 升级到 3.3 可以实现零停机滚动升级：

逐一停止 etcd v3.2 进程，并替换为 etcd v3.3 进程
在所有 v3.3 进程运行后，集群即可使用 v3.3 的新特性

在开始升级之前，请通读本指南其余部分以做好准备。

将 etcd 从 3.1 升级到 3.2

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd 3.1 升级到 3.2 可以实现零停机滚动升级：

逐一停止 etcd v3.1 进程，并替换为 etcd v3.2 进程
在所有 v3.2 进程运行后，集群即可使用 v3.2 的新特性

在开始升级之前，请通读本指南其余部分以做好准备。

将 etcd 从 3.0 升级到 3.1

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd 3.0 升级到 3.1 可以实现零停机滚动升级：

逐一停止 etcd v3.0 进程，并替换为 etcd v3.1 进程
在所有 v3.1 进程运行后，集群即可使用 v3.1 的新特性

在开始升级之前，请通读本指南其余部分以做好准备。

将 etcd 从 2.3 升级到 3.0

Mon, 01 Jan 0001 00:00:00 +0000

在一般情况下，从 etcd 2.3 升级到 3.0 可以实现零停机滚动升级：

逐一停止 etcd v2.3 进程，并替换为 etcd v3.0 进程
在所有 v3.0 进程运行后，集群即可使用 v3.0 的新特性

在开始升级之前，请通读本指南其余部分以做好准备。

Issue 分类处置指南

Mon, 01 Jan 0001 00:00:00 +0000

目的

加快问题管理。

etcd 问题列于 https://github.com/etcd-io/etcd/issues ，并以标签标识。例如，被识别为缺陷的问题最终将被标记为 area/bug 。新创建的问题初始时无标签，但通常由 etcd 维护者和活跃贡献者根据其分析结果添加标签。标签的详细列表可参见 https://github.com/kubernetes/kubernetes/labels

PR 管理

Mon, 01 Jan 0001 00:00:00 +0000

目的

加速 PR 管理。

etcd 的 PR 列表位于 https://github.com/etcd-io/etcd/pulls PR 可能包含多种标签、里程碑、评审人等。标签的详细列表可参见 https://github.com/kubernetes/kubernetes/labels

以下是 PR 中便于参考的若干搜索示例：

归属与授权

Mon, 01 Jan 0001 00:00:00 +0000

pig.center 转载并整理了六个上游项目撰写的文档。每一个文档页面的末尾都有一行署名，指明该页改编自哪份作品、版权归属于谁、依据什么协议授权，并链接回本页对应的小节。

全文搜索

Mon, 01 Jan 0001 00:00:00 +0000

PostgreSQL 社区组件 on PIG.CENTER

pgBadger 13.x 版本记录

v13.2 · 2025-12-29

注解命令（annotate）

命令选项

备份注解选项（--annotation）

动态配置

简介

开发状态

入门指南

特性

新闻

pgBackRest 2.59.1 正式发布

pgBadger 12.x 版本记录

v12.4 · 2023-12-25

归档获取命令（archive-get）

YAML 配置参数

全局/通用

安装

Mac OS 前置依赖

Psycopg

负载均衡基础

配置：pgbouncer.ini

描述

下载与安装

选择分发渠道

用户指南（Debian/Ubuntu）

简介

pgBadger 11.x 版本记录

v11.8 · 2022-04-08

归档推送命令（archive-push）

环境变量

全局/通用

日志

HAProxy 是什么及其实现原理

命令行参考

用法与选项

pgbouncer 命令用法

语法

描述

用户指南（RHEL/Rocky/CentOS）

简介

pgBadger 10.x 版本记录

v10.3 · 2019-02-14

备份命令（backup）

Patroni REST API

PostgreSQL 日志配置

最小查询日志配置

PgBouncer 编译与安装

编译

基本功能

pgBadger 9.x 版本记录

v9.2 · 2017-07-27

检查命令（check）

patronictl 命令行

配置

标准功能

3.4.1. 标准功能：采样与信息转换

并行处理

使用 -j 拆分单个大文件

配置参考

简介

源码发布版下载

PgBouncer 1.25

PgBouncer 1.24

PgBouncer 1.23

PgBouncer 1.22

PgBouncer 1.21

PgBouncer 1.20

PgBouncer 1.19

PgBouncer 1.18

PgBouncer 1.17

PgBouncer 1.16

PgBouncer 1.15

PgBouncer 1.14

PgBouncer 1.13

PgBouncer 1.12

PgBouncer 1.11

PgBouncer 1.10

PgBouncer 1.9

备份注解选项（`--annotation`）

使用 `-j` 拆分单个大文件

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

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