任务

目的 加速 PR 管理。 etcd 的 PR 列表位于 https://github.com/etcd-io/etcd/pulls PR 可能包含多种标签、里程碑、评审人等。标签的详细列表可参见 https://github.com/kubernetes/kubernetes/labels 以下是 PR 中便于参考的若干搜索示例： Open PRS for milestone etcd-v3.4 PRs under investigation 适用范围 本文指南作为管理 etcd 中 PR 的主 …

目的 加快问题管理。 etcd 问题列于 https://github.com/etcd-io/etcd/issues ，并以标签标识。例如，被识别为缺陷的问题最终将被标记为 area/bug 。新创建的问题初始时无标签，但通常由 etcd 维护者和活跃贡献者根据其分析结果添加标签。标签的详细列表可参见 https://github.com/kubernetes/kubernetes/labels 以下是为方便起见预设的若干问题搜索： Bugs Help Wanted Longest …

在一般情况下，从 etcd 2.3 升级到 3.0 可以实现零停机滚动升级： 逐一停止 etcd v2.3 进程，并替换为 etcd v3.0 进程 在所有 v3.0 进程运行后，集群即可使用 v3.0 的新特性 在 开始升级 之前，请通读本指南其余部分以做好准备。 升级检查列表 警告 从 没有 v3 数据的 v2 迁移 时，如果 etcd 从现有快照恢复，但不存在 v3 ETCD_DATA_DIR/member/snap/db 文件，etcd v3.2+ 服务器会发生崩溃。这种情况出现在服务器 …

在一般情况下，从 etcd 3.0 升级到 3.1 可以实现零停机滚动升级： 逐一停止 etcd v3.0 进程，并替换为 etcd v3.1 进程 在所有 v3.1 进程运行后，集群即可使用 v3.1 的新特性 在 开始升级 之前，请通读本指南其余部分以做好准备。 升级检查列表 警告 从 没有 v3 数据的 v2 迁移 时，如果 etcd 从现有快照恢复，但不存在 v3 ETCD_DATA_DIR/member/snap/db 文件，etcd v3.2+ 服务器会发生崩溃。这种情况出现在服务器 …

在一般情况下，从 etcd 3.1 升级到 3.2 可以实现零停机滚动升级： 逐一停止 etcd v3.1 进程，并替换为 etcd v3.2 进程 在所有 v3.2 进程运行后，集群即可使用 v3.2 的新特性 在 开始升级 之前，请通读本指南其余部分以做好准备。 升级检查列表 警告 从 没有 v3 数据的 v2 迁移 时，如果 etcd 从现有快照恢复，但不存在 v3 ETCD_DATA_DIR/member/snap/db 文件，etcd v3.2+ 服务器会发生崩溃。这种情况出现在服务器 …

在一般情况下，从 etcd 3.2 升级到 3.3 可以实现零停机滚动升级： 逐一停止 etcd v3.2 进程，并替换为 etcd v3.3 进程 在所有 v3.3 进程运行后，集群即可使用 v3.3 的新特性 在 开始升级 之前，请通读本指南其余部分以做好准备。 升级检查列表 警告 从 没有 v3 数据的 v2 迁移 时，如果 etcd 从现有快照恢复，但不存在 v3 ETCD_DATA_DIR/member/snap/db 文件，etcd v3.2+ 服务器会发生崩溃。这种情况出现在服务器 …

在一般情况下，从 etcd v3.6 升级到 v3.7 可以实现零停机滚动升级： 逐一停止 etcd v3.6 进程，并替换为 etcd v3.7 进程 在所有 v3.7 进程运行后，集群即可使用 v3.7 中的新特性 在 开始升级 之前，请通读本指南其余部分以做好准备。 升级检查列表 更新 3.6 重要 在升级到 3.7 之前，请确保所有 3.6 成员均已更新至 3.6.11 或更高版本。较早的 3.6 补丁版本可能与 3.7 的滚动升级不兼容。 V2 存储系统 v3.7 版本中已完全移除 …

在一般情况下，从 etcd 3.3 升级到 3.4 可以实现零停机滚动升级： 逐一停止 etcd v3.3 进程，并替换为 etcd v3.4 进程 在所有 v3.4 进程运行后，集群即可使用 v3.4 的新特性 在 开始升级 之前，请通读本指南其余部分以做好准备。 升级检查列表 警告 从 没有 v3 数据的 v2 迁移 时，如果 etcd 从现有快照恢复，但不存在 v3 ETCD_DATA_DIR/member/snap/db 文件，etcd v3.2+ 服务器会发生崩溃。这种情况出现在服务器 …

在一般情况下，从 etcd v3.6 降级到 v3.5 可以实现零停机、滚动降级： 逐一停止 etcd v3.6 进程，并替换为 etcd v3.5 进程 启用降级后，集群将不再支持 v3.6 中的新特性 开始 降级 前，请阅读本指南其余内容并做好准备。 降级检查列表 v3.6 版本到 v3.5 版本的突出变更： 不同标志 如果在 v3.6 配置中使用了以下任一标志，请在降级至 v3.5 时确保移除、重命名或更改其默认值。 说明 本文的差异对比基于版本 v3.6.0 和 v3.5.18。实际差异 …

在一般情况下，从 etcd 3.5 降级到 3.4 可以实现零停机、滚动降级： 逐一停止 etcd 3.5 进程，并替换为 etcd 3.4 进程 启动任意 3.4 进程后，集群将不再支持 3.5 中的新特性 开始 降级 前，请阅读本指南其余内容并做好准备。 降级检查列表 content/enhttps://etcd.io/docs/v3.5/op-guide/authentication/rbac.md 警告 如果集群启用了身份认证，将无法回滚降级至 3.5 版本，因为 3.5 更改了与身份认 …

在一般情况下，从 etcd 3.4 升级到 3.5 可以实现零停机滚动升级： 逐一停止 etcd v3.4 进程，并替换为 etcd v3.5 进程 在所有 v3.5 进程运行后，集群即可使用 v3.5 的新特性 在 开始升级 之前，请通读本指南其余部分以做好准备。 升级检查列表 警告 从 没有 v3 数据的 v2 迁移 时，如果 etcd 从现有快照恢复，但不存在 v3 ETCD_DATA_DIR/member/snap/db 文件，etcd v3.2+ 服务器会发生崩溃。这种情况出现在服务器 …

在一般情况下，从 etcd v3.7 降级到 v3.6 可以实现零停机、滚动降级： 逐一停止 etcd v3.7 进程，并替换为 etcd v3.6 进程 启用降级后，集群将不再支持 v3.7 中的新特性 开始 降级 前，请阅读本指南其余内容并做好准备。 降级检查列表 v3.7 与 v3.6 之间的主要差异： 不同标志 v3.7 未引入任何新标志，因此 v3.6 进程可接受 v3.7 配置中的所有标志，降级时无需进行配置更改。 说明 本次差异对比基于版本 v3.7.0-rc.0 与 …

在一般情况下，从 etcd v3.5 升级到 v3.6 可以实现零停机时间的滚动升级： 逐一停止 etcd v3.5 进程，并替换为 etcd v3.6 进程 所有 v3.6 进程运行后，集群即可使用 v3.6 中的新特性 在 开始升级 之前，请通读本指南其余部分以做好准备。 升级检查列表 更新 3.5 重要 升级至 3.6 之前，请确保 所有 3.5 版本的成员均已更新至 3.5.32 或更高版本 。补丁版本 3.5.24 至 3.5.26 修复了多个潜在的升级障碍；3.5.32 增加了 …

本节包含与升级 etcd 集群及应用程序相关的特定文档。 升级策略 升级前请注意，etcd 仅支持以下两种升级场景： 补丁升级：在同一小版本内升级补丁版本（例如 3.7.0 至 3.7.1）。 小版本升级：每次仅升级一个次版本（例如 3.6 至 3.7）。不支持跳过次版本的升级，此类操作很可能失败。请在升级至下一个次版本前，先更新至最新补丁版本。 升级 etcd v3.x 集群 将 etcd 从 3.0 升级至 3.1 将 etcd 从 3.1 升级至 3.2 将 etcd 从 3.2 升级至 …

本节包含与降级 etcd 集群及应用程序相关的文档。 降级 etcd v3.x 集群 将 etcd 从 3.5 降级至 3.4 将 etcd 从 3.6 降级至 3.5 将 etcd 从 3.7 降级至 3.6

etcd 内置了自动数据损坏检测机制，以防止成员状态发生不一致。 启用数据损坏检测 数据损坏检测可通过以下方式执行： 初始检查，通过 --experimental-initial-corrupt-check 标志启用。 定期检查包括： 已压缩的修订版本哈希，通过 --experimental-compact-hash-check-enabled 标志启用。 最新修订版本哈希，通过 --experimental-corrupt-check-time 标志启用。 引导过程中将执行初始检查。 成员将比 …

etcd 支持增量式运行时重配置，允许用户在运行时更新集群成员。 重新配置请求仅在集群多数成员正常运行时才能处理。生产环境中强烈建议始终将集群规模设置为大于二。从两成员集群中移除成员是不安全的。两成员集群的多数为两个。若在移除过程中发生故障，集群可能无法继续推进，需 从多数故障中重启 。 为更好地理解运行时重配置的设计原理，请阅读 运行时重配置文档 。 重新配置用例 本节将介绍集群重新配置的一些常见原因。大多数情况仅涉及添加或移除成员的组合操作，具体说明如下，详见 集群重新配置操作 。 批量升级 …

每个 etcd 服务器通过其客户端端口上的 HTTP 端点提供本地监控信息。监控数据对于系统健康检查和集群调试均具有实用价值。 调试端点 若设置 --log-level=debug，etcd 服务器将在其客户端端口的 /debug 路径下导出调试信息。设置 --log-level=debug 时需谨慎，因为会导致性能下降和日志输出过于 verbose。 /debug/pprof 端点是标准的 Go 运行时性能分析端点。该端点可用于分析 CPU、堆、互斥锁和协程的使用情况。例如，以下命令通过 go …

概述 etcd 集群需要定期维护以保持可靠性。根据 etcd 应用的需求，此类维护通常可以自动化执行，且无需停机或显著降低性能。 本文所述的 etcd 维护操作均用于管理 etcd 键空间所占用的存储资源。若未能充分控制键空间大小，系统将通过存储空间配额进行防护；当 etcd 成员可用空间不足时，配额将触发集群范围的告警，使系统进入受限操作的维护模式。为避免键空间写入空间耗尽，必须对 etcd 键空间历史数据执行压缩。存储空间本身可通过整理碎片来回收。此外，定期对 etcd 成员状态进行快照备份 …

gRPC 代理是运行在 gRPC 层（L7）的无状态 etcd 反向代理。该代理旨在降低核心 etcd 集群的总体处理负载。为实现横向扩展，代理会合并监听和租约 API 请求。为防止恶意客户端对集群造成影响，代理会缓存键范围请求。 gRPC 代理支持多个 etcd 服务器端点。代理启动时，会随机选择一个 etcd 服务器端点使用。该端点将处理所有请求，直至代理检测到端点故障。若 gRPC 代理检测到端点故障，且存在其他可用端点，则会切换至其他端点，以向客户端隐藏故障。未来可能支持其他重试策略，例 …

etcd 网关是什么 etcd 网关是一个简单的 TCP 代理，负责将网络数据转发至 etcd 集群。网关为无状态且透明的；它既不检查客户端请求，也不干扰集群响应。网关不会终止 TLS 连接，不会代表客户端执行 TLS 握手，也不会验证连接是否已加密。 网关支持多个 etcd 服务器端点，并采用简单的轮询策略。它仅将请求路由至可用端点，并向客户端隐藏故障。未来可能支持其他重试策略，例如加权轮询。 何时使用 etcd 网关 每个访问 etcd 的应用程序都必须首先知晓 etcd 集群客户端端点的地 …

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

本文指南展示了如何使用 Docker 以 静态引导过程 运行 etcd。 Docker 为使 Docker 主机外部的客户端能够访问 etcd API，请使用容器的主机 IP 地址。有关获取 IP 地址的详细信息，请参见 docker inspect 。或者，可向 docker run 命令指定 --net=host 标志，以跳过将容器置于独立网络栈中的操作。 运行单节点 etcd 配置 etcd 时，请使用主机 IP 地址： export NODE1=192.168.1.21 配置 …

以下演示如何作为 Kubernetes StatefulSet 执行 静态引导过程 。 示例 Manifest 本文档包含用于在 Kubernetes 中部署静态 etcd 集群的服务和有状态集（StatefulSet）配置。 如果将清单内容复制到名为 etcd.yaml 的文件中，可使用以下命令将其应用到集群。 $ kubectl apply --filename etcd.yaml 应用后，请等待 Pod 进入就绪状态。 $ kubectl get pods NAME READY …

概述 静态启动 etcd 集群要求每个成员均知晓集群中的其他成员。在某些情况下，集群成员的 IP 地址可能无法提前确定。在这些情况下，可以借助发现服务来引导启动 etcd 集群。 一旦 etcd 集群启动并运行，添加或移除成员需通过 运行时重配置 完成。为更好地理解运行时重配置的设计原理，建议阅读 运行时配置设计文档 。 本文将介绍用于引导 etcd 集群的以下机制： 静态 etcd 发现 DNS 发现 每个引导机制将用于创建一个由三台机器组成的 etcd 集群，具体细节如下： 名称 地址 主机 …

etcd 支持自动 TLS，以及通过客户端证书实现的客户端到服务器和对等成员（服务器到服务器 / 集群）通信的身份认证。请注意，etcd 默认不启用 基于 RBAC 的身份认证 或传输层的身份认证功能，以降低用户入门时的使用门槛。此外，更改此默认设置将对该项目造成破坏性变更，该项目自 2013 年确立以来一直保持该设定。未启用安全功能的 etcd 集群可能使数据暴露于任意客户端。 要快速上手，请先准备一个 CA 证书以及一个成员的已签名密钥对。建议为集群中的每个成员创建并签署新的密钥对。 为方便 …

概述 身份认证功能自 etcd 2.1 版本起引入。etcd v3 API 对身份认证功能的 API 和用户界面进行了轻微调整，以更好地适配新的数据模型。本文旨在帮助用户在 etcd v3 中设置基本的身份认证和基于角色的访问控制。 特殊用户和角色 有一个特殊用户 root，以及一个特殊角色 root。 用户 root root 用户在激活身份认证前必须先创建，该用户拥有对 etcd 的完全访问权限。root 用户的设计初衷是用于系统管理：管理角色和普通用户。root 用户必须拥有 root 角 …

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 …

etcd embed go 包提供了一种简便方式，可将 etcd 服务器直接嵌入应用程序。 有关详细信息，请参见 embed 包文档 。

etcd 提供了一个 gRPC 解析器，用于支持一种替代名称系统，该系统从 etcd 获取端点以发现 gRPC 服务。其底层机制基于监听以服务名称为前缀的键的更新。 请注意，此功能为实验性功能，因为它依赖于 google.golang.org/grpc/resolver 包，而该包在 grpc-go 中仍处于实验阶段。 使用 go-grpc 实现 etcd 发现 etcd 客户端为使用 etcd 后端解析 gRPC 端点提供了 gRPC 解析器。该解析器通过一个 etcd 客户端进行初始化： …

用户通常通过设置或获取键的值来与 etcd 交互。本节介绍如何使用 etcdctl（用于与 etcd 服务器交互的命令行工具）实现这一操作。此处描述的概念同样适用于 gRPC API 或客户端库 API。 etcdctl 与 etcd 通信时所使用的 API 版本可通过 ETCDCTL_API 环境变量设置为 2 或 3。默认情况下，主分支（3.4）上的 etcdctl 使用 v3 API，而较早版本（3.3 及更早）默认使用 v2 API。 请注意，使用 v2 API 创建的任何键均无法通过 …

默认情况下，etcd 的配置在平均网络延迟较低的本地网络环境中应能良好运行。然而，当在多个数据中心之间或高延迟网络上使用 etcd 时，可能需要调整心跳间隔和选举超时设置。 网络并非延迟的唯一来源。每个请求和响应都可能受到领导者和跟随者上慢速磁盘的影响。每个超时时间均表示从请求发出到从另一台机器成功返回响应的总时间。 时间参数 本文所依赖的分布式共识协议依赖两个独立的时间参数，以确保当某个节点停滞或离线时，其他节点能够完成领导权交接。第一个参数称为 心跳间隔（Heartbeat …

如果 etcd 项目任何部分存在缺陷或文档错误，请通过 打开问题 告知我们。我们高度重视缺陷和错误，认为任何问题都不算太小。创建缺陷报告前，请确认尚未存在报告相同问题的议题。 为了使错误报告准确且易于理解，请尽量编写如下格式的错误报告： 具体。尽可能提供详细信息：包括版本号、运行环境、配置信息等。若该问题与运行 etcd 服务器相关，请附上 etcd 日志（包含 etcd 配置的启动日志尤为重要）。 可复现。请提供复现问题的完整步骤。我们理解某些问题可能难以复现，请尽可能提供可能导致问题的步骤。 …

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 …

先决条件 安装 etcd 之前，请参阅以下页面： [支持的平台][] [硬件建议][] 安装预构建二进制文件 安装 etcd 最简便的方式是使用预构建的二进制文件： 从 Releases 下载适用于当前平台的压缩归档文件，选择 v3.7.0 或更高版本。 解压归档文件。解压后会生成一个包含二进制文件的目录。 将可执行二进制文件添加到 PATH。例如，可将二进制文件重命名或移动到 PATH 中的目录（如 /usr/local/bin），也可将上一步创建的目录添加到 PATH。 在 shell 中验 …

先决条件 安装 etcdctl 和 etcdutl 设置本地集群 快照数据库 snapshot 用于保存 etcd 数据库的指定时间点快照： etcdctl --endpoints=$ENDPOINT snapshot save DB_NAME 全局选项 etcdctl --endpoints=[127.0.0.1:2379], gRPC endpoints 快照只能从一个 etcd 节点请求，因此 --endpoints 标志中应仅包含一个端点。 etcd 工具 -w, --write-out …

先决条件 安装 etcd 和 etcdctl 检查整体状态 使用 endpoint status 检查 --endpoints 标志中指定的每个端点的总体状态： etcdctl endpoint status (--endpoints=$ENDPOINTS|--cluster) 选项 --cluster[=false]: use all endpoints from the cluster member list 检查健康状况 使用 endpoint health 检查 --endpoints …

先决条件 确保已安装 etcd 和 etcdctl 。 检查 etcd 集群是否处于活跃状态。 进行领导者选举 etcdctl 命令用于在 etcd 集群中执行选举操作。该命令确保同一时间仅有一个客户端可成为领导者。 etcdctl --endpoints=$ENDPOINTS elect <election-name> [proposal] etcdctl --endpoints=$ENDPOINTS elect election-name p1 选项 --endpoints : …

LOCK 使用指定名称获取一个分布式互斥锁。锁获取成功后，将一直持有，直至 etcdctl 终止。 先决条件 安装 etcd 和 etcdctl 创建锁 lock 用于分布式锁： etcdctl --endpoints=$ENDPOINTS lock mutex1 选项 endpoints - 定义集群中机器地址的逗号分隔列表。 ttl - 锁会话的超时时间，单位为秒。

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 …

先决条件 安装 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 …

先决条件 安装 etcd 和 etcdctl 。 运行中的 etcd 集群。 术语 以下是本文中使用的部分关键术语的定义，这些术语将在 Example 示例中出现。 术语 定义 etcdctl 用于与 etcd 服务器交互的命令行工具。 txn 命令 txn 命令是“事务”的缩写。它从标准输入读取多个 etcd 请求，并将其作为单个原子事务执行。事务包含一组条件、一组在所有条件均为真时执行的请求，以及一组在任一条件为假时执行的请求。有关更多信息，请参阅 etcdctl 键值命令 。 …

先决条件 安装 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 …

HAProxy 旨在以极低的权限运行。使用它的标准方式是将其隔离到 chroot 环境中，并将其权限降级为非 root 用户，且该用户在该环境内没有任何权限，从而确保未来若发现任何漏洞，其被攻破也不会影响系统其余部分。 为执行 chroot 操作，进程必须首先以 root 用户身份启动。手动构建 chroot 环境并在其中启动进程毫无意义，这类 chroot 环境难以构建，通常无法得到妥善维护，且包含的缺陷远多于主文件系统。一旦发生入侵，攻击者可利用特意构建的文件系统。不幸的是，许多系统管理员 …

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

有时会有人报告：系统重启后 HAProxy 服务没有启动，但手动启动又能正常工作。这通常出现在使用 keepalived 等集群 IP 地址机制、只把服务 IP 分配给主节点的环境中。HAProxy 绑定 0.0.0.0 时一切正常，改为绑定虚拟 IP 后却无法启动。原因是服务启动时，本地节点尚未持有该虚拟 IP；HAProxy 尝试绑定时，系统会因其不是本地 IP 地址而拒绝操作。正确的解决办法不是推迟 HAProxy 服务启动——这无法应对服务重启——而是把系统配置为允许绑定非本地地址。在 …

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

可以查询 HAProxy 的运行状态。最常用的机制是 HTTP 统计信息页面。该页面还提供了一种用于监控工具的替代 CSV 输出格式。相同的格式也通过 Unix 套接字提供。 统计信息按类别分组，类别以域（domain）命名，对应 HAProxy 的多个组件。当前提供两个域：proxy 和 resolvers。若未指定，将选择 proxy 域。请注意，仅代理的统计信息会显示在 HTTP 页面上。 9.1. CSV 格式 可通过 Unix 套接字或 HTTP 页面查阅统计信息。两种方式均提供 …

对于日志记录，HAProxy 始终依赖 syslog 服务器，因为它不执行任何文件系统访问。标准用法是通过 UDP 将日志发送至日志服务器（默认端口为 514）。通常情况下，该配置会指向 127.0.0.1，即本地 syslog 守护进程运行的位置，但也常通过网络将日志发送至集中式服务器。在主动-主动场景中，集中式服务器尤其具有优势，可确保日志按到达顺序合并。HAProxy 也可使用 Unix 套接字将日志发送至本地 syslog 守护进程，但强烈不建议使用，因为当 syslog 服务器重启而 …

HAProxy 通常大部分时间运行在系统空间，仅小部分时间运行在用户空间。经过精细调优的 3.5 GHz CPU 在单核满载 100% 时，每秒可维持约 80000 次端到端连接的建立与关闭。当单核达到饱和时，典型数值为： 长 TCP 连接或大 HTTP 对象：系统占用 95%，用户占用 5% 短 TCP 连接或关闭模式下的小 HTTP 对象：系统占用 85%，用户占用 15% 持久连接模式下的小 HTTP 对象：系统占用 70%，用户占用 30% 规则处理和正则表达式的数量会增加用户空间部分 …

先决条件 安装 etcdctl 设置本地集群 按前缀获取键 $ 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 …

HAProxy 采用简单、快速的池式内存管理。由于 HAProxy 只使用少量不同的对象类型，从已经包含适当大小对象的内存池中获取新对象，远比针对每种大小分别调用 malloc() 高效。内存池按栈或 LIFO 方式组织，新分配的对象会优先取自刚刚释放、仍在 CPU 缓存中的对象。大小相近的内存池会合并，以减少内存碎片。 默认配置以性能为先：每个释放的对象都会放回原来的内存池；已分配对象不会归还给系统，因为预计很快便会再次使用。 可以在 CLI 中使用 “show pools” 命令检查各内存 …

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

HAProxy 支持优雅停止和强制停止。强制停止操作简单：当向 HAProxy 进程发送 SIGTERM 信号时，进程立即退出，所有已建立的连接将被关闭。优雅停止通过向 HAProxy 进程发送 SIGUSR1 信号触发，其操作仅包括解除对监听端口的绑定，但会继续处理现有连接，直至所有连接关闭。当最后一个连接关闭后，进程退出。 硬停止方法用于服务管理脚本的“stop”或“restart”动作。 优雅停止用于“reload”动作，该动作尝试在新进程中无缝重载新配置。 在重载或重启过程中，新的 …

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

先决条件 安装 etcdctl 步骤 使用 put 子命令写入键值对： etcdctl --endpoints=$ENDPOINTS put foo "Hello World!" 其中： foo 为键名称 "Hello World!" 为用引号括起的值

本文介绍如何启动、停止、管理 HAProxy 及排查其故障，也会说明一些已知限制和应避免的陷阱。本文不涉及 HAProxy 的配置方法；相关内容请参阅 configuration.txt 。 本文假定读者具备类 Unix 操作系统的管理能力，日常使用 shell，并熟悉 strace、tcpdump 等故障排查工具。

在线交流 如有疑问、需要互动式故障排查帮助，或希望与其他 Patroni 用户交流，欢迎加入 PostgreSQL Slack 的 #patroni 频道。 报告缺陷 提交缺陷报告前，请务必 在最新版 Patroni 上复现该问题！同时请检查 Issues Tracker 中是否已存在相同问题。 运行测试 运行 behave 测试的前置条件： 需要安装包含 contrib 模块的 PostgreSQL 软件包。 PostgreSQL 二进制文件必须在 PATH 中可访问。您可能需要通过类似 …

先决条件 安装 etcdctl 步骤 使用 get 子命令从 etcd 读取： $ etcdctl --endpoints=$ENDPOINTS get foo foo Hello World! $ 其中： foo 为请求的键 Hello World! 为获取的值 或者，以格式化输出形式： $ etcdctl --endpoints=$ENDPOINTS --write-out="json" get foo …

本文的强项之一无疑是其精确的日志记录。它可能为这类产品提供了最详尽的信息级别，这对排查复杂环境中的问题至关重要。日志中提供的标准信息包括客户端端口、TCP/HTTP 状态定时器、流在终止时的精确状态以及精确的终止原因，关于将流量导向服务器的决策信息，当然还包括捕获任意头字段的能力。 为提升系统管理能力的响应速度，该功能可清晰呈现所遇到的内部与外部问题，且可同时将日志发送至多个目标，并针对不同级别设置过滤器： 全局进程级日志（系统错误、启动/停止等） 每个实例的系统和内部错误（资源不足、缺陷等） …

本节介绍将独立 PostgreSQL 实例转换为 Patroni 集群的操作流程。 如需从零开始部署 Patroni 集群（不使用已有 PostgreSQL 实例），请参阅 运行与配置 。 操作步骤 以下是将现有 PostgreSQL 集群转换为 Patroni 托管集群的步骤概览。本步骤假设现有集群的所有节点当前均在运行，并且您 不打算 在迁移过程中修改 PostgreSQL 配置。具体步骤如下： 按照 Patroni 配置中 认证 章节的说明创建 PostgreSQL 用户。下方代码块中提 …

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

pgBadger 是一个开放维护的项目。缺陷报告、功能建议、文档修复与代码补丁都通过上游 GitHub 仓库处理。 缺陷与功能需求 升级到最新正式版本，确认问题仍然存在。 搜索开放问题 与已关闭问题 ，查看是否已有答案。 把问题缩减为仍能复现的最小安全日志样本与命令行。 删除凭据、敏感 SQL、绑定值、主机名、地址与业务数据。 创建新问题 ，写明 pgBadger 版本、操作系统、输入格式、完整选项、实际结果与预期结果。 对于崩溃或解析错误，只应附上复现边界所需的最少脱敏日志。完整生产日志或生成 …

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

在每个 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 …

HAProxy 是一个采用 GPLv2 许可证的开源项目，这意味着只要在请求时提供源代码，任何人都可以自由分发该软件，尤其是当进行了任何修改时。 HAProxy 以名为“master”或“mainline”的主开发分支持续演进，当代码被认为稳定后，便会从该分支衍生出新的分支。许多网站自愿在生产环境中运行开发分支，或为参与项目，或因需要前沿功能，其反馈对修复缺陷、评估所开发版本的整体质量与稳定性具有极高价值。 当代码稳定到一定程度时创建的新分支即构成稳定版本，通常会维护数年，因此即使未处于最新分 …

Patroni 还支持通过"备用集群"功能向远程数据中心（Region）运行级联复制。这类集群具有以下特点： 备用领导者（standby leader）：行为与普通集群领导者基本相同，区别在于它从远程节点进行复制。 级联从库：从备用领导者进行复制。 备用领导者在 DCS 中持有并更新领导者锁。若领导者锁过期，级联从库将通过选举从备用节点中选出新的领导者。 备用集群与其所复制的主集群之间没有其他关联。特别是，若双方使用同一个 DCS，则不能共享相同的 DCS 作用域（scope）。双方除复制信息 …

增量模式先以二进制形式保存解析统计，再生成每日 HTML 报告、每周累计报告，以及把它们组织起来的日历式索引。它适合反复处理轮转日志，同时避免重复统计相同记录。 生成每日与每周报告 在每日轮转完成后运行 pgBadger，并指定一个持久化输出目录： crontab 0 4 * * * /usr/bin/pgbadger -I -q /var/log/postgresql/postgresql.log.1 -O /var/www/pg_reports/ -I 启用增量模式，-O 指定保存二进制状态 …

Patroni 支持自定义新从库的创建方式，也支持定义全新空集群在引导时的行为。两者有明确区别：只有当 DCS 中存在 initialize 键时，Patroni 才会创建从库。若不存在该键，Patroni 将在第一个抢到初始化锁的节点上独占执行引导流程。 引导（Bootstrap） PostgreSQL 提供了 initdb 命令来初始化新集群，Patroni 默认即调用此命令。在某些场景下——尤其是将现有集群复制一份来创建新集群时——有必要用自定义操作替换内置方式。Patroni 支持执行 …

pgBadger 提供两种互补的多进程模式。选择时应关注输入日志的形态，而不只是 CPU 数量。 选项 并行单位 最适合 主要限制 -j N / --jobs N 一个日志文件的多个分块 单个可定位的大日志 分块边界可能重复或漏掉少量查询 -J N / --Jobs N 完整日志文件 大量相互独立的日志 只有文件数量足以填满工作进程时才有明显收益 使用 -j 拆分单个大文件 $ pgbadger -j 8 /var/log/postgresql/postgresql.log 上游算法把每个文件分 …

pgBadger 只能报告 PostgreSQL 实际写入日志的信息。应先确定可解析的日志前缀与清晰的语句记录策略，再按需要加入检查点、锁、临时文件和自动清理等运行事件。 最小查询日志配置 若报告需要查询文本与执行耗时，请启用按时长记录语句： log_min_duration_statement = 0 0 会记录每一条执行完毕的语句。繁忙服务器应使用更高的毫秒阈值来控制日志量；在生产环境使用较低阈值前，应先评估开销与存储增长。 若只需要耗时与查询数量，不需要查询文本，可使用： …

语法 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 …