跳到主要内容

备份和恢复 etcd

etcd 集群通常具有容错能力。尽管如此，仍可能出现多个 etcd 节点故障并失去与集群连接的情况。为了从此类故障中恢复，etcd 支持备份和恢复功能，可在不丢失数据的情况下重新创建实例。

设置备份有助于保存 APISIX 实例的状态。这在升级 APISIX 时也很有用，可确保你的配置已保存。

本文档介绍如何在 Docker 中运行 APISIX 和 etcd，以及如何备份和恢复 etcd。请将示例中的容器名称、网络名称和路径替换为你的部署所使用的值。

前置条件​

通过临时容器备份​

etcd 自带了 etcdctl，这是一个用于操作 etcd API 的命令行工具。etcdctl 支持 etcdctl snapshot 命令，可以对 etcd 数据库进行备份。

下面的示例在一个临时 Docker 容器上运行此命令，并在主机上创建备份。

首先，在主机上创建一个 backup 文件夹用于存放备份。该文件夹将作为卷挂载到临时容器中。

在与 APISIX 和 etcd 容器相同的网络中创建用于备份 etcd 的临时容器，并运行 etcdctl snapshot 命令，提供 etcd 端点：

export NET_NAME="apisix-quickstart-net"
export ETCD_LISTEN_PORT=2379
export ETCD_NAME="etcd-quickstart"
mkdir -p ./backup

docker run --rm \
    --mount type=bind,source="$(pwd)/backup",target=/backup \
    -e ETCDCTL_API=3 \
    --network "$NET_NAME" \
    gcr.io/etcd-development/etcd:v3.5.32 \
    etcdctl --endpoints="http://$ETCD_NAME:$ETCD_LISTEN_PORT" snapshot save /backup/snapshot.db

如果成功，你应该会看到类似以下的响应：

{"level":"info","ts":"2026-07-21T06:04:56.103946Z","caller":"snapshot/v3_snapshot.go:65","msg":"created temporary db file","path":"/backup/snapshot.db.part"}
{"level":"info","ts":"2026-07-21T06:04:56.107775Z","logger":"client","caller":"v3@v3.5.32/maintenance.go:212","msg":"opened snapshot stream; downloading"}
{"level":"info","ts":"2026-07-21T06:04:56.107820Z","caller":"snapshot/v3_snapshot.go:73","msg":"fetching snapshot","endpoint":"http://etcd-quickstart:2379"}
{"level":"info","ts":"2026-07-21T06:04:56.113786Z","logger":"client","caller":"v3@v3.5.32/maintenance.go:220","msg":"completed snapshot read; closing"}
{"level":"info","ts":"2026-07-21T06:04:56.114407Z","caller":"snapshot/v3_snapshot.go:88","msg":"fetched snapshot","endpoint":"http://etcd-quickstart:2379","size":"45 kB","took":"now"}
{"level":"info","ts":"2026-07-21T06:04:56.114681Z","caller":"snapshot/v3_snapshot.go:97","msg":"saved","path":"/backup/snapshot.db"}
Snapshot saved at /backup/snapshot.db

直接在 etcd 容器上备份​

etcdctl snapshot 也可以直接在 etcd 容器上运行。请注意，这可能需要为 Docker 容器设置目录权限。

export ETCD_NAME="etcd-quickstart"
docker exec -it "$ETCD_NAME" \
  etcdctl --endpoints="http://127.0.0.1:2379" snapshot save /tmp/snapshot.db
docker cp "$ETCD_NAME:/tmp/snapshot.db" ./backup/snapshot.db
docker exec "$ETCD_NAME" rm /tmp/snapshot.db

这样会先将快照保存到 etcd 容器内，然后将其复制到主机。

从主机备份​

如果可以访问 etcd API 端点，则可以在主机上运行 etcdctl。etcd 端点可以通过 TLS 安全地暴露。

请注意，etcdctl 应安装在主机上。下载适用于相应操作系统的二进制文件，或使用包管理器安装 etcdctl。

在主机上运行 etcdctl 以保存快照：

export ETCD_LISTEN_PORT=2379
export ETCD_ADDRESS="127.0.0.1"
etcdctl --endpoints="http://$ETCD_ADDRESS:$ETCD_LISTEN_PORT" snapshot save ./backup/snapshot.db

从备份恢复​

官方 etcd 发行版同时包含这两个工具。使用 etcdctl 从正在运行的 etcd 成员保存快照，使用 etcdutl 将快照恢复到数据目录。

恢复快照会根据快照重新创建 etcd 数据目录。请恢复到新目录，然后按照当前部署方式使用已恢复的数据启动 etcd。

运行以下命令，将快照恢复到新数据目录：

mkdir -p ./restore
docker run --rm \
    --mount type=bind,source="$(pwd)/backup",target=/backup \
    --mount type=bind,source="$(pwd)/restore",target=/restore \
    gcr.io/etcd-development/etcd:v3.5.32 \
    etcdutl snapshot restore /backup/snapshot.db --data-dir /restore/data

如果主机上已安装 etcdutl，也可以直接在主机上运行恢复命令。

恢复后，使用已恢复的数据目录和当前环境所需的引导配置启动 etcd。例如，在容器化部署中，通常需要在重新启动 etcd 之前，用恢复后的数据替换旧 etcd 容器或其挂载数据卷。

etcd 恢复健康后，请确认 APISIX 已重新连接到恢复后的数据存储。如果 etcd 恢复可用后 APISIX 未自动恢复，请根据部署方式重启或重新加载 APISIX。

对于 Docker 部署，可以运行：

docker restart apisix-quickstart

恢复后，请在宣布恢复完成之前同时验证控制面数据和代理流量。

如果已完成前置条件中的路由教程，请验证其路由和流量路径是否已恢复：

curl -i "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip"
curl -i "http://127.0.0.1:9080/ip"

对于多节点 etcd 集群或非 Docker 部署，请使用相同的快照和恢复概念，但要根据运行环境调整已恢复的数据目录、引导配置和服务重启流程。有关集群恢复指南，请参阅官方 etcd 灾难恢复文档。