任务 on PIG.CENTER

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 会创建一个到实际服务器的连接，或者复用已有连接。

PostgreSQL 日志配置

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

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

最小查询日志配置

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

并行处理

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

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

增量报告

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

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

备用集群

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

运维任务

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

如何搭建演示集群

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 版本、操作系统、输入格式、完整选项、实际结果与预期结果。

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

在 Kubernetes 中使用 Patroni

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

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

将独立实例转换为 Patroni 集群

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

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

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

操作步骤

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

开发任务

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

8. 日志记录

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

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

从 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 中是否已存在相同问题。

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!" 为用引号括起的值

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 用于分布式锁：

如何在 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 之前，请参阅以下页面：

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

安装预构建二进制文件

安装 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 交互

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

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

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

身份认证指南

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

身份认证

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

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

调试端点

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

运行时重配置

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

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

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

数据损坏

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

升级

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

降级 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 的新特性

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

分类处置

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

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 中便于参考的若干搜索示例：

任务 on PIG.CENTER

pgbouncer 命令用法

语法

描述

PostgreSQL 日志配置

最小查询日志配置

并行处理

使用 -j 拆分单个大文件

从库镜像与引导

增量报告

备用集群

发布、软件包与升级

任务

运维任务

如何搭建演示集群

集群的暂停/恢复模式

目标

支持与贡献

缺陷与功能需求

在 Kubernetes 中使用 Patroni

将独立实例转换为 Patroni 集群

操作步骤

开发任务

8. 日志记录

从 etcd 中读取

先决条件

步骤

贡献指南

在线交流

报告缺陷

1. 先决条件

向 etcd 写入

先决条件

步骤

3. 启动 HAProxy

4. 停止与重启 HAProxy

5. 文件描述符限制

6. 内存管理

如何根据前缀获取键

先决条件

按前缀获取键

全局选项

选项

示例

7. CPU 使用率

8. 日志记录

9. 统计信息与监控

10. 简化配置管理

11. 应避免的常见陷阱

12. 调试与性能问题

13. 安全注意事项

如何删除键

先决条件

添加或删除键

选项

继承自父命令的选项

示例

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

先决条件

术语

如何监听键值变化

先决条件

监听键

选项

继承自父命令的选项

示例

如何创建租约

如何创建锁

先决条件

创建锁

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

先决条件

进行领导者选举

如何检查集群状态

先决条件

检查整体状态

选项

检查健康状况

如何保存数据库

先决条件

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