架构与系统设计 / 系统课时

建立 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 与 Envoy 最小实验拓扑

本实验固定 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 均可直接使用。

bash
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"

预期输出

text
go: creating new go.mod: module example.com/grpc-lab

依赖下载日志会随本地缓存状态变化,只要命令最终返回 0 即可。接着定义一个只包含 Ping 的服务,响应中额外返回实例名,后面才能观察 Envoy 实际选中了哪个后端。

proto
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 代码并整理依赖。

bash
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

预期输出

text
lab.pb.go
lab_grpc.pb.go

服务端只做一件事:把启动参数中的实例名原样放进响应。这样后续看到 backend-a 或 backend-b 时,不需要依赖日志猜测流量落点。

go
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)
    }
}

预期结果

text
保存为 server/main.go;在生成 Protobuf 代码并执行后续构建命令时应无编译错误

客户端保持同一个 ClientConn 连续调用多次,目标地址通过参数传入,因此同一份程序既能测试单个后端,也能测试 Envoy。

go
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())
    }
}

预期结果

text
保存为 client/main.go;在生成 Protobuf 代码并执行后续构建命令时应无编译错误

这两个程序没有客户端重试、服务发现或健康检查逻辑,故障实验开始前的行为更容易解释。

用 Compose 启动两个后端与 Envoy

用一个镜像同时构建 server 和 client。Dockerfile 只负责编译,不在镜像中写死启动角色。

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:nonroot

Envoy 监听 15000,并把 gRPC 请求转发到两个 Compose 服务。上游显式启用 HTTP/2;如果漏掉这一点,Envoy 可能按 HTTP/1.1 建立上游连接,gRPC 请求就无法按预期工作。

yaml
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 服务只在手动执行测试时启动。

yaml
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"]

启动环境并确认三个常驻服务都处于运行状态。

bash
docker compose up -d --build
docker compose ps --services --status running

预期结果

text
backend-a
backend-b
envoy

服务名的显示顺序可能不同;只要三项都存在即可。如果列表缺少某个服务,先用 docker compose logs <NAME> 查看对应日志,其中 <NAME> 替换为实际服务名。

验证直连与代理路径

先绕过 Envoy 直连 backend-a。这一步是基线:如果它失败,不应继续把问题归因于代理。

bash
docker compose run --rm client /client -target backend-a:50051 -n 2 -message direct

预期输出

text
call=1 instance=backend-a message=direct
call=2 instance=backend-a message=direct

再把目标改为 Envoy,并连续发送多次请求。

bash
docker compose run --rm client /client -target envoy:15000 -n 8 -message via-envoy

预期结果

text
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 配置。到这里,直连和代理两条路径已经被分别验证,后续任何超时、重试或摘除实验都可以在同一拓扑上对照观察。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立 gRPC-Go 与 Envoy 实验环境

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通