etcd快速入门 - 技术栈

etcd 快速入门

一、etcd 是什么

分布式强一致键值存储，基于 Raft 共识算法，Go 开发。三大核心用途：

配置中心：项目配置统一存放，支持实时热更新
服务注册发现：微服务自动上下线管理
分布式锁：多程序 / 多机器互斥竞争资源 K8s 底层元数据存储就是 etcd。

两个核心程序：

etcd.exe：服务端（必须先启动，提供 2379 端口）
etcdctl.exe：客户端命令行，用来增删改查数据

端口：

2379：客户端读写端口
2380：集群节点之间通信端口

二、Windows 环境准备

下载对应系统包：etcd-v3.6.12-windows-amd64.zip
解压到 E:\Db\etcds\etcd-v3.6.12
在目录新建修复后的启动脚本 etcd-server.bat（解决环境变量冲突报错）

batch

复制代码

etcd-server.bat
=====================
@echo off
chcp 65001 >nul
title Etcd 单机服务端(Windows)

:: ====================== 配置参数区 ======================
set "ETCD_NAME=win-local-etcd"
set "DATA_DIR=.\etcd-data"
set "CLIENT_PORT=2379"
set "PEER_PORT=2380"
:: ======================================================

:: 关键：清空系统残留的etcd环境变量，避免冲突
set ETCD_NAME=
set ETCD_DATA_DIR=
set ETCD_LISTEN_CLIENT_URLS=
set ETCD_LISTEN_PEER_URLS=
set ETCD_ADVERTISE_CLIENT_URLS=

echo ==============================================
echo Etcd 单机启动脚本
echo 节点名称: %ETCD_NAME%
echo 数据目录: %DATA_DIR%
echo 客户端端口: %CLIENT_PORT%
echo 集群通信端口: %PEER_PORT%
echo ==============================================
echo.

:: 判断etcd.exe是否存在
if not exist "etcd.exe" (
    echo 错误：当前目录未找到 etcd.exe，请将脚本放在etcd解压目录！
    pause
    exit /b 1
)

:: 创建数据目录
if not exist "%DATA_DIR%" (
    echo 创建数据目录 %DATA_DIR%
    md "%DATA_DIR%"
)
echo.

:: 启动etcd
etcd.exe ^
--name win-local-etcd ^
--data-dir %DATA_DIR% ^
--listen-client-urls http://0.0.0.0:%CLIENT_PORT% ^
--advertise-client-urls http://127.0.0.1:%CLIENT_PORT% ^
--listen-peer-urls http://0.0.0.0:%PEER_PORT%

echo.
echo Etcd 服务已停止，按任意键关闭窗口
pause

三、标准操作流程（必按顺序）

双击 etcd-server.bat 启动服务端，窗口保持打开（关了服务就停）
新开一个 PowerShell/CMD，进入同目录执行 etcdctl 命令

连通测试

powershell

复制代码

.\etcdctl.exe version
# 输出版本号代表连接正常

四、etcdctl 常用基础命令（CRUD）

1. 写入数据 put

powershell

复制代码

# 基础写入 key=demo value=123456
.\etcdctl.exe put demo 123456

# 分层目录格式（推荐，像文件夹）
.\etcdctl.exe put /app/db/user root
.\etcdctl.exe put /app/db/pwd 123123

2. 查询数据 get

powershell

复制代码

# 查单个key
.\etcdctl.exe get demo

# 查询前缀下所有key（/app全部数据）
.\etcdctl.exe get /app --prefix

# 只打印value，不显示key
.\etcdctl.exe get /app/db/user --print-value-only

3. 删除 del

powershell

复制代码

# 删除单个键
.\etcdctl.exe del demo

# 删除 /app 下所有数据
.\etcdctl.exe del /app --prefix

4. Watch 监听（核心功能）

新开窗口执行监听，修改 / 删除对应 key 会实时推送消息，适合配置热更新

powershell

复制代码

# 监听单个key
.\etcdctl.exe watch demo

# 监听整个目录所有变化
.\etcdctl.exe watch /app --prefix

5. Lease 租约（自动过期，服务注册专用）

租约到期绑定的 key 自动删除，适合临时服务注册

powershell

复制代码

# 创建10秒租约，返回lease ID
.\etcdctl.exe lease grant 10
=========================
验证方式：
1.把上面输出的"id"放到这个命令的地方
.\etcdctl.exe lease timetolive "ID"

# 写入key并绑定租约（替换ID）
.\etcdctl.exe put /service/gateway 127.0.0.1:8080 --lease=123456789



# 续租，防止过期
.\etcdctl.exe lease keep-alive "id"

6. Txn 事务（原子操作，分布式锁底层）

要么全部成功，要么全部失败

powershell

复制代码

.\etcdctl.exe txn <<EOF
compares:
value("/lock") = ""
success:
put /lock 1
failure:
get /lock
EOF

五、常见报错 & 解决

connect refused / context deadline exceeded 原因：没启动 etcd-server.bat 或服务窗口关闭解决：启动服务，保持窗口打开，新开终端操作 ctl
conflicting environment variable ETCD_NAME fatal崩溃 原因：系统残留 etcd 环境变量，和脚本 --name 冲突解决：使用上面修复版 bat，启动前清空所有 ETCD_* 环境变量
端口占用

powershell

复制代码

# 查询2379占用进程
netstat -ano | findstr "2379"

修改 bat 内 CLIENT_PORT 更换端口即可

六、简单业务场景举例

配置中心 所有服务读取 /config 下配置，用 watch 监听，修改 etcd 配置不用重启程序。
微服务注册 网关 / 业务服务启动时创建租约写入自身地址，程序退出租约过期自动清除。
分布式锁 使用 txn 事务写入临时 key，执行完删除，多进程互斥操作文件 / 数据库。

七、极简实操演示完整流程

双击 etcd-server.bat 启动服务
新开终端写入配置

powershell

复制代码

.\etcdctl.exe put /server/port 8090
.\etcdctl.exe put /server/name test-api

监听配置窗口

powershell

复制代码

.\etcdctl.exe watch /server --prefix

修改配置，监听窗口立刻收到变更

powershell

复制代码

.\etcdctl.exe put /server/port 9090