Docker 安装 Etcd 超详细教程：从部署到验证，避坑指南全收录

原创已于 2025-11-19 11:38:23 修改 · 1.8k 阅读

23 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#docker #etcd #容器

于 2025-11-19 11:37:16 首次发布

Docker 专栏收录该内容

22 篇文章

订阅专栏

Docker 安装 Etcd 超详细教程：从部署到验证，避坑指南全收录

Docker 安装 Etcd 超详细教程：从部署到验证，避坑指南全收录

Docker 安装 Etcd 超详细教程：从部署到验证，避坑指南全收录

Etcd 作为分布式系统的关键组件，常被用作服务发现、配置管理和分布式锁。使用 Docker 部署 Etcd 能极大简化环境配置，但新手过程中容易遭遇命令格式错误、服务访问失败等问题。本文将从 前置准备、部署实施、常见问题解决到服务验证，提供一套完整的 Docker 安装 Etcd 实操指南，附带关键避坑技巧。

一、前置准备：确认环境与依赖

部署前需确保基础环境满足要求，避免后续出现兼容性问题：

1.1 系统与 Docker 环境要求

操作系统：支持 CentOS 7+/RHEL 7+/Ubuntu 16.04+ 等 Linux 发行版（本文以 RHEL 7.5 为例）；
Docker 版本：建议 19.03+，确保 Docker 服务正常运行；
网络要求：开放 Etcd 默认端口 2379（客户端通信）和 2380（集群节点通信），或提前规划自定义端口。

1.2 环境检查命令


# 1. 检查 Docker 版本（需 19.03+）
docker -v
# 2. 确认 Docker 服务运行状态（显示 active (running) 为正常）
systemctl status docker
# 3. 若 Docker 未启动，执行启动命令
systemctl start docker
# 4. （可选）设置 Docker 开机自启
systemctl enable docker
# 5. 检查端口占用情况（避免 2379/2380 被占用）
netstat -tulpn | grep -E "2379|2380"

1.3 核心说明

若端口被占用，可停止占用进程（kill -9 进程ID）或在部署时修改端口映射（如 -p 23790:2379 表示将容器 2379 端口映射到主机 23790 端口）。

二、部署实施：Docker 启动 Etcd 完整步骤

Etcd 部署需区分「单节点部署」和「集群部署」，新手建议先从单节点入手，熟悉后再扩展集群。以下为单节点部署的详细流程：

2.1 核心参数说明

Etcd 启动需配置必要的环境变量（-e 参数），核心参数含义如下，避免因参数缺失导致服务异常：

参数名称	作用说明	示例值
ETCD_NAME	节点名称，集群模式下需唯一	etcd-node1
ETCD_LISTEN_CLIENT_URLS	监听客户端请求的地址，0.0.0.0 表示允许所有地址访问	http://0.0.0.0:2379
ETCD_ADVERTISE_CLIENT_URLS	对外暴露的客户端访问地址，需填写主机实际 IP	http://192.168.88.31:2379
ETCD_LISTEN_PEER_URLS	监听集群节点通信的地址	http://0.0.0.0:2380
ETCD_INITIAL_ADVERTISE_PEER_URLS	对外暴露的集群通信地址	http://192.168.88.31:2380
ETCD_INITIAL_CLUSTER	集群节点列表，单节点为自身名称和地址	etcd-node1=http://192.168.88.31:2380
ETCD_INITIAL_CLUSTER_STATE	集群状态，new 表示新建集群	new
ETCD_INITIAL_CLUSTER_TOKEN	集群令牌，确保唯一性避免冲突	etcd-cluster-token

2.2 两种启动命令：避免格式陷阱

部署时最易踩坑的是 命令换行格式，以下提供两种可靠的启动方式，根据需求选择：

方案 1：多行命令（可读性高，参数清晰）

适合参数较多时使用，核心要求：反斜杠 \ 后无任何字符（包括空格），直接回车换行。执行命令：


docker run -d --name etcd \
-p 2379:2379 \
-p 2380:2380 \
-e ETCD_NAME="etcd-node1" \
-e ETCD_LISTEN_CLIENT_URLS="http://0.0.0.0:2379" \
-e ETCD_ADVERTISE_CLIENT_URLS="http://192.168.88.31:2379" \
-e ETCD_LISTEN_PEER_URLS="http://0.0.0.0:2380" \
-e ETCD_INITIAL_ADVERTISE_PEER_URLS="http://192.168.88.31:2380" \
-e ETCD_INITIAL_CLUSTER="etcd-node1=http://192.168.88.31:2380" \
-e ETCD_INITIAL_CLUSTER_STATE="new" \
-e ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster-token" \
quay.io/coreos/etcd:v3.5.0

操作技巧：

手动输入时，输完 \ 后立刻按回车，终端显示 > 表示命令未结束；
复制命令时，先粘贴到记事本清除多余空格，再复制到终端。

方案 2：单行命令（新手首选，无格式风险）

若担心换行格式出错，直接使用单行命令，所有参数连在一起执行（将 192.168.88.31 替换为你的主机 IP）：


docker run -d --name etcd -p 2379:2379 -p 2380:2380 -e ETCD_NAME="etcd-node1" -e ETCD_LISTEN_CLIENT_URLS="http://0.0.0.0:2379" -e ETCD_ADVERTISE_CLIENT_URLS="http://192.168.88.31:2379" -e ETCD_LISTEN_PEER_URLS="http://0.0.0.0:2380" -e ETCD_INITIAL_ADVERTISE_PEER_URLS="http://192.168.88.31:2380" -e ETCD_INITIAL_CLUSTER="etcd-node1=http://192.168.88.31:2380" -e ETCD_INITIAL_CLUSTER_STATE="new" -e ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster-token" quay.io/coreos/etcd:v3.5.0

优势：一次性执行，无换行格式干扰，排查问题时优先使用此方式验证命令正确性。

方案 3：带数据持久化的启动命令（生产必备）

默认情况下，Etcd 数据存储在容器内部，容器删除后数据丢失。生产环境需添加 -v 参数挂载数据卷，命令如下：


# 1. 先在主机创建数据存储目录
mkdir -p /data/etcd
# 2. 带数据卷的启动命令（多行格式）
docker run -d --name etcd \
-p 2379:2379 \
-p 2380:2380 \
-v /data/etcd:/var/lib/etcd \
-e ETCD_NAME="etcd-node1" \
-e ETCD_LISTEN_CLIENT_URLS="http://0.0.0.0:2379" \
-e ETCD_ADVERTISE_CLIENT_URLS="http://192.168.88.31:2379" \
-e ETCD_LISTEN_PEER_URLS="http://0.0.0.0:2380" \
-e ETCD_INITIAL_ADVERTISE_PEER_URLS="http://192.168.88.31:2380" \
-e ETCD_INITIAL_CLUSTER="etcd-node1=http://192.168.88.31:2380" \
-e ETCD_INITIAL_CLUSTER_STATE="new" \
-e ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster-token" \
quay.io/coreos/etcd:v3.5.0

其中 /data/etcd 是主机的存储目录，/var/lib/etcd 是 Etcd 容器内的数据存储路径。

三、常见问题解决：避坑指南

部署过程中可能遇到命令执行错误、服务访问失败等问题，以下为高频问题及解决方案：

3.1 命令执行报错：invalid reference format 或 command not found

报错场景：执行多行命令后，终端提示 invalid reference format 或 -p: command not found。

根源：反斜杠 \ 后存在空格或特殊字符，终端将其识别为普通字符，导致命令被拆分执行。

解决方案：

严格按照方案 1 的要求编写多行命令，确保 \ 后无任何字符；
改用方案 2 的单行命令，快速规避格式问题；
若镜像未拉取成功，手动拉取镜像：docker pull quay.io/coreos/etcd:v3.5.0。

3.2 端口占用问题：bind: address already in use

报错场景：启动容器时提示端口被占用。

解决方案：


# 1. 查找占用端口的进程
netstat -tulpn | grep -E "2379|2380"
# 2. 停止占用进程（替换 1234 为实际进程 ID）
kill -9 1234
# 3. 或修改端口映射（如将 2379 改为 23790）
docker run -d --name etcd -p 23790:2379 -p 23800:2380 ...

3.3 服务访问报错：404 page not found

报错场景：容器启动成功，但执行 curl http://127.0.0.1:2379 时返回 404。

根源：Etcd v3 版本默认不兼容 v2 API，核心 API 路径需带 /v3/ 前缀，直接访问根路径会返回 404（正常现象）。

解决方案：使用带 /v3/ 前缀的 API 访问，具体验证方法见下文「服务验证」章节。

四、服务验证：确认 Etcd 正常工作

容器启动后，需从「容器状态」和「服务功能」两个维度验证，确保 Etcd 可正常使用：

4.1 验证容器状态


# 1. 查看 Etcd 容器运行状态（Status 为 Up 表示正常）
docker ps | grep etcd
# 输出示例：
# 2c659766f185   quay.io/coreos/etcd:v3.5.0   "/usr/local/bin/etcd"   5min ago   Up 5min    0.0.0.0:2379-2380->2379-2380/tcp   etcd

# 2. 若容器未运行，查看日志排查错误
docker logs etcd

4.2 验证 Etcd 服务功能

通过 Etcd 自带的 etcdctl 工具或 curl 命令验证服务可用性，推荐使用 etcdctl 工具（容器内已内置，无需额外安装）：

方式 1：使用容器内 etcdctl 工具验证

在这里插入图片描述


# 1. 查看 Etcd 版本（确认服务正常启动）
docker exec -it etcd etcdctl --endpoints=http://127.0.0.1:2379 version
# 输出示例（包含版本信息即为正常）：
# etcdctl version: 3.5.0
# API version: 3.5

# 2. 写入键值对（测试数据写入功能）
docker exec -it etcd etcdctl --endpoints=http://127.0.0.1:2379 put test "hello-etcd"
# 成功输出：OK

# 3. 读取键值对（测试数据读取功能）
docker exec -it etcd etcdctl --endpoints=http://127.0.0.1:2379 get test
# 成功输出：
# test
# hello-etcd

# 4. 删除键值对（可选，测试删除功能）
docker exec -it etcd etcdctl --endpoints=http://127.0.0.1:2379 del test

方式 2：使用 curl 访问 API 验证

Etcd v3 API 需带 /v3/ 前缀，直接访问根路径会返回 404，正确访问方式如下：


# 1. 查看 Etcd 版本（替换为你的主机 IP）
curl http://192.168.88.31:2379/v3/version
# 成功输出（JSON 格式版本信息）：
# {"etcdserver":"3.5.0","etcdcluster":"3.5.0"}

# 2. 写入键值对（key 和 value 需 Base64 编码）
# 注：test 的 Base64 编码为 dGVzdA==，hello-etcd 为 aGVsbG8tZXRjZA==
curl -X POST http://192.168.88.31:2379/v3/kv/put \
-H "Content-Type: application/json" \
-d '{"key":"dGVzdA==","value":"aGVsbG8tZXRjZA=="}'
# 成功输出：{"header":{"revision":2}}

五、扩展：Etcd 集群部署简介（可选）

生产环境为保证高可用，需部署 Etcd 集群（至少 3 个节点）。核心思路是通过 ETCD_INITIAL_CLUSTER 参数指定所有节点信息，以下为 3 节点集群的核心配置示例（以节点 IP 192.168.88.31、32、33 为例）：


# 节点 1（192.168.88.31）启动命令
docker run -d --name etcd \
-p 2379:2379 \
-p 2380:2380 \
-v /data/etcd:/var/lib/etcd \
-e ETCD_NAME="etcd-node1" \
-e ETCD_LISTEN_CLIENT_URLS="http://0.0.0.0:2379" \
-e ETCD_ADVERTISE_CLIENT_URLS="http://192.168.88.31:2379" \
-e ETCD_LISTEN_PEER_URLS="http://0.0.0.0:2380" \
-e ETCD_INITIAL_ADVERTISE_PEER_URLS="http://192.168.88.31:2380" \
-e ETCD_INITIAL_CLUSTER="etcd-node1=http://192.168.88.31:2380,etcd-node2=http://192.168.88.32:2380,etcd-node3=http://192.168.88.33:2380" \
-e ETCD_INITIAL_CLUSTER_STATE="new" \
-e ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster-token" \
quay.io/coreos/etcd:v3.5.0

# 节点 2（192.168.88.32）启动命令（仅修改名称和 IP）
docker run -d --name etcd \
-p 2379:2379 \
-p 2380:2380 \
-v /data/etcd:/var/lib/etcd \
-e ETCD_NAME="etcd-node2" \
-e ETCD_LISTEN_CLIENT_URLS="http://0.0.0.0:2379" \
-e ETCD_ADVERTISE_CLIENT_URLS="http://192.168.88.32:2379" \
-e ETCD_LISTEN_PEER_URLS="http://0.0.0.0:2380" \
-e ETCD_INITIAL_ADVERTISE_PEER_URLS="http://192.168.88.32:2380" \
-e ETCD_INITIAL_CLUSTER="etcd-node1=http://192.168.88.31:2380,etcd-node2=http://192.168.88.32:2380,etcd-node3=http://192.168.88.33:2380" \
-e ETCD_INITIAL_CLUSTER_STATE="new" \
-e ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster-token" \
quay.io/coreos/etcd:v3.5.0

# 节点 3（192.168.88.33）启动命令（同理修改）

集群部署后，通过以下命令验证集群状态：


docker exec -it etcd etcdctl --endpoints=http://192.168.88.31:2379,http://192.168.88.32:2379,http://192.168.88.33:2379 endpoint health

六、总结

Docker 安装 Etcd 的核心流程为「环境检查 → 命令部署 → 服务验证」，其中最易踩坑的是 命令换行格式 和 参数配置，关键要点总结如下：

环境先行：确保 Docker 服务正常运行，提前检查端口占用情况；
命令可靠：新手优先使用单行命令部署，生产环境务必添加数据持久化参数；
验证到位：不仅要确认容器运行状态，还要通过 etcdctl 或 API 验证数据读写功能；
高可用扩展：集群部署需保证节点数为奇数（3/5 个），通过初始集群参数关联所有节点。

若有转载，请标明出处：https://blog.csdn.net/CharlesYuangc/article/details/155018591