K8s集群SpringCloudZuul网关部署管理实操
技术栈：Spring Cloud Zuul v1.x + Kubernetes v1.32.13 + Rocky Linux 8.6 + Eureka/Nacos + Java 17
操作环境 / 对接原理 / 详细步骤 / 完整命令 / 配置文件 / 验证流程 / 排错方案
K8s集群SpringCloudZuul网关部署管理实操
操作环境
Zuul 网关服务（Spring Boot 2.7 + Spring Cloud 2021）
K8s 集群 v1.32.13，Rocky Linux 8.6
注册中心 Nacos 2.x 或 Eureka
后端微服务：user-service/order-service/product-service
JDK 17，Maven 3.9，镜像已推送到 Harbor
Zuul 部署在 default 命名空间，3副本
kubectl v1.32.13，应用日志输出到标准输出
对接原理
Zuul 是 Netflix 开源的 JVM 网关，Spring Cloud 集成提供声明式路由和过滤器机制，适合 Java 微服务体系。核心机制：过滤器（Filter）是 Zuul 的核心，分为 PRE（路由前，认证/限流/日志）、ROUTING（路由中，请求转发）、POST（路由后，响应修改/日志）、ERROR（错误处理）四种类型，通过 shouldFilter() 判断是否执行，run() 实现逻辑。路由配置：通过 zuul.routes 配置服务路由，支持 serviceId（服务发现自动路由）和 url（直接URL）两种方式，配合 Eureka/Nacos 实现服务发现和负载均衡（Ribbon）。Zuul 1.x 是阻塞式 IO（Servlet），Zuul 2.x 是异步非阻塞（Netty），Spring Cloud 主要集成 Zuul 1.x。熔断集成 Hystrix，降级方法在 fallback 中实现。K8s 部署：Zuul 无状态多副本，Service LoadBalancer 暴露，通过 ConfigMap 动态配置路由（@RefreshScope + Spring Cloud Config）。注意：Spring Cloud 已推荐使用 Spring Cloud Gateway（WebFlux 异步）替代 Zuul，但 Zuul 仍广泛用于存量系统。
详细步骤
1. Zuul网关部署到K8s
# 1. 创建Spring Boot Zuul项目 # pom.xml依赖 cat > pom.xml << 'EOF' <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-netflix-zuul</artifactId> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId> </dependency> EOF # 启动类 cat > ZuulApplication.java << 'EOF' @SpringBootApplication @EnableZuulProxy @EnableDiscoveryClient public class ZuulApplication { public static void main(String[] args) { SpringApplication.run(ZuulApplication.class, args); } } EOF # application.yml cat > application.yml << 'EOF' server: port: 8080 spring: application: name: zuul-gateway cloud: nacos: discovery: server-addr: nacos.default.svc:8848 zuul: routes: user: path: /user/** serviceId: user-service order: path: /order/** serviceId: order-service sensitive-headers: add-host-header: true ribbon: ReadTimeout: 5000 ConnectTimeout: 2000 hystrix: command: default: execution: isolation: thread: timeoutInMilliseconds: 10000 EOF # 构建镜像 mvn clean package -DskipTests docker build -t harbor.example.com/default/zuul-gateway:v1 . docker push harbor.example.com/default/zuul-gateway:v1 # K8s部署 cat > zuul-deploy.yaml << 'EOF' apiVersion: apps/v1 kind: Deployment metadata: name: zuul-gateway spec: replicas: 3 selector: matchLabels: app: zuul-gateway template: metadata: labels: app: zuul-gateway spec: containers: - name: zuul image: harbor.example.com/default/zuul-gateway:v1 ports: - containerPort: 8080 resources: requests: {cpu: 500m, memory: 1Gi} limits: {cpu: 2, memory: 2Gi} livenessProbe: httpGet: {path: /actuator/health, port: 8080} initialDelaySeconds: 60 readinessProbe: httpGet: {path: /actuator/health, port: 8080} --- apiVersion: v1 kind: Service metadata: name: zuul-gateway spec: type: LoadBalancer selector: app: zuul-gateway ports: - port: 80 targetPort: 8080 EOF kubectl apply -f zuul-deploy.yaml验证流程
# 1. 验证Zuul启动 kubectl get pods -l app=zuul-gateway # Running # 2. 验证健康检查 curl http://zuul-gateway/actuator/health # {"status":"UP"} # 3. 验证路由 curl http://zuul-gateway/user/api/users # 返回用户服务响应 # 4. 验证过滤器 # 无token返回401，有token返回200 # 5. 验证限流 for i in {1..110}; do curl -s -o /dev/null -w "%{http_code}\n" http://zuul/api; done | grep 429 # 6. 验证熔断 # 停止后端服务，访问返回降级响应 # 7. 验证灰度 curl -H "X-Canary: true" http://zuul/user/version # 返回v2排错方案
路由404：检查zuul.routes配置，path是否匹配，serviceId是否在注册中心，ignored-services是否排除了服务，stripPrefix配置，actuator/routes查看实际路由
500内部错误：查看Zuul日志，后端服务异常，过滤器run()抛出异常，ERROR过滤器是否处理，Hystrix超时，Ribbon连接失败
服务不可用（502）：检查后端服务是否注册到Nacos/Eureka，服务实例是否健康，Ribbon是否获取到服务列表，网络是否连通，端口是否正确
超时：调整ribbon.ReadTimeout/ConnectTimeout，hystrix.timeoutInMilliseconds，后端响应慢需优化，Zuul线程池大小，增加副本
过滤器不执行：检查filterType是否正确，shouldFilter()返回true，filterOrder顺序，@Component是否被Spring扫描，是否有异常被吞掉
熔断不恢复：检查circuitBreaker.sleepWindowInMilliseconds，后端是否恢复健康，错误率是否降到阈值以下，Hystrix dashboard查看状态
动态配置不刷新：检查@RefreshScope，Nacos Config是否配置，bootstrap.yml优先级，发布配置是否成功，actuator/refresh手动刷新
性能瓶颈：Zuul 1.x阻塞IO，增加副本数，调大tomcat max-threads，JVM堆内存，异步处理非核心逻辑，考虑迁移到Spring Cloud Gateway
