在生产环境中运维 etcd
在传统模式下，以及控制面和数据面使用 etcd 配置提供方的解耦部署中，APISIX 使用 etcd 作为配置存储。该集群的可用性和延迟决定运维人员能否发布配置，以及新的 APISIX 进程能否加载初始配置。
在传统模式下，每个 APISIX 实例管理配置并代理流量。在解耦模式下，控制面实例通过 Admin API 接收配置变更，数据面实例则加载这些配置并代理流量。APISIX 使用 etcd watch（即对配置变更的订阅）使自身配置保持最新。
如果 etcd 变得不可用，正在运行的 APISIX 进程会在内存中保留最近一次成功加载的配置。因此，在 APISIX 重新连接期间，现有代理路径可以继续处理流量，但配置写入和同步会停止。新启动或重启的进程必须从可用端点加载配置后才能就绪。依赖其他运行时系统的能力（例如服务发现或外部限流存储）具有各自的故障行为。
本文适用于 APISIX 专用的 etcd 集群，不适用于独立模式。独立模式将配置存储在文件或内存中，而不使用 etcd。除非已规划并演练过切换和回滚流程，否则不要在事故响应中临时将生产部署切换为独立模式。
生产基线
在生产环境中使用由 etcd 支持的 APISIX 部署之前，请建立以下基线：
| 领域 | 要求 |
|---|---|
| 版本和平台 | 固定确切的 etcd 版本或镜像摘要。记录并测试完整的 APISIX、etcd、操作系统和部署平台 组合。 |
| 集群拓扑 | 使用三个位于不同故障域的投票成员，并确保成员间延迟较低且可预测。 |
| 存储和容量 | 使用基于 SSD 的存储。在测试有代表性的 APISIX 连接、watch、配置写入、故障和维护操作后确定集群容量。 |
| 安全 | 使用 TLS 加密客户端和对等节点流量，启用身份认证，并将凭证权限限制到配置的前缀。为传统模式实例和控制面授予读写权限，为数据面授予读取和 watch 权限。 |
| 生产验收 | 在将流量导向部署之前，完成部署顺序、只读检查、故障测试、备份测试和生产检查清单。 |
| 监控 | 同时监控 etcd 仲裁和存储，以及 APISIX 可达性和配置传播。对需要运维人员立即处理的故障发出告警。 |
| 维护 | 启用自动压缩。按既定周期评估维护需求；执行破坏性操作时一次只处理一个成员，并在成员之间进行健康检查。 |
| 恢复 | 加密快照，在集群故障域之外至少保留一份副本，并演练恢复流程。学习者成员或额外成员不等同于备份。 |
了解故障行为
规划恢复时，应考虑对配置和流量的影响，而不应只关注 etcd 进程状态：
| 状况 | 配置操作 | 现有代理流量 | 新启动或重启的 APISIX 进程 |
|---|---|---|---|
| 一个成员不可用，但仍保持仲裁 | 通过其余成员继续执行读取、写入和 watch。 | 正常继续。 | 可以从可用端点加载配置。 |
| 丢失仲裁或所有端点均不可达 | Admin API 写入和配置同步停止。 | 使用内存中最近加载的配置继续运行。 | 在恢复仲裁并验证初始加载之前，使其保持停止服务状态。 |
| watch 的修订版本已被压缩 | APISIX 执行完整读取，并从当前状态恢复 watch。 | APISIX 重新连接期间，使用已加载的配置继续运行。 | 加载当前状态，而不是重放旧修订版本。 |
| 从较旧的快照恢复集群 | 存储的配置回退到快照状态。 | 正在运行的进程在重新同步前可能暂时保留更新的内存状态。 | 加载恢复后的状态。 |
etcd 故障期间，请勿重启 APISIX 实例。配置缓存只存在于进程内存中，重启会丢弃维持现有代理流量的配置。重启后的进程必须从 etcd 加载配置后才能就绪。
规划和配置生产部署
请统一考虑版本、平台、拓扑、容量、安全和客户端配置决策。每项决策都会影响部署必须支持的故障行为和维护流程。
选择经过测试的版本
固定生产环境使用的确切 etcd 版本或镜像摘要，并与 APISIX 版本、客户端配置、操作系统、部署平台、验证日期和已测试场景一起记录。APISIX 启动时会检查最低 etcd 版本，但该最低版本要求并不代表生产建议。请使用 etcd 项目支持的版本，并在变更 APISIX 或 etcd 之前重新执行生产就绪测试。
选择部署平台
专用 etcd 部署可以运行在主机、虚拟机、Kubernetes 或兼容的托管服务上。平台必须提供可预测的存储延迟、故障域隔离、备份访问、证书和凭证控制，以及一次维护一个成员的能力。
对于托管服务，请验证 API 和版本兼容性、TLS 和角色控制、快照导出、声明的恢复目标、服务提供方的维护行为以及跨可用区延迟。采用该服务前，请确认哪些成员和存储操作仍由服务提供方控制。
在专用主机或虚拟机上，使用 systemd 等服务管理器监管 etcd 并保留日志。确认各成员不会共用可能同时发生故障的电源或底层存储卷。
请勿将 APISIX 配置存储在 Kubernetes 控制面内部使用的 etcd 集群中。共用该集群会使 APISIX 的容量、权限、维护和故障恢复与 Kubernetes 耦合。
启动单个本地 etcd 成员的安装示例仅适用于评估。在生产环境中使用 APISIX 之前，请将其替换为专用、持久化且受监控的集群。
规划集群
从三个投票成员开始，每个成员运行一个参与集群决策的 etcd 服务器。仲裁是就更新达成一致所需的投票成员多数：在三成员集群中为两个成员。此拓扑可容忍一个成员故障。请将成员放置在独立主机、机架或可用区等不同故障域中，同时保持成员间网络延迟较低且可预测。
推荐拓扑将客户端访问、对等节点流量、监控和备份置于明确的信任边界和故障边界内：
APISIX 客户端通过 TLS 或 mTLS 连接到 2379 端口上的授权端点；将 2380 端口保留给成员间流量。监控应同时覆盖 etcd 健康状况和 APISIX 配置同步。请加密快照，将其存储在集群故障域之外，并演练恢复流程。
除非经测量的恢复目标需要更广的拓扑，否则请将成员保持在同一区域。每次提交写入都需要仲裁，因此跨区域延迟会直接影响配置写入和集群稳定性 。对于区域级灾难恢复，请使用复制备份和经过测试的恢复环境，而不要默认将仲裁扩展到相距遥远的区域。
根据配置工作负载确定容量
选择计算和存储资源前，请收集以下输入：
| 输入 | 测量内容 |
|---|---|
| APISIX 进程 | 控制面和数据面实例数、worker 数、etcd 连接数和 watch 数 |
| 配置 | 键数量、键空间总大小、值的平均大小和最大大小，以及最大配置事务 |
| 变更速率 | 常规和峰值写入、修订版本增长、批量配置活动，以及插件或控制器产生的后台写入 |
| 增长 | 容量规划周期内预期的配置和客户端增长 |
| 基础设施 | 成员间延迟、丢包、磁盘同步延迟和存储吞吐量 |
| 恢复目标 | 可接受的最大配置数据丢失量（恢复点目标，RPO）、最长恢复时间（恢复时间目标，RTO）以及维护窗口 |
快速且稳定的磁盘写入比标称磁盘容量更重要。请使用基于 SSD 的存储，监控实际卷上的写入延迟，并避免与日志处理、批处理作业或其他波动性工作负载共用 I/O 路径。etcd 硬件指南将 2–4 个 CPU 核心和约 8 GB 内存作为典型起点。拥有大量客户端、watch 或键的集群需要针对工作负载进行测试。
使用有代表性的配置写入和 watch 验证所选容量。测试应包含成员故障、领导者选举、快照、压缩和 defrag 操作。在峰值负载下，集群不应持续积压待处理的 etcd 更新，也不应反复选举领导者。停止任一成员后，集群仍应满足配置传播目标。
对于繁重工作负载，etcd 硬件指南给出的起始范围为 8–16 个专用 CPU 核心和 16–64 GB 内存。这些只是容量估算示例，并非容量保证。请预留足够内存，使 etcd 在正常或峰值运行期间不依赖交换空间，并为预期增长留出余量。
保护集群
将客户端端口访问限制为 APISIX 和经授权的运维人员，并将对等节点端口访问限制为 etcd 成员。请勿将客户端、对等节点、健康检查或指标端点直接暴露到互联网。
为客户端和对等节点流量启用 TLS。如果身份模型支持双向 TLS，请要求并验证客户端证书，同时保持启用 APISIX 证书验证。有关 APISIX 示例，请参阅在 APISIX 和 etcd 之间配置 mTLS。
启用 etcd 身份认证和基于角色的访问控制（RBAC）。将每个角色限制到配置的 etcd 键前缀（例如 APISIX 存储配置的 /apisix）：
| 实例或运维人员 | etcd 访问权限 |
|---|---|
| 传统模式实例 | 读取和写入配置的前缀 |
| 控制面 | 读取和写入配置的前缀 |
| 数据面 | 读取并 watch 配置的前缀 |
| 备份或维护运维人员 | 仅授予恢复流程所需的集群级操作权限 |
为备份自动化和成员维护使用不同账户。将监控访问限制到所需的健康检查和指标端点；监控不应需要修改配 置或成员关系的权限。
即使连接同时使用客户端证书，也请为 APISIX 配置 etcd 用户名和密码以向 etcd 进行身份认证。APISIX 通过 etcd gRPC 网关执行启动请求，而该网关无法将客户端证书的通用名称（Common Name）用作 etcd 用户。组合使用这些机制时，请签发不含通用名称的 APISIX 客户端证书。使用证书认证 TLS 连接，并使用配置的 etcd 用户授权前缀访问。
为控制面、数据面和维护自动化使用不同凭证。为每个环境使用不同的前缀和凭证集，避免预发布环境的操作读取或修改生产配置。
etcd 不会加密磁盘上的键值数据。如果配置或 Secret 需要静态加密，请使用加密存储，并按照与实时数据存储相同的标准保护快照。
安全配置 etcd
以 etcd 的时间和请求限制默认值为起点，仅在获得生产网络和工作负载测量结果后进行调整。请使用单一配置来源，并记录生效的配置。使用配置文件启动 etcd 时，etcd 会忽略命令行参数和环境变量，而不会合并这些来源。
| 配置项 | 生产建议 |
|---|---|
strict-reconfig-check | 保持启用，以拒绝可能导致仲裁丢失的成员关系变更。 |
auto-compaction-mode 和 auto-compaction-retention | 启用自动压缩，并根据测得的修订版本增长和 APISIX 预计最长断开时间选择保留窗口。请参阅设置压缩保留期。 |
quota-backend-bytes | 设置低于可用存储容量的明确配额，为预写日志（WAL）、快照、临时维护工作 和操作系统预留空间。 |
max-request-bytes | 保持默认的 1.5 MiB（1572864 字节）。提高限制前，请缩减过大的对象，或在不要求原子性的场景中拆分事务。较大的请求可能延迟其他请求；请在峰值负载和单成员故障期间测试任何提高后的限制。 |
| 心跳和选举超时 | 保持默认值，除非测得的成员延迟和丢包情况证明需要在所有成员上协调调整。 |
| 损坏检查 | 启用所选 etcd 版本支持的检查，并在容量验证时计入其 I/O 开销。 |
unsafe-no-fsync | 保持禁用。启用后可能在写入持久化之前就确认成功。 |
对每个成员应用相同且经过审查的基线。将成员间生效配置的差异视为配置漂移，并通过部署系统修正，而不要进行未记录的手动变更。
配置 APISIX 端点
列出同一 etcd 集群的多个端点，以便一个端点不可用时 APISIX 可以直接连接到另一成员。数据面配置可以从以下设置开始：
apisix:
ssl:
ssl_trusted_certificate: /run/secrets/etcd-ca.crt
deployment:
role: data_plane
role_data_plane:
config_provider: etcd
etcd:
host:
- "https://etcd-1.example.net:2379"
- "https://etcd-2.example.net:2379"
- "https://etcd-3.example.net:2379"
prefix: /apisix
timeout: 30
watch_timeout: 50
resync_delay: 5
health_check_timeout: 10
startup_retry: 2
user: "${{ETCD_USER}}"
password: "${{ETCD_PASSWORD}}"
tls:
cert: /run/secrets/etcd-client.crt
key: /run/secrets/etcd-client.key
verify: true
所示的超时、watch、重新同步、健康检查和启动重试值均为 APISIX 默认值。请将其作为初始基线，仅在测量网络和故障行为后进行调整。增加超时可以降低对瞬时延迟的敏感度，但也会延迟故障检测。
此数据面示例应使用只读凭证。提供 Admin API 的传统模式实例或控制面需要对同一前缀具有写权限的凭证。
如果在 etcd 前配置负载均衡器，请确保负载均衡器高可用，并移除未就绪的成员。直接列出成员端点可以避免引入这一额外依赖。
部署和验证
请将以下检查作为统一的生产验收门禁。不要仅根据 etcd 端点健康就推断部署已就绪。
遵循部署顺序
- 预置三个故障域、持久化存储、网络规则、DNS 名称和时间同步。
- 签发对等节点和客户端证书，并为凭证准备受保护的存储。
- 在受限网络上使用客户端和对等节点 TLS 启动 etcd 成员。验证成员关系、领导者、告警和端点健康状况，然后创建用户和最小权限角色，并在连接 APISIX 前启用身份认证。
- 启用监控和告警，然后创建并验证初始快照，再将其复制到集群故障域之外。
- 连接一个传统模式实例或控制面实例，并验证其可以通过 Admin API 创建、更新和删除测试配置。
- 连接一个数据面实例作为灰度验证实例，在连接其余实例前用它验证部署。验证配置同步和代理流量。
- 模拟一个跟随者故障，然后确认恢复后的成员可以赶上进度且没有持续告警，并确认配置操作仍满足传播目标。
- 分阶段连接其余 APISIX 进程，只有在检查清单中的所有项目都通过后，才导入生产流量。
执行只读集群检查
在部署、维护窗口或事故响应前执行只读检查。通过受保护的环境变量或 Secret 文件提供 TLS 和身份认证值，避免其留在 shell 历史记录中。
etcdctl --endpoints="${ETCD_ENDPOINTS}" endpoint health --cluster
etcdctl --endpoints="${ETCD_ENDPOINTS}" endpoint status --cluster -w table
etcdctl --endpoints="${ETCD_ENDPOINTS}" member list -w table
etcdctl --endpoints="${ETCD_ENDPOINTS}" alarm list
完成生产检查清单
| 要求 | 需要保留的证据 | 要求未满足时的处理方式 |
|---|---|---|
| 三个投票成员分布在彼此独立的故障域。 | 成员列表、公布的对等节点 URL、放置记录，以及恢复成员能够赶上进度且没有持续告警的跟随者故障测试。 | 不要导入生产流量。先修正放置或成员关系。 |
| 每个端点都已就绪，并报告预期的集群 ID 和对等节点 URL；集群恰好有一个领导者且没有持续告警。 | 验收窗口中的 endpoint health、endpoint status、member list 和 alarm list 输出。 | 连接 APISIX 前修正成员关系、网络、存储或告警。 |
| APISIX 和 etcd 版本均已固定，且该组合已通过工作负载测试。 | 版本记录和容量测试结果，包括单成员故障测试。 | 固定版本并重新测试。 |
| 已强制实施 TLS、身份认证和最小权限角色。 | 证书验证、一次失败的数据面写入，以及使用控制面或传 统模式实例凭证访问配置前缀之外内容时被拒绝的请求。 | 关闭网络暴露并修正身份或权限。 |
| 峰值负载下的存储和网络性能满足传播目标。 | WAL 和后端延迟、成员延迟、待处理 etcd 更新积压、领导者稳定性以及 APISIX 传播测量结果。 | 调整工作负载大小或迁移工作负载；不要仅通过增加超时来掩盖故障。 |
| APISIX 可以创建、更新和删除测试配置，且每个数据面都能在传播目标时间内应用每项变更。 | Admin API 结果、各进程的修改索引、传播时间和成功的代理请求。 | 使部署保持停止服务状态，并修正 APISIX 到 etcd 的路径。 |
已定义压缩、配额和依次执行 defrag 的流程。 | 生效的配置、测得的修订版本增长，以及已完成的维护记录。 | 在增长达到配额前建立保留和维护流程。 |
| 监控同时覆盖 etcd 和 APISIX 同步。 | 针对仲裁、存储、证书、备份和传播故障的告警测试。 | 添加并测试缺失的信号。 |
| 快照满足恢复目标，且最近一次隔离恢复已成功。 | 快照哈希、集群外副本、恢复日期、恢复的修订版本、RPO 和 RTO。 | 将恢复能力视为未经验证，并完成恢复演练。 |
| 事故处理流程会保留正在运行的 APISIX 进程，并禁止不安全的捷径。 | 已审查的流程和演练记录。 | 将服务交给值班运维人员前修正流程。 |
监控和维护部署
将 etcd 和 APISIX 作为一个配置存储与同步系统进行运维。持续监控两个系统，并根据测得的集群状态执行维护，而不是只依据固定阈值。
监控端到端路径
同时监控 etcd 和 APISIX。仅 etcd 进程健康，并不能证明每个 APISIX 进程都能完成身份认证、watch 其前缀并应用配置变更。
至少跟踪以下信号：
| 层级 | 信号 |
|---|---|
| 主机和进程 | CPU 饱和与限流、内存压力与内存不足（OOM）事件、进程重启以及存储 I/O 争用 |
| 集群 | 就绪成员、领导者存在性和变更、失败和待处理的 etcd 更新以及成员间延迟 |
| 存储 | WAL 同步延迟、数据库提交延迟、数据库大小、配额用量、可用磁盘空间和可回收空间 |
| APISIX | apisix_etcd_reachable、apisix_etcd_modify_indexes、配置错误以及最近一次成功的测试变更 |
| 恢复 | 快照存续时间、快照验证结果、距上次恢复演练的时间以及证书到期时间 |
当 Prometheus 插件导出 APISIX etcd 指标时，可以使用这些指标。比较各 APISIX 进程的修改索引，以检测不再接收更新的 APISIX 实例。
比较 watch 同一前缀的实例上的相同资源标签。不同资源类型或前缀的索引可能本就不同；请使用已知的测试变更检查每个相关实例是否收到预期更新。
启用 APISIX 状态服务器后，/status/ready 可确认每个 worker 已收到可用配置。完成初始同步后，即使 etcd 暂时不可用，该端点仍可能保持就绪，因为 worker 仍持有缓存配置。请使用可达性指标、日志和受控配置变更监控实时 etcd 路径。
对紧急故障发出告警
根据测得的基线和部署恢复目标设置告警阈值。在观察正常和峰值工作负载后，校准延迟、资源和增长告警。
以下数值是候选告警规则，需要在负载测试和初始 2–4 周的观察期内验证。这些只是运维示例，并非 etcd 限制或保证的检测时间。请根据配置传播目标和值班响应时间进行调整。下文列出的紧急故障优先于这些延迟设置。
| 信号 | 告警示例 | 严重条件示例 |
|---|---|---|
| 成员健康状况 | 端点健康检查失败、/readyz 失败或监控目标报告 up=0。 | 可用投票成员少于仲裁数，或 /livez 失败。 |
| 领导者变更 | 15 分钟内变更超过 3 次。 | 没有领导者；应立即调查，而不是等待达到变更次数阈值。 |
| 待处理或失败的更新 | 待处理提案持续不为零，或提案失败连续 5 分钟增加。 | 已提交与已应用提案之间的差距持续扩大，且请求失败。 |
| 磁盘延迟 | WAL 同步 P99 连续 10 分钟超过 10 ms，或后端提交 P99 连续 10 分钟超过 25 ms。 | WAL 同步 P99 连续 5 分钟超过 50 ms，或后端提交 P99 连续 5 分钟超过 100 ms，或者请求已经超时。 |
| 后端配额 | 数据库大小达到配额的 70%。 | 数据库大小达到配额的 85%；出现 NOSPACE 告警时需要立即处理。 |
| APISIX 同步 | 实例连续 30 秒报告 apisix_etcd_reachable=0，或测试变更 后 2 分钟内可比的配置修改索引仍未收敛。 | 一个控制面或至少 20% 的数据面持续断开 1 分钟，或同步耗时超过 5 分钟。如果传播目标要求更短时间，请缩短延迟。 |
| 证书 | 证书将在 30 天内到期。 | 证书将在 7 天内到期；请根据轮换所需时间调整两个窗口。 |
| 备份 | 快照存续时间超过恢复点目标。 | 连续两次备份失败，或没有经过验证的快照。第一次备份失败或逾期时就应立即调查。 |
请根据已分配资源、测得的峰值、增长速率和扩容所需时间设置 CPU、内存和可用磁盘阈值。照搬其他部署的绝对资源阈值可能产生误导性告警。
将仲裁丢失、没有领导者、OOM 事件、进程反复终止、NOSPACE 告警、备份失败或逾期，以及无法传播配置视为需要立即处理的运维故障。
设置压缩保留期
etcd 修订版本是分配给键值数据变更的递增版本号。请启用自动历史压缩。APISIX 会 watch 配置修订版本；如果请求的修订版本已被压缩，则会自动执行完整读取。但覆盖常规断开时长的保留窗口可以避免不必要的完整重载。
auto-compaction-retention 的默认值为 0，表示禁用自动压缩。仅选择压缩模式并不会启用自动压缩。
对于配置变更不频繁的 APISIX 集群，24–72 小时的周期性保留窗口是一个实用起点。如果 APISIX 进程可能断开更长时间，或完整重载成本较高，请延长窗口；如果修订版本增长威胁存储目标且常规断开时间很短，请缩短窗口。应根据测得的修订版本增长验证决策，而不要在环境之间照搬修订版本数量。
如果选择按修订版本压缩，请根据测得的峰值修订版本速率计算保留量，而不要使用固定的修订版本数量：
retained revisions
>= peak revisions per second × maximum expected disconnection in seconds × safety factor
根据工作负载波动和恢复风险选择安全系数，然后让 APISIX 灰度验证实例断开目标时长以验证结果。
例如，峰值速率为每秒 2 个修订版本、断开窗口为 6 小时且安全系数为 2 时，需要保留 2 × 21600 × 2 = 86400 个修订版本。在该峰值速率下，1,000 个修订版本只能覆盖 500 秒，即约 8 分钟。这些输入仅用于说明计算方式；请替换为当前部署的测量值。
一次在一个成员上回收空间
压缩会使旧修订版本不可用，但不会将释放的空间归还给文件系统。当可回收空间较大或磁盘增长接近告警阈值时，请运行 etcdctl defrag。在线 defrag 操作会阻塞正在处理的成员上的读取和写入。请在低流量时段执行，一次处理一个成员，并在继续前验证集群和 APISIX 健康状况。
一个维护触发条件示例是可回收空间持续超过数据库文件大小的 30%。请将其视为候选策略而非 etcd 限制：安排操作前，应考虑可回收空间的绝对大小、可用磁盘空间以及阻塞每个成员的代价。
从 NOSPACE 告警中恢复
为 etcd 后端数据库设置不超过可用磁盘的配额，并为预写日志、快照、临时维护工作和操作系统预留空间。后端超过配额时，etcd 会触发集群级 NOSPACE 告警并停止接受普通写入。提高配额不能替代压缩、defrag 或对产生异常写入的客户端进行调查。
若要从 NOSPACE 恢复：
- 停止或隔离产生异常写入的客户端，并暂停非必要的 APISIX 配置变更。
- 确认当前告警、后端大小、实际使用大小和最新修订版本。
- 压缩过时历史记录。
- 运行
etcdctl defrag，并一次验证一个成员。 - 只有当集群低于配额后才清除告警。
- 测试一次 APISIX 配置写入，并确认每个进程都收到该变更。
- 通过调整保留期、写入来源、容量或告警时机来修正根因。关闭事故前，确认修订版本增长恢复到预期速率，且存储用量降至告警阈值以下。
安全替换成员和轮换证书
学习者成员不参与投票，在晋升前不会提高仲裁容错能力。对于故障或待退役成员，请先将替代成员作为学习者加入，并等待其赶上进度。只有在集群健康后才能晋升替代成员并移除旧成员。不要将已移除成员的数据目录重新用作新成员的数据目录。一次只变更一个成员，并在各次变更之间验证 APISIX 配置传播。
轮换信任时，不要造成新旧证书无法通信的时间点。先添加新的信任根，再分阶段轮换对等节点和客户端身份。确认没有活动客户端或成员依赖旧信任根后，才能将其移除。在运维记录中保留证书所有权和到期日期。
遵循维护计划
为每项定期检查指定运维人员。如果恢复目标、变更速率或风险状况有需要，请提高检查频率。
| 频率 | 运维检查 |
|---|---|
| 持续 | 仲裁、领导者、提案和存储延迟、后端配额、APISIX 可达性和传播、快照存续时间以及证书到期时间。 |
| 每日 | 计划快照是否成功及集群外副本；紧急告警；异常的修订版本或数据库增长。 |
| 每周 | 成员健康状况、领导者变更、慢请求、容量趋势、备份验证和未解决告警。 |
| 每月 | 可回收空间及是否有必要依次执行 defrag；版本支持情况；证书到期前剩余时间；最小权限访问。 |
| 每季度 | 在隔离环境中恢复快照，并演练单成员故障和仲裁丢失；记录实际恢复点和恢复时间。 |
| 事件触发 | 在 APISIX 或 etcd 发布新版本、发布安全公告、证书或成员关系变更、重大配置迁移、基础设施变更或事故后，重新执行受影响的检查。 |
不要仅因为日历周期已到就运行 defrag、轮换证书或替换成员。应通过检查判断是否需要执行操作，然后遵循已记录的一次处理一个成员的流程。
维护运维记录
保留在维护窗口或事故期间做出安全决策所需的信息：
- APISIX 和 etcd 版本、生效的 etcd 配置、成员放置和证书所有权；
- etcd 用户和角色清单，包括授权的前缀和权限；
- 生产拓扑、故障域、DNS 名称、端口和网络访问规则；
- 当前恢复点目标和恢复时间目标、快照位置和保留期，以及最近一次恢复证据；
- 容量基线、预期配置增长、告警阈值以及每项设置变更的原因；
- 已批准的成员替换、
defrag、证书轮换、恢复和升级流程； - Prometheus 控制台、告警规则、值班负责人和 升级路径；以及
- 维护、演练、事故、已知限制、例外及其后续措施的记录，包括负责人和下次检查日期。
备份和演练恢复
应将恢复视为经过测试的能力，而不是只确认快照任务存在。先定义备份策略，再证明经过验证的快照可以恢复 APISIX 配置和流量。
定义备份策略
根据配置恢复点目标设置快照计划。策略应定义运维人员可审查的证据，而不是只声明备份任务存在：
| 策略项 | 要求 |
|---|---|
| 计划 | 在测得的写入速率下，快照间隔满足配置恢复点目标。 |
| 保留 | 保留窗口覆盖发现意外删除或错误配置变更所需的时间。 |
| 存储 | 建议以 3-2-1 模式作为组织起点：保留 3 份副本，使用 2 种不同类型的存储介质，其中 1 份存储在集群故障域之外的异地。加密每份副本并限制访问。 |
| 验证 | 每个快照记录其状态、哈希、修订版本、键总数和总大小；快照失败或逾期时向运维人员发出告警。 |
| 恢复证据 | 计划执行的隔离恢复记录所恢复的修订版本、实际恢复点、实际恢复时间和 APISIX 验证结果。 |
备份策略示例可以每小时创建快照，并保留最近 24 份小时副本和 14–30 份每日副本。只有在快照存续时间、任务持 续时间和可能的故障符合恢复点目标时，才采用此策略。恢复目标更严格时应提高频率；为了覆盖删除发现时间、审计要求或恢复需求，应延长保留期。
复制或恢复每个快照前都要检查。状态输出提供验证记录所需的元数据：
etcdutl snapshot status snapshot.db -w table
通过维护 API 保存快照。不要将活动后端数据库的副本用作常规备份，因为它可能遗漏仅存在于预写日志中的数据。etcd 灾难恢复指南说明了快照和恢复模型。学习者成员或额外成员不等同于备份，因为它们也会复制意外删除和逻辑上无效的配置变更。
演练恢复
从同一经过验证的快照将每个成员恢复到新的数据目录，以创建新的逻辑集群。先在隔离网络中恢复，然后验证集群修订版本、键数量、路由、消费者、SSL 证书、上游、Admin API 操作和真实代理流量，最后再重新连接所有 APISIX 进程。
恢复较旧的快照会使配置状态回退。由于 APISIX 使用 watch 和内存配置缓存，请计算一个修订版本增量，使其覆盖快照创建后可能产生的修订版本。恢复时通过 --bump-revision 传入该值，并使用 --mark-compacted。这样会使现有 watch 失效，使 APISIX 进入已压缩 watch 的恢复路径并执行完整读取。请针对所选 etcd 版本测试确切的恢复流程，不要从示例中照搬任意增量值。
有关快照流程，请参阅备份和恢复 etcd。请在该流程中增加集群外保留，并计划执行恢复演练以测量实际恢复点和恢复时间。
响应 etcd 故障
当所有端点均不可用或集群丢失仲裁时，请冻结配置变更，并保持健康的 APISIX 进程运行。
不要将以下操作用作恢复捷径：
- 在没有经过验证的快照时删除数据目录。
- 同时重启或替换多个 etcd 成员。
- 在旧集群成员仍在运行时使用
--force-new-cluster。 - 在隔离验证之前，将恢复后的集群重新连接到所有 APISIX 进程。
保留证据并控制影响
在采取破坏性操作前，记录事故开始时间、成员列表、端点状态、告警、存储和 Raft 指标、APISIX 错误，以及最近的基础设施或配置变更。暂停可能改变证据或重启健康 APISIX 进程的自动配置交付和基础设施协调。
在判断故障源于网络、凭证、单个成员还是仲裁期间，请保持现有 APISIX 进程继续提供服务。记录每项恢复操作及其结果，避免下一位运维人员重复执行破坏性步骤。
选择恢复路径
恢复路径取决于集群是否仍保持仲裁。如果仲裁已丢失，请在恢复快照前区分临时中断与永久成员丢失。整个恢复期间都应冻结配置变更，并保留正在运行的 APISIX 进程。
如果仍保持仲裁
恢复连接，或一次替换一个故障成员。先将替代成员作为学习者加入，等待其赶上进度并将其晋升，然后才能移除旧成员。处理另一个成员前，请验证集群健康状况和一次 APISIX 配置变更。
如果仲裁永久丢失
按照所选 etcd 版本的恢复流程，从最新的已验证快照恢复新集群。保持旧成员隔离，使用一个 APISIX 灰度验证实例验证恢复后的状态，再分阶段重新连接其余进程。
如果 etcd 健康但 APISIX 配置已过时
重启进程前，请检查端点可达性、证书验证、身份认证、前缀权限、已压缩 watch 消息和修改索引。将受影响进程与健康的同类进程进行比较，并保留显示最近一次成功同步的日志。
使用症状指南
| 症状 | 立即采取的操作 | 恢复标准 |
|---|---|---|
| 所有端点均不可达 | 冻结配置变更，保留正在运行的 APISIX 进程，并区分网络隔离与仲裁丢失。 | 端点可达、仲裁稳定，且 APISIX 测试变更可以传播。 |
| 仲裁暂时丢失 | 恢复连接，或一次恢复一个可恢复成员。冻结配置变更并保留正在运行的 APISIX 进程。 | 现有集群重新获得仲裁，且写入和 APISIX 同步成功。 |
| 仲裁永久丢失 | 隔离旧成员并选择最新的已验证快照。不要重启 APISIX 实例。 | 恢复后的集群通过隔离验证，且 APISIX 进程分阶段重新连接。 |
| 反复选举或出现慢请求 | 检查成员延迟、丢包、CPU 压力、WAL 同步、后端提交延迟，以及争用磁盘 I/O 的其他工作负载。 | 领导者稳定，且测得的延迟在负载下恢复到验收基线。 |
数据库增长或 NOSPACE 告警 | 停止产生异常写入的客户端，检查修订版本增长和配额用量，然后执行压缩和 一次处理一个成员的 defrag 流程。 | 后端低于配额、告警已清除，且写入和 watch 成功。 |
| APISIX 配置过时 | 比较修改索引，并检查可达性、TLS、身份认证、权限和已压缩 watch 的恢复。 | 所有 APISIX 进程都应用测试配置修订版本，且代理流量使用预期配置。 |
| TLS 或 RBAC 错误 | 停止凭证变更，并检查证书到期时间、CA 信任、主题备用名称（SAN）、服务器名称指示（SNI）、时间同步和前缀权限。 | 每种 APISIX 角色的握手以及允许和拒绝访问测试均通过，并且在不扩大权限的情况下验证了凭证回滚路径。 |
恢复后，执行一次测试配置变更和一次真实代理请求。确认所有 APISIX 进程都应用预期配置后，才能重新开放常规配置变更。
安全升级
将升级作为受控的生产变更，设置明确的准入标准、逐成员验证以及已记录的回滚边界。
决定是否升级
当目标版本解决相关安全问题、缺陷或提供所需能力时再升级 etcd，而不要只为跟随最新版本而升级。请使用 etcd 项目支持的版本，并结合当前运行的 APISIX 版本、客户端配置、操作系统和部署平台进行验证。APISIX 启动时会检查最低 etcd 版本，但该最低版本要求并不代表生产版本建议。
选择目标版本前，请审查发布说明、安全公告、配置变更和存储版本变更。如果当前受支持次版本中的补丁版本包含所需修复，请优先使用该补丁版本。如果当前次版本没有该修复或已停止支持，请迁移到受支持的次版本。
执行继续或停止门禁
只有当集群保持仲裁、每个成员都健康且已赶上进度，并且没有活动告警时，才能继续。存储必须有足够空间重建成员，监控必须正常工作，并且最近经过验证的快照必须通过所需的恢复测试。请遵循受支持的次版本步骤，不要跳过次版本。如果缺少任何前置条件，或源版本到目标版本的升级路径不受支持，请推迟升级。
一次滚动升级一个成员
升级 etcd 前，请确认集群健康、没有告警、具有足够容量重建成员，并且拥有最近经过验证的快照。按照源版本和目标版本对应的 etcd 升级路径，一次升级一个成员，并等待其就绪且赶上进度后再继续。升级每个成员后，验证集群健康状况、一次 APISIX 配置写入、配置传播和代理流量。集群升级完成后，还要启动一个新的 APISIX 灰度验证实例，以验证初始配置加载和扩容路径。
不要套用通用的“最后升级领导者”规则。受支持的顺序和领导权转移行为取决于源版本和目标版本。请遵循该版本组合的确切升级流程，包括停止当前领导者前所需的任何领导权转移。
了解回滚边界
在变更第一个成员前定义回滚决策点。在受支持的混合版本阶段，特定版本的流程可能允许用旧版本替换新二进制文件。所有成员升级完成且集群被视为已完全升级后，恢复可能需要执行已记录的降级流程或恢复快照。
快照并不能保证任意原地回滚安全。二进制回滚、存储版本降级和快照恢复是不同操作。变更第一个成员前，请确认确切源版本和目标版本所支持的混合版本、回滚和降级流程。
升级每个成员后，记录已达到的版本、验证结果和仍可用的回滚选项。验证失败时应停止升级，而不是为了缩短混合版本窗口而继续。