Envoy on Liangweidong's blog

反向代理 6 巨头 + 内网穿透双雄：从 Nginx/Tengine 健康检查到全场景工具横评

Wed, 15 Apr 2026 00:00:00 +0800

写于 2026 年 4 月的回望

做博客 14 年，第一次把"反向代理 + 内网穿透"合并到一篇文章里——不是因为它们逻辑上多紧密，而是因为在写代码、跑业务、对外服务这条链路上，这两类工具几乎总是成对出现：你先要有个公网入口（反代 + 四层代理），再考虑内网服务怎么被访问（内网穿透）。入口打不通，内网穿透也无处发力。

本文是 0.7 批次"架构实战"系列的一篇，合并源文档 9 篇（其中 3 篇有实战内容、6 篇仅有工具骨架），目标是给读者一份可立即拿去选型的横评 + 实战手册。

全文目录

一、为什么需要反向代理？3 个真实场景
二、6 款主流反代工具特性横评
三、Nginx 与 Tengine：编译安装 + 健康检查实战（基于源文档深度展开）
四、Stream 四层代理：主动检查 vs 被动检查的踩坑点
五、内网穿透双雄：frp 与 cpolar 选型
六、选型矩阵：按业务场景一图看懂
七、常见 8 个坑点速查

一、为什么需要反向代理？3 个真实场景

反向代理（Reverse Proxy） 站在客户端与真实服务器之间，客户端只看到代理的地址，永远不知道后端有几台机器。在生产环境里，反向代理通常承担三类职责：

统一入口 + 域名路由：把 a.example.com、b.example.com 解析到同一个入口，按 Host 头转发到不同后端
TLS 终结 + HTTPS 加速：所有证书/加解密在反代层完成，后端只跑明文 HTTP，省 CPU 省证书
负载均衡 + 健康检查：检测后端故障、自动剔除/恢复

在微服务、Service Mesh、API 网关场景里，反代还承担动态路由、灰度发布、限流熔断等高级职责——这正是 Caddy、Traefik、Envoy、BFE 竞相入场的原因。

二、6 款主流反代工具特性横评

工具	出品方 / 协议	核心定位	配置风格	动态生效	四层代理	生态优势
Nginx	F5 / BSD-2	HTTP 反代事实标准	静态 conf + reload	需 reload	stream 模块	模块生态最丰富
Tengine	阿里 / BSD-2	Nginx 增强 + 通用 API 网关	兼容 Nginx + 动态配置	支持域名/证书/路由动态生效	stream + UDP bypass	双 11 验证 + Ingress 标注
Caddy	个人作者 / Apache-2	自动 HTTPS + 极简配置	Caddyfile / JSON	reload（零停机）	需 reverse_proxy + layer4 插件	自动 ACME、HTTP/3 默认开
Traefik	Traefik Labs / MIT	云原生动态反代	动态发现（Docker/K8s）	热加载（监听 provider）	需 entrypoints TCP	K8s Ingress 一等公民
Envoy	Lyft/CNCF / Apache-2	Service Mesh 数据面	YAML/JSON xDS	xDS 热推送	原生 L4/L7	Istio 默认 sidecar
BFE	百度 / Apache-2	大流量七层网关	类 Nginx conf	动态配置	支持七层 + 部分四层	百度搜索/地图规模验证

工具生态位速读

Nginx / Tengine：做"经典反代"——nginx.conf 写好、reload 完事，适合中小规模、配置不频繁变化的场景
Caddy：做"个人/小团队站点"——默认自动 HTTPS，省心，配置文件 5 行就能跑
Traefik：做"K8s/容器编排动态反代"——监听 Docker/K8s 标签自动生成路由
Envoy：做"Service Mesh 数据面"——xDS 协议动态下发配置，Istio 默认用它
BFE：做"超大流量七层网关"——百度搜索级别流量验证，国内大厂可选

三、Nginx 与 Tengine：编译安装 + 健康检查实战

本节是源文档里有完整实战内容的部分，逐行引用并补全注释。

3.1 编译选项对比

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# Nginx 1.24 编译（Debian/Ubuntu 风格）
./configure \
 --prefix=/usr/local/nginx \
 --with-http_ssl_module \
 --with-http_stub_status_module \
 --with-pcre \
 --with-http_gzip_static_module \
 --with-stream \
 --with-stream_ssl_module \
 --add-module=../nginx_upstream_check_module

make && make install

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# Tengine 3.1 编译（额外启用 HTTP/2、realip、upstream_check）
./configure \
 --prefix=/usr/local/nginx \
 --with-http_ssl_module \
 --with-http_v2_module \
 --with-stream \
 --with-stream_ssl_module \
 --with-http_realip_module \
 --with-http_gzip_static_module \
 --add-module=../nginx_upstream_check_module

Tengine 在 Nginx 1.24 基础上额外提供（源文档原文特性清单）：

HTTP/3 支持（QUIC v1 与 draft-29）
基于 header / cookie / query / 服务权重的高级路由，动态无损生效
配置分域名 TLS 多版本、timeout、强制 HTTPS、CORS、robots 动态生效
bypass 内核的用户态 UDP 转发（xUDP），性能远高于内核 UDP
流式上传到后端 / FastCGI
异步 OpenSSL，可对接 QAT 硬件加速
更强大的负载均衡：一致性 hash、会话保持、主动健康检查、动态 upstream 域名解析
CSS/JS 合并、空白字符去除、内存监控、CPU 亲缘性自动绑定

3.2 迁移原 Nginx 到 Tengine

源文档提供了一套保留证书与 conf 的安全迁移流程：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# 1. 备份
mkdir -p /backup
rsync -av /usr/local/nginx/conf/cert /backup/
rsync -av /usr/local/nginx/conf/nginx.conf /backup/

# 2. 停止原服务（如有 HAProxy/keepalived 协同）
systemctl stop keepalived
systemctl stop nginx
systemctl stop nginxwebui

# 3. 卸载旧版
rm -rf /usr/local/nginx

# 4. 安装 Tengine（编译步骤见 3.1）

# 5. 还原备份
rsync -av --force /backup/nginx.conf /usr/local/nginx/conf/
rsync -av /backup/cert /usr/local/nginx/conf/

# 6. 启动
systemctl start keepalived
systemctl start nginx
systemctl start nginxwebui

关键点：Tengine 完全兼容 Nginx 配置，所以可以直接复用 nginx.conf 与证书目录。--force 标志在还原时避免 rsync 因目标存在而拒绝覆盖。

四、Stream 四层代理：主动检查 vs 被动检查的踩坑点

源文档反复强调的一条铁律：

注意：这个模块（nginx_upstream_check_module）只能支持 HTTP，不支持 stream；且被动检查不能和主动检查同时使用。

4.1 主动健康检查（仅 HTTP）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


http {
 upstream backend_http {
 server {{BACKEND_1}}:8080;
 server {{BACKEND_2}}:8080;
 check type=http;
 check interval=5000 rise=2 fall=3 timeout=2000;
 check_http_send "GET /health HTTP/1.0\r\nHost: example.com\r\n\r\n";
 check_http_expect_alive http_2xx;
 }

 server {
 listen 80;
 location / {
 proxy_pass http://backend_http;
 }
 }
}

参数含义（源文档原文）：

interval：调用间隔（毫秒）
rise：连续成功多少次后标记存活
fall：连续失败多少次后摘除
timeout：单次检查超时

4.2 被动健康检查（stream 块）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


stream {
 upstream backend_tcp {
 server {{MQTT_NODE_1}}:1883 fail_timeout=30s max_fails=3;
 server {{MQTT_NODE_2}}:1883 fail_timeout=30s max_fails=3;
 server {{MQTT_NODE_3}}:1883 fail_timeout=30s max_fails=3;
 server {{MQTT_NODE_4}}:1883 fail_timeout=30s max_fails=3;
 server {{MQTT_NODE_5}}:1883 fail_timeout=30s max_fails=3;
 server {{MQTT_NODE_6}}:1883 fail_timeout=30s max_fails=3;
 keepalive 32;
 }

 server {
 listen 1883;
 proxy_pass backend_tcp;
 }
}

被动检查的语义：客户端连接失败 3 次（max_fails=3）后，30 秒内不再向该后端转发——完全由"连接失败"驱动，不需要主动探测。

4.3 主动 vs 被动：什么时候用哪个？

维度	主动检查	被动检查
适用协议	HTTP（仅）	TCP/UDP/任意四层
检查方式	定期 GET 健康路径	客户端连接失败计数
摘除速度	`interval` 周期级	30s 内响应
副作用	后端会收到"无意义的健康探测"	零副作用
踩坑点	不能与被动同时用	必须配置 `max_fails`

结论：HTTP 反代用主动（拿到 2xx 200 状态才算健康）；stream / MQTT / 数据库连接池用被动（主动检查模块不支持 stream）。

4.4 主动检查可视化（Nginx 自带状态页）

1
2
3
4
5
6


# 启动两个测试后端
docker run -d --name nginx1 --restart=always -p {{PORT_HTTP_1}}:80 nginx:latest
docker run -d --name nginx2 --restart=always -p {{PORT_HTTP_2}}:80 nginx:latest

# 访问状态页
curl http://{{STATUS_HOST}}:{{STATUS_PORT}}/status

输出示例（源文档原文截图对应文字）：

1
2
3
4
5


Nginx http upstream check status
Check upstream server number: 2, generation: 1
Index Upstream Name Status Rise counts Fall counts Check type Check port
0 cluster {{HOST}}:{{PORT_HTTP_1}} up 2 0 tcp 0
1 cluster {{HOST}}:{{PORT_HTTP_2}} up 2 0 tcp 0

停掉一个后端（docker stop nginx1），状态页会显示 down + Fall counts 递增；两个全挂后服务直接 502——这就是 source 文档实测的"主动检查 + 服务降级"行为。

五、内网穿透双雄：frp 与 cpolar 选型

内网穿透解决"没有公网 IP 时，怎么让外部访问内网服务“的问题。市面上有两类典型玩家：

frp（fast reverse proxy）：开源、自建、需要一台公网 VPS 当中转
cpolar：商业化、零配置、官方中转服务器（有公网域名）

5.1 frp / frpc 速读

维度	详情
协议	TCP / UDP / HTTP / HTTPS / QUIC
客户端	frpc（运行在内网机器）
服务端	frps（运行在公网 VPS）
配置格式	INI（v0.50 之前）/ TOML（v0.50+）
鉴权	token + TLS 可选
性能	公网 VPS 带宽上限
部署成本	需要 1 台公网 VPS（最低配置 1C1G）

典型 frpc 配置文件片段（公开文档参考）：

1
2
3
4
5
6
7
8
9


serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000

启动后 ssh -oPort=6000 user@x.x.x.x 就能连到内网机器的 22 端口。

5.2 cpolar 速读

维度	详情
部署	零配置，下载即用
中转	官方中转服务器（提供二级公网域名）
限制	免费档限带宽、限连接数
适合场景	临时演示 / 个人远程
不适合场景	长期高带宽、对延迟敏感

5.3 选型建议

自建、自有 VPS、长期使用 → 选 frp
临时演示、个人远程、不想运维 → 选 cpolar
公司有安全合规要求、要求数据走自建 → frp
想用现成公网域名做微信小程序回调 → cpolar

六、选型矩阵：按业务场景一图看懂

业务场景	推荐工具	理由
经典 Web 反代 + 域名路由	Nginx	文档最全、运维最熟
Nginx 配置 + 动态生效 + 阿里生态	Tengine	双 11 验证、Ingress 注解丰富
个人博客 / 小团队 + 想省心	Caddy	自动 HTTPS + 配置 5 行
K8s/容器编排	Traefik	动态发现 + Ingress 一等公民
Service Mesh 数据面	Envoy	Istio 默认 + xDS 协议
超大流量七层网关（百度级别）	BFE	国内大厂验证
内网 SSH/MySQL 临时外访	frp	自建、可控、性能强
个人远程、临时演示	cpolar	零配置、免运维

七、常见 8 个坑点速查

stream 块里用 nginx_upstream_check_module → 不支持，主动检查只对 HTTP 生效
主动检查 + 被动检查同时配置 → 行为未定义，只能二选一
/status 状态页暴露在公网 → 加 allow / deny 或只监听内网 IP
Tengine 迁移后旧证书路径不一致 → 备份+还原时注意 cert/ 相对路径
HTTP/3（QUIC）开启后 443/udp 被防火墙拦 → 提前在 LB/防火墙开 UDP 443
Traefik 监听 Docker 标签后服务起来没路由 → 检查 traefik.enable=true 标签
frpc 配置改完忘 reload → frpc 默认不会自动 reload，用 systemctl restart frpc
cpolar 免费档被限速 → 长期高带宽业务直接换 frp

前置知识 / 下一步

前置：Nginx 基础配置（upstream、location、proxy_pass）、systemd 服务管理
下一步：K8s Ingress 选型（Traefik vs nginx-ingress）、Service Mesh 入门（Envoy + Istio）、CDN 与反代的协同

ProtoBuf & gRPC 实战：proto3 时代的跨语言 RPC 与数据建模

Sun, 15 Oct 2017 00:00:00 +0800

ProtoBuf & gRPC 实战：proto3 时代的跨语言 RPC 与数据建模

TL;DR：ProtoBuf 是一类语言无关、平台无关、可扩展的二进制结构化数据序列化方法，比 XML 小 3 ~ 10 倍、快 20 ~ 100 倍。2017 年是它真正"工业化"的一年——gRPC 1.0（2017-08 GA）、protoc-gen-validate（2017-08 开源）、Envoy 1.0（2017-09）先后落地，proto3 也从 2016-07 GA 后成为默认语法。本文用 5 个心智模型 + 一组完整示例，讲清 proto3 的数据建模、字段类型、嵌套、Map、service 与四种流模式。

一、为什么需要 ProtoBuf（When to use）

在微服务、跨端通信、持久化序列化场景中，传统 JSON / XML 是人类友好但机器低效的格式：

体积：JSON 里一个 int 字段最少 1~~11 字节，ProtoBuf 用变长编码通常 1~~5 字节
速度：XML 解析要遍历 DOM，ProtoBuf 直接按 schema 二进制切片
类型安全：JSON 拿到的是字符串，ProtoBuf 拿到的是强类型对象
演进能力：ProtoBuf 通过**字段编号（field number）**支持前向/后向兼容，新增字段不会破坏旧客户端

典型适用场景（2017 视角）：

微服务间 RPC——gRPC 1.0（2017-08）以 ProtoBuf 作为 IDL 和默认序列化器，跨语言、强类型、双向流
消息队列载荷——Kafka 早已支持 ProtoBuf，Pulsar（2016-09 在 Yahoo! 开源、2017 年逐步成熟）也提供 schema registry 与 ProtoBuf 集成
K8s 内部通信——Kubernetes 1.0（2015-07 GA）以来，所有 API 资源（Pod、Service、Deployment…）的 schema 都用 ProtoBuf 定义，apiserver 与 kubelet、scheduler、controller-manager 之间走 ProtoBuf over HTTP/2
Service Mesh 数据面——Envoy（2017-09 发布 v1.0）的 xDS（LDS/RDS/CDS/EDS）API 全部基于 ProtoBuf，Istio 等控制面通过 xDS 下发配置
跨语言 SDK 数据交换——前端、移动端、后端用同一份 .proto 各自生成代码
移动端与后端通信——节省流量、电量

不适用场景：

需要人类可读的配置（用 YAML / TOML）
Web 前端到后端的标准通信（JSON 更通用）
一次性、小数据量、无演进需求的传输

二、ProtoBuf 速览

一个数据交换的协议

protocol buffers（ProtoBuf）是一种语言无关、平台无关、可扩展的序列化结构数据的方法，可用于（数据）通信协议、数据存储等。

是一种灵活、高效、自动化机制的结构数据序列化方法——可类比 XML，但比 XML 更小（3 ~ 10 倍）、更快（20 ~ 100 倍）、更简单。

JSON / XML 都是基于文本格式，ProtoBuf 是二进制格式。

三、proto3 速览：与 proto2 的关键差异

2016-07 proto3 正式 GA，并成为 protoc 的默认语法。和 proto2 相比，proto3 的核心简化是：

维度	proto2	proto3
默认语法	需显式 `syntax = "proto2"`	2016-07 后默认为 proto3
字段是否存在	区分 `optional` / `required` / 默认	没有 `required`，字段默认"存在与否"用 `optional` 关键字显式标注（proto3 默认字段可以被设默认值以"不编码"）
默认值	0 / 空字符串	同上，但未设置字段不会被序列化（节省体积）
枚举	第一个值必须为 0	同上，但首成员必须为 0，且枚举值在 wire format 中是 varint
未知字段	解析时默认保留	解析时不保留未知字段（演进更严格）
`map` 支持	旧版本不支持	原生支持 `map<K, V>`
`Any` 类型	需 `google/protobuf/any.proto` 扩展	官方内置 `google.protobuf.Any`
时间戳	同上	同上，但官方推荐 `google.protobuf.Timestamp`
JSON 映射	需插件	官方 `proto3 <-> JSON` 映射规范

实战建议：新项目一律 syntax = "proto3"；维护老服务再保留 proto2。

四、第一个 .proto：消息定义

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 指定 proto3 语法（2016-07 后是默认，但显式声明更稳）
syntax = "proto3";

package foo.bar; // 包名避免同名 Message 冲突

// option 可用于 proto、message、enum、service 的 scope

// Message ≈ Java 的 class / C 的 struct
message Response {
 // 字段 = 类型 + 名字 + 序号（序号是 wire format 的"身份证"，绝不能改）
 string data = 1;
 int32 status = 2;
}

关键约定：

package：避免命名空间冲突
message：数据结构的最小单元
字段序号 = 1, = 2, ...：一旦发布就不可修改、不可复用——这是 ProtoBuf 演进能力的根基
syntax = "proto3"：2017 主流；不写时 2017 之后的 protoc 默认按 proto3 解析

五、编译器：.proto → 目标语言

官方编译器 protoc 仓库：https://github.com/protocolbuffers/protobuf/releases

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 安装 protoc 后，生成 Java 代码到当前目录
protoc --java_out=. response.proto

# 生成 Go 代码
protoc --go_out=. --go_opt=paths=source_relative response.proto

# 生成 Python 代码
protoc --python_out=. response.proto

# 生成 C++ 代码
protoc --cpp_out=. --proto_path=. response.proto

# 生成 gRPC 桩代码（protoc + 插件 grpc-plugin，gRPC 1.0 GA 后官方推荐）
protoc --grpc_out=. --plugin=protoc-gen-grpc=`which grpc_cpp_plugin` response.proto

小贴士：生成的代码不要手动改——下次 protoc 会被覆盖。业务代码继承/组合生成的类即可。

六、数据类型映射表

proto 类型	说明	java 类型	golang 类型
`double`	双精度浮点	`double`	`float64`
`float`	单精度浮点	`float`	`float32`
`int32`	变长编码，对负值效率低，负值请用 `sint32`	`int`	`int32`
`uint32`	变长编码	`int`	`uint32`
`uint64`	变长编码	`long`	`uint64`
`sint32`	变长编码，负值比 int32 高效	`int`	`int32`
`sint64`	变长编码，有符号	`long`	`int64`
`fixed32`	固定 4 字节，值域常大于 2²⁸ 时比 `uint32` 高效	`int`	`uint32`
`fixed64`	固定 8 字节，值域常大于 2²⁵⁶ 时比 `uint64` 高效	`long`	`uint64`
`sfixed32`	固定 4 字节	`int`	`int32`
`sfixed64`	固定 8 字节	`long`	`int64`
`bool`	布尔	`boolean`	`bool`
`string`	必须 UTF-8 或 7-bit ASCII	`String`	`string`
`bytes`	任意二进制（文件、图片）	`ByteString`	`[]byte`

实战口诀：负数 → sint32/sint64；大正整数 → fixed32/fixed64；其余 → int32/uint32。

七、枚举、数组、嵌套、导入

7.1 枚举

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


syntax = "proto3";

enum PhoneType { // 枚举首成员必须为 0，且值唯一
 MOBILE = 0;
 HOME = 1;
 WORK = 2;
}

message PhoneNumber {
 string number = 1;
 PhoneType type = 2;
}

7.2 数组（repeated）

1
2
3
4
5


message Msg {
 repeated int32 arrays = 1; // 整数数组
 repeated string names = 2; // 字符串数组
 repeated PhoneNumber phones = 3;
}

7.3 嵌套消息 vs 跨文件导入

1
2
3
4
5
6
7
8
9


// 嵌套：把 Result 写进 SearchResponse 内部
message SearchResponse {
 message Result {
 string url = 1;
 string title = 2;
 repeated string snippets = 3;
 }
 repeated Result results = 1;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// 跨文件导入：把 Result 抽到 result.proto
// result.proto
syntax = "proto3";
package foo.bar;
message Result {
 string url = 1;
 string title = 2;
 repeated string snippets = 3;
}

// search_response.proto
syntax = "proto3";
package foo.bar;
import "result.proto";
message SearchResponse {
 repeated Result results = 1;
}

proto3 中不允许直接嵌套枚举（嵌套 enum 必须先 message 包一层），这是与 proto2 的小差异。

八、Map / 时间戳 / Any

8.1 Map 类型

1
2
3
4
5
6
7


syntax = "proto3";

message Product {
 string name = 1;
 // key 不能是浮点 / bytes / enum；value 不能是另一个 map
 map<string, string> attrs = 2; // 商品属性 K/V
}

Map 字段不能用 repeated 修饰；map 不能迭代顺序依赖。

8.2 时间戳

1
2
3
4
5
6
7


syntax = "proto3";

import "google/protobuf/timestamp.proto";

message MyMessage {
 google.protobuf.Timestamp my_field = 1;
}

简单场景可直接用 int64 时间戳（毫秒/秒），看团队约定。

8.3 Any 任意类型

1
2
3
4
5


// Any 可以承载 .proto 未定义的任意内置类型
message ErrorStatus {
 string message = 1;
 repeated google.protobuf.Any details = 2;
}

K8s API 的 runtime.RawExtension 字段底层就是 Any——apiserver 把不识别的对象原样塞进去。

九、定义服务

proto3 原生支持 service 定义，与 gRPC 1.0 配合即可生成跨语言 RPC 桩代码：

1
2
3


service SearchService {
 rpc Search (SearchRequest) returns (SearchResponse);
}

gRPC 1.0（2017-08）默认走 HTTP/2 + ProtoBuf，这是 ProtoBuf 在 RPC 领域最主流的落地形态。

十、stream 关键字：四种流模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 客户端推 → 服务端（client-side streaming）
rpc GetStream (StreamReqData) returns (stream StreamResData) {}

// 服务端推 → 客户端（server-side streaming）
rpc PutStream (stream StreamReqData) returns (StreamResData) {}

// 双向流（bidirectional streaming）
rpc AllStream (stream StreamReqData) returns (stream StreamResData) {}

// 单调用（非流式）
rpc Unary (UnaryReq) returns (UnaryRes);

典型场景：

客户端流：IoT 设备上报（go2rtc 这类轻量级流媒体代理 / RTSP-over-WebRTC 设备采集后的元数据上报就属于这一类）
服务端流：股票行情、消息推送、K8s watch API
双向流：聊天、协同编辑、Envoy xDS（控制面 ↔ 数据面长连接推送配置）
单调用：普通 RPC

Envoy 1.0 的 xDS（LDS/RDS/CDS/EDS）正是 gRPC 双向流的典型案例——控制面（Istio Pilot 等）通过 gRPC stream 主动推送配置变更给数据面（Envoy）。

十一、数据校验：protoc-gen-validate（2017-08）

ProtoBuf 本身不包含字段值校验（最小值、最大值、长度、枚举合法性等）。2017-08 开源的 protoc-gen-validate（Envoy 项目出品）补齐了这一点：

仓库：https://github.com/envoyproxy/protoc-gen-validate

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


syntax = "proto3";

package foo.bar;

import "validate/validate.proto";

message CreateUserRequest {
 // 用户名：3~32 字符，正则限制
 string username = 1 [
 (validate.rules).string = {
 min_len: 3
 max_len: 32
 pattern: "^[a-zA-Z0-9_]+$"
 }
 ];

 // 年龄：0~150
 int32 age = 2 [(validate.rules).int32 = {gte: 0, lte: 150}];

 // 邮箱：必须是 email 格式
 string email = 3 [(validate.rules).string = {email: true}];

 // 列表元素非空、长度限制
 repeated string tags = 4 [
 (validate.rules).repeated = {
 min_items: 1
 max_items: 10
 items: {string: {min_len: 1, max_len: 32}}
 }
 ];
}

1
2
3
4
5
6
7


# 安装 protoc-gen-validate 后，protoc 会生成带校验逻辑的桩代码
protoc \
 -I . \
 -I /path/to/protoc-gen-validate \
 --go_out=. \
 --validate_out=lang=go,paths=source_relative:. \
 create_user.proto

相比 JSR 303 Bean Validation（Java 生态），protoc-gen-validate 的优势是校验规则写在 .proto 里、跨语言、跨 RPC 框架一致——这正是 2017 年 gRPC + Envoy 生态推崇的"单一来源"做法。

十二、现代基础设施里的 ProtoBuf

2017 年这个时间点，ProtoBuf 已经不只是"序列化格式"，而是分布式系统的事实 IDL。

12.1 Kubernetes：所有 API 资源都是 ProtoBuf

Kubernetes 1.0（2015-07 GA）以来，所有 API 资源（Pod、Service、Deployment…）的 schema 都定义在 k8s.io/api 仓库的 .proto 文件中：

apiserver ↔ kubelet / scheduler / controller-manager：通过 HTTP/2 + ProtoBuf 通信
CRD / Operator：用户自定义资源也走 .proto（或 OpenAPI 自动生成）
kubectl：本地构造 ProtoBuf 对象 → 走 apiserver 序列化

典型 .proto 片段（简化版）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// k8s.io/api/core/v1/generated.proto
syntax = "proto3";
package k8s.io.api.core.v1;

import "k8s.io/apimachinery/pkg/runtime/generated.proto";

message Pod {
 map<string, string> labels = 1;
 map<string, string> annotations = 2;
 PodSpec spec = 3;
 PodStatus status = 4;
}

12.2 gRPC：ProtoBuf 跨语言 RPC 的事实标准

gRPC 1.0（2017-08 GA）由 Google 开源（2015 年从内部 Stubby 演进，移到 GitHub），以 ProtoBuf 作为 IDL 和默认序列化：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// user.proto
syntax = "proto3";

package user;

service UserService {
 // 单调用
 rpc GetUser (GetUserRequest) returns (User);
 // 服务端流
 rpc ListUsers (ListUsersRequest) returns (stream User);
 // 客户端流
 rpc CreateUsers (stream User) returns (CreateUsersResponse);
 // 双向流
 rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}

message User { string id = 1; string name = 2; }

gRPC 关键特性：

HTTP/2 多路复用
ProtoBuf 二进制序列化
双向流、四种流模式
自动生成 10+ 语言桩代码（Java/Go/C++/Python/Ruby/Node/PHP/C#/Dart/Android-Java）
截止时间（deadline）、取消、metadata 等通用拦截语义

12.3 Pulsar：消息总线里的 ProtoBuf

Apache Pulsar（2016-09 在 Yahoo! 开源、2017 年逐步孵化成 Apache 顶级项目）原生支持 ProtoBuf schema：

内置 Schema.PROTOBUF，producer / consumer 用 .proto 自动反序列化
与 SchemaRegistry 配合做 schema 演进
消息载荷紧凑、跨语言、多租户隔离

12.4 Envoy / xDS：Service Mesh 的数据面 API

Envoy（Lyft 开源，2017-09 发布 v1.0）的 xDS 协议族是 gRPC + ProtoBuf 的工业级范本：

LDS（Listener Discovery Service）：下发监听器配置
RDS（Route Discovery Service）：下发路由配置
CDS（Cluster Discovery Service）：下发集群配置
EDS（Endpoint Discovery Service）：下发端点配置

控制面（Istio Pilot 等）通过 gRPC 双向流把 ProtoBuf 消息增量推送给数据面（Envoy），实现配置热更新。

这套 xDS 协议后来成为 Istio（2017-05 由 Google/IBM/Lyft 联合开源）的核心数据面 API。

12.5 IoT / 视频流场景

ProtoBuf 在 IoT 与视频流领域的应用同样广泛——比如轻量级流媒体代理在设备元数据、控制信令、配置同步上都会用 .proto 定义设备能力集，避免重复造轮子。go2rtc 这类工具虽然面世更晚，但同样遵循"ProtoBuf 作为控制面信令、媒体流走 RTSP/WebRTC"的分层思路。

十三、协议升级的视角：IPv4→IPv6 给我们的启示

2017 年前后正值 IPv6 规模部署讨论。把网络协议和序列化协议放一起看，能发现共通的设计哲学：

协议升级对现有程序的影响（参考 IPv4→IPv6）

地址格式的硬编码问题——视频监控、配置文件、程序中字面量硬编码
网络 API / 库的协议版本依赖——Java 库要使用更通用的 InetAddress；Go 视频播放客户端优先 net.LookupIP 同时解析 A 与 AAAA
地址解析与 DNS 交互逻辑——程序需支持"双 DNS 查询"（同时请求 A 和 AAAA 记录）
操作系统层面支持
运行时 / 容器——Java 需确保 java.net.preferIPv6Addresses=true；libc 解析器需开启 getaddrinfo 的 AI_ADDRCONFIG；Docker / K8s 需配置 IPv6 网络模式（--ipv6 flag、CNI 插件）
防火墙规则——IPv4 规则需重新配置 IPv6 专属规则

升级建议路径：

阶段	目标
第一阶段	支持双栈兼容（IPv4/IPv6 并存）
第二阶段	修复IPv6 专属问题（DNS、MTU、链路本地地址）
第三阶段	全量 IPv6，下线 IPv4

类比到 ProtoBuf：

第一阶段（双栈）：旧字段保留 + 新字段加 optional 标注
第二阶段（修复兼容问题）：使用 reserved 关键字冻结废弃字段编号（防止误用）

1
2
3
4
5
6
7


message User {
 reserved 5, 7, 9 to 11; // 保留字段编号，未来也不能用
 reserved "old_name", "old_email"; // 保留字段名

 string name = 1;
 string email = 2;
}

第三阶段（全量）：灰度下架旧字段、提供 schema 校验工具

十四、常见 5 个坑

#	坑	现象	对策
1	修改已发布字段的序号	旧客户端解码新数据字段错位、值乱跳	一旦发布，序号就是合约；只能加新字段 + 用 `reserved` 废弃旧的
2	误用 `int32` 存负数	负数被编码为 10 字节超大无符号数	负数统一用 `sint32` / `sint64`
3	`string` 字段塞非 UTF-8	反序列化报错、跨语言崩溃	文本类字段用 `string`；二进制用 `bytes`
4	`repeated` 字段不设上限	大消息体 OOM、带宽爆炸	在 `Service` 入口拦截层加 `Collection.size()` 校验；或用 `protoc-gen-validate` 的 `repeated.min_items` / `max_items` 限制
5	proto2 / proto3 混用	wire format 行为不同，反序列化失败	团队统一 `syntax = "proto3"`；proto2 仅在维护老服务时保留

十五、核心 6 点速记

字段编号 = 合约：一旦发布就不可改；用 reserved 冻结废弃编号
负数用 sint：变长编码对负值有专门优化
stream 关键字：四种流模式决定 ProtoBuf 自带 RPC 通信方向——gRPC 1.0 把它变成跨语言标准
校验靠 protoc-gen-validate：2017-08 开源，跨语言、.proto 单一来源，比 JSR 303 更适合 gRPC 时代
现代基础设施统一用 .proto 作为 IDL：K8s API、Pulsar schema、Envoy xDS、gRPC、CRD
演进式升级：双栈 → 修复 → 全量，与 IPv4→IPv6 的协议升级哲学一致

十六、参考资料

ProtoBuf 官方仓库：https://github.com/protocolbuffers/protobuf
protoc 发布页：https://github.com/protocolbuffers/protobuf/releases
gRPC 1.0 公告：https://grpc.io/blog/grpc-1-0-goes-ga/
gRPC 仓库：https://github.com/grpc/grpc
protoc-gen-validate：https://github.com/envoyproxy/protoc-gen-validate
Envoy 仓库：https://github.com/envoyproxy/envoy
xDS 协议：https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/xds_api
Kubernetes API 源码：https://github.com/kubernetes/api
Apache Pulsar：https://pulsar.apache.org/
Any 类型：https://developers.google.com/protocol-buffers/docs/proto#any