# etcd

**Repository Path**: middleware-lab/etcd

## Basic Information

- **Project Name**: etcd
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# etcd 使用场景演示 / etcd Playground

一个用 **Go 后端（内嵌 etcd）+ React 前端** 搭建的交互式演示项目，覆盖 etcd 的常见**使用场景、特性与常见坑**。后端在进程内直接拉起一个单节点 etcd，**开箱即用，无需额外部署**。

An interactive demo built with a **Go backend (embedded etcd) + React frontend**, covering common etcd **usage scenarios, features, and pitfalls**. The backend boots a single-node etcd in-process — run it and it just works.

## 架构 / Architecture

```
┌────────────────────────────┐        ┌──────────────────────────────────┐
│  React 前端 (Vite + antd)   │  HTTP  │  Go 后端 (net/http, :18081)          │
│  - 场景化页面 + 可视化        │ ─────▶ │  - REST + SSE 接口                 │
│  - EventSource 接收 SSE      │        │  - 内嵌 etcd (embed, 127.0.0.1:2379)│
└────────────────────────────┘        └──────────────────────────────────┘
```

- **后端**：Go + `go.etcd.io/etcd/server/v3/embed`（内嵌 etcd）+ `go.etcd.io/etcd/client/v3`，标准库 `net/http`，SSE 实时推送。
- **前端**：React 18 + TypeScript + Vite + Ant Design v5 + axios + 原生 EventSource。

## 目录结构 / Layout

```
etcd/
├── backend/            # Go 后端
│   ├── main.go         # 启动内嵌 etcd + HTTP 服务
│   └── internal/
│       ├── embedsrv/   # embed 配置与启动
│       └── api/        # 路由 + 各场景处理器（kv/watch/lease/txn/lock/...）
├── frontend/           # React 前端
│   └── src/
│       ├── App.tsx     # 布局 + 侧边导航
│       ├── components/ # CodeBlock / JsonView / LiveStream
│       └── pages/      # 10 个场景页
├── Makefile
└── README.md
```

## 环境要求 / Prerequisites

- Go ≥ 1.26（依赖 etcd v3.7）
- Node.js ≥ 18（推荐 20+）

## 快速开始 / Quick start

**1. 启动后端**（首次会拉取 Go 依赖，已配置 `goproxy.cn`）：

```bash
make dev-backend            # 或 cd backend && go run .
```

启动成功后会看到：

```
etcd-demo backend listening on http://127.0.0.1:18081 (embedded etcd on 127.0.0.1:2379)
```

**2. 启动前端**（另开一个终端；首次 `npm install`，已配置 npmmirror）：

```bash
make dev-frontend          # 或 cd frontend && npm install && npm run dev
```

然后打开 http://localhost:5173 即可交互。

**构建产物**：

```bash
make build    # go build ./... + npm run build
```

## 场景一览 / Scenarios

| 页面 | 演示内容 |
| --- | --- |
| 概览 Overview | 集群状态、etcd 版本、成员信息 |
| KV 基础 | Put / Get / Delete / Range 前缀查询 / MVCC 历史（WithRev） |
| Watch 监听 | 单 key / 前缀监听、PUT/DELETE 事件、fromRev 回放 |
| Lease 租约 | Grant / 绑定 key / Revoke，lease 过期后 key 自动消失 |
| 事务 Transaction | 原子 CAS，以及「非原子读改写 vs 事务」的丢更新对比 |
| 分布式锁 Lock | lease + 事务实现 mutex，安全释放（持有者校验） |
| 选主 Election | Campaign / Resign / Observe 观测 leadership 切换 |
| 配置中心 Config | 配置写入 + Watch 热加载 |
| 服务发现 Discovery | 实例注册（lease 心跳）、注销、上下线事件 |
| 常见坑 Pitfalls | 大 value 超限、误释放他人锁、并发丢更新等 |

每个页面都附带对应的 **Go 实现代码片段**，可折叠查看。

## 场景级接口 / API summary

所有接口位于 `/api` 前缀下，除标注外均返回 JSON；`*/events`、`*/stream`、`*/watch` 为 SSE 长连接。

- `GET /api/health`、`GET /api/meta`
- KV：`PUT/GET/DELETE /api/kv`、`GET /api/kv/range`、`GET /api/kv/history`、`POST /api/kv/large`
- Watch：`GET /api/watch/stream?key=|prefix=&fromRev=`
- Lease：`POST /api/lease/grant|put|revoke`、`GET /api/lease/keys`、`GET /api/lease/events`
- Txn：`POST /api/txn/cas`、`POST /api/txn/race`
- Lock：`POST /api/lock/acquire|release|force-release`、`GET /api/lock/list`
- Election：`POST /api/election/campaign|resign`、`GET /api/election/leader`、`GET /api/election/events`
- Config：`PUT/GET /api/config`、`GET /api/config/watch`
- Discovery：`POST /api/discovery/register`、`DELETE /api/discovery/deregister`、`GET /api/discovery/list`、`GET /api/discovery/watch`

## 设计说明 / Notes

- 内嵌 etcd 的数据目录使用临时目录，进程退出后自动清理；若需连接外部 etcd，可在 `internal/embedsrv` 增加「环境变量指定端点」分支，其余场景代码复用。
- 锁 / 选主 / 服务发现场景会记录进程内存中的会话状态（用于续约与释放），etcd 本身仍是分布式状态的唯一事实来源。
- SSE 事件统一以 `event:` 命名（`open` / `event` / `leader`），前端 EventSource 只处理 GET 请求。