架构与系统设计 / 系统课时
建立 gRPC-Go 与 Envoy 实验环境
建立 gRPC-Go 与 Envoy 实验环境
这节课搭出一个可重复使用的最小可靠性实验环境:同一个 gRPC-Go 客户端既能直连单个后端,也能通过 Envoy 访问两个后端实例。完成后,你可以明确区分“客户端到代理”和“代理到后端”两段链路,为后续重试、负载均衡与故障治理实验提供基线。
学习目标
- 用 gRPC-Go 创建可识别实例身份的最小 Unary RPC 服务与客户端。
- 用 Envoy 把两个 gRPC 后端组成一个 HTTP/2 上游集群。
- 分别验证直连与代理访问路径,并确认请求确实能够到达不同实例。
固定实验拓扑
实验只保留四类对象:Client、Envoy、backend-a、backend-b。直连路径用于证明服务本身可用;代理路径用于观察 Envoy 的转发与负载均衡行为。所有组件放在同一个 Docker Compose 网络中,避免宿主机端口、DNS 与平台差异干扰结论。

本实验固定 gRPC-Go v1.83.0、Protocol Buffers Go v1.36.11、protoc-gen-go-grpc v1.6.2 与 Envoy v1.39.0。准备 Go 1.25+、Docker、Docker Compose 和 protoc,并确保 protoc --version 可以正常执行。
创建最小 gRPC-Go 服务
先创建独立目录并初始化模块。下面命令按 Bash 环境编写,Linux、macOS 或 WSL 均可直接使用。
mkdir -p grpc-lab/{proto,server,client}
cd grpc-lab
go mod init example.com/grpc-lab
go get google.golang.org/grpc@v1.83.0
go get google.golang.org/protobuf@v1.36.11
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.11
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.6.2
export PATH="$PATH:$(go env GOPATH)/bin"预期输出
go: creating new go.mod: module example.com/grpc-lab依赖下载日志会随本地缓存状态变化,只要命令最终返回 0 即可。接着定义一个只包含 Ping 的服务,响应中额外返回实例名,后面才能观察 Envoy 实际选中了哪个后端。
syntax = "proto3";
package lab.v1;
option go_package = "example.com/grpc-lab/gen/labv1;labv1";
service Lab {
rpc Ping(PingRequest) returns (PingReply);
}
message PingRequest {
string message = 1;
}
message PingReply {
string instance = 1;
string message = 2;
}将文件保存为 proto/lab.proto,然后生成 Go 代码并整理依赖。
protoc -I proto --go_out=. --go_opt=module=example.com/grpc-lab --go-grpc_out=. --go-grpc_opt=module=example.com/grpc-lab proto/lab.proto
go mod tidy
ls gen/labv1预期输出
lab.pb.go
lab_grpc.pb.go服务端只做一件事:把启动参数中的实例名原样放进响应。这样后续看到 backend-a 或 backend-b 时,不需要依赖日志猜测流量落点。
package main
import (
"context"
"flag"
"fmt"
"log"
"net"
pb "example.com/grpc-lab/gen/labv1"
"google.golang.org/grpc"
)
type server struct {
pb.UnimplementedLabServer
instance string
}
func (s *server) Ping(_ context.Context, in *pb.PingRequest) (*pb.PingReply, error) {
return &pb.PingReply{
Instance: s.instance,
Message: in.GetMessage(),
}, nil
}
func main() {
port := flag.Int("port", 50051, "listen port")
instance := flag.String("instance", "backend", "instance name")
flag.Parse()
lis, err := net.Listen("tcp", fmt.Sprintf(":%d", *port))
if err != nil {
log.Fatal(err)
}
grpcServer := grpc.NewServer()
pb.RegisterLabServer(grpcServer, &server{instance: *instance})
log.Printf("instance=%s listening=:%d", *instance, *port)
if err := grpcServer.Serve(lis); err != nil {
log.Fatal(err)
}
}预期结果
保存为 server/main.go;在生成 Protobuf 代码并执行后续构建命令时应无编译错误客户端保持同一个 ClientConn 连续调用多次,目标地址通过参数传入,因此同一份程序既能测试单个后端,也能测试 Envoy。
package main
import (
"context"
"flag"
"fmt"
"log"
"time"
pb "example.com/grpc-lab/gen/labv1"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials/insecure"
)
func main() {
target := flag.String("target", "127.0.0.1:50051", "gRPC target")
n := flag.Int("n", 1, "number of RPCs")
message := flag.String("message", "hello", "payload")
flag.Parse()
conn, err := grpc.NewClient(
*target,
grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
log.Fatal(err)
}
defer conn.Close()
client := pb.NewLabClient(conn)
for i := 1; i <= *n; i++ {
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
out, err := client.Ping(ctx, &pb.PingRequest{Message: *message})
cancel()
if err != nil {
fmt.Printf("call=%d error=%v\n", i, err)
continue
}
fmt.Printf("call=%d instance=%s message=%s\n", i, out.GetInstance(), out.GetMessage())
}
}预期结果
保存为 client/main.go;在生成 Protobuf 代码并执行后续构建命令时应无编译错误这两个程序没有客户端重试、服务发现或健康检查逻辑,故障实验开始前的行为更容易解释。
用 Compose 启动两个后端与 Envoy
用一个镜像同时构建 server 和 client。Dockerfile 只负责编译,不在镜像中写死启动角色。
FROM golang:1.25 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY gen ./gen
COPY server ./server
COPY client ./client
RUN CGO_ENABLED=0 go build -o /out/server ./server && CGO_ENABLED=0 go build -o /out/client ./client
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/server /server
COPY --from=build /out/client /client
USER nonroot:nonrootEnvoy 监听 15000,并把 gRPC 请求转发到两个 Compose 服务。上游显式启用 HTTP/2;如果漏掉这一点,Envoy 可能按 HTTP/1.1 建立上游连接,gRPC 请求就无法按预期工作。
static_resources:
listeners:
- name: grpc_ingress
address:
socket_address:
address: 0.0.0.0
port_value: 15000
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: grpc_ingress
codec_type: HTTP2
route_config:
name: grpc_route
virtual_hosts:
- name: grpc_service
domains: ["*"]
routes:
- match:
prefix: "/"
route:
cluster: grpc_backends
timeout: 0s
http_filters:
- name: envoy.filters.http.router
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
clusters:
- name: grpc_backends
type: STRICT_DNS
connect_timeout: 1s
lb_policy: ROUND_ROBIN
typed_extension_protocol_options:
envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
"@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
explicit_http_config:
http2_protocol_options: {}
load_assignment:
cluster_name: grpc_backends
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: backend-a
port_value: 50051
- endpoint:
address:
socket_address:
address: backend-b
port_value: 50051
admin:
address:
socket_address:
address: 0.0.0.0
port_value: 9901将其保存为 envoy.yaml。最后创建 compose.yaml;client 服务只在手动执行测试时启动。
services:
backend-a:
build: .
command: ["/server", "-port=50051", "-instance=backend-a"]
backend-b:
build: .
command: ["/server", "-port=50051", "-instance=backend-b"]
envoy:
image: envoyproxy/envoy:v1.39.0
volumes:
- ./envoy.yaml:/etc/envoy/envoy.yaml:ro
ports:
- "15000:15000"
- "9901:9901"
depends_on:
- backend-a
- backend-b
client:
build: .
profiles: ["tools"]
command: ["/client"]启动环境并确认三个常驻服务都处于运行状态。
docker compose up -d --build
docker compose ps --services --status running预期结果
backend-a
backend-b
envoy服务名的显示顺序可能不同;只要三项都存在即可。如果列表缺少某个服务,先用 docker compose logs <NAME> 查看对应日志,其中 <NAME> 替换为实际服务名。
验证直连与代理路径
先绕过 Envoy 直连 backend-a。这一步是基线:如果它失败,不应继续把问题归因于代理。
docker compose run --rm client /client -target backend-a:50051 -n 2 -message direct预期输出
call=1 instance=backend-a message=direct
call=2 instance=backend-a message=direct再把目标改为 Envoy,并连续发送多次请求。
docker compose run --rm client /client -target envoy:15000 -n 8 -message via-envoy预期结果
call=<ID> instance=backend-a message=via-envoy
call=<ID> instance=backend-b message=via-envoy<ID> 表示实际调用序号。调用顺序可能不同,但多次请求中应能观察到两个实例名。若直连成功而代理路径全部失败,优先检查 docker compose logs envoy;若只出现一个实例,则先确认 backend-b 是否运行,再检查 Envoy 的 cluster 配置。到这里,直连和代理两条路径已经被分别验证,后续任何超时、重试或摘除实验都可以在同一拓扑上对照观察。