Docker部署etcd：curl调用正常但Golang客户端报DeadlineExceeded

核心原因分析 #

你的问题是：curl能正常调用etcd的HTTP网关接口，但Golang的clientv3（基于gRPC）连接超时，报错error reading server preface: EOF。这是因为etcd的v3 API有两种访问方式：

• curl调用的是HTTP网关接口（基于HTTP/1.1）
• clientv3直接使用gRPC协议（基于HTTP/2）

报错说明客户端尝试建立HTTP/2连接时，服务器返回了非预期响应（直接断开连接），大概率是etcd未正确开启gRPC服务，或客户端与服务器版本不兼容。

排查步骤与解决方法 #

1. 验证etcd服务器的gRPC服务是否正常 #

使用grpcurl工具测试gRPC连接：

# 安装grpcurl（需已安装Go环境）
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# 测试gRPC服务是否可访问
grpcurl -plaintext my-server-ip:2379 list

• 如果输出类似etcdserverpb.EtcdServer、etcdserverpb.Watch等服务列表，说明gRPC服务正常；
• 如果报错（如Failed to dial target host），则问题出在etcd服务器配置。

2. 修复etcd服务器配置（若gRPC服务异常） #

针对Bitnami的etcd镜像，调整Docker Compose的环境变量：

environment:
  # 保留原有变量，新增或修改以下项
  - "ETCD_ENABLE_V2=false"  # 强制禁用v2 API，避免端口冲突
  - "ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379"  # 明确监听所有IP的2379端口（gRPC+HTTP网关）
  - "ETCD_ADVERTISE_CLIENT_URLS=http://my-server-ip:2379"  # 替换为你的服务器公网/内网IP，避免客户端拿到0.0.0.0

重启etcd服务：

docker-compose down && docker-compose up -d

3. 确保Golang客户端与etcd版本兼容 #

clientv3版本需与etcd服务器版本尽量匹配（差异不超过1个大版本）：

• 查看服务器etcd版本：

  docker exec -it <etcd容器ID> etcd --version
  

• 在go.mod中指定对应版本：

  require go.etcd.io/etcd/client/v3 v3.5.11  # 替换为服务器对应的版本
  

4. 修正Golang客户端代码 #

你的代码存在两处问题：未及时检查错误、未给Status调用设置超时，同时需明确指定不安全连接（因为etcd用的是HTTP而非HTTPS）：

package main

import (
	"context"
	"log"
	"time"

	"go.etcd.io/etcd/client/v3"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
)

func main() {
	cli, err := clientv3.New(clientv3.Config{
		Endpoints:   []string{"my-server-ip:2379"},
		DialTimeout: 5 * time.Second,
		// 添加gRPC拨号选项，明确使用不安全连接
		DialOptions: []grpc.DialOption{
			grpc.WithTransportCredentials(insecure.NewCredentials()),
		},
	})
	if err != nil {
		log.Fatal("连接etcd失败:", err)
	}
	defer cli.Close()
	log.Println("成功连接etcd")

	// Put操作添加超时并立即检查错误
	putCtx, putCancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer putCancel()
	_, err = cli.Put(putCtx, "sample_key", "sample_value")
	if err != nil {
		log.Fatal("Put操作失败:", err)
	}
	log.Println("Put操作成功")

	// Status操作添加超时
	statusCtx, statusCancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer statusCancel()
	statusRes, err := cli.Status(statusCtx, "my-server-ip:2379")
	if err != nil {
		log.Fatal("获取Status失败:", err)
	}
	log.Printf("etcd状态: %+v", statusRes)
}

5. 排除网络拦截（最后一步） #

若以上步骤无效，检查服务器是否存在其他网络限制：

• 确认服务器的iptables规则未拦截2379端口的HTTP/2流量；
• 若服务器在云平台，检查安全组是否允许2379端口的TCP流量（HTTP/2基于TCP）。

内容的提问来源于stack exchange，提问作者Messagehw