SpringBoot 3.x 优雅停机与 AWS ECS Service Connect 协同实战

server:
  # 启用优雅停机。可选值：graceful（优雅停机），immediate（立即强杀，默认值）
  shutdown: graceful

spring:
  lifecycle:
    # 每个 SmartLifecycle 关闭阶段的最大等待宽限时间，默认 30s
    # 超过此时间仍有未处理完的请求，将被强制打断
    timeout-per-shutdown-phase: 30s

  task:
    execution:
      shutdown:
        # 等待 @Async 异步线程池任务完成
        await-termination: true
        await-termination-period: 30s
    scheduling:
      shutdown:
        # 等待 @Scheduled 定时任务执行完毕
        await-termination: true
        await-termination-period: 30s

management:
  endpoint:
    health:
      # 开启存活态与就绪态探针 (/actuator/health/liveness 和 /actuator/health/readiness)
      probes:
        enabled: true
  endpoints:
    web:
      exposure:
        include: health,info,metrics

#!/bin/sh
set -e

# 1. 后台启动 Spring Boot 应用，记录其进程 PID
java -XX:+UseContainerSupport \
     -XX:MaxRAMPercentage=75.0 \
     -jar /app/application.jar &
JAVA_PID=$!

# 2. 定义 SIGTERM 信号拦截处理函数
term_handler() {
  echo "[$(date +'%Y-%m-%dT%H:%M:%S%z')] [INFO] Received SIGTERM from ECS."
  
  # 缓冲时间：给 AWS Cloud Map 注销与客户端 Envoy 更新 SDS 留出足够时间
  BUFFER_SECONDS=15
  echo "[$(date +'%Y-%m-%dT%H:%M:%S%z')] [INFO] Sleeping ${BUFFER_SECONDS}s for Service Connect draining..."
  sleep $BUFFER_SECONDS
  
  echo "[$(date +'%Y-%m-%dT%H:%M:%S%z')] [INFO] Forwarding SIGTERM to Spring Boot (PID: ${JAVA_PID})..."
  kill -TERM "$JAVA_PID"
  
  # 等待 Java 进程优雅退出
  wait "$JAVA_PID"
  EXIT_STATUS=$?
  echo "[$(date +'%Y-%m-%dT%H:%M:%S%z')] [INFO] Application exited cleanly with status ${EXIT_STATUS}."
  exit $EXIT_STATUS
}

# 注册信号陷阱 (Trap)
trap 'term_handler' TERM INT

# 3. 前台阻塞等待 Java 进程，直到收到信号或自然退出
wait "$JAVA_PID"

FROM eclipse-temurin:21-jre-alpine

WORKDIR /app

# 安装 curl 用于健康检查
RUN apk add --no-cache curl

COPY target/*.jar application.jar
COPY entrypoint.sh entrypoint.sh

RUN chmod +x entrypoint.sh

# 务必以 entrypoint 脚本执行
ENTRYPOINT ["./entrypoint.sh"]

package com.example.config;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.availability.AvailabilityChangeEvent;
import org.springframework.boot.availability.ReadinessState;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.context.SmartLifecycle;
import org.springframework.stereotype.Component;

import java.util.concurrent.TimeUnit;

/**
 * Service Connect 优雅停机缓冲生命周期组件
 */
@Component
public class ServiceConnectGracefulShutdownHook implements SmartLifecycle {

    private static final Logger log = LoggerFactory.getLogger(ServiceConnectGracefulShutdownHook.class);
    
    // 缓冲时间 (秒)
    private static final int DRAIN_BUFFER_SECONDS = 15;
    
    private final ApplicationEventPublisher eventPublisher;
    private volatile boolean running = false;

    public ServiceConnectGracefulShutdownHook(ApplicationEventPublisher eventPublisher) {
        this.eventPublisher = eventPublisher;
    }

    @Override
    public void start() {
        this.running = true;
    }

    @Override
    public void stop() {
        // 同步停机逻辑
    }

    @Override
    public void stop(Runnable callback) {
        new Thread(() -> {
            try {
                log.info("Shutdown initiated. Marking readiness probe as REFUSING_TRAFFIC...");
                // 1. 将 Spring Boot Actuator 就绪状态置为拒绝流量 (HTTP 503)
                AvailabilityChangeEvent.publish(this.eventPublisher, this, ReadinessState.REFUSING_TRAFFIC);

                // 2. 阻塞休眠，等待 Service Connect/Cloud Map 完成端点注销广播
                log.info("Waiting {} seconds for Service Connect Envoy SDS propagation...", DRAIN_BUFFER_SECONDS);
                TimeUnit.SECONDS.sleep(DRAIN_BUFFER_SECONDS);
                log.info("Drain buffer completed. Proceeding to stop WebServer...");
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                log.warn("Drain sleep interrupted", e);
            } finally {
                this.running = false;
                callback.run(); // 触发下一个 Phase (即 WebServer 停机)
            }
        }, "service-connect-drain-thread").start();
    }

    @Override
    public boolean isRunning() {
        return this.running;
    }

    /**
     * WebServer 的 phase 是 Integer.MAX_VALUE - 2048
     * 设置一个比 WebServer 更大的 Phase 值，确保它在 WebServer 关闭前优先执行 stop()
     */
    @Override
    public int getPhase() {
        return Integer.MAX_VALUE;
    }
}

{
  "family": "order-service",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "1024",
  "memory": "2048",
  "containerDefinitions": [
    {
      "name": "order-service-app",
      "image": "123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/order-service:v1.0.0",
      "essential": true,
      "stopTimeout": 60,
      "portMappings": [
        {
          "name": "http-api",
          "containerPort": 8080,
          "hostPort": 8080,
          "protocol": "tcp"
        }
      ],
      "healthCheck": {
        "command": [
          "CMD-SHELL",
          "curl -f http://localhost:8080/actuator/health/readiness || exit 1"
        ],
        "interval": 10,
        "timeout": 5,
        "retries": 2,
        "startPeriod": 30
      }
    }
  ]
}

resource "aws_ecs_service" "order_service" {
  name            = "order-service"
  cluster         = aws_ecs_cluster.main.id
  task_definition = aws_ecs_task_definition.order_service.arn
  desired_count   = 3
  launch_type     = "FARGATE"

  # 滚动部署策略：保证发布时始终有额外健康实例
  deployment_minimum_healthy_percent = 100
  deployment_maximum_percent         = 200

  service_connect_configuration {
    enabled   = true
    namespace = aws_service_discovery_private_dns_namespace.corp.arn

    service {
      port_name      = "http-api"
      discovery_name = "order-service"
      client_alias {
        port = 8080
      }
      timeout {
        idle_timeout_seconds        = 60
        per_request_timeout_seconds = 30
      }
    }
  }

  network_configuration {
    subnets         = ["subnet-abc12345", "subnet-def67890"]
    security_groups = [aws_security_group.app_sg.id]
  }
}

                ┌────────────────────────────────────────────────────────┐
                │             100% 业务零中断 (Zero-Downtime)              │
                └───────────────────────────┬────────────────────────────┘
                                            │
                    ┌───────────────────────┴────────────────────────┐
                    ▼                                                ▼
       【服务端：吸收 99.9% 流量】                       【客户端：兜底剩余 0.1%】
    1. Pre-stop Buffer 15s (路由收敛)             1. 捕获 503 / ECONNRESET 瞬断
    2. Spring Boot Graceful (在途排空)             2. 幂等 GET/查询请求无感重试 1~2 次
    3. stopTimeout 60s (防强杀)                   3. 指数退避 100ms 重试到集群其他存活节点

package com.example.client;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpRequestInterceptor;
import org.springframework.http.client.ClientHttpResponse;
import org.springframework.web.client.RestClient;

import java.io.IOException;

@Configuration
public class RestClientConfig {

    @Bean
    public RestClient orderServiceRestClient() {
        return RestClient.builder()
                .baseUrl("http://order-service:8080")
                .requestInterceptor(retryInterceptor())
                .build();
    }

    private ClientHttpRequestInterceptor retryInterceptor() {
        return (request, body, execution) -> {
            int maxAttempts = 3;
            int attempt = 0;
            while (true) {
                attempt++;
                try {
                    ClientHttpResponse response = execution.execute(request, body);
                    // 如果遇到 503 (下游服务处于停机排空状态) 且属于幂等 GET 请求，进行重试
                    if (response.getStatusCode().value() == 503 && "GET".equalsIgnoreCase(request.getMethod().name())) {
                        if (attempt >= maxAttempts) {
                            return response;
                        }
                        Thread.sleep(100L * attempt); // 简易指数退避
                        continue;
                    }
                    return response;
                } catch (IOException ex) {
                    // 遇到底层连接被断开 (Connection reset) 时尝试重试
                    if (attempt >= maxAttempts) {
                        throw ex;
                    }
                    try {
                        Thread.sleep(100L * attempt);
                    } catch (InterruptedException ie) {
                        Thread.currentThread().interrupt();
                        throw ex;
                    }
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    throw new IOException("Request retry interrupted", e);
                }
            }
        };
    }
}

trap 'term_handler' TERM INT  # 同时捕获 SIGTERM 和 SIGINT

docker run -it --rm -p 8080:8080 my-spring-app:latest