361 lines
13 KiB
Markdown
361 lines
13 KiB
Markdown
---
|
||
tags: [gRPC, Go, Server, Configuration]
|
||
create time: 2026-05-13 23:20
|
||
---
|
||
|
||
# ServerOption — 生产级配置速查
|
||
|
||
## 概述
|
||
|
||
`grpc.NewServer(...)` 接受任意数量的 `ServerOption`，每个 Option 都是一个函数，用来改变 server 的行为。它们使用**函数式选项模式**——看起来像参数列表，其实是链式修改内部状态。
|
||
|
||
本文不罗列所有选项（官方文档有），只讲你在生产环境中最常遇到、最需要认真考虑的这几个——从 TLS 到传输层优化，共九项。
|
||
|
||
> [!question] 为什么不全部开启？
|
||
> 有些选项只在特定场景有用，开了反而增加复杂度或带来副作用。学会"知道什么时候不开"比"知道开什么"更重要。
|
||
|
||
## 核心选项速查
|
||
|
||
### 1. TLS 认证
|
||
|
||
```go
|
||
grpc.Creds(credentials.NewTLS(tlsConfig))
|
||
```
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **默认值** | 无加密，明文传输 |
|
||
| **必须配吗** | **生产环境必须** |
|
||
| **为什么** | gRPC 通常跑在内网，但不代表数据可以不加密。中间人攻击、旁路监听都可能读到你的请求体 |
|
||
|
||
> [!tip] 内网也要 TLS
|
||
> "我们部署在内网，不需要 TLS"——这个想法在过去可能成立，但现在零信任架构下，内网到内网之间也应该加密。即使只做 mTLS（双向认证）也好过什么都没有。
|
||
|
||
### 2. 消息大小限制
|
||
|
||
```go
|
||
grpc.MaxRecvMsgSize(16 * 1024 * 1024), // 接收上限 16MB
|
||
grpc.MaxSendMsgSize(16 * 1024 * 1024), // 发送上限 16MB
|
||
```
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **默认值** | 各 4MB |
|
||
| **调大原因** | 文件上传、大批量导出等场景需要更大的消息 |
|
||
| **注意事项** | 每次收到一个超过上限的消息，连接会被直接关闭，client 收到 `resource exhausted` 错误 |
|
||
|
||
> [!warning] 对称设置
|
||
> `MaxRecvMsgSize` 和 `MaxSendMsgSize` 应该对称设置。如果你限制了接收为 16MB，但发送还是默认的 4MB，那当你的服务要返回大数据时也会报错。
|
||
|
||
### 3. 最大并发流数量
|
||
|
||
```go
|
||
grpc.MaxConcurrentStreams(1024)
|
||
```
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **默认值** | 100 |
|
||
| **含义** | HTTP/2 单个连接上最多同时存在 100 个未响应的 stream |
|
||
| **为什么要改** | 如果 client 大量使用 streaming RPC，100 可能不够用；放宽到 1024+ 是常见做法 |
|
||
|
||
> [!note] DoS 防护考量
|
||
> 这个值的本质是防恶意客户端开太多并发流耗尽服务器资源。正常业务不会触发上限，所以调到 1024 基本没有风险。
|
||
|
||
### 4. Keepalive 心跳参数 ⭐ 高频踩坑
|
||
|
||
```go
|
||
grpc.KeepaliveParams(keepalive.ServerParameters{
|
||
MaxConnectionIdle: 15 * time.Minute, // 空闲多久断开
|
||
KeepaliveTime: 20 * time.Second, // 每多久发一次心跳
|
||
KeepaliveTimeout: 5 * time.Second, // 心跳超时时间
|
||
MinTimeBetweenPings: 10 * time.Second,
|
||
PingWithoutCallsAllowed: true, // 没请求时也允许发 ping
|
||
})
|
||
```
|
||
|
||
这是最容易忽略也最容易出问题的配置。
|
||
|
||
#### 默认值的问题
|
||
|
||
gRPC 默认的 keepalive 策略是：idle 超过 **2 小时**才断开连接。这意味着：
|
||
|
||
- 如果你的服务后面有 **负载均衡器**（如 Envoy、Nginx、AWS ALB），LB 的超时时间通常只有几分钟
|
||
- LB 会在 idle 几分钟后切断连接，但 gRPC server 不知道，还在往已经断掉的 socket 写数据
|
||
- Client 侧看到的现象就是随机的 **"connection reset by peer"** 错误
|
||
|
||
#### 解决方案
|
||
|
||
把 `MaxConnectionIdle` 设短到 **15~20 分钟**——让 server 在 LB 之前主动重建连接。这样两端对连接生命周期有一致认知，LB 只是被动转发，不会被要求管理长连接。
|
||
|
||
| 场景 | `MaxConnectionIdle` | 建议 |
|
||
|------|---------------------|------|
|
||
| **直连无 LB** | 保持默认 (2h) | 减少不必要的连接重建开销 |
|
||
| **有 LB (Nginx/Envoy)** | 15~20 分钟 | 与 LB 超时时间错开即可 |
|
||
| **K8s + Ingress** | 5~10 分钟 | K8s Service 的 timeout 更短 |
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph Client["Client"]
|
||
C_conn["HTTP/2 Connection"]
|
||
end
|
||
|
||
subgraph LB["Load Balancer<br/>timeout: 5min"]
|
||
LB_state["连接状态: active → idle → close"]
|
||
end
|
||
|
||
subgraph Server["Server<br/>默认 idle: 2h"]
|
||
S_conn["HTTP/2 Connection"]
|
||
end
|
||
|
||
C_conn -->|连接| LB_state
|
||
LB_state -->|连接| S_conn
|
||
|
||
style C_conn fill:#E3F2FD
|
||
style S_conn fill:#A8E6CF
|
||
style LB_state fill:#FFEAA7,color:#000
|
||
```
|
||
|
||
直连场景：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Client["Client"] -->|直连| Server["Server"]
|
||
style Client fill:#E3F2FD
|
||
style Server fill:#A8E6CF
|
||
```
|
||
|
||
### 5. 拦截器链
|
||
|
||
```go
|
||
grpc.ChainUnaryInterceptor(logging.Unary(), auth.Unary())
|
||
```
|
||
|
||
拦截器是 gRPC 里最灵活的扩展点，用于在方法执行前后插入横切逻辑。
|
||
|
||
| 层级 | 做什么 | 例子 |
|
||
|------|--------|------|
|
||
| **外层** | 横切关注点 | 日志、链路追踪、指标采集 |
|
||
| **中层** | 业务安全校验 | 鉴权、限流 |
|
||
| **内层** | 兜底逻辑 | panic recover、超时控制 |
|
||
|
||
执行顺序像剥洋葱：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Client["请求到达"] --> Logging["日志拦截器<br/>(最外)"]
|
||
Logging --> Auth["鉴权拦截器<br/>(中层)"]
|
||
Auth --> Recovery["恢复拦截器<br/>(最内)"]
|
||
Recovery --> Handler["实际业务方法"]
|
||
|
||
style Client fill:#E3F2FD
|
||
style Handler fill:#FFF3E0
|
||
```
|
||
|
||
拦截器的详细用法参见 [[hhs/gRPC/5. 中间件与拦截器/14-Unary 与 Stream 拦截器]]。
|
||
|
||
### 6. StatsHandler（链路追踪 / 指标）
|
||
|
||
```go
|
||
// grpc.StatsHandler(otelgrpc.NewServerHandler()), // OpenTelemetry
|
||
```
|
||
|
||
StatsHandler 是一种比拦截器更底层的方式注入可观测性数据。典型用途是接入 OpenTelemetry 做分布式链路追踪。
|
||
|
||
> [!note] 拦截器 vs StatsHandler
|
||
> - 拦截器：Go-only 方案，编写灵活，可以直接访问 request/response
|
||
> - StatsHandler：多语言统一方案，OpenTelemetry SDK 原生支持，跨语言的 metrics/tracing 一致性好
|
||
|
||
#### 用 StatsHandler 采集 gRPC 核心指标
|
||
|
||
一个典型的 server-side StatsHandler 需要关注三个事件：
|
||
|
||
```go
|
||
type MetricsHandler struct{}
|
||
|
||
func (*MetricsHandler) TagConn(ctx context.Context, info *stats.ConnTagInfo) context.Context {
|
||
return ctx // 连接级别标签（可选）
|
||
}
|
||
|
||
func (*MetricsHandler) HandleConn(ctx context.Context, cs stats.ConnStats) {
|
||
if cs.Done() {
|
||
zap.L().Sugar().Infow("连接关闭",
|
||
"remote", cs.RemoteAddr(),
|
||
"duration", cs.Duration().Milliseconds(),
|
||
)
|
||
}
|
||
}
|
||
|
||
func (*MetricsHandler) TagRPC(context.Context, *stats.RPCTagInfo) context.Context { return context.Background() }
|
||
|
||
func (*MetricsHandler) HandleRPC(ctx context.Context, rs stats.RPCStats) {
|
||
switch rs.(type) {
|
||
case *stats.Begin:
|
||
// RPC 开始
|
||
case *stats.OutPayload:
|
||
// 记录请求大小
|
||
case *stats.InPayload:
|
||
// 记录响应大小 + 耗时
|
||
case *stats.End:
|
||
// 汇总：状态码、总耗时 → Prometheus counter/histogram
|
||
}
|
||
}
|
||
```
|
||
|
||
生产环境通常不需要自己写——直接使用 `prometheus-grpc` 或 `otelgrpc` 库即可。理解原理是为了排查"为什么某个指标的粒度不够"时知道该去哪里改。
|
||
|
||
---
|
||
|
||
## 更多实用选项
|
||
|
||
### 7. 流式安全模式
|
||
|
||
gRPC **没有提供**一个直接的全局选项来限制 stream 累计收到的消息数量。这是有意为之的设计选择——有些场景（如大文件分块传输）天然需要大量小消息。
|
||
|
||
因此你需要在应用层做防护：
|
||
|
||
```go
|
||
// Stream 服务端实现中手动计数
|
||
func (s *server) UploadFile(stream pb.UserService_UploadFileServer) error {
|
||
var msgCount int64
|
||
const maxMessages = 100000
|
||
|
||
for {
|
||
req, err := stream.Recv()
|
||
if err != nil {
|
||
return status.Convert(err).Err()
|
||
}
|
||
msgCount++
|
||
if msgCount > maxMessages {
|
||
return status.Errorf(codes.ResourceExhausted,
|
||
"max messages exceeded: %d", msgCount)
|
||
}
|
||
// 处理数据...
|
||
}
|
||
}
|
||
```
|
||
|
||
> [!tip] 结合上下文取消
|
||
> gRPC streaming RPC 天然会收到 `context.Canceled` / `context.DeadlineExceeded`。只要你正确设置了 client deadline，大多数异常情况都会被自动终止，不需要额外兜底。
|
||
|
||
### 8. 请求超时控制的完整理解 ⭐
|
||
|
||
> [!question] gRPC 有默认的客户端超时吗？
|
||
> 没有。gRPC 协议本身不设定任何超时——如果 client 不指定 deadline，server 会一直等下去。这意味着一个慢查询可以永远占用一个 goroutine。
|
||
|
||
这是 gRPC 最容易让人困惑的地方：**超时控制本质上是 client 的责任**，但 server 也应该有自己的兜底策略。
|
||
|
||
| 层 | 谁设 | 怎么设 | 作用 |
|
||
|----|------|--------|------|
|
||
| **client 端 deadline** | Client | `context.WithTimeout(ctx, 5*time.Second)` | 请求从发起起最多活 5 秒，超时时自动取消 |
|
||
| **server 端 recover** | Server interceptor | panic recover / context 检查 | 防止业务逻辑泄漏 goroutine |
|
||
|
||
```go
|
||
// Client 侧：设置 5 秒超时
|
||
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||
defer cancel()
|
||
resp, err := client.GetUser(ctx, &pb.GetRequest{Id: "123"})
|
||
```
|
||
|
||
```go
|
||
// Server 侧：拦截器兜底（放在拦截器链最内层）
|
||
func TimeoutUnaryInterceptor(maxTimeout time.Duration) grpc.UnaryServerInterceptor {
|
||
return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
|
||
if _, ok := ctx.Deadline(); !ok {
|
||
var cancel context.CancelFunc
|
||
ctx, cancel = context.WithTimeout(ctx, maxTimeout)
|
||
defer cancel()
|
||
}
|
||
return handler(ctx, req)
|
||
}
|
||
}
|
||
```
|
||
|
||
> [!tip] 最佳实践
|
||
> - **Client 必须设 deadline**——这是第一道防线
|
||
> - **Server 拦截器设兜底 timeout**——防止漏网的请求挂住 goroutine
|
||
> - 兜底 timeout 应该 ≥ 大部分正常请求的 P99 耗时，否则会把正常请求误杀
|
||
|
||
### 9. 传输层性能优化 ⭐
|
||
|
||
这些选项直接操作 TCP 层缓冲行为，在高吞吐场景下效果明显。
|
||
|
||
```go
|
||
grpc.WriteBufferSize(512 * 1024), // 写缓冲区 512KB（默认 32KB）
|
||
```
|
||
|
||
| 选项 | 默认值 | 适用场景 | 注意事项 |
|
||
|------|--------|---------|---------|
|
||
| `WriteBufferSize` | 32KB | 大消息频繁发送的场景 | 增大可减少系统调用次数，但会引入更多写入延迟 |
|
||
| `ReadBufferSize` | 32KB | 接收大消息的场景 | 同写入侧，增大读缓冲减少 read() 系统调用 |
|
||
|
||
> [!note] gRPC-Go 的公开边界
|
||
> gRPC-Go 把大部分传输层调优参数放在内部类型中（如 `InitialWindowSize`、`InitialConnWindowSize`），对普通用户不开放。**大多数情况下你只需要关注 `WriteBufferSize`**。如果连它都不需要调——说明你的瓶颈不在网络 I/O。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
CA["Client App"] --> CB["Write Buffer<br/>客户端 32KB"]
|
||
CB --> CT["TCP Send<br/>Stack"]
|
||
CT -->|TCP Packets| ST["TCP Recv<br/>Stack"]
|
||
ST --> SB["Read Buffer<br/>服务端 32KB"]
|
||
SB --> SA["Server App"]
|
||
|
||
style CB fill:#FFEAA7,color:#000
|
||
style SB fill:#FFEAA7,color:#000
|
||
style CT fill:#E3F2FD
|
||
style ST fill:#A8E6CF
|
||
```
|
||
|
||
> [!tip] 什么时候需要改？
|
||
> 如果你的 QPS 不高、消息体 ≤ 1MB，默认值完全够用。**先测后调**——用压测工具对比调整前后的 CPU 和 throughput，有提升再上线。不要凭感觉改参数。
|
||
|
||
---
|
||
|
||
## 完整配置示例
|
||
|
||
把上面讲到的所有选项组合在一起。按需裁剪，**不要照抄**。
|
||
|
||
```go
|
||
s := grpc.NewServer(
|
||
// TLS — 生产必配
|
||
grpc.Creds(credentials.NewTLS(tlsConfig)),
|
||
|
||
// 消息大小 — 根据业务需要调整
|
||
grpc.MaxRecvMsgSize(16*1024*1024),
|
||
grpc.MaxSendMsgSize(16*1024*1024),
|
||
|
||
// 并发流限制 — 放宽到 1024
|
||
grpc.MaxConcurrentStreams(1024),
|
||
|
||
// Keepalive — 适配 LB 环境
|
||
grpc.KeepaliveParams(keepalive.ServerParameters{
|
||
MaxConnectionIdle: 15 * time.Minute,
|
||
KeepaliveTime: 20 * time.Second,
|
||
KeepaliveTimeout: 5 * time.Second,
|
||
PingWithoutCallsAllowed: true,
|
||
}),
|
||
|
||
// 传输层优化 — 高吞吐场景才需要调整
|
||
grpc.WriteBufferSize(512 * 1024),
|
||
|
||
// 拦截器链
|
||
grpc.ChainUnaryInterceptor(
|
||
logging.Unary(), // 外层：日志
|
||
auth.Unary(), // 中层：鉴权
|
||
recovery.Unary(), // 内层：panic recover
|
||
),
|
||
|
||
// OpenTelemetry 链路追踪（替代或叠加拦截器）
|
||
// grpc.StatsHandler(otelgrpc.NewServerHandler()),
|
||
)
|
||
```
|
||
|
||
记住：**不要照抄上面的配置**。每一个参数都应该根据你的具体场景（有没有 LB、消息有多大、是否需要 TLS）来做决策。
|
||
|
||
## 关联笔记
|
||
|
||
- [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/01-Hello World 最小可运行 Server]]
|
||
- [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/06-Graceful Shutdown 优雅关闭]]
|
||
- [[hhs/gRPC/5. 中间件与拦截器/14-Unary 与 Stream 拦截器]]
|
||
- [[hhs/gRPC/5. 中间件与拦截器/16-日志与链路追踪]]
|