概念

本文描述了 etcd 项目所支持的版本。 服务版本管理与支持版本 etcd 版本号采用 x.y.z 格式，其中 x 表示主版本号，y 表示次版本号，z 表示补丁版本号，遵循 语义化版本控制 规范。 新次版本号可能向 API 添加额外功能。 etcd 项目为当前版本及前一个版本维护发布分支。例如，当 v3.5 为当前版本时，v3.4 仍受支持。当 v3.6 发布后，v3.4 即停止支持。 根据严重性和可行性，适用于这两个发布分支的修复（包括安全修复）可能被回溯应用。 必要时，将从这些分支中发布补丁 …

运行时重配置是分布式系统中最为复杂且最容易出错的功能之一，尤其是在基于共识的系统（如 etcd）中。 继续阅读以了解 etcd 运行时重配置命令的设计原理，以及我们如何解决这些问题。 两阶段配置变更确保集群安全 在 etcd 中，每次运行时重配置都必须出于安全考虑，经过 两个阶段 。例如，添加成员时，需先通知集群新配置，再启动新成员。 1 - 通知集群新配置 要将成员添加到 etcd 集群，需通过 API 调用请求将新成员加入集群。这是向现有集群添加新成员的唯一方式。API 调用将在集群就配置变 …

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

在大规模机器部署中，故障是常见现象。当硬件或软件发生故障时，机器会失效。若出现断电或网络问题，多台机器可能同时失效。多种类型的故障也可能同时发生；几乎无法穷举所有可能的故障场景。 本节列举各类故障，并讨论 etcd 的设计如何容忍这些故障。大多数用户（若非全部）均可将特定故障归入某一类故障。为应对罕见或 不可恢复的故障 ，务必 备份 etcd 集群。 次要跟随者故障 当少于一半的跟随者发生故障时，etcd 集群仍可接受请求并持续进展，不会出现重大中断。例如，五个成员的 etcd 集群中发生两个跟 …

etcd v3 使用 gRPC 作为其消息协议。etcd 项目包含一个基于 gRPC 的 Go 客户端 ，以及一个命令行工具 etcdctl ，用于通过 gRPC 与 etcd 集群通信。对于不支持 gRPC 的语言，etcd 提供一个 JSON gRPC 网关 。该网关提供一个 RESTful 代理，可将 HTTP/JSON 请求转换为 gRPC 消息。 使用 gRPC 网关 网关接受 etcd 的 协议缓冲 消息定义的 JSON 映射 。请注意，key 和 value 字段定义为字节数组，因 …

etcd 这个名称源自两个理念：Unix 系统中的“/etc”目录和“d”istributed（分布式）系统。其中，“/etc”目录是用于存储单个系统配置数据的路径，而 etcd 则用于存储大规模分布式系统的配置信息。因此，“d”istributed “/etc”即为 etcd。 etcd 旨在作为大规模分布式系统的通用基础架构。这类系统无法容忍脑裂（split-brain）运行，且愿意牺牲可用性以达成此目标。etcd 以一致且容错的方式存储元数据。etcd 集群旨在提供具备顶级稳定性、可靠性、 …

etcd 是一个一致且持久的键值存储系统。 键值存储通过 gRPC Services 暴露。etcd 为分布式系统提供最强的一致性和持久性保证。 本文规范列出了 etcd 所提供的 API 保证。 值得考虑的 API KV API 范围 范围流 写入 删除 事务 监听 API 监听 租约 API 授予 [撤销] 保活 KV API 支持对键值存储进行直接读取和操作。 监听 API 支持订阅键值存储的变更。 租约 API 支持为键指定生存时间（TTL）。 KV 和 Watch API 均允许访问键 …

本文介绍了 etcd 持久化存储格式：命名规则、内容结构以及可供开发者用于检查存储内容的工具。后续应随着存储模型的变更持续扩展本文内容。本文面向 etcd 开发者，旨在帮助其满足数据恢复需求。 先决条件 以下文章为本文提供了有益的背景信息： etcd 数据模型概述 Raft 概述 （特别是“5.3 日志复制”节）。 概述 长期存在的文件 文件名 主要用途 ./member/snap/db bbolt b+tree 用于存储所有已应用的数据、成员权限信息及元数据。它知晓最新的已应用 WAL 日志索 …

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

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

etcd 学习者成员 Gyuho Lee (github.com/gyuho, Amazon Web Services, Inc.), Joe Betz (github.com/jpbetz, Google Inc.) 背景 成员变更配置一直是运维中最大的挑战之一。回顾常见问题。 1. 集群成员过载领导者 新加入的 etcd 成员初始时无任何数据，因此需要从领导者获取更多更新，直到其日志与领导者同步。此时，领导者网络更可能因负载过重而阻塞或丢弃发往跟随者的心跳。在这种情况下，跟随者可能因选举超时 …

etcd 客户端设计 Gyuho Lee (github.com/gyuho, Amazon Web Services, Inc.), Joe Betz (github.com/jpbetz, Google Inc.) 简介 etcd 服务器通过多年的故障注入测试验证了其稳健性。大多数复杂的应用逻辑已由 etcd 服务器及其数据存储处理（例如，集群成员关系对客户端透明，提案通过 Raft 层转发至领导者）。尽管服务器组件本身正确，但其与客户端的组合需采用一组复杂的协议，以确保在故障条件下仍能保证 …

etcd 旨在可靠地存储更新频率较低的数据，并提供可靠的监听查询。etcd 通过暴露键值对的旧版本，支持低成本的快照和监听历史事件（“时间旅行查询”）。持久化、多版本、并发控制的数据模型非常适合这些应用场景。 etcd 将数据存储在多版本 持久化 键值存储中。当键值对的值被新数据覆盖时，持久化键值存储会保留该键值对的先前版本。键值存储本质上是不可变的；其操作不会就地更新结构，而是始终生成新的已更新结构。在修改后，所有历史版本的键仍可访问并可被监听。为防止数据存储随时间无限增长并避免长期保留旧版本 …

HAProxy 是一个多线程、事件驱动、非阻塞的守护进程。它使用事件多路复用机制调度所有活动，而不依赖系统在多项活动之间切换调度。大多数情况下，HAProxy 只运行一个进程，因此在系统上执行 “ps aux” 时通常只会看到一个 “haproxy” 进程；平滑重载期间是例外，此时旧进程会与新进程并行完成剩余工作。因此，使用 strace 始终可以轻松跟踪其活动。为利用多个处理器，HAProxy 默认会为每个允许使用的处理器启动一个工作线程。除非另有明确配置，传入流量会均匀分配给所有线程，每个 …

部署在多个数据中心的 PostgreSQL 集群，其高可用基于复制实现，复制可以是同步的，也可以是异步的（参见 复制模式 ）。 无论哪种模式，都需要明确以下概念： PostgreSQL 仅在持有领导者键且能够更新领导者键时，才能以主库或备用领导者身份运行。 etcd、ZooKeeper 或 Consul 节点的数量应为奇数：3 个或 5 个！ 同步复制 要构建能够自动容忍单区域故障的多数据中心集群，至少需要 3 个数据中心。 架构图如下： 需要跨不同数据中心部署一个 …

Patroni 集群有两个需要防范未授权访问的接口：分布式配置存储（DCS）和 Patroni REST API。 保护 DCS Patroni 和 patronictl 都会向 DCS 读写数据。 尽管 DCS 本身不包含任何敏感信息，但它允许修改部分 Patroni/PostgreSQL 配置，因此首要保护对象就是 DCS 本身。 具体的保护方式取决于所使用的 DCS 类型。各类 DCS 的认证和加密参数（令牌/基本认证/客户端证书）详见 配置说明 。 通用建议是为所有 DCS 通信启用 …

Patroni 能够与技术栈中的其他工具集成。本节列举了一些集成示例，并不详尽，但希望能为您提供参考和启发。 Barman Patroni 提供了一个名为 patroni_barman 的应用程序，内含与 pg-backup-api 通信的逻辑，可用于远程执行 Barman 操作。 该应用程序目前包含两个子命令：recover 和 config-switch。 patroni_barman recover recover 子命令可用作自定义引导方法或自定义从库创建方法。详情请参阅 …

Patroni 使部署 多节点 Citus 集群变得极为简单。 TL;DR 只需遵循以下几条简单规则： 所有节点上必须安装 Citus 数据库扩展。最低支持的 Citus 版本为 10.0，但为了充分利用工作节点透明主从切换和重启的特性，建议使用至少 Citus 11.2。 集群名称（scope）在所有 Citus 节点上必须相同！ 超级用户凭据在协调节点和所有工作节点上必须相同，且 pg_hba.conf 应允许所有节点之间的超级用户访问。 工作节点到协调节点的 REST API 访问必须被 …

本文涵盖上述指定版本中实现的配置语言。 本文不提供任何提示、示例或建议。 如需此类文档，请参阅参考手册或架构手册。 编号章节在 HAProxy 扁平侧边栏中按顺序排列，支持直接导航。 当 HAProxy 以 HTTP 模式运行时，请求和响应均会被完整分析并索引，因此可基于内容中发现的几乎任何信息构建匹配条件。 然而，理解 HTTP 请求和响应的构成方式，以及 HAProxy 如何对其进行解析，至关重要。掌握这些原理后，编写正确的规则以及排查现有配置将变得更加容易。 首先，HTTP 由一系列 …

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

HAProxy 与以下列出的某些产品集成良好，因此尽管这些产品与 HAProxy 无直接关联，仍在此提及。 4.1. Apache HTTP 服务器 Apache 是事实上的标准 HTTP 服务器。它是一个功能完整且模块化的项目，支持静态文件服务和动态内容处理。Apache 可以作为某些应用服务器的前端。它甚至可以代理请求并缓存响应。在所有这些使用场景中，通常需要一个前端负载均衡器。Apache 可以在多种模式下运行，其中某些模式的开销较大。某些模块仍需依赖开销较大的预派生模型，这将导致 …

同时存在多个以主库身份运行的 PostgreSQL 实例，可能因时间线分叉而导致事务丢失，这种情况也称为脑裂（split-brain）问题。为了避免脑裂，Patroni 需要确保在 DCS 中的领导者键过期后，PostgreSQL 不再接受任何事务提交。正常情况下，Patroni 会在领导者锁更新失败时尝试停止 PostgreSQL 来实现这一目标。然而，以下各种原因可能导致该机制失效： Patroni 因程序缺陷、内存溢出或系统管理员误操作而崩溃。 PostgreSQL 关闭速度过慢。 系统 …

代码覆盖率 pgBackRest 致力于对 /src 目录下的核心 C 代码实现完整的函数、分支和行覆盖。 函数覆盖率和行覆盖率均已达到 100%，无任何例外。 分支覆盖率排除了宏内部的分支和 assert() 调用。宏有专属的单元测试，因此无需在每处调用时都进行测试。assert 断言不要求完整的分支覆盖，因为它们测试的是应当始终为真的条件。 目录 函数 分支 行 build/common 32/32 (100.00%) 72/72 (100.00%) 268/268 (100.00%) …

教程 为 Postgres Plus Standard Server 配置 PgBouncer 对 PgBouncer 概念的精彩概述。 连接池究竟有什么意义？ 讨论各种池化模式之间的差异。 支持 项目主页 （GitHub） 问题追踪 （GitHub） PgBouncer 专区 （Stack Overflow） 社区讨论 （GitHub）

Patroni 使用 PostgreSQL 流复制。关于流复制的更多信息，请参阅 Postgres 文档 。默认情况下，Patroni 将 PostgreSQL 配置为异步复制。选择哪种复制方案取决于你的业务需求。建议同时研究异步和同步复制，以及其他高可用方案，以确定最适合自己的解决方案。 异步模式的持久性 在异步模式下，集群允许丢失部分已提交的事务以保证可用性。当主库故障或因任何其他原因变得不可用时，Patroni 会自动将一个足够健康的备库提升为主库。尚未复制到该备库的事务将残留在主库的" …

3.5.1. 高级功能：系统管理 HAProxy 旨在在常规生产环境中保持极高的稳定性与安全性。它以单个可执行文件的形式提供，无需任何安装过程。多个版本可轻松共存，因此建议按重要性顺序逐步升级实例，而非一次性全部迁移。配置文件易于版本化。配置检查可在离线状态下完成，无需重启可能失败的服务。在配置检查过程中，可检测到多种高级错误（例如规则相互隐藏，或无法生效的会话粘性），并提供详细的警告信息与配置建议以修复问题。配置文件的向后兼容性极为持久，版本 1.5 仍完全支持 13 年前为版本 1.1 编 …

etcd 是一个强一致的分布式键值存储。本套指南涵盖 etcd 3.7 系列的安装与运行、API 应用开发、设计原理、性能衡量，以及集群升级与降级。 从 快速入门 开始，部署本地单成员集群；通过 安装 了解受支持的安装路径；或参考 运维指南 进行生产环境部署。

在本段中，列举了一些在 HAProxy 中非常常见但未必存在于其他负载均衡器上的功能。 3.4.1. 标准功能：采样与信息转换 HAProxy 支持使用多种“样本提取函数”进行信息采样。其原理是提取称为样本的信息片段，以供即时使用。该机制用于实现会话粘性、构建条件判断、生成日志信息或丰富 HTTP 头。 样本可从多种来源获取： 常量：整数、字符串、IP 地址、二进制块； 进程：日期、环境变量、服务器/前端/后端/进程状态、字节/连接数及速率、队列长度、随机数生成器等 变量：会话级、请求级、响应 …

本段将列举 HAProxy 实现的若干功能，其中部分功能是现代负载均衡器普遍具备的特性，另一些则是 HAProxy 架构带来的直接优势。更高级的功能将在下一节中详细说明。 3.3.1. 基本功能：代理 代理是指通过两个独立连接在客户端与服务器之间传输数据的动作。HAProxy 支持以下基本功能，涉及代理和连接管理： 为服务器提供干净的连接，以保护其免受客户端缺陷或攻击的影响； 监听多个 IP 地址和/或端口，包括端口范围； 透明接收：拦截目标为任意 IP 地址的流量，即使该地址并不属于本地系统 …

pgBadger 是一款使用 Perl 编写的高性能独立 PostgreSQL 日志分析器。它可以读取 PostgreSQL 或 PgBouncer 日志，并生成 HTML、文本、二进制、JSON 或原始 CSV 输出。HTML 报告自带全部资源，图表可交互、缩放并保存为 PNG，只需浏览器即可查看。 为什么使用 pgBadger pgBadger 面向大规模日志与日常运维场景设计： 单个 Perl 程序，不强制依赖非核心 Perl 模块； 自动识别 …

HAProxy 用于指代产品，而 HAProxy 用于指代可执行程序、软件包或进程。然而，两者常被互换使用，且均发音为 H-A-Proxy。早期，“HAProxy”曾代表“高可用性代理”，名称以两个独立单词书写，但如今其含义已仅限于“HAProxy”。 3.1. HAProxy 是与非 HAProxy 是： TCP 代理：可从监听套接字接收 TCP 连接，连接至服务器，并将这两个套接字绑定在一起，从而实现双向流量传输；支持任一侧使用 IPv4、IPv6 或 Unix 套接字，因此可提供一种简便 …

pgbouncer 是 PostgreSQL 的连接池。任何目标应用都可以像连接 PostgreSQL 服务器一样连接到 pgbouncer，pgbouncer 将负责创建到实际服务器的连接，或者复用已有的连接。 pgbouncer 的目标是降低向 PostgreSQL 建立新连接所带来的性能损耗。 为了在连接池化时不破坏事务语义，pgbouncer 在轮换连接时支持多种池化类型： 会话池化：最温和的方式。当客户端连接时，将为其分配一个服务端连接，并在客户端保持连接期间始终持有。当客户端断开时， …

本文旨在向所有尚未了解 HAProxy 的用户以及希望重新认识该软件（尤其是熟悉旧版本的用户）提供入门引导。本文主要目的在于为用户提供充分信息，以判断 HAProxy 是否符合其需求。高级用户可能在此发现某些解决方案的片段，仅因此前未意识到某项新功能的存在。此外，本文还提供了部分容量规划信息，说明了产品的生命周期，并对部分功能重叠的产品进行了对比。 本文不提供任何配置帮助或提示，但说明了如何查找相关文档。本指南以 HAProxy 侧边栏中的扁平主题页面序列形式呈现。 负载均衡是指将多个组件聚合 …

简介 pgBackRest 是一款可靠的 PostgreSQL 备份与恢复解决方案，可无缝扩展以应对超大规模数据库和各类工作负载。 pgBackRest v2.59.1 是当前稳定版本。发布说明请查阅 发布历史 页面。 如果您喜欢 pgBackRest，欢迎在 GitHub 上给我们点星！ 新闻 2026 年 8 月 17 日 - pgBackRest 2.59.1 正式发布 2026 年 7 月 20 日 - 新的发行版 tarball 2026 年 7 月 20 日 - …

连接轮换时，按激进程度分为以下几种策略： 会话池化 最温和的方式。当客户端连接时，将为其分配一个服务端连接，并在客户端保持连接期间始终持有。当客户端断开时，服务端连接将放回连接池。此模式支持所有 PostgreSQL 特性。 事务池化 仅在事务期间为客户端分配服务端连接。当 PgBouncer 检测到事务结束时，服务端连接将放回连接池。此模式会破坏 PostgreSQL 的部分会话级特性，只有在应用程序配合、不使用不兼容特性的情况下才可使用。不兼容特性详见下表。 语句池化 最激进的方式。这是事 …

Patroni 是一个基于 Python 构建的高可用 PostgreSQL 解决方案模板框架。它最初 fork 自 Compose 公司的 Governor 项目，并在此基础上引入了大量新特性。 更多背景资料，请参阅： PostgreSQL HA with Kubernetes and Patroni ——Josh Berkus 在 KubeCon 2016 上的演讲（视频） 2016 年 2 月 Zalando 技术博客文章 开发状态 Patroni 正处于活跃开发阶段，欢迎社区贡献。详情 …

警告 在内存受限的系统上运行 Python 3.11+ 版本的 Patroni 如果系统设置了严格的内存限制，例如启用 PostgreSQL 推荐的 vm.overcommit_memory=2，并使用 Python 3.11 或更高版本，可能出现以下异常： Patroni 表面上保持健康； PostgreSQL 继续运行； Patroni REST API 失去响应； 操作系统仍显示 Patroni 正在监听 REST API 端口； Patroni 日志看似正常，但可能短暂出现 …