把 etcd 做成一个可用的 mock 镜像，最大的价值不是省掉安装，而是让本地测试和 CI 环境拥有一致的键值服务行为。EtcdMock2Image 这个名字可以理解为两步：先实现一个 etcd mock，再用 Docker 把它打成 image。本文使用 Node.js 作为实现语言，因为它启动快、HTTP 处理直接，非常适合写这类轻量级替身服务。
一、EtcdMock2Image要解决的测试环境问题
在微服务项目里，配置中心、服务发现和分布式锁经常依赖 etcd。真实的 etcd 服务虽然稳定，但它终究是一个需要独立部署和维护的组件。开发机资源有限时，安装一个完整 etcd 集群并不划算，单节点模式也需要管理数据目录、启动参数和端口占用。EtcdMock2Image 的思路就是把 etcd 的核心键值能力抽象出来，用 Node.js 写一个足够轻量的模拟服务，再打包成标准 Docker 镜像。测试环境需要时，一条 docker run 命令就能拿到可用的键值接口。
这种做法并不是要替代生产环境的 etcd，而是为了降低测试成本。很多集成测试只需要 put、get、delete 和简单的 watch 语义，并不关心 etcd 的 Raft 一致性、WAL 日志或集群选举。把这些复杂部分剥离掉，mock 服务可以做到秒级启动，而且每次运行都不保留历史数据，从源头上避免测试数据互相污染。
Node.js 在这里的优势很明显：单线程事件循环天然适合处理大量短连接请求，启动速度比 Java 或 Go 的服务更快，写一个简单的 HTTP 接口也不需要引入重量级框架。对于想定制 mock 行为的团队来说，Node.js 代码更容易修改，比如在 put 时加延迟、在 range 时返回固定值，都能快速实现。
二、用 Node.js 实现核心键值接口
要模拟 etcd，先要确定客户端通过什么协议访问。真实 etcd v3 使用 gRPC 协议，完整兼容需要引入 proto 文件和 gRPC 服务端，复杂度较高。对于大部分测试场景，使用 HTTP JSON 接口已经够用，客户端只需要把请求发到 mock 服务对应的路径上。本文的实现选择了 /v3/kv/put、/v3/kv/range 和 /v3/kv/delete 这几个常用路径，请求和响应格式与 etcd 的 gRPC gateway 类似。
存储层用一个 Map 结构保存键值对，再引入一个全局递增的 revision 版本号。每次 put 操作都会让 revision 加一，这样调用方可以根据版本号判断数据是否变化。delete 操作需要支持按 key 删除，也可以简化为从 Map 中移除对应项。为了让模拟服务更容易排查问题，可以在控制台输出每次操作的 key 和 revision。
下面是一个最小可运行的服务实现，使用 Node.js 原生 http 模块，不依赖任何第三方框架。put 和 range 都通过读取请求体来解析 JSON 参数。
const http = require("http");
const url = require("url");
const store = new Map();
let revision = 0;
function json(res, code, data) {
res.writeHead(code, {"Content-Type": "application/json"});
res.end(JSON.stringify(data));
}
const server = http.createServer(function(req, res) {
const parsed = url.parse(req.url, true);
const path = parsed.pathname;
if (path === "/v3/kv/put" && req.method === "POST") {
let body = "";
req.on("data", function(chunk) { body += chunk; });
req.on("end", function() {
const input = JSON.parse(body);
const key = input.key;
const value = input.value || "";
revision = revision + 1;
store.set(key, {value: value, rev: revision});
json(res, 200, {result: {revision: revision}});
});
return;
}
if (path === "/v3/kv/range" && req.method === "POST") {
let body = "";
req.on("data", function(chunk) { body += chunk; });
req.on("end", function() {
const input = JSON.parse(body);
const key = input.key;
const item = store.get(key);
if (item) {
json(res, 200, {kvs: [{key: key, value: item.value, mod_revision: item.rev}]});
} else {
json(res, 200, {kvs: []});
}
});
return;
}
json(res, 404, {error: "not found"});
});
server.listen(2379, function() {
console.log("etcd mock listening on 2379");
});
delete 接口与 put 类似，只是将 store 中的 key 删除并返回删除数量。watch 的实现相对复杂一些，最简单的做法是采用长轮询：客户端发送 watch 请求后，服务端把连接挂起，当目标 key 发生写入时立即返回新值；如果超过设定时间没有变化，则返回一个空事件。这样虽然不如 gRPC 双向流高效，但对于测试已经足够。
如果要模拟租约 lease，可以给每个 key 增加过期时间字段，服务端用定时器扫描并清理过期数据。不过租约不是所有测试都需要的，建议先实现键值操作，等确实遇到依赖 lease 的用例时再补上。保持 mock 的代码量可控，比追求大而全更重要。
三、Dockerfile 多阶段构建与镜像优化
把 Node.js 服务打包成镜像，最直接的方式是使用 node 官方镜像。为了控制最终镜像体积，推荐采用多阶段构建。第一阶段安装依赖并编译，第二阶段只复制运行时需要的文件，避免把 npm 缓存和开发依赖打进镜像。下面是一个基于 node:20-alpine 的 Dockerfile。
FROM node:20-alpine AS build WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci --omit=dev COPY src ./src FROM node:20-alpine WORKDIR /app ENV NODE_ENV=production COPY --from=build /app/node_modules ./node_modules COPY --from=build /app/src ./src EXPOSE 2379 CMD ["node", "src/server.js"]
这个 Dockerfile 假设项目结构里 package.json 位于根目录，服务代码放在 src 目录下。如果代码中使用的是原生 http 模块，第一阶段甚至不需要执行 npm run build，因为 JavaScript 文件可以直接运行。第二阶段复制 node_modules 是为了确保没有任何依赖缺失，但如果项目完全没有第三方依赖，也可以省掉这层复制，镜像会更小。
构建完成后，可以用 docker build -t etcdmock2image . 生成镜像，再用 docker run -p 2379:2379 etcdmock2image 启动。alpine 基础镜像加上 node 运行时，最终镜像大小通常在 150 MB 左右。如果对体积要求更高，可以改用 gcr.io/distroless/nodejs 作为运行时基础镜像，但 distroless 没有 shell，排查问题会稍微麻烦一点。
四、接入测试环境与验证方式
把 EtcdMock2Image 接入测试环境有两种常见方式。第一种是在 docker-compose 中声明一个服务，把 2379 端口映射到宿主机或容器网络内部，微服务通过环境变量指向 mock 地址。第二种是在 CI 流水线中作为 sidecar 容器启动，跑完测试后自动销毁。两种方式都能保证每次测试使用干净的键值空间。
验证 mock 服务是否正常，可以用 curl 发送一个 put 请求，再发送 range 请求查看返回值。下面是一个示例命令序列。
curl -X POST http://127.0.0.1:2379/v3/kv/put -d '{"key":"/app/config","value":"true"}'
curl -X POST http://127.0.0.1:2379/v3/kv/range -d '{"key":"/app/config"}'
看到 range 返回的 kvs 数组里包含刚刚写入的 key 和 value，说明服务基本可用。需要特别注意的是，这个 mock 服务并没有实现权限认证和 TLS，因此只适合在本地或内网测试环境中使用，不要暴露到公网。
对于使用 etcd 客户端的项目，可以在测试配置里将 endpoints 改为 http://127.0.0.1:2379，并关闭 TLS 校验。虽然真实 etcd v3 客户端通常使用 gRPC 协议，但很多语言也提供了 HTTP JSON 的接入方式。如果客户端强制走 gRPC，可以进一步扩展 mock 服务，使用 grpc-js 实现 etcd 的 KV 服务定义，这样可以做到协议级兼容。