SpringAI SSE流式API安全加固：API Key鉴权与生产级实现

1. 项目概述：为什么SSE MCP Server需要API Key鉴权

最近在折腾SpringAI的SSE流式输出，结合MCP Server搞了个智能体应用。东西跑起来挺酷，但一上线就发现个要命的问题：我的API端点谁都能调，这不成公共厕所了吗？尤其是当你的服务里集成了像OpenAI、Anthropic这类按token计费的模型时，一个没有鉴权的端点，分分钟就能让你的账单爆炸，或者被恶意调用导致服务不可用。这可不是危言耸听，我亲眼见过有开发兄弟测试环境没关公网访问，一晚上被刷了几百刀。

所以，今天我们就来聊聊怎么给这个“SpringAI SSE MCP Server”上个锁，实现一套靠谱的API Key鉴权。这不仅仅是加个 Authorization 头那么简单，它涉及到流式场景下的连接管理、密钥的安全存储与验证、以及如何与Spring Security或者更轻量的方案优雅集成。很多教程只讲怎么用 SseEmitter 发数据，但到了生产环境，安全这一关不过，前面所有花里胡哨的功能都是空中楼阁。

简单说，我们要做的是： 在保持Server-Sent Events长连接、低延迟、实时推送特性的前提下，确保每一个连接请求都是经过授权的合法请求。 这适合所有正在或计划将SpringAI用于生产级流式对话、实时数据推送，并且后端集成了MCP Server（Model Context Protocol）来管理工具调用的开发者。无论你是做AI客服、实时报表、还是智能编程助手，这套加固方案都能让你的服务更健壮。

2. 核心方案选型与设计思路拆解

给SSE端点加鉴权，听起来简单，做起来坑不少。首要问题是： 鉴权发生在一个HTTP请求的哪个环节？ 对于普通的REST API，我们通常在过滤器（Filter）或拦截器（Interceptor）里校验Token，无效就直接返回401。但SSE连接一旦建立，就是一个持久化的HTTP连接，数据是服务器单向、持续推送的。你不能在连接建立后，每发一条消息都去验一次权（虽然技术上可以，但极度不优雅且开销大）。

因此，最合理的设计是： 在连接建立之初（即客户端发起SSE连接请求时）完成鉴权。 鉴权通过，才创建 SseEmitter 对象并加入连接池；鉴权失败，则立即关闭连接并返回错误。这样，后续的数据流推送就建立在安全的连接之上。

接下来是鉴权方式的选择。常见的有：

1. HTTP Basic Auth ：简单，但不够安全，密钥在每次请求头中明文传输（除非全程HTTPS），且不易于轮换和管理。
2. JWT (JSON Web Token) ：无状态，适合分布式，但需要维护令牌的签发与验证逻辑，对于内部服务或简单的API网关场景可能稍重。
3. 自定义API Key ：最简单直接，也是很多AI服务商（如OpenAI）采用的方式。一个密钥对应一个客户端或一个租户，易于理解和实现。

对于SpringAI SSE MCP Server这种场景，我倾向于选择 自定义API Key 。原因如下：

• 心智负担轻 ：客户端调用方式与调用OpenAI API完全一致，在 Authorization 头里加个 Bearer {api_key} 即可，开发者无需学习新协议。
• 管理简单 ：服务端维护一个API Key的白名单或数据库表即可，可以轻松绑定额度、调用次数、过期时间等元信息。
• 与MCP Server集成顺畅 ：MCP Server本身可能已经有一套工具调用链，API Key鉴权可以作为最外层、最通用的安全防护，不影响内部业务逻辑。

那么，这个API Key从哪里来，存到哪里？我的设计思路是：

• 生成 ：由服务管理员在后台生成，可以是一串高强度的随机字符串（如UUID），也可以是有特定格式的字符串。
• 存储 ：绝不能硬编码在代码或配置文件中。对于生产环境，应该存储在环境变量、配置中心（如Nacos、Apollo）或者数据库中。这里我推荐结合环境变量和数据库：将主密钥或加密密钥放在环境变量中，将生成的API Key（加密后）和其元信息（如所属项目、状态、过期时间、调用次数）存在数据库里。
• 验证 ：实现一个 HandlerInterceptor 或 Filter ，在请求进入SSE控制器之前，截取 Authorization 头，解析出API Key，然后去查数据库（或缓存）验证其有效性和权限。

3. 核心组件与依赖准备

在动手写代码之前，我们需要把轮子准备好。这个项目基于Spring Boot和SpringAI，所以核心依赖是明了的。

首先，确保你的 pom.xml 或 build.gradle 包含了SpringAI的依赖。这里以Maven为例，你需要类似下面的配置。注意，SpringAI的版本迭代较快，建议使用当前稳定版。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>0.8.1</version> <!-- 请替换为最新版本 -->
</dependency>
<!-- 如果你使用其他模型，如Azure OpenAI、Ollama等，需引入对应starter -->

为了构建SSE端点，我们需要Spring MVC的Web支持：

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

对于API Key的存储与验证，我们大概率需要操作数据库。这里选择常用的Spring Data JPA和H2内存数据库（用于演示，生产环境请换用MySQL/PostgreSQL）。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

最后，为了代码的健壮性，可以引入Lombok减少样板代码，以及Spring Boot Configuration Processor以便在 application.yml 中有更好的提示。

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

注意 ：依赖版本兼容性是个大坑。特别是SpringAI，它可能对Spring Boot的版本有特定要求。在开始前，最好去 SpringAI官方文档 查看当前版本的兼容性矩阵，避免启动时报各种奇怪的 ClassNotFoundException 。

4. 数据库设计与API Key管理

鉴权的核心在于对API Key的有效管理。我们不能简单地把密钥扔到一个 List<String> 里就完事。一个生产可用的设计至少需要记录：密钥本身、所属用户或应用、状态（启用/禁用）、创建时间、最后使用时间、调用次数限额、已用次数等。

我设计了一个简单的 ApiKey 实体，它将是我们在数据库中存储密钥信息的蓝图。

import jakarta.persistence.*;
import lombok.Data;
import java.time.LocalDateTime;

@Entity
@Table(name = "api_keys", indexes = {@Index(columnList = "keyHash")}) // 对哈希值建索引，加速查询
@Data
public class ApiKey {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String name; // 密钥名称，如“移动端App-Prod”

    @Column(nullable = false, length = 500)
    private String keyHash; // 存储API Key的哈希值，而非明文

    @Column(nullable = false)
    private String salt; // 用于哈希的盐值

    @Column(nullable = false)
    private Boolean enabled = true; // 是否启用

    @Column
    private LocalDateTime expiresAt; // 过期时间，null表示永不过期

    @Column(nullable = false)
    private Long totalQuota = 1000L; // 总调用配额

    @Column(nullable = false)
    private Long usedQuota = 0L; // 已使用配额

    @Column(nullable = false)
    private LocalDateTime createdAt;

    @Column
    private LocalDateTime lastUsedAt;

    @PrePersist
    protected void onCreate() {
        createdAt = LocalDateTime.now();
    }
}

为什么存储哈希值而不是明文？ 这是安全的基本要求。即使数据库被拖库，攻击者拿到的也只是密钥的哈希值，无法直接用于API调用。验证时，我们用同样的盐值和哈希算法（如BCrypt）对客户端传来的密钥进行计算，然后对比数据库中的哈希值。

接下来，我们需要一个服务来管理这些API Key的生命周期：生成、存储、验证、更新、作废。我创建了一个 ApiKeyService 。

import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.util.Optional;

@Service
@Slf4j
public class ApiKeyService {
    private final ApiKeyRepository apiKeyRepository;
    private final BCryptPasswordEncoder passwordEncoder = new BCryptPasswordEncoder();
    private final SecureRandom secureRandom = new SecureRandom();

    public ApiKeyService(ApiKeyRepository apiKeyRepository) {
        this.apiKeyRepository = apiKeyRepository;
    }

    /**
     * 生成一个新的API Key。
     * @param name 密钥名称
     * @param expiresInDays 有效期天数，null为永久
     * @param totalQuota 总调用配额
     * @return 明文API Key（仅在此刻返回一次，务必保存好）
     */
    @Transactional
    public String generateApiKey(String name, Integer expiresInDays, Long totalQuota) {
        // 1. 生成随机明文密钥（例如，使用Base64编码的32字节随机数）
        byte[] randomKeyBytes = new byte[32];
        secureRandom.nextBytes(randomKeyBytes);
        String plainApiKey = Base64.getUrlEncoder().withoutPadding().encodeToString(randomKeyBytes); // 类似`sk-abc123`

        // 2. 生成盐值并计算哈希
        String salt = BCrypt.gensalt();
        // 注意：BCrypt通常用于密码，这里我们用它哈希“盐+密钥”，增加复杂度
        String keyHash = passwordEncoder.encode(salt + plainApiKey);

        // 3. 创建实体并保存
        ApiKey apiKey = new ApiKey();
        apiKey.setName(name);
        apiKey.setKeyHash(keyHash);
        apiKey.setSalt(salt);
        apiKey.setEnabled(true);
        apiKey.setTotalQuota(totalQuota);
        apiKey.setUsedQuota(0L);
        if (expiresInDays != null) {
            apiKey.setExpiresAt(LocalDateTime.now().plusDays(expiresInDays));
        }
        apiKeyRepository.save(apiKey);

        log.info("API Key '{}' 已生成。明文密钥：{}", name, plainApiKey);
        // 重要：在真实场景中，这个明文密钥应该通过安全渠道（如站内信、密钥管理平台）返回给用户。
        // 服务端不应持久化明文，这里打印日志仅为演示，生产环境必须移除。
        return plainApiKey;
    }

    /**
     * 验证API Key是否有效，并更新使用记录。
     * @param plainApiKey 客户端传来的明文API Key
     * @return 验证通过返回ApiKey实体，否则返回Optional.empty()
     */
    @Transactional
    public Optional<ApiKey> validateAndUpdateUsage(String plainApiKey) {
        // 优化点：由于我们存储的是哈希，无法直接查询。一种方案是额外存储一个“密钥标识”（如密钥前8位）用于快速查找。
        // 这里为了简化，我们遍历所有启用的密钥进行验证（数据量不大时可行，量大时需优化）。
        List<ApiKey> enabledKeys = apiKeyRepository.findByEnabledTrue();
        for (ApiKey apiKey : enabledKeys) {
            // 使用存储的盐值和传入的明文密钥，重新计算哈希进行比对
            String computedHash = passwordEncoder.encode(apiKey.getSalt() + plainApiKey);
            if (passwordEncoder.matches(apiKey.getSalt() + plainApiKey, apiKey.getKeyHash())) {
                // 验证通过，检查是否过期、是否超配额
                if (apiKey.getExpiresAt() != null && LocalDateTime.now().isAfter(apiKey.getExpiresAt())) {
                    log.warn("API Key '{}' 已过期。", apiKey.getName());
                    apiKey.setEnabled(false); // 自动禁用过期密钥
                    apiKeyRepository.save(apiKey);
                    return Optional.empty();
                }
                if (apiKey.getUsedQuota() >= apiKey.getTotalQuota()) {
                    log.warn("API Key '{}' 调用配额已用尽。", apiKey.getName());
                    return Optional.empty();
                }
                // 更新使用记录
                apiKey.setUsedQuota(apiKey.getUsedQuota() + 1);
                apiKey.setLastUsedAt(LocalDateTime.now());
                apiKeyRepository.save(apiKey);
                return Optional.of(apiKey);
            }
        }
        return Optional.empty();
    }
}

对应的 ApiKeyRepository 很简单：

import org.springframework.data.jpa.repository.JpaRepository;
import java.util.List;

public interface ApiKeyRepository extends JpaRepository<ApiKey, Long> {
    List<ApiKey> findByEnabledTrue();
}

实操心得 ：上面 validateAndUpdateUsage 方法中的遍历验证在生产环境中是性能瓶颈。一个优化方案是：在生成API Key时，同时生成一个短的、唯一的“Key ID”（如 sk_abc123 的前缀），客户端在请求时同时提供 Key ID 和完整的 API Key 。服务端先用 Key ID 快速从数据库或缓存中查出对应的 ApiKey 实体（包含盐值和哈希），再进行哈希验证。这样就将O(n)的查询优化成了O(1)。

5. 实现API Key鉴权拦截器

有了密钥管理服务，接下来就要在请求到达SSE控制器前把它拦住验明正身。Spring MVC提供了 HandlerInterceptor 接口，非常适合做这件事。我们创建一个 ApiKeyAuthInterceptor 。

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

@Component
@Slf4j
public class ApiKeyAuthInterceptor implements HandlerInterceptor {

    private final ApiKeyService apiKeyService;
    // 可以配置哪些路径需要拦截，这里我们拦截所有以 /sse/ 开头的路径
    private static final String SSE_PATH_PREFIX = "/sse/";

    public ApiKeyAuthInterceptor(ApiKeyService apiKeyService) {
        this.apiKeyService = apiKeyService;
    }

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String requestURI = request.getRequestURI();

        // 只拦截SSE相关的端点
        if (!requestURI.startsWith(SSE_PATH_PREFIX)) {
            return true;
        }

        // 1. 从Authorization头提取Bearer Token
        String authHeader = request.getHeader("Authorization");
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            log.warn("SSE连接请求未提供Authorization头或格式错误。URI: {}", requestURI);
            sendErrorResponse(response, HttpStatus.UNAUTHORIZED, "Missing or invalid Authorization header. Format: Bearer {api_key}");
            return false;
        }

        String apiKey = authHeader.substring(7).trim(); // 去掉"Bearer "前缀
        if (apiKey.isEmpty()) {
            log.warn("SSE连接请求的API Key为空。URI: {}", requestURI);
            sendErrorResponse(response, HttpStatus.UNAUTHORIZED, "API Key cannot be empty");
            return false;
        }

        // 2. 验证API Key
        Optional<ApiKey> validApiKeyOpt = apiKeyService.validateAndUpdateUsage(apiKey);
        if (validApiKeyOpt.isEmpty()) {
            log.warn("API Key验证失败。URI: {}", requestURI);
            sendErrorResponse(response, HttpStatus.UNAUTHORIZED, "Invalid or expired API Key");
            return false;
        }

        // 3. 验证通过，可以将ApiKey信息存入请求属性，供后续控制器使用
        ApiKey validApiKey = validApiKeyOpt.get();
        request.setAttribute("apiKeyId", validApiKey.getId());
        request.setAttribute("apiKeyName", validApiKey.getName());
        log.debug("API Key '{}' 验证通过，建立SSE连接。", validApiKey.getName());
        return true;
    }

    private void sendErrorResponse(HttpServletResponse response, HttpStatus status, String message) throws IOException {
        response.setStatus(status.value());
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setCharacterEncoding(StandardCharsets.UTF_8.name());
        Map<String, String> errorBody = Map.of("error", message);
        response.getWriter().write(new ObjectMapper().writeValueAsString(errorBody));
    }
}

拦截器写好了，还需要把它注册到Spring MVC的拦截器链中。创建一个配置类 WebMvcConfig ：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    private final ApiKeyAuthInterceptor apiKeyAuthInterceptor;

    public WebMvcConfig(ApiKeyAuthInterceptor apiKeyAuthInterceptor) {
        this.apiKeyAuthInterceptor = apiKeyAuthInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // 拦截所有路径，在拦截器内部再做细粒度路径判断
        registry.addInterceptor(apiKeyAuthInterceptor)
                .addPathPatterns("/**");
    }
}

注意事项 ：这里我选择拦截所有路径（ /** ），然后在拦截器内部通过 requestURI 判断是否SSE路径。这样做的好处是配置简单，且未来如果新增其他需要鉴权的端点，只需修改拦截器内部的判断逻辑即可。你也可以在 addPathPatterns 里更精确地指定路径，如 /api/v1/sse/** 。

6. 构建安全的SSE流式端点

安全的大门已经装好，现在可以放心地构建我们的核心业务——SSE流式端点了。这里我们将创建一个控制器，它接收用户的问题，通过SpringAI调用大模型（比如OpenAI），并以SSE流的形式返回模型的思考过程或最终答案。同时，我们会集成MCP Server的概念，假设模型在回答过程中可以调用一些外部工具。

首先，创建一个简单的请求体 ChatRequest ：

@Data
public class ChatRequest {
    @NotBlank
    private String message;
    private Map<String, Object> options; // 可传递一些额外参数，如temperature
}

然后，是核心的SSE控制器 SseChatController ：

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
import java.io.IOException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

@RestController
@RequestMapping("/sse")
@Slf4j
public class SseChatController {

    private final ChatClient chatClient;
    // 用于管理SSE连接的线程池，避免阻塞Web容器的线程
    private final ExecutorService sseExecutor = Executors.newCachedThreadPool();

    public SseChatController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @PostMapping(value = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public SseEmitter streamChat(@RequestBody ChatRequest chatRequest,
                                 HttpServletRequest request) {
        // 从请求属性中获取通过鉴权的API Key信息（可选，可用于更细粒度的审计或限流）
        String apiKeyName = (String) request.getAttribute("apiKeyName");
        log.info("API Key '{}' 发起流式聊天请求。", apiKeyName);

        // 设置SSE连接超时时间，例如30分钟
        SseEmitter emitter = new SseEmitter(30 * 60 * 1000L);
        // 设置连接完成和超时的回调
        emitter.onCompletion(() -> log.debug("SSE连接完成。API Key: {}", apiKeyName));
        emitter.onTimeout(() -> {
            log.warn("SSE连接超时。API Key: {}", apiKeyName);
            emitter.complete();
        });

        // 提交任务到线程池，异步处理流式响应
        sseExecutor.submit(() -> {
            try {
                // 使用SpringAI的ChatClient进行流式调用
                // 这里假设ChatClient已经配置好了模型（如OpenAI GPT-4）和必要的工具（MCP Server）
                chatClient.prompt()
                        .user(chatRequest.getMessage())
                        .options(chatRequest.getOptions()) // 传递额外参数
                        .stream()
                        .contentStream() // 获取内容流
                        .forEach(chunk -> {
                            try {
                                // 将每个流式块通过SSE发送给客户端
                                // 数据格式可以自定义，这里简单发送文本内容
                                SseEmitter.SseEventBuilder event = SseEmitter.event()
                                        .data(chunk.getContent()) // 发送文本内容
                                        .id(String.valueOf(System.currentTimeMillis())) // 可选：事件ID
                                        .name("message"); // 可选：事件名称
                                emitter.send(event);
                            } catch (IOException e) {
                                log.error("向客户端发送SSE数据失败。API Key: {}", apiKeyName, e);
                                emitter.completeWithError(e);
                            }
                        });
                // 流式输出结束，发送一个完成事件或直接关闭连接
                emitter.send(SseEmitter.event().name("end").data("[DONE]"));
                emitter.complete();
            } catch (Exception e) {
                log.error("处理流式聊天请求时发生异常。API Key: {}", apiKeyName, e);
                emitter.completeWithError(e);
            }
        });

        return emitter;
    }
}

关键点解析：

1. produces = MediaType.TEXT_EVENT_STREAM_VALUE ：这个注解告诉Spring，这个端点返回的是 text/event-stream 类型的数据，这是SSE协议的标准MIME类型。
2. SseEmitter ：Spring提供的用于处理SSE的类。我们设置了30分钟的超时，对于长对话场景是合理的。
3. 异步处理 ：我们将耗时的AI模型调用放在一个独立的线程池（ sseExecutor ）中执行。这是 至关重要 的一步，因为模型推理可能很慢，如果放在Web容器的请求线程（如Tomcat的worker线程）中执行，会迅速耗尽线程池，导致服务无法处理其他请求。
4. 流式迭代 ： chatClient.prompt().stream().contentStream().forEach(...) 是SpringAI提供的流式调用方式。每产生一个“块”（chunk），我们就通过 emitter.send() 将其推送给客户端。
5. 事件格式 ：我们发送了 data （内容）、 id （事件ID）、 name （事件名称）。客户端可以根据 name 来区分不同类型的事件（如“message”是内容，“tool_call”是工具调用，“end”是结束）。

实操心得 ： SseEmitter 的内存管理需要留意。每个连接都会持有一个 SseEmitter 对象，如果客户端异常断开（比如关闭浏览器标签），服务端可能不会立即感知。虽然设置了 onCompletion 和 onTimeout 回调，但在高并发下，仍有内存泄漏风险。一个常见的做法是维护一个全局的 SseEmitter 管理器，定期清理超时或无效的连接。这里为了简化没有实现，生产环境建议加上。

7. 客户端调用示例与连接管理

服务端准备好了，客户端怎么调用呢？这里给出一个使用JavaScript（浏览器环境）和Python的简单示例。

JavaScript (使用EventSource API):

const apiKey = 'sk-your-generated-api-key-here'; // 替换成你生成的API Key
const message = '你好，请介绍一下SpringAI。';

const eventSource = new EventSource(`/sse/chat?message=${encodeURIComponent(message)}`, {
    headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json' // EventSource 默认是 GET，不支持请求体，这里需要变通
    }
});

// 注意：EventSource 原生不支持 POST 和请求体。上述方式行不通。
// 正确做法：使用 Fetch API 来模拟 SSE
function streamChatWithFetch() {
    const url = '/sse/chat';
    const payload = { message: message };

    fetch(url, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json',
            'Accept': 'text/event-stream' // 重要：告诉服务器我们期望SSE流
        },
        body: JSON.stringify(payload)
    }).then(response => {
        if (!response.ok || !response.body) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const reader = response.body.getReader();
        const decoder = new TextDecoder();

        function readStream() {
            reader.read().then(({ done, value }) => {
                if (done) {
                    console.log('Stream finished.');
                    return;
                }
                const chunk = decoder.decode(value, { stream: true });
                // 处理接收到的SSE数据块
                // SSE数据格式是 "data: some text\n\n"，需要解析
                const lines = chunk.split('\n');
                for (const line of lines) {
                    if (line.startsWith('data: ')) {
                        const data = line.substring(6); // 去掉 "data: " 前缀
                        if (data.trim() === '[DONE]') {
                            console.log('Received end signal.');
                        } else {
                            console.log('Received data:', data);
                            // 在这里更新UI，例如将数据追加到聊天框
                            document.getElementById('output').innerText += data;
                        }
                    }
                }
                readStream(); // 继续读取下一个块
            }).catch(error => {
                console.error('Error reading stream:', error);
            });
        }

        readStream();
    }).catch(error => {
        console.error('Fetch error:', error);
    });
}

// 调用函数
streamChatWithFetch();

Python (使用requests库):

import requests
import json

api_key = "sk-your-generated-api-key-here"
url = "http://your-server.com/sse/chat"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
    "Accept": "text/event-stream"
}
payload = {
    "message": "你好，请介绍一下SpringAI。"
}

response = requests.post(url, headers=headers, json=payload, stream=True)
response.raise_for_status()

for line in response.iter_lines():
    if line:
        decoded_line = line.decode('utf-8')
        if decoded_line.startswith('data: '):
            data = decoded_line[6:]  # 去掉 'data: ' 前缀
            if data.strip() == '[DONE]':
                print("Stream finished.")
                break
            else:
                print(f"Received: {data}")
                # 处理数据，例如打印或保存

注意事项 ：浏览器原生的 EventSource API不支持设置自定义Header（如 Authorization ）和POST请求体，这是一个很大的限制。因此，对于需要鉴权的SSE， 必须使用 Fetch API 并手动处理流式响应 ，如上例所示。在服务器端，我们的拦截器正是通过检查 Authorization 头来工作的，所以 Fetch API 是唯一正确的打开方式。

8. 高级安全加固与生产级考量

基础的API Key鉴权实现了，但要想真正用于生产，还有几道关卡要过。

1. 密钥存储与加密的再加固 之前我们把哈希值存在数据库，这很好。但加密密钥（用于哈希的盐）和数据库密码本身也是敏感信息。绝对不要提交到代码仓库。

• 使用环境变量 ：将数据库连接字符串、加密盐的种子等，通过环境变量注入。在Spring Boot中，可以在 application.yml 中使用 ${DB_PASSWORD:default} 这样的占位符。
• 使用Secret管理服务 ：在Kubernetes中可以使用Secrets，在云平台（如AWS, GCP, Azure）可以使用其密钥管理服务（KMS/Secrets Manager）。
• 配置文件加密 ：对于本地配置文件，可以考虑使用Jasypt等库对敏感属性进行加密。

2. 限流与防刷 有了API Key，我们可以做更精细的限流。防止某个密钥被疯狂调用拖垮服务。

• Spring Boot整合Resilience4j或Sentinel ：可以为每个API Key或每个IP设置每秒/每分钟的请求速率限制。
• 自定义限流器 ：在 ApiKeyService 的 validateAndUpdateUsage 方法中，我们已经在更新使用次数。可以很容易地扩展，加入“每秒最大调用次数”的检查。可以将限流数据放在Redis这类高性能缓存中，实现分布式限流。

// 伪代码示例：基于Redis的简单限流
public boolean isRateLimited(String apiKeyId) {
    String redisKey = "rate_limit:" + apiKeyId;
    Long currentCount = redisTemplate.opsForValue().increment(redisKey, 1);
    if (currentCount == 1) {
        // 第一次设置，同时设置过期时间（如1秒）
        redisTemplate.expire(redisKey, 1, TimeUnit.SECONDS);
    }
    return currentCount != null && currentCount > 100; // 假设限制每秒100次
}

3. 连接数限制与心跳保活 一个客户端可能建立多个SSE连接。我们需要防止资源被耗尽。

• 全局连接数限制 ：在 SseChatController 中，可以维护一个 ConcurrentHashMap 来存储活跃的 SseEmitter ，并以API Key为维度进行计数。当某个Key的连接数超过阈值（比如10个）时，拒绝新的连接请求。
• 心跳机制 ：SSE连接可能因为网络问题僵死。服务器可以定期（比如每15秒）向客户端发送一个注释行（以 : 开头的行，如 :heartbeat ），这不会触发客户端的事件监听器，但能保持TCP连接活跃，并帮助检测连接是否已断开。

4. 审计日志 所有鉴权成功和失败的尝试，以及关键的API调用，都应该记录审计日志。这有助于安全分析和问题排查。日志应包含：时间戳、API Key ID（或名称）、客户端IP、请求路径、操作类型（连接建立、消息发送、连接关闭）、结果（成功/失败）等。可以使用Spring AOP或直接在拦截器和控制器中记录。

5. HTTPS是必须的 API Key在 Authorization 头里是明文传输的。如果走HTTP，中间人攻击可以轻易截获密钥。 生产环境必须启用HTTPS 。Spring Boot配置HTTPS很简单，申请一个SSL证书（可以从Let‘s Encrypt免费获取），然后在 application.yml 中配置即可。

9. 常见问题排查与调试技巧

在实际部署和联调中，你肯定会遇到各种问题。这里记录几个我踩过的坑和解决方法。

问题1：客户端收不到任何数据，连接很快关闭。

• 检查点1：鉴权是否通过？ 查看服务端日志，看 ApiKeyAuthInterceptor 是否打印了验证失败的警告。用curl或Postman模拟请求，仔细检查 Authorization 头的格式是否正确（Bearer后面有空格，密钥无误）。

  curl -X POST -H "Authorization: Bearer sk-test123" -H "Content-Type: application/json" -H "Accept: text/event-stream" -d '{"message":"hello"}' http://localhost:8080/sse/chat -N
  

• 检查点2：SSE响应头是否正确？ 服务器必须返回 Content-Type: text/event-stream ，并且 不能有 Transfer-Encoding: chunked 之外的任何压缩或缓存头 。有些网关或过滤器可能会修改响应头。确保你的Spring Security配置或其他全局过滤器没有干扰SSE端点。
• 检查点3：客户端是否正确解析？ 使用浏览器的开发者工具“网络”标签，查看SSE请求的响应。你应该能看到一系列以 data: 开头的文本行。如果看不到，说明服务器端没有成功流式输出。可以在控制器里加日志，看 chatClient.stream() 是否被正常执行。

问题2：流式输出不连贯，总是攒一段时间才发一大段。

• 原因 ：这通常是缓冲区（Buffering）造成的。Spring MVC或底层的Servlet容器可能对响应进行了缓冲。
• 解决 ：在控制器方法上添加 @ResponseBody （如果已有 @RestController 则不需要），并尝试在返回 SseEmitter 之前，手动刷新响应。

  // 在发送第一个事件前，尝试设置缓冲区大小（不一定所有容器都支持）
  response.setBufferSize(1024); // 设置一个较小的缓冲区
  

  更根本的解决方法是检查你的Web服务器（Tomcat/Undertow/Netty）配置，确保对SSE端点禁用了响应缓冲。

问题3：连接一段时间后自动断开。

• 原因 ：默认情况下， SseEmitter 的超时时间可能较短，或者客户端/服务器的网络设备（如Nginx、负载均衡器）有连接空闲超时设置。
• 解决 ：
  1. 如我们代码所示，创建 SseEmitter 时指定一个较长的超时（如30分钟）。
  2. 实现前面提到的心跳机制，定期发送注释行保持连接活跃。
  3. 配置你的反向代理（如Nginx）。在Nginx中，需要为SSE连接调整以下参数：

     location /sse/ {
         proxy_pass http://backend;
         proxy_set_header Connection '';
         proxy_http_version 1.1;
         proxy_buffering off; # 关键！关闭代理缓冲
         proxy_cache off; # 关闭缓存
         proxy_read_timeout 3600s; # 设置长的读取超时
         chunked_transfer_encoding off; # 对于SSE，通常需要关闭分块传输编码
     }
     

问题4：高并发下，服务器线程数飙升，内存占用高。

• 原因 ：每个SSE连接都会占用一个Servlet容器线程（如果使用Tomcat）。虽然我们用了线程池异步处理业务，但连接本身持有的线程在等待数据时是阻塞的。
• 解决 ：
  • 使用异步Servlet（已经做了） ：确保你的控制器返回的是 SseEmitter 、 ResponseBodyEmitter 或 DeferredResult ，这已经使用了Spring的异步处理能力。
  • 调整Web服务器线程池 ：增加Tomcat的 max-threads 数量，但这只是权宜之计。
  • 考虑使用响应式栈 ：对于极高并发的SSE场景，可以考虑迁移到Spring WebFlux（基于Netty），它是非阻塞的，可以轻松处理数万甚至更多的并发连接。但这意味着整个应用架构需要调整为响应式。

问题5：API Key验证性能慢，每次请求都查数据库。

• 优化 ：正如之前提到的，引入“Key ID”进行快速查找。此外，可以将有效的API Key信息（如id, name, 剩余配额）缓存在Redis中，设置一个合理的TTL（如5分钟）。验证时先查缓存，缓存未命中再查数据库并回写缓存。当管理员禁用或更新密钥时，需要主动清除或更新缓存。

把这些点都考虑到并处理好，你的SpringAI SSE MCP Server就有了一个坚实的安全和性能基础，可以放心地部署到生产环境，去支撑那些有趣的AI应用了。安全无小事，尤其是在AI能力开放时，多花点心思在加固上，能避免后续无数麻烦。