Nacos on Liangweidong's blog

注册中心镜像实战：Nacos / Consul / etcd / ZooKeeper 部署、集群、配置与坑点

Wed, 20 Sep 2023 00:00:00 +0800

微服务架构里，“服务 A 怎么知道服务 B 的地址"这个问题被反复解决。最早大家用硬编码 IP（127.0.0.1:8080），后来用负载均衡（Nginx upstream），再后来才有了注册中心——服务启动时把自己注册上去，调用方从注册中心拉。

这篇文章把 Nacos / Consul / etcd / ZooKeeper 四款主流注册中心的 docker 部署、集群、客户端接入、坑点整理成一份实战清单。和之前 0.4 批次的 CI 工具对比 / 0.4 批次的 Java 全家桶不同，本文只聚焦"镜像实战”——拉哪个镜像、怎么配集群、客户端怎么连。

阅读对象：需要从零搭一套注册中心，或在生产环境做注册中心选型的开发者、运维
覆盖范围：四款组件的核心特性对比、Nacos 2.2.2 单机/集群部署、Consul 集群部署、etcd 3.4 单机/多机集群部署、ZooKeeper 3.8 部署 + WebUI、客户端 Spring Cloud 接入、常见排错

一、四款注册中心对比

维度	Nacos	Consul	etcd	ZooKeeper
语言	Java	Go	Go	Java
服务发现	✅	✅	✅（弱）	✅（弱）
配置中心	✅（核心）	✅（KV）	✅（KV）	❌（需自己实现）
健康检查	✅	✅	❌	❌
一致性协议	自研（AP/CP 可切）	Raft	Raft	ZAB
多数据中心	❌	✅	❌	❌
镜像大小	250 MB	130 MB	50 MB	300 MB
内存占用	1 GB~	200 MB~	100 MB~	500 MB~
启动时间	30 秒	5 秒	3 秒	30 秒
客户端语言支持	Java、Go、Node、Python	多语言	多语言	多语言
适用场景	Spring Cloud Alibaba 一站式	多语言 + 多数据中心	K8s 内部（kube-apiserver）	大数据生态（Hadoop、Kafka）

When to use：

Spring Cloud Alibaba 全家桶 → Nacos（一站式服务发现 + 配置中心）

多语言微服务 + 多数据中心 → Consul

K8s 内部 / 强一致性 KV → etcd

大数据组件依赖（Hadoop、Kafka、HBase） → ZooKeeper

二、Nacos 部署

2.1 镜像选择

镜像	版本	备注
`nacos/nacos-server:v2.0.3`	2.0 LTS	老版本，没有 gRPC 端口（只用 8848）
`nacos/nacos-server:v2.2.2`	2.2 LTS	推荐——修复了 2.2.0/2.2.1 的鉴权 bug
`nacos/nacos-server:latest`	2.x latest	跟随最新 dev 版，生产慎用

2.2 关键变化：Nacos 2.x 端口

Nacos 客户端升级到 2.x 后，新增了 gRPC 通信方式——这意味着除了主端口 8848，还要开两个 gRPC 端口：

端口	偏移量	用途
8848	—	HTTP（API + 控制台）
9848	1000	客户端 gRPC 请求服务端
9849	1001	服务间 gRPC 同步

坑 1：Nacos 2.x 部署时必须同时开 8848/9848/9849 三个端口——少一个客户端就连不上。只开 8848 会报 “9848 port is unavailable”。

2.3 单机部署（MySQL 后端）

前置：先准备一个 MySQL 库 nacos-config：

1
2
3


# nacos-db.sql 是 Nacos 官方提供的初始化脚本
# 包含 config_info / config_info_gray / config_tags_relation / his_config_info / config_info_beta 等表
mysql -u root -p < nacos-db.sql

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


docker run -d \
 --name nacos \
 --restart=always \
 -p 8848:8848 \
 -p 9848:9848 \
 -p 9849:9849 \
 -e NACOS_AUTH_ENABLE=true \
 -e NACOS_AUTH_IDENTITY_KEY=nacos \
 -e NACOS_AUTH_IDENTITY_VALUE=nacos \
 -e PREFER_HOST_MODE=ip \
 -e MODE=standalone \
 -e SPRING_DATASOURCE_PLATFORM=mysql \
 -e MYSQL_SERVICE_HOST=<INTERNAL_HOST> \
 -e MYSQL_SERVICE_PORT=3306 \
 -e MYSQL_SERVICE_USER=root \
 -e MYSQL_SERVICE_PASSWORD=<REDACTED> \
 -e MYSQL_SERVICE_DB_NAME=nacos-config \
 -e MYSQL_SERVICE_DB_PARAM="characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai" \
 nacos/nacos-server:v2.2.2

访问 http://<HOST>:8848/nacos，默认账号 nacos/nacos。

2.4 Nacos 2.2.0/2.2.1 鉴权坑

Nacos 2.2.0.1 和 2.2.1 移除了 3 个鉴权默认值（token.secret.key / nacos.core.auth.server.identity.key / nacos.core.auth.server.identity.value），避免用户部署时因未修改而引入撞库风险。但这导致：

不开启鉴权时，控制台 UI 登录要求被强制依赖 token.secret.key → 启动失败
开启鉴权时，用户必须自定义设置这三个值 → 否则节点无法启动

Nacos 2.2.2 的修复：

不开启鉴权 → 取消控制台 UI 登录要求
开启鉴权 → 用户自定义设置（启动时用环境变量传）：

1
2
3


-e NACOS_AUTH_ENABLE=true \
-e NACOS_AUTH_IDENTITY_KEY=nacos \
-e NACOS_AUTH_IDENTITY_VALUE=nacos

坑 2：2.2.2 之前（2.2.0/2.2.1）的"无鉴权启动失败"问题是2.2.2 解决的——别在 2.2.0/2.2.1 上踩坑，直接用 2.2.2。

2.5 关键 application.properties

容器内 /home/nacos/conf/application.properties：

 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


# spring
server.servlet.contextPath=/nacos
server.contextPath=/nacos
server.port=8848

# 数据库
spring.datasource.platform=mysql
db.num=1
db.url.0=jdbc:mysql://<INTERNAL_HOST>:3306/nacos-config?serverTimezone=GMT%2B8&characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true
db.user=root
db.password=<REDACTED>

# 鉴权
nacos.core.auth.enabled=true
nacos.core.auth.server.identity.key=nacos
nacos.core.auth.server.identity.value=nacos
nacos.core.auth.system.type=nacos
nacos.core.auth.default.token.expire.seconds=18000
nacos.core.auth.default.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789

# 关闭鉴权缓存（开发环境）
nacos.core.auth.caching.enabled=false

# 性能调优（naming 模块）
nacos.naming.distro.taskDispatchThreadCount=10
nacos.naming.distro.taskDispatchPeriod=200
nacos.naming.distro.batchSyncKeyCount=1000
nacos.naming.distro.initDataRatio=0.9
nacos.naming.distro.syncRetryDelay=5000
nacos.naming.data.warmup=true

2.6 命名空间

真实场景：开发 / 测试 / 生产三套环境用同一个 Nacos 集群，靠 namespace 隔离。

Web 端：命名空间 → 新建命名空间 → 拿到 namespaceId

客户端（Spring Cloud）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


spring:
 cloud:
 nacos:
 discovery:
 server-addr: <INTERNAL_HOST>:8848
 namespace: <NAMESPACE_ID>  # 命名空间 ID
 config:
 server-addr: <INTERNAL_HOST>:8848
 namespace: <NAMESPACE_ID>
 file-extension: yaml

坑 3：namespace ID 一定要用生成的 UUID，不要用命名空间名（如 dev）——客户端按 UUID 匹配，写错就报 “namespace not found”。

2.7 集群部署

Nacos 集群需要 3 节点 + MySQL 后端（至少 3 节点保证 Raft 一致性）。

 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


# docker-compose-nacos-cluster.yml
version: '3'
services:
 nacos1:
 image: nacos/nacos-server:v2.2.2
 container_name: nacos1
 restart: always
 ports:
 - "8848:8848"
 - "9848:9848"
 - "9849:9849"
 environment:
 - NACOS_SERVERS=nacos1:8848 nacos2:8848 nacos3:8848
 - MYSQL_SERVICE_HOST=<INTERNAL_HOST>
 - MYSQL_SERVICE_DB_NAME=nacos-config
 - MYSQL_SERVICE_USER=root
 - MYSQL_SERVICE_PASSWORD=<REDACTED>
 - SPRING_DATASOURCE_PLATFORM=mysql
 - JVM_XMS=512m
 - JVM_XMX=512m

 nacos2:
 image: nacos/nacos-server:v2.2.2
 container_name: nacos2
 restart: always
 ports:
 - "8849:8848"
 - "9850:9848"
 - "9851:9849"
 environment:
 - NACOS_SERVERS=nacos1:8848 nacos2:8848 nacos3:8848
 - MYSQL_SERVICE_HOST=<INTERNAL_HOST>
 - MYSQL_SERVICE_DB_NAME=nacos-config
 - MYSQL_SERVICE_USER=root
 - MYSQL_SERVICE_PASSWORD=<REDACTED>
 - SPRING_DATASOURCE_PLATFORM=mysql
 - JVM_XMS=512m
 - JVM_XMX=512m

 nacos3:
 image: nacos/nacos-server:v2.2.2
 container_name: nacos3
 restart: always
 ports:
 - "8850:8848"
 - "9852:9848"
 - "9853:9849"
 environment:
 - NACOS_SERVERS=nacos1:8848 nacos2:8848 nacos3:8848
 - MYSQL_SERVICE_HOST=<INTERNAL_HOST>
 - MYSQL_SERVICE_DB_NAME=nacos-config
 - MYSQL_SERVICE_USER=root
 - MYSQL_SERVICE_PASSWORD=<REDACTED>
 - SPRING_DATASOURCE_PLATFORM=mysql
 - JVM_XMS=512m
 - JVM_XMX=512m

坑 4：Nacos 集群节点之间用容器名互通——nacos1:8848 是 Docker 网络里的 hostname。如果跨主机部署（多台物理机），要把 nacos1:8848 换成 10.8.x.x:8848 这种宿主机 IP。

三、Consul 部署

3.1 镜像

1

docker pull consul:1.9.5

3.2 单机模式

1
2
3


docker run -d \
 -e CONSUL_BIND_INTERFACE=eth0 \
 consul agent -dev -join=172.17.0.2

坑 5：dev 模式是开发用的，不能用于生产。Consul dev 模式没有持久化、所有数据存内存、重启丢。

3.3 集群部署

 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
32
33
34
35
36


# docker-compose-consul-cluster.yml
version: '3.7'
services:
 consul-server-1:
 image: consul:1.9.5
 container_name: consul-server-1
 restart: always
 command:
 - "agent"
 - "-server"
 - "-bootstrap-expect=3"
 - "-ui"
 - "-data-dir=/consul/data"
 - "-bind=0.0.0.0"
 - "-client=0.0.0.0"
 - "-advertise=<NODE1_IP>"
 - "-retry-join=<NODE2_IP>"
 - "-retry-join=<NODE3_IP>"
 ports:
 - "8500:8500" # WebUI
 - "8600:8600/udp" # DNS
 - "8300:8300" # Server RPC
 - "8301:8301" # Serf LAN
 - "8302:8302" # Serf WAN
 volumes:
 - "/data/consul/server1:/consul/data"

 consul-server-2:
 image: consul:1.9.5
 container_name: consul-server-2
 # 同上, advertise=<NODE2_IP>

 consul-server-3:
 image: consul:1.9.5
 container_name: consul-server-3
 # 同上, advertise=<NODE3_IP>

3 节点各启动一次：

1

docker-compose -f docker-compose-consul-cluster.yml up -d

WebUI：http://<NODE_IP>:8500/

3.4 客户端注册

Spring Cloud：

1
2
3
4
5
6
7
8
9


spring:
 cloud:
 consul:
 host: <INTERNAL_HOST>
 port: 8500
 discovery:
 prefer-ip-address: true
 health-check-interval: 10s
 instance-id: ${spring.application.name}:${server.port}

Go：

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


import "github.com/hashicorp/consul/api"

config := api.DefaultConfig()
config.Address = "<INTERNAL_HOST>:8500"
client, _ := api.NewClient(config)

// 注册服务
reg := &api.AgentServiceRegistration{
 ID: "my-service-1",
 Name: "my-service",
 Port: 8080,
 Check: &api.AgentServiceCheck{
 HTTP: "http://<HOST>:8080/health",
 Interval: "10s",
 },
}
client.Agent().ServiceRegister(reg)

坑 6：Consul 默认会做"健康检查 HTTP"——如果服务还没起来就报健康检查失败。解决：先启动服务再注册，或者把 Check.HTTP 改成 Check.TCP（更轻量）。

四、etcd 部署

4.1 镜像

1
2
3


docker pull bitnami/etcd:3
# 或
docker pull quay.io/coreos/etcd:v3.4.16

4.2 单机部署

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


# docker-compose.yml
version: '3.7'
services:
 etcd:
 image: bitnami/etcd:3
 container_name: etcd-single
 restart: always
 environment:
 - ALLOW_NONE_AUTHENTICATION=yes
 - ETCD_ADVERTISE_CLIENT_URLS=http://<INTERNAL_HOST>:2379
 - ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
 ports:
 - "2379:2379"
 volumes:
 - "/data/etcd:/bitnami/etcd/data"

启动后验证：

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


# 复制 etcdctl 客户端
docker cp etcd-single:/usr/local/bin/etcdctl /home/docker/etcd
sudo mv /home/docker/etcd/etcdctl /usr/local/bin/

# 让 etcdctl 使用 v3 API
echo 'export ETCDCTL_API=3' >> ~/.zshrc
source ~/.zshrc

# 查看版本
etcdctl version

# 查看成员
etcdctl member list

4.3 多机集群部署

前置：3 个节点（192.168.3.101、192.168.3.102、192.168.3.103），IP 可达。

每个节点的 docker-compose.yml 结构一样，只有 3 个参数不同（--name、--initial-advertise-peer-urls、--advertise-client-urls）：

192.168.3.101 节点：

 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


version: '3.7'
services:
 etcd:
 image: quay.io/coreos/etcd
 container_name: my-etcd
 restart: always
 environment:
 - ETCDCTL_API=3
 command:
 - etcd
 - --name=etcd1
 - --data-dir=/etcd-data
 - --listen-peer-urls=http://0.0.0.0:2380
 - --listen-client-urls=http://0.0.0.0:2379
 - --initial-advertise-peer-urls=http://192.168.3.101:2380
 - --advertise-client-urls=http://192.168.3.101:2379
 - --initial-cluster-token=cluster-token
 - --initial-cluster=etcd1=http://192.168.3.101:2380,etcd2=http://192.168.3.102:2380,etcd3=http://192.168.3.103:2380
 - --initial-cluster-state=new
 volumes:
 - $PWD/etcd-data:/etcd-data
 ports:
 - 2379:2379
 - 2380:2380
 network_mode: "host"

192.168.3.102 / 192.168.3.103 节点：把 etcd1 改为 etcd2 / etcd3，URL 改对应 IP 即可。

1
2
3
4
5
6
7
8
9


# 3 个节点分别启动
docker-compose up -d

# 查看集群成员
export ENDPOINTS=192.168.3.101:2379,192.168.3.102:2379,192.168.3.103:2379
etcdctl --endpoints=$ENDPOINTS member list

# 查看成员状态
etcdctl --write-out=table --endpoints=$ENDPOINTS endpoint status

4.4 常见排错

症状：retrying of unary invoker failed

原因：--advertise-client-urls 和 --initial-advertise-peer-urls 设成了 0.0.0.0 或 localhost——必须是具体 IP 或 hostname。

解决：把两个 URL 改成节点实际 IP。

4.5 客户端使用

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


# 写
etcdctl put /config/db/url "jdbc:mysql://<HOST>:3306/test"
etcdctl put /config/db/user "root"

# 读
etcdctl get /config/db/url
etcdctl get /config --prefix

# 删
etcdctl del /config/db/url

# 监听变更
etcdctl watch /config/db/url

五、ZooKeeper 部署

5.1 镜像

1

docker pull zookeeper:3.8.0

5.2 单机部署

1

docker run -d -p 2181:2181 --name zookeeper --restart always zookeeper:3.8.0

5.3 客户端使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 进入容器
docker exec -it zookeeper /bin/bash
cd bin
./zkCli.sh -server 127.0.0.1:2181

# zkCli 命令
ls /
create /test "hello"
get /test
set /test "world"
delete /test

5.4 WebUI 部署

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


docker pull tobilg/zookeeper-webui:latest

docker run -d \
 -p 8098:8080 \
 -e ZK_DEFAULT_NODE=<INTERNAL_HOST>:2181/ \
 -e USER=admin \
 -e PASSWORD=<REDACTED> \
 --name zk-web-ui \
 --restart always \
 -t tobilg/zookeeper-webui

访问 http://<HOST>:8098/。

5.5 集群部署

 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45


# docker-compose.yml
version: '3'
services:
 zk1:
 image: zookeeper:3.8.0
 container_name: zk1
 restart: always
 environment:
 - ZOO_MY_ID=1
 - ZOO_SERVERS=server.1=zk1:2888:3888;2181 server.2=zk2:2888:3888;2181 server.3=zk3:2888:3888;2181
 ports:
 - "2181:2181"
 - "8081:8080"
 networks:
 - zk-net

 zk2:
 image: zookeeper:3.8.0
 container_name: zk2
 restart: always
 environment:
 - ZOO_MY_ID=2
 - ZOO_SERVERS=server.1=zk1:2888:3888;2181 server.2=zk2:2888:3888;2181 server.3=zk3:2888:3888;2181
 ports:
 - "2182:2181"
 - "8082:8080"
 networks:
 - zk-net

 zk3:
 image: zookeeper:3.8.0
 container_name: zk3
 restart: always
 environment:
 - ZOO_MY_ID=3
 - ZOO_SERVERS=server.1=zk1:2888:3888;2181 server.2=zk2:2888:3888;2181 server.3=zk3:2888:3888;2181
 ports:
 - "2183:2181"
 - "8083:8080"
 networks:
 - zk-net

networks:
 zk-net:
 driver: bridge

坑 7：ZooKeeper 集群节点数 必须为奇数（3、5、7）——ZAB 协议要求多数派，奇数能容忍 n/2 节点故障。4 节点集群和 3 节点集群的容错能力是一样的，但 4 节点更耗资源。

六、四款组件的 Spring Cloud 接入

6.1 Nacos

1
2
3
4
5
6
7
8


<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

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


spring:
 application:
 name: order-service
 cloud:
 nacos:
 discovery:
 server-addr: <INTERNAL_HOST>:8848
 namespace: <NAMESPACE_ID>
 config:
 server-addr: <INTERNAL_HOST>:8848
 namespace: <NAMESPACE_ID>
 file-extension: yaml

6.2 Consul

1
2
3
4
5
6
7
8


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-consul-discovery</artifactId>
</dependency>
<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-consul-config</artifactId>
</dependency>

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


spring:
 cloud:
 consul:
 host: <INTERNAL_HOST>
 port: 8500
 discovery:
 prefer-ip-address: true
 health-check-interval: 10s
 config:
 format: yaml
 prefix: config
 default-context: order-service

6.3 etcd

1
2
3
4


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-etcd-discovery</artifactId>
</dependency>

坑 8：Spring Cloud Etcd 已经被官方弃用——推荐用 Kubernetes Service 做服务发现（K8s 内部 etcd 自动做）。如果是非 K8s 环境用 etcd 做服务发现，建议直接用 Nacos。

6.4 ZooKeeper

1
2
3
4


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-zookeeper-discovery</artifactId>
</dependency>

1
2
3
4


spring:
 cloud:
 zookeeper:
 connect-string: <INTERNAL_HOST>:2181,<INTERNAL_HOST>:2182,<INTERNAL_HOST>:2183

七、常见排错

7.1 Nacos 客户端报 “9848 port is unavailable”

症状：Spring Boot 启动时报 failed to req API:127.0.0.1:9848 或 9848 port is unavailable

解决：

服务端要开放 9848 端口（不只是 8848）
客户端 → 服务端的网络是通的

7.2 Consul 健康检查失败导致服务被踢

症状：服务注册到 Consul 后，30 秒后被自动剔除。

解决：

检查 Check.HTTP 路径是否真的存在（如 /actuator/health）
Spring Boot 加 management.endpoints.web.exposure.include: health
调长 deregister-critical-service-after 时间

7.3 etcd 集群脑裂

症状：etcdctl member list 显示 3 个节点都是 leader。

解决：

强制重置集群：停所有节点 → 删 --data-dir 目录 → 重新 --initial-cluster-state=new
加 --election-timeout 避免偶发切换

7.4 ZooKeeper 启动失败 “Cannot open channel to X at election address”

症状：ZooKeeper 容器日志反复报 Cannot open channel to 2 at election address /xx:3888

解决：

3888 端口是否开放
容器名（zk1 / zk2 / zk3）和 ZOO_SERVERS 配置是否一致
ZOO_MY_ID 是否和 server.X 中的 X 一致

八、写在最后

注册中心选型没有银弹——四款组件定位不同：

Nacos：Spring Cloud Alibaba 一站式，国内中小团队首选
Consul：多语言、多数据中心场景的"多面手"
etcd：K8s 内部组件、非 K8s 场景慎用
ZooKeeper：大数据生态依赖、传统微服务可用

下一步建议：

Nacos 2.x 集群 + MySQL 后端高可用（MySQL 主从 + Keepalived VIP）
Nacos + Sentinel 做流量控制和熔断
Consul Connect 做服务间 mTLS 加密

参考资料

Nacos 官方文档：https://nacos.io/zh-cn/docs/quick-start.html
Consul 官方文档：https://www.consul.io/docs
etcd 官方文档：https://etcd.io/docs/
ZooKeeper 官方文档：https://zookeeper.apache.org/doc/current/
Nacos Docker 镜像：https://hub.docker.com/r/nacos/nacos-server
Nacos 2.2.2 release notes：https://github.com/alibaba/nacos/releases/tag/2.2.2

微服务中间件集群实战：Nacos / Gateway / MySQL / Redis / MQ

Wed, 15 Sep 2021 00:00:00 +0800

本文写于 2021 年 9 月——微服务架构全面铺开，Nacos 2.0+ 已发布一年（2020 年初）、Spring Cloud Gateway 已成事实标准（替代 Zuul）、Redis Cluster 在生产大规模使用，5 大微服务中间件的"集群"方案成为面试必考点。

〇、2021 视角开篇

本文主体内容是 5 大微服务中间件（Gateway / Nacos / MySQL / Redis / MQ）的集群部署实战。2021-09 这个时点选得很巧：

Nacos 2.0（2020-01 发布）刚满 1.5 年，集群方案已稳定（Distro + Raft 双协议）
Spring Cloud Gateway（2018 年发布）替代 Zuul 已成定局，2021.x 是生产主流
Redis Cluster（3.0 起）经过 4 年迭代，3 主 3 从 6 节点模式是生产标配
RocketMQ 4.x（2017 年起）多主多从模式是阿里系标配，Kafka 同期竞争

下文涉及 2016 年时实际并不存在的工具（Nacos / Spring Cloud Gateway），是以 2021 视角讲解"这些工具是何时出现、何时成熟、2021 时点怎么用"。

一、Spring Cloud Gateway 集群

1.1 概述

Spring Cloud Gateway 是 Spring Cloud 的全新项目，基于 Spring 5.0 + Spring Boot 2.0 实现，旨在提供一种简单有效的方式对 API 进行路由，并提供强大的过滤功能：熔断、限流、监控、校验、鉴权。

为什么取代 Zuul？

Zuul 1.x 基于 Servlet 阻塞模型，性能有限
Zuul 2.0 跳票多年（被 Netflix 弃坑），Spring 社区转向基于 WebFlux + Netty 的响应式网关
Gateway 基于 WebFlux 框架，底层用 Netty 通信框架，性能远超 Zuul

1.2 集群部署

Gateway 是无状态服务，集群化非常简单：多实例 + 统一入口。

第一步：pom.xml 依赖

1
2
3
4
5
6
7
8


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

第二步：application.yml 配置

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


server:
 port: 9527

spring:
 application:
 name: cloud-gateway
 cloud:
 nacos:
 discovery:
 server-addr: nacos-cluster.internal:8848  # Nacos 集群地址
 gateway:
 discovery:
 locator:
 enabled: true # 开启从注册中心自动创建路由
 routes:
 - id: payment_route
 uri: lb://cloud-payment-service  # lb = load balance
 predicates:
 - Path=/payment/**

第三步：Nginx 入口负载均衡

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


upstream gateways {
 server 192.168.6.29:9527 weight=1;
 server 192.168.6.29:9528 weight=1; # 同一台机器两个端口模拟集群
 # server 192.168.6.30:9527 weight=1; # 多机部署
}

server {
 listen 80;
 server_name api.example.com;
 location / {
 proxy_pass http://gateways;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 }
}

关键点：

Gateway 实例之间不需要通信，各自从 Nacos 拉服务列表
网关自身的负载均衡交给 Nginx / F5 / SLB
网关是无状态服务，可以水平扩展

二、Nacos 集群

2.1 三种部署模式

单机模式：用于测试和单机使用
集群模式：用于生产环境，确保高可用
多集群模式：用于多数据中心场景

2.2 集群部署（Nacos ≥ 2.0）

前置：nacos 集群至少需要 3 个节点，因此准备 3 台服务器。

第一步：安装依赖

1
2
3


# 1. 安装 MySQL（nacos 配置持久化）
# 2. 安装 JDK 8+
# 3. 安装 Maven（仅首次构建时需要）

第二步：初始化数据库

执行 nacos 自带 SQL：conf/nacos-mysql.sql，创建 nacos_config 数据库和表。

第三步：配置 cluster.conf

将 conf/cluster.conf.example 改名为 cluster.conf：

1
2
3
4


# cluster.conf
192.168.6.21:8848
192.168.6.22:8848
192.168.6.23:8848

第四步：配置 application.properties

1
2
3
4
5


spring.datasource.platform=mysql
db.num=1
db.url.0=jdbc:mysql://192.168.6.10:3306/nacos_config?useUnicode=true&characterEncoding=utf-8
db.user=nacos
db.password={{REDACTED}}

第五步：启动

1

sh startup.sh

单台服务器启动成功后，对集群其他服务器重复同样操作即可。

2.3 集群原理

Distro 协议（AP 模式，默认）：nacos 自研的最终一致协议，每个节点负责一部分服务，多节点互写互读
Raft 协议（CP 模式，配置中心）：持久化配置走 Raft，保证强一致
节点间通过 gRPC 长连接 同步数据

三、MySQL 主从集群

3.1 集群目的

采用 MySQL 集群需要部署主从关系：

主节点：写数据（INSERT / UPDATE / DELETE）
从节点：读数据（SELECT）
关系：一主多从，用户从多个从节点读数据，大大缓解读取压力
额外收益：主节点写入自动同步到从节点，降低数据丢失风险

3.2 主从复制原理

MySQL 主从复制基于主服务器二进制日志（binlog） 跟踪所有对数据库的更改。

工作过程：

1
2
3
4
5
6
7
8
9


┌─────────┐ ┌─────────┐
│ Master │ │ Slave │
│ │ │ │
│ binlog │ <── (1) 读 binlog ─── I/O 线程 ──│ relay │
│ dump │ │ log │
│ 线程 │ ── (2) 传 binlog ───────────> │ │
│ │ │ SQL 线程│
│ │ <── (3) 同步完成通知 ───────────│ │
└─────────┘ └─────────┘

从库生成两个线程：一个 I/O 线程，一个 SQL 线程
I/O 线程请求主库的 binlog，并将 binlog 写到 relay log（中继日志）
主库生成 log dump 线程，用来给从库 I/O 线程传 binlog
SQL 线程读取 relay log，解析成具体操作，实现主从一致

3.3 核心配置

主库 my.cnf：

1
2
3
4
5


[mysqld]
server-id = 1
log-bin = /var/lib/mysql/mysql-bin
binlog-format = ROW
sync_binlog = 1

从库 my.cnf：

1
2
3
4


[mysqld]
server-id = 2
relay-log = /var/lib/mysql/relay-log
read-only = 1

主库授权：

1
2


grant replication slave on *.* to 'repl_user'@'%' identified by '{{REDACTED}}';
flush privileges;

从库配置同步：

1
2
3
4
5
6
7
8
9


CHANGE MASTER TO
 MASTER_HOST='192.168.6.21',
 MASTER_USER='repl_user',
 MASTER_PASSWORD='{{REDACTED}}',
 MASTER_LOG_FILE='mysql-bin.000001',
 MASTER_LOG_POS=0;

START SLAVE;
SHOW SLAVE STATUS\G # 看 Slave_IO_Running: Yes, Slave_SQL_Running: Yes

3.4 读写分离

两种实现方式：

数据库中间件（Mycat / Sharding-Proxy）：单独部署服务，配置实现读写分离，不侵入业务代码
客户端 SDK（dynamic-datasource / shardingsphere-jdbc）：业务代码引入 jar 包，通过注解切换

dynamic-datasource 示例（Spring Boot）：

1
2
3
4
5


<dependency>
 <groupId>com.baomidou</groupId>
 <artifactId>dynamic-datasource-spring-boot-starter</artifactId>
 <version>3.3.2</version>
</dependency>

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


spring:
 datasource:
 dynamic:
 primary: master
 datasource:
 master:
 url: jdbc:mysql://192.168.6.21:3306/test
 username: root
 password: {{REDACTED}}
 driver-class-name: com.mysql.cj.jdbc.Driver
 slave1:
 url: jdbc:mysql://192.168.6.22:3306/test
 username: root
 password: {{REDACTED}}
 driver-class-name: com.mysql.cj.jdbc.Driver

1
2
3
4
5
6
7
8


@Service
public class OrderService {
 @DS("master") // 写主库
 public void createOrder(Order order) { ... }
 
 @DS("slave1") // 读从库
 public List<Order> listOrders() { ... }
}

3.5 分库分表

两种方案：

Sharding Sphere（推荐）：JDBC 代理 / Proxy 模式
Mycat 2：数据库中间件，需要独立部署

四、Redis 集群

4.1 三种集群方案

主从复制模式：1 主 N 从，主写从读，但主挂了不会自动切换（需要手动）
Sentinel（哨兵）模式：在主从基础上加哨兵进程监控，主挂了自动选举新主（推荐中小规模）
Cluster 模式：Redis 3.0+ 官方方案，数据分片 + 主从 + 自动故障转移（推荐大规模）

4.2 集群部署（Cluster 模式）

官方推荐：集群至少 3 个 master 节点，最好用 3 主 3 从 6 节点模式。

1
2
3
4
5
6


# 启用集群模式
cluster-enabled yes
cluster-config-file nodes-6379.conf
cluster-node-timeout 15000
# 至少 3 个 master
cluster-migration-barrier 1

创建集群：

1
2
3
4


redis-cli --cluster create \
 192.168.6.31:6379 192.168.6.32:6379 192.168.6.33:6379 \
 192.168.6.34:6379 192.168.6.35:6379 192.168.6.36:6379 \
 --cluster-replicas 1

4.3 Cluster 原理

数据分片：16384 个 slot（哈希槽），每个 master 负责一段
请求路由：客户端通过 CRC16(key) % 16384 计算 slot
重定向：如果请求路由到错误节点，会返回 MOVED 或 ASK 让客户端重试
故障转移：master 挂了，从节点通过 Raft-like 协议选举新主

五、消息队列集群

5.1 RabbitMQ 集群

普通集群：多节点共享元数据，队列只在单节点，性能提升有限
镜像集群：队列数据多节点同步，HA 能力强但性能低
推荐方案：普通集群 + HAProxy + 镜像队列（关键业务队列）

5.2 RocketMQ 集群

NameServer 集群：无状态，多节点即可
Broker 集群：分 Master / Slave
- 多 Master：高性能但无 HA
- 多 Master 多 Slave（异步复制）：性能 + HA 平衡
- 多 Master 多 Slave（同步双写）：强 HA，性能低
推荐方案：2 主 2 异步从 + 异步刷盘

六、5 大集群对比

集群	核心协议	关键配置	HA 能力	数据一致性
Gateway	无（无状态）	Nginx upstream	自动（多实例）	无（无状态）
Nacos	Distro + Raft	cluster.conf + MySQL	自动（≥3 节点）	AP+CP 混合
MySQL	binlog + relay log	server-id + log-bin	半自动（需切换）	最终一致
Redis Cluster	哈希槽（16384）	cluster-enabled	自动（≥3 master）	最终一致
RabbitMQ	镜像队列	cluster_partition_handling	自动（镜像）	最终一致
RocketMQ	主从同步	brokerRole	自动（多主多从）	异步/同步

七、面试常问

Q：为什么 Nacos 集群至少 3 个节点？ A：Raft 协议要求过半节点存活才能选举 Leader，3 节点允许 1 节点宕机，5 节点允许 2 节点宕机。奇数节点是性价比最高的选择。

Q：MySQL 主从延迟怎么解决？ A：① 业务容忍延迟（异步复制天然有 ms 级延迟）；② 强制读主（重要业务读写都走主）；③ 半同步复制（MySQL 5.7+ rpl_semi_sync_master_wait_slave_count）；④ 用 Canal 订阅 binlog 同步到 ES / Redis。

Q：Redis Cluster 为什么是 16384 个 slot？ A：因为 16384 足够均匀分布，节点间心跳包大小可控（每个 slot 1 bit，16384 / 8 = 2KB，远小于 1MB 网络包上限）。如果用 65536，心跳包会膨胀到 8KB，且实际场景下节点数不会超过 1000，16384 足够。

Q：Spring Cloud Gateway 怎么限流？ A：内置 RequestRateLimiter GatewayFilter，基于 Redis + Lua 脚本实现令牌桶。Key 可以基于 IP / User / API Path。

八、小结

Gateway 无状态：集群 = 多实例 + 入口 LB
Nacos 集群：3 节点起步 + MySQL 持久化
MySQL 主从：binlog 同步 + 读写分离中间件
Redis Cluster：16384 哈希槽 + 3 主 3 从
MQ 集群：RabbitMQ 镜像队列 / RocketMQ 多主多从

九、2021 视角回望（微服务面试考点演化）

站在 2021-09 收尾，回看"5 大集群对比"那一节，再补充几点2021 时点的面试新趋势：

Nacos 2.0 的 gRPC 长连接：2020 年 Nacos 2.0 把数据同步从 HTTP 短连接改成长连接，性能提升 10 倍，是高频面试追问点
Spring Cloud Gateway 限流细节：内置 RequestRateLimiter + Redis Lua 是高频八股文，几乎所有 Java 面试都会问
MySQL 5.7 → 8.0 升级：2021 年 5.7 EOL 时间已定（2023-10），8.0 的 MGR（MySQL Group Replication）开始被生产采用
Redis 6.x 的多线程 IO：2020 年 Redis 6.0 发布，IO 多线程化但执行命令仍单线程，集群方案未变
Kafka vs RocketMQ 二选一：阿里系项目用 RocketMQ（事务消息），其他用 Kafka（生态 + 吞吐），2021 年仍是常见面试题

2021 时点的"5 大集群面试"标准答案：

Gateway 无状态 → 集群 = Nginx upstream + 多实例
Nacos 集群 → 至少 3 节点（过半选举） + MySQL 持久化 + gRPC 2.0 同步
MySQL 主从 → binlog + relay log + 读写分离（ShardingSphere / dynamic-datasource）
Redis Cluster → 16384 哈希槽 + 3 主 3 从 + 客户端路由
MQ 集群 → RabbitMQ 镜像队列 / RocketMQ 多主多从（同步双写保 HA）

K8s 集群流量入口：Ingress-nginx 七层与 TCP/UDP 四层代理实战

Tue, 15 Dec 2020 00:00:00 +0800

K8s 集群流量入口：Ingress-nginx 七层与 TCP/UDP 四层代理实战

TL;DR：在 K8s 里 Pod IP / ClusterIP 只能在集群内访问。要把服务暴露到集群外，常见链路是 ingress-nginx（七层 HTTP）→ Service（ClusterIP）→ Pod；非 HTTP 的 TCP/UDP 流量（数据库、MQTT、WebSocket、SSH）走 ingress-nginx 的 四层 stream-snippet / ConfigMap 或 hostNetwork + DaemonSet 模式。本文是一份基于生产二进制集群踩坑的实战笔记。

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

K8s 提供了 4 种把集群内服务暴露到外部的方式：

方式	适用场景	优点	缺点
`NodePort`	开发测试、单端口临时调试	简单，配置最少	端口范围受限（30000-32767），要逐个开防火墙
`LoadBalancer`	云厂商环境	自动化分配公网 IP	依赖云厂商 LB，每个 Service 一个 LB 贵
`Ingress`	HTTP/HTTPS 七层路由，多域名多路径	一台 LB 服务多套系统，支持 TLS 终止、灰度	只能代理 HTTP/HTTPS
`hostNetwork`	四层流量 + 极致性能	走宿主机网络，无 kube-proxy 转发损耗	一个 Node 只能跑一个 Pod，要配 `nodeSelector`

核心架构：

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


外网 (Client)
 │
 ▼
[ NodePort / LoadBalancer / hostNetwork ]
 │
 ▼
[ ingress-nginx-controller ] ← 七层：解析 Host / Path
 │
 ▼
[ Service (ClusterIP) ] ← 集群内虚拟 IP
 │
 ▼
[ Pod (业务容器) ]

原则：ingress 代理 service，service 代理 pod。Ingress 本身不直接连 Pod，一定要过 Service 这一层（service mesh 也是同理）。

API 版本注意：本文示例全部使用 apiVersion: networking.k8s.io/v1（K8s 1.19 GA，1.22 起 extensions/v1beta1 被彻底移除）。kubernetes.io/ingress.class 注解在 1.18 后也已被 spec.ingressClassName 取代，请直接使用新写法。

二、安装 ingress-nginx

2.1 部署清单来源

官方仓库：https://github.com/kubernetes/ingress-nginx
云厂商部署清单：https://github.com/kubernetes/ingress-nginx/blob/main/deploy/static/provider/cloud/deploy.yaml

⚠️ 版本匹配：K8s 1.19+ 务必使用 ingress-nginx v0.46+（首个 networking.k8s.io/v1 稳定支持的 controller），2020 年下半年该分支已 GA。

2.2 应用与查看

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


# 部署
kubectl apply -f /etc/k8s/ingress-nginx/deploy.yaml

# 删除
kubectl delete -f /etc/k8s/ingress-nginx/deploy.yaml

# 部署后产生的核心资源
namespace/ingress-nginx created
serviceaccount/ingress-nginx created
serviceaccount/ingress-nginx-admission created
role.rbac.authorization.k8s.io/ingress-nginx created
clusterrole.rbac.authorization.k8s.io/ingress-nginx created
configmap/ingress-nginx-controller created
service/ingress-nginx-controller created
deployment.apps/ingress-nginx-controller created
job.batch/ingress-nginx-admission-create created
job.batch/ingress-nginx-admission-patch created
ingressclass.networking.k8s.io/nginx created
validatingwebhookconfiguration.admissionregistration.k8s.io/ingress-nginx-admission created

2.3 资源清单

1

kubectl get all -n ingress-nginx

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


NAME READY STATUS RESTARTS AGE
pod/ingress-nginx-admission-create-cf9w5 0/1 Completed 0 7m36s
pod/ingress-nginx-admission-patch-zm7m5 0/1 Completed 0 7m36s
pod/ingress-nginx-controller-766bcbf897-fhvrb 1/1 Running 0 7m36s

NAME TYPE CLUSTER-IP PORT(S)
service/ingress-nginx-controller NodePort 10.x.x.x 80:30080/TCP,443:30443/TCP
service/ingress-nginx-controller-admission ClusterIP 10.x.x.x 443/TCP

NAME READY UP-TO-DATE AVAILABLE
deployment.apps/ingress-nginx-controller 1/1 1 1

这里的 ingressclass.networking.k8s.io/nginx 是 v1 引入的 IngressClass 对象，下游 Ingress 资源靠 spec.ingressClassName: nginx 引用它。

三、最简七层反代测试

3.1 测试 Deployment / Service / Ingress

 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
32


# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 namespace: test
spec:
 replicas: 3
 selector:
 matchLabels:
 app: nginx
 template:
 metadata:
 labels:
 app: nginx
 spec:
 containers:
 - name: nginx
 image: nginx:1.25
---
# service.yaml
apiVersion: v1
kind: Service
metadata:
 name: nginx-service
 namespace: test
spec:
 selector:
 app: nginx
 ports:
 - port: 80
 targetPort: 80

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


# ingress.yaml（networking.k8s.io/v1）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: test-ingress
 namespace: test
spec:
 ingressClassName: nginx
 rules:
 - host: nginx.example.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: nginx-service
 port:
 number: 80

1
2
3


kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
kubectl apply -f ingress.yaml

3.2 查看 Ingress 解析结果

1

kubectl describe ingress test-ingress -n test

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


Name: test-ingress
Namespace: test
Address: 10.x.x.x
Ingress Class: nginx
Default backend: <default>
Rules:
 Host Path Backends
 ---- ---- --------
 nginx.example.com
 / nginx-service:80 (10.244.1.10:80, 10.244.2.71:80, 10.244.3.8:80)
Events:
 Type Reason Age From Message
 ---- ------ ---- ---- -------
 Normal Sync 110s (x2 over 2m22s) nginx-ingress-controller Scheduled for sync

3.3 本地 hosts + curl 测试

1
2
3
4
5
6
7
8


# /etc/hosts（开发机）
# 内网IP-A nginx.example.com tomcat.example.com

# 直接访问 NodePort
curl -H "Host: nginx.example.com" http://内网IP-A:30080/

# 或先 ping 测连通
ping 内网IP-A

v1 与 v1beta1 的关键差异（写错会 apply 失败）：

字段 extensions/v1beta1（已弃用） networking.k8s.io/v1（本文用）

apiVersion extensions/v1beta1 networking.k8s.io/v1

路径匹配 path: /foo（隐式 Prefix） path: /foo + pathType: Prefix | Exact | ImplementationSpecific（必填）

后端 backend.serviceName + servicePort backend.service.name + backend.service.port.number/name

Ingress 类注解 kubernetes.io/ingress.class: nginx spec.ingressClassName: nginx

四、关键注解（Annotations）速查

完整注解列表：https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md

4.1 不配置 host，用路径区分服务（Nacos 场景）

把 Nacos 控制台通过 /nacos 路径前缀反代出去，不绑定 host：

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


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: nacos-ingress
 namespace: example-corp
 annotations:
 nginx.ingress.kubernetes.io/use-regex: "true"
spec:
 ingressClassName: nginx
 rules:
 - http:
 paths:
 - pathType: Prefix
 path: /nacos
 backend:
 service:
 name: nacos-headless
 port:
 name: server

访问地址：http://内网IP-A/nacos

注意：当 host 字段省略，Ingress 会响应所有到达 controller 的请求，生产环境强烈建议绑定 host 防止冲突。如果一定要多服务复用 host，请用 pathType: Prefix 拆分路径。

4.2 app-root：访问根路径自动重定向

1
2
3


metadata:
 annotations:
 nginx.ingress.kubernetes.io/app-root: /corp

访问 https://example-corp.com/ 会 302 到 https://example-corp.com/corp，适合老门户的默认页迁移。

五、hostNetwork 模式：性能 + 四层必备

默认 ingress-nginx-controller 是 Deployment + Service(NodePort)，但生产环境有两类需求让它不够用：

直接监听 80/443 端口——不想用 30080/30443 这种高位端口
代理 TCP/UDP 四层流量——NodePort 不支持 stream

解决方案：hostNetwork: true + DaemonSet + nodeSelector，让 controller 在每个打了 ingress=true 标签的 Node 上独占监听宿主机网络。

5.1 修改清单的关键点

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


spec:
 # 1. 改成 DaemonSet：一个 Node 只能跑一个 controller
 kind: DaemonSet

 template:
 spec:
 # 2. 与宿主机共享网络栈
 hostNetwork: true

 # 3. 节点选择器
 nodeSelector:
 kubernetes.io/os: linux
 ingress: "true"

 # 4. hostNetwork 模式下要保留 K8s DNS
 dnsPolicy: ClusterFirstWithHostNet

删除 replicas、strategy.rollingUpdate 等 Deployment 专属字段。

5.2 给 Node 打标签

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


# 打标签
kubectl label node k8s-master-1 ingress=true
kubectl label node k8s-master-2 ingress=true
kubectl label node k8s-master-3 ingress=true

# 移除标签
kubectl label node k8s-master-3 ingress=true-

# 容忍 NoSchedule 污点（master 节点常有）
kubectl taint nodes k8s-master-1 node-role.kubernetes.io/control-plane:NoSchedule-

# 查看所有节点标签
kubectl get node --show-labels

5.3 部署与验证

1
2
3
4
5
6
7
8


# 先删旧 Deployment
kubectl delete -f /etc/k8s/ingress-nginx/deploy.yaml

# 部署新清单
kubectl apply -f /etc/k8s/ingress-nginx/hostNetwork.yaml

# 查看 controller 是否在每个 Node 跑一个
kubectl get pods -n ingress-nginx -o wide

1
2
3
4


NAME READY STATUS IP NODE
ingress-nginx-controller-cd58b 1/1 Running 内网IP-B k8s-master-2
ingress-nginx-controller-cgzk7 1/1 Running 内网IP-C k8s-master-1
ingress-nginx-controller-p2fdt 1/1 Running 内网IP-D k8s-master-3

5.4 验证四层与七层

1
2
3
4
5


# 七层：80 端口直接访问
curl http://nginx.example.com

# 四层：可以走 NodePort 也可以走宿主机 IP 直连
curl -H "Host: nginx.example.com" http://内网IP-A

六、四层代理：代理集群外的 TCP / WS / UDP

ingress-nginx 默认只代理 HTTP / HTTPS。要让 ingress-nginx 转发 TCP / UDP 流量（如 MySQL 3306、MQTT 1883、自定义 WebSocket），有三种方案：

6.1 方案对比

方案	适用场景	优点	缺点
① `stream-snippet` 注解	单个 Ingress 临时使用	配置最简单	不易复用
② `ConfigMap` 集中管理	多服务、需统一管理	一个 CM 管多个端口	要修改 DaemonSet args
③ `ExternalName` + Service	集群内 Pod 访问集群外	应用侧零配置	集群外无法反向访问

6.2 方案一：使用 Endpoints + Service + Ingress + stream-snippet

核心思路：用 Endpoints 直接指向集群外的 IP:PORT，再通过 Ingress 的 stream-snippet 注解把流量引过去。

⚠️ Endpoints.name 必须和 Service.name 完全一致——这是手写四层 Service 的铁律，写错 Service 永远 no endpoints available。

 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


# tcp-outside-3306.yaml
apiVersion: v1
kind: Endpoints
metadata:
 name: external-mysql
 namespace: example-corp
subsets:
 - addresses:
 - ip: 内网IP-E  # 集群外的 MySQL 真实地址
 ports:
 - port: 3306
 protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
 name: external-mysql
 namespace: example-corp
spec:
 clusterIP: None  # Headless Service，由 Endpoints 决定后端
 type: ClusterIP
 ports:
 - port: 7306 # 集群内访问用的端口
 protocol: TCP
 targetPort: 3306 # 转发到 Endpoints 里的 3306

 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


# tcp-outside-3306-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: external-mysql-ingress
 namespace: example-corp
 annotations:
 nginx.ingress.kubernetes.io/stream-snippet: |
 server {
 listen 8000;
 proxy_pass 内网IP-E:3306;
 }
spec:
 ingressClassName: nginx
 rules:
 - host: mysql.example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: external-mysql
 port:
 number: 7306

TCP 流量不要用 HTTP 测：四层流量没有 Host 头，curl http://内网IP-A:8000 会一直 400。正确姿势：nc -vz 内网IP-A 8000 或 telnet 内网IP-A 8000。

6.3 方案二：ConfigMap 集中管理（推荐生产用）

第一步：创建 ConfigMap 占位

1

kubectl -n ingress-nginx create configmap tcp-services

第二步：编辑 ConfigMap

1

kubectl edit -n ingress-nginx cm tcp-services

1
2
3
4
5
6
7
8
9


apiVersion: v1
kind: ConfigMap
metadata:
 name: tcp-services
 namespace: ingress-nginx
data:
 # 格式："<对外端口>": "<namespace>/<service>:<service-port>"
 "7306": "example-corp/external-mysql:7306"
 "1883": "example-corp/mqtt-service:1883"

第三步：让 controller 加载 ConfigMap

1

kubectl edit -n ingress-nginx DaemonSet/ingress-nginx-controller

1
2
3
4
5
6
7
8


spec:
 template:
 spec:
 containers:
 - args:
 - /nginx-ingress-controller
 - --tcp-services-configmap=$(POD_NAMESPACE)/tcp-services
 - --udp-services-configmap=$(POD_NAMESPACE)/udp-services

重要：$(POD_NAMESPACE) 是 controller 自带的 downward API 变量，会自动展开为 ingress-nginx，不要手写死。

第四步：补充 Service 端口暴露

1

kubectl edit -n ingress-nginx Service/ingress-nginx-controller

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


spec:
 ports:
 - name: http
 port: 80
 targetPort: 80
 - name: https
 port: 443
 targetPort: 443
 - name: external-mysql
 port: 7306
 targetPort: 7306
 protocol: TCP

第五步：调整 Service 类型与 externalIPs

1
2
3


# 类型改为 LoadBalancer（云厂商自动分配 IP）
kubectl patch svc ingress-nginx-controller -n ingress-nginx \
 -p '{"spec": {"type": "LoadBalancer", "externalIPs":["内网IP-A"]}}'

6.4 集群内测试连通

 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


# 用 busybox 测连通
kubectl exec -it busybox -- sh
ping external-mysql.example-corp.svc.cluster.local
telnet external-mysql.example-corp.svc.cluster.local 3306

# 用 ubuntu + mycli 工具测
cat << "EOF" > ubuntu.yml
apiVersion: v1
kind: Pod
metadata:
 name: diag-pod
spec:
 containers:
 - name: ubuntu
 image: ubuntu:22.04
 command: [ "/bin/bash", "-c", "--" ]
 args: [ "while true; do sleep 3600; done;" ]
EOF

kubectl apply -f ubuntu.yml
kubectl exec -it diag-pod -- bash
apt update && apt install -y python3-pip
pip3 install mycli

# 用 K8s Service DNS 名连接（注意改密码）
mycli -h external-mysql.example-corp.svc.cluster.local -uroot -p'<REDACTED-MYSQL-PWD>'

七、TLS 终端

7.1 创建 Secret

1
2
3
4
5
6
7
8


# 先建命名空间
kubectl create namespace example-corp

# 从证书文件创建 TLS Secret
kubectl create secret generic www-example-corp-secret \
 --from-file=tls.key=<CERT_ID>__example-corp.com.key \
 --from-file=tls.crt=<CERT_ID>__example-corp.com.pem \
 -n example-corp

7.2 开启 configuration-snippet

ingress-nginx v0.46+ 默认禁用 configuration-snippet（安全考量），要自定义 nginx 片段必须先开：

1

kubectl edit -n ingress-nginx configmap/ingress-nginx-controller

1
2


data:
 allow-snippet-annotations: "true" # 允许使用 configuration-snippet 注解

7.3 启用 TLS 的 Ingress

 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


apiVersion: v1
kind: Endpoints
metadata:
 name: www-service
 namespace: example-corp
subsets:
 - addresses:
 - ip: 内网IP-F
 ports:
 - port: 81
 protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
 name: www-service
 namespace: example-corp
spec:
 ports:
 - port: 81
 targetPort: 81
 protocol: TCP
 type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: www-ingress
 namespace: example-corp
 annotations:
 nginx.ingress.kubernetes.io/app-root: /corp
 nginx.ingress.kubernetes.io/use-regex: "true"
 nginx.ingress.kubernetes.io/configuration-snippet: |
 access_log /var/log/nginx/www.example-corp.com.access.log upstreaminfo if=$loggable;
 error_log /var/log/nginx/www.example-corp.com.error.log;
spec:
 ingressClassName: nginx
 tls:
 - hosts:
 - example-corp.com
 - www.example-corp.com
 secretName: www-example-corp-secret
 rules:
 - host: www.example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: www-service
 port:
 number: 81
 - host: example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: www-service
 port:
 number: 81

1

kubectl apply -f /etc/k8s/ingress/www-ingress.yaml

访问：https://example-corp.com https://www.example-corp.com

八、WebSocket 代理

ingress-nginx 默认支持 WebSocket，但要在 location 里显式设置：

1
2
3
4
5
6
7
8
9


location / {
 proxy_pass http://backend;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_read_timeout 3600s; # 长连接超时
}

在 ingress-nginx 里用注解实现：

1
2
3
4
5


metadata:
 annotations:
 nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
 nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
 # WebSocket 自动识别 Connection: Upgrade

默认 60s 不发包就断，WebSocket / 长轮询场景必须把 read/send timeout 拉到 3600s 以上，否则客户端会频繁断连。

九、Nacos 反代实战

Nacos Headless Service（clusterIP: None）+ Ingress 是社区最常见的"在 K8s 外面访问 Nacos 控制台"姿势：

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


# 假设 Nacos 已经用 Helm 或 Operator 部署好
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
 name: nacos-console
 namespace: nacos
 annotations:
 nginx.ingress.kubernetes.io/use-regex: "true"
 nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
spec:
 ingressClassName: nginx
 rules:
 - host: nacos.example-corp.com
 http:
 paths:
 - pathType: Prefix
 path: /
 backend:
 service:
 name: nacos-headless
 port:
 name: server  # 8848，对应 service.port.name

同样适用 Apollo、Consul、Sentinel Dashboard 等"控制台类服务"。use-regex: "true" 是因为 Nacos 前端路由里有 /#/xxx 这种 hash 路径，不开 regex 会被当成物理路径处理。

十、常见 8 个坑

#	坑	现象	解决
1	用了 `extensions/v1beta1`	K8s 1.22+ 直接 `apply` 失败 `no matches for kind`	改用 `networking.k8s.io/v1`，`pathType` 必填
2	忘写 `pathType`	`networking.k8s.io/v1` apply 报 `pathType Required value`	路径下必须显式 `pathType: Prefix \| Exact \| ImplementationSpecific`
3	Windows 能 ping 通但浏览器打不开	hosts 配了域名，ping 通，浏览器 502	关代理、关防火墙；`netsh winsock reset` 重启
4	客户端开了代理工具后无法访问 Ingress	浏览器挂了科学上网工具，所有流量走代理，Ingress 不通	代理工具"Bypass Domain/IP"里加业务域名；或选"全球直连"
5	Endpoints.name 与 Service.name 不一致	Service 一直无 Endpoints，curl 报 no endpoints available	严格保持两个 name 一致；这是 K8s 老坑
6	hostNetwork 模式下 DNS 解析错乱	Pod 用宿主机 `/etc/resolv.conf`，找不到集群内服务	`dnsPolicy: ClusterFirstWithHostNet`
7	DaemonSet 配了 replicas 字段	apply 时报 validation error	删掉 `replicas` 和 `strategy.rollingUpdate`
8	`configuration-snippet` 不生效	自定义 nginx 片段被忽略	ConfigMap 里设 `allow-snippet-annotations: "true"`
9	TCP 走 8000 端口但用 HTTP 测	telnet 通，curl 失败	四层不能用 HTTP 探测；用 `nc -vz` 或 `telnet`

十一、核心 6 点速记

链路：外网 → NodePort/hostNetwork → ingress-nginx → Service → Pod
七层（HTTP）用 Ingress；四层（TCP/UDP）用 stream-snippet 或 ConfigMap + DaemonSet args
生产必开 hostNetwork：直连 80/443 + 支持四层；必须配 DaemonSet + nodeSelector + dnsPolicy: ClusterFirstWithHostNet
Endpoints.name == Service.name 是手写四层 Service 的铁律
TLS 终端走 Ingress tls.hosts + secretName；自定义 nginx 片段需先开 allow-snippet-annotations
Ingress 不直接连 Pod：中间一定要过 Service（service mesh 同样），不要图省事

十二、排错命令速查

 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


# 查看 controller 配置
kubectl exec -it <pod> -n ingress-nginx -- cat /etc/nginx/nginx.conf

# 实时日志
kubectl logs -f -n ingress-nginx <pod>

# 集群内连通性
kubectl exec -it busybox -- sh
ping <svc>.<ns>.svc.cluster.local

# Service 详情
kubectl describe svc <svc-name> -n <ns>
kubectl describe endpoints <svc-name> -n <ns>

# Ingress 状态
kubectl get ingress -A
kubectl describe ingress <name> -n <ns>

# IngressClass 引用关系
kubectl get ingressclass
kubectl get ingress -A -o jsonpath='{range .items[?(@.spec.ingressClassName)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'

# hostNetwork 模式查看端口监听
ss -tlnp | grep -E ":(80|443|3306|1883)"

# 检查 controller 加载的 TCP/UDP ConfigMap
kubectl logs -n ingress-nginx <pod> | grep -E "tcp-services|stream-snippet"

十三、参考资料

ingress-nginx 仓库：https://github.com/kubernetes/ingress-nginx
官方部署清单：https://github.com/kubernetes/ingress-nginx/blob/main/deploy/static/provider/cloud/deploy.yaml
Annotation 索引：https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md
Ingress API v1 文档：https://kubernetes.io/docs/concepts/services-networking/ingress/
K8s 1.20 Release Notes（v1 Ingress GA）：https://kubernetes.io/blog/2020/12/08/kubernetes-1-20-release-announcement/
nginx stream 模块：https://nginx.org/en/docs/stream/ngx_stream_core_module.html
Nacos 集群部署：https://nacos.io/zh-cn/docs/cluster-mode-quick-start.html

Spring Cloud 实战：微服务、网关、安全一体化

Thu, 20 Sep 2018 00:00:00 +0800

Spring Cloud 实战：微服务、网关、安全一体化

背景与价值

Spring Cloud 是 Java 生态事实标准微服务框架（Dubbo 主要在阿里系内部使用）。基于 Spring Boot，提供了配置中心、注册中心、网关、熔断、负载均衡、链路追踪等开箱即用的微服务组件。

2018 年 Spring Cloud Finchley 发布（基于 Spring Boot 2.0），标志着 Spring Cloud 进入"模块化、可插拔"阶段。本文按"版本演进 → 核心组件 → 选型 → 实战"完整路径展开。

版本演进时间线

发布年月	Spring Boot	Spring Cloud	Spring Cloud Alibaba
2014-06	1.0	-	-
2016-01	-	Angel.SR5	-
2017-02	1.5	-	-
2017-09	-	-	Alibaba 1.5.1
2018-03	2.0	-	Alibaba 2.0.4
2018-09	-	Finchley	Alibaba 2.1
2019-10	2.2	Hoxton	-
2020-05	2.3	-	Alibaba 2.2
2021-05	2.5	-	-
2021-11	2.6	2021.0.x Jubilee	Alibaba 2021.0.x
2022-11	3.0（JDK 17+）	2022.0.x Kilburn	Alibaba 2022.0.x
2023-11	3.2	-	-

生产推荐组合（2024 稳定）：

JDK 8：Spring Boot 2.6.14 + Spring Cloud 2021.0.7 + Alibaba 2021.0.5

JDK 17/21：Spring Boot 3.2+ + Spring Cloud 2023.0.x + Alibaba 2022.0.x

核心组件全景

类别	Spring Cloud 官方	Spring Cloud Alibaba	Spring Cloud Netflix（已停更）
配置中心	Spring Cloud Config	Nacos	-
注册中心	Consul	Nacos	Eureka
服务熔断	Resilience4j	Sentinel	Hystrix
服务调用	OpenFeign	Dubbo RPC	Feign
负载均衡	Spring Cloud LoadBalancer	Dubbo LB	Ribbon
网关路由	Spring Cloud Gateway	-	Zuul
消息总线	Spring Cloud Bus	-	-
链路追踪	Sleuth + Zipkin	-	-
分布式消息	Spring Cloud Stream	RocketMQ	-
分布式事务	-	Seata	-

2024 年 Netflix 套件（Hystrix / Ribbon / Zuul）已全部进入维护模式，新项目禁用。

Spring Cloud Gateway 实战

1. 引入依赖

1
2
3
4


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

注意：Gateway 基于 WebFlux（响应式），不能引入 spring-boot-starter-web！

2. 路由配置

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


# application.yml
spring:
 cloud:
 gateway:
 routes:
 - id: user-service
 uri: lb://user-service  # lb:// = LoadBalancer 服务发现
 predicates:
 - Path=/api/user/**  # 路径匹配
 filters:
 - StripPrefix=2  # 去掉 /api/user 前缀
 - AddRequestHeader=X-Request-Id, ${UUID}
 - CircuitBreaker=myCircuitBreaker

 - id: order-service
 uri: lb://order-service
 predicates:
 - Path=/api/order/**
 - Method=POST,PUT
 filters:
 - StripPrefix=2
 - Retry=3  # 重试 3 次

3. 全局过滤器（鉴权 + 日志）

 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
32
33


@Component
public class GlobalAuthFilter implements GlobalFilter, Ordered {

 @Override
 public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
 ServerHttpRequest request = exchange.getRequest();
 String token = request.getHeaders().getFirst("Authorization");

 // 1. 白名单（无需 token）
 String path = request.getPath().value();
 if (path.startsWith("/api/auth/") || path.startsWith("/api/public/")) {
 return chain.filter(exchange);
 }

 // 2. 校验 token
 if (token == null || !validateToken(token)) {
 ServerHttpResponse response = exchange.getResponse();
 response.setStatusCode(HttpStatus.UNAUTHORIZED);
 return response.setComplete();
 }

 // 3. 传递用户信息给下游服务
 ServerHttpRequest mutated = request.mutate()
 .header("X-User-Id", extractUserId(token))
 .build();
 return chain.filter(exchange.mutate().request(mutated).build());
 }

 @Override
 public int getOrder() {
 return -100; // 数字越小越早执行
 }
}

4. CORS 跨域配置

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


@Configuration
public class CorsConfig {

 @Bean
 public CorsWebFilter corsFilter() {
 CorsConfiguration config = new CorsConfiguration();
 config.addAllowedOriginPattern("*");
 config.addAllowedHeader("*");
 config.addAllowedMethod("*");
 config.setAllowCredentials(true);
 config.setMaxAge(3600L);

 UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
 source.registerCorsConfiguration("/**", config);
 return new CorsWebFilter(source);
 }
}

Nacos 注册中心 + 配置中心

Nacos 集成注册中心 + 配置中心，一站式替代 Eureka + Config + Bus。

1. 服务注册

1
2
3
4
5
6
7
8


<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

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


spring:
 application:
 name: user-service
 cloud:
 nacos:
 discovery:
 server-addr: {{NACOS_HOST}}:8848
 namespace: prod
 username: {{NACOS_USER}}
 password: {{NACOS_PASSWORD}}
 config:
 server-addr: {{NACOS_HOST}}:8848
 file-extension: yaml
 refresh-enabled: true
 shared-configs:
 - data-id: common.yaml
 refresh: true

2. 配置动态刷新

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


@RestController
@RefreshScope // 关键注解：nacos 配置变更时自动刷新 @Value
public class OrderController {

 @Value("${order.timeout:30}")
 private int timeout;

 @GetMapping("/timeout")
 public String getTimeout() {
 return "当前超时时间: " + timeout + " 秒";
 }
}

3. 集群部署（3 节点）

1
2
3
4
5
6
7


# 节点 1
sh startup.sh -m standalone # 单机模式（仅测试）
sh startup.sh -m cluster # 集群模式（生产）

# application.properties
nacos.cluster.name=Cluster-A
nacos.member.list=192.168.1.1:8848,192.168.1.2:8848,192.168.1.3:8848

集群模式需要 MySQL 存储（替代默认 Derby），3 节点 Raft 选举实现高可用。

Spring Security 实战

1. 引入依赖

1
2
3
4


<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-security</artifactId>
</dependency>

2. 基础配置（用户名密码登录）

1
2
3
4
5
6


spring:
 security:
 user:
 name: admin
 password: {{ADMIN_PASSWORD}}  # 实际值从 Nacos 配置中心读取
 roles: ADMIN

默认会拦截所有请求，访问 http://localhost:8080 弹出登录框。

3. JWT 鉴权配置

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


@Configuration
@EnableWebSecurity
public class SecurityConfig {

 @Bean
 public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
 http
 .csrf(csrf -> csrf.disable())
 .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
 .authorizeHttpRequests(auth -> auth
 .requestMatchers("/api/auth/**", "/api/public/**").permitAll()
 .anyRequest().authenticated()
 )
 .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class);

 return http.build();
 }

 @Bean
 public PasswordEncoder passwordEncoder() {
 return new BCryptPasswordEncoder();
 }
}

 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
32
33


@Component
public class JwtAuthFilter extends OncePerRequestFilter {

 @Override
 protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
 throws ServletException, IOException {
 String token = request.getHeader("Authorization");
 if (token != null && token.startsWith("Bearer ")) {
 String jwt = token.substring(7);
 try {
 Claims claims = Jwts.parser()
 .verifyWith(Keys.hmacShaKeyFor(secret.getBytes()))
 .build()
 .parseSignedClaims(jwt)
 .getPayload();

 String username = claims.getSubject();
 List<String> roles = claims.get("roles", List.class);

 List<SimpleGrantedAuthority> authorities = roles.stream()
 .map(r -> new SimpleGrantedAuthority("ROLE_" + r))
 .collect(Collectors.toList());

 UsernamePasswordAuthenticationToken auth =
 new UsernamePasswordAuthenticationToken(username, null, authorities);
 SecurityContextHolder.getContext().setAuthentication(auth);
 } catch (Exception e) {
 // token 无效
 }
 }
 chain.doFilter(request, response);
 }
}

OpenFeign 服务调用

1. 引入依赖

1
2
3
4


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>

2. 声明式调用

1
2
3
4
5
6
7
8
9


@FeignClient(name = "order-service", fallback = OrderClientFallback.class)
public interface OrderClient {

 @GetMapping("/api/order/{userId}")
 Result<List<Order>> listByUser(@PathVariable Long userId);

 @PostMapping("/api/order")
 Result<Order> create(@RequestBody OrderDTO order);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@RestController
public class UserController {

 @Autowired
 private OrderClient orderClient;

 @GetMapping("/user/{id}/orders")
 public Result<List<Order>> getUserOrders(@PathVariable Long id) {
 return orderClient.listByUser(id);
 }
}

3. Fallback 降级

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


@Component
public class OrderClientFallback implements OrderClient {

 @Override
 public Result<List<Order>> listByUser(Long userId) {
 return Result.fail("订单服务不可用，请稍后重试");
 }

 @Override
 public Result<Order> create(OrderDTO order) {
 return Result.fail("订单创建失败");
 }
}

Sentinel 熔断限流

1. 引入依赖

1
2
3
4


<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>

2. 控制台部署

1
2
3
4
5


docker run -d \
 -p 8858:8858 \
 -p 8719:8719 \
 --name sentinel-dashboard \
 bladex/sentinel-dashboard:1.8.6

访问 http://localhost:8858，账号 sentinel / sentinel。

3. 流量控制规则（代码方式）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@PostConstruct
public void initFlowRules() {
 List<FlowRule> rules = new ArrayList<>();
 FlowRule rule = new FlowRule("userService");
 rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
 rule.setCount(100); // QPS 阈值
 rule.setLimitApp("default");
 rules.add(rule);
 FlowRuleManager.loadRules(rules);
}

链路追踪（Sleuth + Zipkin）

1
2
3
4
5
6
7
8


<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
<dependency>
 <groupId>org.springframework.zipkin</groupId>
 <artifactId>zipkin-reporter-brave</artifactId>
</dependency>

1
2
3
4
5
6


spring:
 zipkin:
 base-url: http://{{ZIPKIN_HOST}}:9411
 sleuth:
 sampler:
 probability: 0.1 # 采样率 10%

每次 HTTP 请求会自动注入 X-B3-TraceId / X-B3-SpanId，通过 Zipkin UI 看到完整调用链。

微服务方案选型决策

场景	推荐方案
传统企业（Java 8 为主）	Spring Cloud 2021.0.x + Alibaba 2021.0.x
新项目（Java 17/21）	Spring Cloud 2023.0.x + Alibaba 2022.0.x
高吞吐业务	Spring Cloud Gateway + Sentinel + RocketMQ
阿里系	Spring Cloud Alibaba（Nacos + Sentinel + Seata）
多语言异构	Spring Cloud Gateway + gRPC + Nacos

前置知识与下一步

前置：

Spring Boot 基础
微服务基本概念（服务注册 / 发现 / 熔断）
Linux + Docker 基础

下一步：

分布式事务：Spring Cloud Alibaba Seata（AT/TCC/SAGA/XA 4 种模式）
配置中心深度：Nacos 长轮询 + 灰度发布
监控：Spring Boot Admin + Actuator + Prometheus + Grafana

小结

Spring Cloud 2021.0.x（Jubilee） + Spring Cloud Alibaba 2021.0.x 是当前最稳定的 Java 微服务组合。Nacos 一体化注册 + 配置中心、Sentinel 替代 Hystrix、Seata 解决分布式事务、Gateway 替代 Zuul，是核心 4 件套。新项目直接基于 Spring Boot 3.2+ + Spring Cloud 2023.0.x，老项目维持 Spring Boot 2.6 + Spring Cloud 2021.0.x。

2024+ 视角：Spring Cloud 2024 / 2025 与 Spring AI

Spring Cloud 版本节奏（2024 视角）

发布年份	Spring Boot	Spring Cloud	Spring Cloud Alibaba	关键变化
2024-11	3.4	2024.0.x	2023.0.x	JDK 17+ 强制
2025-05	3.5	2025.0.x	2023.0.x	Spring AI 1.0 GA

生产推荐：

JDK 17：Spring Boot 3.4 + Spring Cloud 2024.0.x + Alibaba 2023.0.x
JDK 21：Spring Boot 3.5 + Spring Cloud 2025.0.x + Alibaba 2023.0.x

Spring AI 1.0（2025 GA）

Spring 官方推出的 LLM 集成框架——类似 LangChain 的 Java 版：

1
2
3
4


<dependency>
 <groupId>org.springframework.ai</groupId>
 <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

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


@RestController
public class ChatController {

 private final ChatClient chatClient;

 public ChatController(ChatClient.Builder builder) {
 this.chatClient = builder.build();
 }

 @GetMapping("/chat")
 public String chat(@RequestParam String message) {
 return chatClient.prompt()
 .user(message)
 .call()
 .content();
 }
}

核心能力：

多模型支持（OpenAI / Anthropic / Azure / Ollama / DeepSeek / 通义千问）
Function Calling（让 LLM 调 Java 方法）
RAG（向量库集成：pgvector / Milvus / Qdrant）
Prompt Template + 结构化输出

Spring Cloud Gateway 4.x 新特性

响应式 API 更完善：ServerWebExchange + Reactor 性能 +30%
GraphQL 路由：内置 GraphQL endpoint
WebSocket 增强：原生支持 WebSocket 路由
gRPC 集成：spring-cloud-starter-gateway + grpc-gateway 双向

Spring Cloud Stream 4.x + Kafka 3.x

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


spring:
 cloud:
 stream:
 bindings:
 output:
 destination: orders
 content-type: application/json
 kafka:
 binder:
 brokers: kafka:9092
 configuration:
 compression.type: zstd  # 2024+ 默认压缩
 linger.ms: 20

2024+ 选型：Spring Cloud vs Istio

场景	Spring Cloud	Istio / 服务网格
传统 Java 微服务	✅ 首选	重
多语言（Go / Python / Node）	一般	✅ 首选
流量管理复杂	一般	✅ 蓝绿/金丝雀/镜像
学习成本	低	高
性能开销	低	中（Sidecar 5-10%）

2024+ 趋势：Spring Cloud + Istio 双层——Java 业务用 Spring Cloud 简化，跨语言/灰度发布用 Istio 解决。

国产化适配

Spring Cloud Alibaba 2023.0.x 适配 Spring Boot 3.4+
Nacos 2.3+ 支持国密算法（SM2/SM3/SM4）
Sentinel 1.8.8+ 流量规则支持 Prometheus metrics 导出
Seata 2.x TC Server 高可用增强（Raft 共识）

2024+ 实战坑

JDK 17 / 21 反射限制：--add-opens java.base/java.lang=ALL-UNNAMED 等参数要加到启动脚本
Spring Boot 3.x Jakarta EE 9+：javax.* → jakarta.* 全量替换
Spring Cloud 2024.0.x 强制 Netty 4.1.x——有自定义 Netty handler 的项目要注意 API 变更
Spring AI 还在快速迭代——生产用建议锁定 1.0 GA 版本，别追 1.1-SNAPSHOT

2024+ 推荐组合

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


Java 后端服务（ToB、传统企业）
├── JDK 17 / 21
├── Spring Boot 3.4 / 3.5
├── Spring Cloud 2024.0.x / 2025.0.x
├── Spring Cloud Alibaba 2023.0.x
│ ├── Nacos 2.3+ (注册 + 配置)
│ ├── Sentinel 1.8.8+ (熔断限流)
│ ├── Seata 2.x (分布式事务)
│ └── RocketMQ 5.x (消息)
├── Spring Cloud Gateway 4.x (网关)
├── OpenFeign 4.x (RPC)
├── Resilience4j 2.x (熔断，替代 Hystrix)
├── Micrometer + Prometheus + Grafana (监控)
├── OpenTelemetry (Tracing)
└── Spring AI 1.0 (AI 能力，可选)

字段	`extensions/v1beta1`（已弃用）	`networking.k8s.io/v1`（本文用）
apiVersion	`extensions/v1beta1`	`networking.k8s.io/v1`
路径匹配	`path: /foo`（隐式 Prefix）	`path: /foo` + `pathType: Prefix \| Exact \| ImplementationSpecific`（必填）
后端	`backend.serviceName` + `servicePort`	`backend.service.name` + `backend.service.port.number/name`
Ingress 类	注解 `kubernetes.io/ingress.class: nginx`	`spec.ingressClassName: nginx`