企业官网建设流程全解析

1. 项目概述：这不是“第九掌”，而是Spring AI在阿里云生态落地的实战切口

“降SpringAI阿里第9掌-或跃在渊-ReactAgent”——这个标题乍看像武侠小说里的秘籍名，但拆开来看，它其实是一条非常精准的技术路径信号：“降”不是贬义，而是指降低接入门槛、降低使用成本、降低运维复杂度；“Spring AI”是核心框架；“阿里”明确指向阿里云基础设施与服务生态；“第9掌”是戏谑说法，实则暗示这是系列化实践中的关键一环；而“或跃在渊”出自《周易》，形容蓄势待发、临界突破的状态，精准对应当前Spring AI在企业级Agent开发中从概念验证走向生产部署的转折点；最后的“ReactAgent”是技术落点——一个基于React模式构建、可响应式调度工具与记忆、具备状态管理能力的智能体。

我从去年底开始在三个客户现场推进Spring AI Agent落地，其中两个跑在阿里云ECS+RDS+OSS组合上，一个直接部署在阿里云Serverless应用引擎SAE。过程中最常被问到的问题就是：“Spring Boot项目怎么无缝对接阿里云的向量库、大模型API、对象存储和消息队列？”——这恰恰是本项目要解决的底层缝合问题。它不讲大模型原理，不堆Prompt工程技巧，只聚焦一件事：让一个标准Spring Boot工程，在不改一行业务逻辑的前提下，通过最小依赖变更和配置调整，原生支持阿里云全栈AI服务，并能以React模式驱动多步骤任务流。

关键词“SpringAI”“阿里”“ReactAgent”不是并列关系，而是层级依赖：SpringAI是骨架，阿里是血肉（提供算力、存储、网络、安全等基础能力），ReactAgent是神经反射系统（定义“感知-决策-执行-反馈”的闭环节奏）。所谓“降”，本质是把原本需要手动拼接OpenAI/Anthropic SDK、自建向量库、硬编码OSS上传逻辑的散装方案，收束进Spring AI官方抽象层，并用阿里云官方SDK做深度适配。比如，你不再需要写ossClient.putObject(...)，而是声明一个AliyunOssToolBean，再把它注册进ToolRegistry，Agent运行时自动调用——这才是真正的“降维”。

这个项目适合三类人：一是正在用Spring Boot做后台系统的Java工程师，想快速给现有系统加AI能力；二是负责AI平台建设的架构师，需要评估Spring AI在阿里云环境的可行性与扩展瓶颈；三是刚学完LangChain/Spring AI基础、卡在“本地跑通→线上部署”这一关的开发者。它不教你怎么写100行Prompt，但会告诉你：当你的Agent要调用阿里云短信API发验证码时，如何让TextToSpeechTool自动注入AcsClient实例，且密钥管理符合阿里云RAM最佳实践；当Agent需要读取用户上传到OSS的PDF合同并提取条款时，如何让DocumentLoaderTool天然支持oss://bucket-name/path/file.pdf协议。这些细节，才是真实世界里“能用”和“好用”的分水岭。

2. 整体设计思路：为什么选择React模式而非Chain？为什么必须绑定阿里云？

2.1 ReactAgent不是新发明，而是对Spring AI原生能力的精准补位

Spring AI 0.8.x之后，官方明确将ChatClient作为核心交互入口，但默认提供的DefaultChatClient本质上仍是单轮问答模式（Single-turn）。当你需要让Agent完成“查订单→解析发票→比对金额→触发退款”这样的多跳任务时，就必须自己实现状态维护、工具调用链路、错误回滚机制——这正是React模式的价值所在。React（Reason, Act, Observe）不是指前端框架React.js，而是认知科学中的反应式智能体范式：Agent持续观察环境（Observe）、基于规则或LLM推理决定下一步动作（Reason）、执行具体操作（Act），然后循环。Spring AI本身不内置React引擎，但提供了ToolExecutor、MessageHistory、StatefulChatMemory等模块，足够我们搭出轻量级React内核。

我试过两种方案：第一种是直接集成LangChain4j的ReactExecutor，但它与Spring AI的ChatModel抽象层存在类型冲突，需大量Adapter代码；第二种是基于Spring AI的ChatClient+ToolRegistry+ 自研ReactLoop，仅增加3个核心类（ReactState、ReactStep、ReactEngine），却完全复用Spring AI的配置体系、消息序列化、流式响应等能力。最终选了后者，因为它的侵入性最低——你现有的@Bean ChatClient chatClient()配置无需改动，只需额外声明@Bean ReactEngine reactEngine()，所有旧有Prompt模板、SystemMessage、Tool定义全部兼容。这正是“降”的第一层含义：不颠覆现有技术栈，只做增量增强。

2.2 阿里云绑定不是厂商锁定，而是对国产化基础设施的务实适配

标题里强调“阿里”，绝非营销噱头。当前国内企业级AI落地面临三大刚性约束：数据不出域、API调用受控、运维体系统一。阿里云恰好覆盖这三点：百炼大模型API满足合规要求；RDS PostgreSQL + PGVector插件提供成熟向量数据库方案；OSS提供高可靠对象存储；RAM权限体系确保密钥最小化授权。更重要的是，阿里云SDK（aliyun-java-sdk-*）与Spring生态深度整合——spring-cloud-starter-alicloud-oss、spring-cloud-starter-alicloud-acm等starter已成事实标准。

对比其他云厂商，阿里云在Java生态的适配成熟度更高。举个例子：Spring AI的EmbeddingClient接口需要实现向量化逻辑，AWS Bedrock需处理复杂的签名V4，而阿里云百炼API仅需AcsClient+CommonRequest，且官方SDK已内置重试、熔断、日志埋点。再如OSS文件加载，MinIO需自行处理Endpoint、Region映射，而aliyun-spring-boot-starter-oss直接通过spring.cloud.alicloud.oss.*配置即可注入OssTemplate。这种“开箱即用”的体验，大幅降低了ReactAgent的工程化成本。所以，“绑定阿里云”本质是选择一条阻力最小、审计友好的国产化落地路径，而非技术偏好。

2.3 “或跃在渊”的真实含义：从单点工具调用迈向业务流程编织

很多团队卡在“Agent能调API，但不会编排业务”。比如，一个电商客服Agent能查订单，也能发短信，但无法自动判断“订单超时未支付→触发催付短信→若30分钟未支付→关闭订单”。这就是React模式要解决的核心问题——状态驱动的流程编织（Orchestration）。我们设计的ReactAgent内核包含四个不可变状态：IDLE（等待输入）、REASONING（LLM生成Action Plan）、ACTING（执行Tool）、OBSERVING（接收Tool返回并更新Context）。每个状态转换都由ReactStep定义，而ReactStep本身是Spring Bean，支持@Autowired注入任意Service，这意味着你可以把“检查库存”、“调用风控接口”、“写审计日志”等业务逻辑无缝嵌入Agent执行流。

这种设计让Agent不再是黑盒LLM调用器，而是可调试、可监控、可审计的业务组件。我们在某银行项目中，将ReactAgent嵌入信贷审批流程：当用户提交申请，Agent自动调用CreditScoreTool（对接内部评分系统）、IdentityVerifyTool（调用人脸识别API）、RiskAssessTool（调用风控模型），每步结果存入ReactState，失败时自动触发FallbackStep（转人工审核）。整个过程在SkyWalking中呈现为清晰的Span链路，运维人员一眼就能看出卡在哪一步。这才是“或跃在渊”的实质——Agent已具备跃出技术Demo深渊、潜入真实业务深水区的能力。

3. 核心细节解析：Spring AI + 阿里云的七处关键缝合点

3.1 Maven配置：为什么必须用阿里云Maven仓库镜像？

Spring AI的里程碑版本（如0.8.1）发布在Spring Milestone仓库，而国内访问该仓库极不稳定。直接配置<repository>会导致mvn clean compile卡在下载spring-ai-core依赖上。解决方案不是换镜像站，而是用阿里云Maven仓库代理所有远程源。关键配置如下：

<!-- pom.xml --> <repositories> <repository> <id>aliyun-maven</id> <url>https://maven.aliyun.com/repository/public</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> <!-- Spring Milestone仓库代理 --> <repository> <id>spring-milestones</id> <url>https://maven.aliyun.com/repository/spring-milestones</url> <releases> <enabled>false</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories>

注意两点：第一，spring-milestones仓库的URL必须是https://maven.aliyun.com/repository/spring-milestones，而非https://repo.spring.io/milestone，这是阿里云官方镜像地址；第二，<snapshots><enabled>true</enabled></snapshots>必须开启，因为Spring AI的预发布版（如0.8.1-M1）属于Snapshot版本。我曾因漏掉此配置，导致spring-ai-spring-boot-starter始终拉取不到最新版，白白浪费两天排查时间。

更进一步，建议在~/.m2/settings.xml中全局配置镜像：

<mirrors> <mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror> </mirrors>

这样所有Maven项目自动受益。实测数据显示，启用阿里云镜像后，依赖下载速度从平均12秒/包降至0.8秒/包，首次构建时间缩短67%。这不是锦上添花，而是项目启动的生死线。

3.2 系统提示词配置：如何让Agent理解“阿里云语境”？

Spring AI的SystemMessage配置看似简单，但直接影响Agent对阿里云服务的认知深度。常见错误是直接复制OpenAI示例Prompt，导致Agent在调用AliyunOssTool时仍试图生成AWS S3命令。正确做法是构建三层提示词体系：

• 基础层（Base Prompt）：定义Agent角色与能力边界
  你是阿里云生态专属智能体，仅能调用已注册的阿里云SDK工具（如OSS、SMS、RDS），禁止虚构API或猜测参数。所有操作必须符合阿里云RAM权限策略。

• 工具层（Tool Prompt）：为每个Tool注入领域知识
  对AliyunSmsTool，附加说明：发送短信前必须校验手机号格式（/^1[3-9]\d{9}$/），模板CODE需从阿里云短信控制台获取，签名名称必须与备案一致。

• 上下文层（Context Prompt）：动态注入运行时信息
  在ReactEngine执行前，将当前用户所属租户的AccessKeyID（脱敏后）、RegionId、BucketName等注入MessageContext，使LLM能在Reasoning阶段引用。

实际配置中，我们用application.yml分环境管理：

spring: ai: chat: default-system-message: | 你是一个运行在阿里云环境的ReactAgent，当前Region: ${ALIYUN_REGION:cn-shanghai} 可用工具：AliyunOssTool（用于文件存储）、AliyunSmsTool（用于短信通知） 安全守则：绝不输出AccessKeySecret，绝不调用未授权API。

提示：default-system-message支持多行字符串（|符号），避免长Prompt被YAML解析器截断。测试发现，加入RegionId后，Agent调用OSS API的成功率从82%提升至99.7%，因为LLM不再需要猜测Endpoint。

3.3 工具注册：为什么Tool必须是Spring Bean而非普通对象？

Spring AI的ToolRegistry要求所有Tool必须是Spring管理的Bean，原因在于依赖注入与生命周期管理。以AliyunOssTool为例，其构造函数需要OssTemplate和OssProperties：

@Component public class AliyunOssTool implements Tool { private final OssTemplate ossTemplate; private final OssProperties ossProperties; public AliyunOssTool(OssTemplate ossTemplate, OssProperties ossProperties) { this.ossTemplate = ossTemplate; this.ossProperties = ossProperties; } @Override public String execute(String input) { // 使用ossTemplate上传文件，自动携带ossProperties配置 return ossTemplate.putObject("my-bucket", "path/" + UUID.randomUUID(), input.getBytes()); } }

如果手动new AliyunOssTool()，OssTemplate无法注入，且ossProperties需硬编码。而声明为@Component后，Spring自动完成依赖装配。更重要的是，OssTemplate本身是@ConditionalOnClass(OssTemplate.class)条件化Bean，只有引入spring-cloud-starter-alicloud-oss时才创建——这实现了按需加载，避免无用依赖污染Classpath。

实操心得：所有Tool类必须添加@Component或@Service注解，并确保其构造函数参数均为Spring Bean。曾有同事将AliyunRdsTool的JdbcTemplate参数改为DataSource，导致启动报NoSuchBeanDefinitionException，因为JdbcTemplate是Spring Boot自动配置的Bean，而DataSource需手动声明。

3.4 向量存储：为什么选用RDS+PGVector而非阿里云OpenSearch？

阿里云OpenSearch确实提供向量检索，但其Java SDK与Spring Data不兼容，且不支持@Query注解。而RDS PostgreSQL开启PGVector插件后，可直接使用Spring Data JPA：

@Entity public class DocumentChunk { @Id private String id; private String content; @Column(columnDefinition = "vector(1536)") private float[] embedding; } @Repository public interface DocumentChunkRepository extends JpaRepository<DocumentChunk, String> { @Query("SELECT d FROM DocumentChunk d ORDER BY d.embedding <-> :embedding LIMIT 5") List<DocumentChunk> findSimilar(@Param("embedding") float[] embedding); }

关键优势有三：第一，embedding <-> :embedding是PGVector原生相似度运算符，性能优于OpenSearch的近似搜索；第二，DocumentChunk实体可与其他业务表（如Order、User）建立JPA关联，实现“订单文档+用户画像”联合检索；第三，RDS的备份、监控、SQL审计能力直接复用，无需新建运维体系。我们在某政务项目中，用RDS+PGVector支撑10亿级文档向量化，P99查询延迟稳定在120ms以内，而OpenSearch同规格集群P99达380ms。

注意：启用PGVector需在RDS控制台执行CREATE EXTENSION vector;，且RDS版本需≥PostgreSQL 14。低于此版本需升级，切勿尝试手动编译安装，可能导致实例崩溃。

3.5 消息历史：如何用Redis实现跨请求Stateful Chat Memory？

ReactAgent必须记住多轮对话状态，但Spring AI默认InMemoryChatMemory在重启后丢失。我们采用RedisChatMemory，但做了两处关键改造：

• Key命名空间隔离：避免不同用户Session混用

  @Bean public ChatMemory chatMemory(RedisConnectionFactory connectionFactory) { RedisChatMemory redisChatMemory = new RedisChatMemory(connectionFactory); // 关键：为每个用户生成唯一key前缀 redisChatMemory.setKeyPrefix("chat:memory:" + getUserIdFromContext() + ":"); return redisChatMemory; }

• TTL自动清理：防止Redis内存溢出

  // 在RedisChatMemory.save()后追加TTL设置 redisTemplate.expire(key, Duration.ofHours(24));

实测发现，未加TTL时，10万用户并发下Redis内存每日增长12GB，加TTL后稳定在3GB。另外，getMessages()方法默认返回全部历史，但ReactAgent只需最近5轮，因此重写findMessagesByConversationId：

@Override public List<Message> findMessagesByConversationId(String conversationId) { // 仅取最近5条，减少网络传输 return super.findMessagesByConversationId(conversationId).stream() .skip(Math.max(0, size() - 5)) .collect(Collectors.toList()); }

3.6 流式响应：如何让ReactAgent的每步Action都实时推送？

Spring AI的StreamingChatClient默认只流式返回LLM输出，但ReactAgent需要将REASONING、ACTING、OBSERVING各阶段结果实时推送给前端。解决方案是自定义StreamingChatClient包装器：

@Component public class ReactStreamingChatClient { private final StreamingChatClient streamingChatClient; private final SseEmitter emitter; // 前端建立的SSE连接 public void executeReactStep(ReactStep step) { // 步骤开始时推送状态 emitter.send(SseEmitter.event().name("step-start").data(step.getType())); // 执行Tool并流式返回结果 streamingChatClient.stream(step.getPrompt()) .doOnNext(chunk -> emitter.send(SseEmitter.event().name("chunk").data(chunk.getContent()))) .doOnComplete(() -> emitter.send(SseEmitter.event().name("step-end").data(step.getResult()))); } }

前端用EventSource监听step-start、chunk、step-end事件，即可实现“Agent思考中… → 调用OSS上传 → 上传完成”这样的渐进式反馈。相比WebSocket，SSE更轻量，且Nginx默认支持，无需额外配置。

3.7 安全加固：如何让Agent调用阿里云API时符合RAM最小权限原则？

所有Tool的阿里云客户端（AcsClient、OssClient）必须使用RAM子账号的AK/SK，且权限策略需精确到API级别。例如，AliyunSmsTool的RAM Policy应为：

{ "Version": "1", "Statement": [ { "Action": ["dybaseapi:SendSms"], "Effect": "Allow", "Resource": "*" } ] }

绝对禁止授予"Action": ["*"]。更进一步，我们为每个Tool创建独立RAM角色：

• sms-tool-role：仅允许dybaseapi:SendSms
• oss-tool-role：仅允许oss:GetObject,oss:PutObject
• rds-tool-role：仅允许rds:DescribeDBInstances

然后在application.yml中配置角色ARN：

aliyun: sms: role-arn: acs:ram::1234567890123456:role/sms-tool-role oss: role-arn: acs:ram::1234567890123456:role/oss-tool-role

AcsClient初始化时自动扮演该角色，实现权限动态切换。此举让Agent即使被注入恶意Prompt，也无法越权调用其他API——这是生产环境的底线。

4. 实操过程：从零搭建一个可运行的ReactAgent Demo

4.1 环境准备：四步完成阿里云服务开通

1. 开通百炼大模型API
   登录阿里云百炼控制台 → 创建应用 → 获取API_KEY和API_SECRET→ 记录Endpoint（如https://dashscope.aliyuncs.com/api/v1）。注意：免费额度仅限qwen-max，生产环境需购买qwen-plus。

2. 创建RDS PostgreSQL实例
   规格选2核4G起步，版本选PostgreSQL 14，网络选与ECS同VPC。创建后进入数据库管理 → 执行CREATE EXTENSION vector;启用PGVector。

3. 开通OSS并创建Bucket
   Bucket名称需全局唯一（如my-reactagent-bucket-2024），读写权限设为私有，跨域CORS配置允许http://localhost:3000（开发环境）。

4. 配置RAM子账号与权限
   创建子账号react-agent-user→ 为其附加自定义Policy（见3.7节）→ 生成AK/SK → 将AK/SK存入阿里云ACM配置中心（非明文写入application.yml）。

提示：所有服务必须在同一地域（如cn-shanghai），否则跨Region调用会失败。我们曾因OSS在cn-beijing、RDS在cn-shanghai，导致Agent上传文件时抛出InvalidEndpoint异常，排查耗时6小时。

4.2 项目初始化：Maven依赖与Spring Boot版本选择

使用Spring Boot 3.2.x（Java 17+），这是Spring AI 0.8.x的强制要求。pom.xml核心依赖：

<dependencies> <!-- Spring AI 核心 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-spring-boot-starter</artifactId> <version>0.8.1</version> </dependency> <!-- 阿里云OSS --> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alicloud-oss</artifactId> <version>2.3.1</version> </dependency> <!-- 阿里云短信 --> <dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-dysmsapi</artifactId> <version>2.1.1</version> </dependency> <!-- RDS + PGVector --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>org.postgresql</groupId> <artifactId>postgresql</artifactId> </dependency> <!-- Redis --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency> </dependencies>

关键版本匹配：spring-cloud-starter-alicloud-oss2.3.1 适配 Spring Boot 3.2.x，若误用2.2.x会因WebMvcConfigurer接口变更导致启动失败。

4.3 核心代码实现：ReactEngine的300行精简版

以下为ReactEngine核心逻辑（已删减日志与异常处理，保留主干）：

@Component public class ReactEngine { private final ChatClient chatClient; private final ToolRegistry toolRegistry; private final ChatMemory chatMemory; public ReactEngine(ChatClient chatClient, ToolRegistry toolRegistry, ChatMemory chatMemory) { this.chatClient = chatClient; this.toolRegistry = toolRegistry; this.chatMemory = chatMemory; } public Flux<ReactResponse> execute(String userMessage, String conversationId) { // 1. 初始化ReactState ReactState state = ReactState.builder() .conversationId(conversationId) .messages(chatMemory.findMessagesByConversationId(conversationId)) .build(); // 2. 进入React循环（最多5轮，防死循环） return Flux.generate( () -> state, (stateRef, sink) -> { if (stateRef.isCompleted()) { sink.complete(); return; } // Step 1: Reasoning - 让LLM生成Action Plan String reasoningPrompt = buildReasoningPrompt(stateRef); Message response = chatClient.call(reasoningPrompt); // Step 2: Parse Action from LLM output ReactAction action = parseAction(response.getContent()); // Step 3: Acting - 执行Tool String toolResult = toolRegistry.invoke(action.getToolName(), action.getInput()); // Step 4: Observing - 更新State stateRef = stateRef.next(action, toolResult); chatMemory.save(stateRef.getMessages(), conversationId); // 发送响应 sink.next(new ReactResponse(action, toolResult)); }, stateRef -> { // 清理资源 chatMemory.delete(conversationId); } ); } private String buildReasoningPrompt(ReactState state) { return """ 你正在执行React模式。当前状态：%s 可用工具：%s 请生成下一步Action，格式：{"tool":"toolName","input":"toolInput"} """.formatted(state.getStatus(), toolRegistry.getToolNames()); } }

ReactResponse是自定义DTO，包含actionType、toolName、result字段，前端据此渲染不同UI组件。整个循环逻辑控制在300行内，却完整覆盖React四态，证明Spring AI的抽象能力足够支撑复杂Agent。

4.4 配置文件：application.yml的12处关键参数

# application.yml spring: profiles: active: prod ai: chat: # 百炼API配置 model: qwen-plus base-url: https://dashscope.aliyuncs.com/api/v1 api-key: ${ALIYUN_API_KEY} # 系统提示词 default-system-message: | 你是一个阿里云ReactAgent，当前Region: cn-shanghai 可用工具：AliyunOssTool（文件存储）、AliyunSmsTool（短信通知） 安全守则：绝不输出AK/SK，绝不调用未授权API。 cloud: alicloud: # OSS配置 oss: endpoint: https://oss-cn-shanghai.aliyuncs.com bucket: my-reactagent-bucket-2024 access-key-id: ${ALIYUN_OSS_AK} access-key-secret: ${ALIYUN_OSS_SK} # 短信配置 sms: region-id: cn-shanghai sign-name: 【我的应用】 template-code: SMS_123456789 datasource: url: jdbc:postgresql://rm-xxx.pg.rds.aliyuncs.com:3306/reactdb?currentSchema=public username: ${ALIYUN_RDS_USER} password: ${ALIYUN_RDS_PASS} redis: host: r-bp1xxx.redis.cn-shanghai.rds.aliyuncs.com port: 6379 password: ${ALIYUN_REDIS_PASS}

注意：所有敏感配置（AK/SK）必须通过阿里云ACM或Kubernetes Secret注入，application.yml中仅留占位符。本地开发可用application-dev.yml，生产环境由ACM动态下发。

4.5 启动与验证：curl命令直击核心链路

启动应用后，用curl模拟一次完整React流程：

# 1. 发起对话（触发REASONING） curl -X POST http://localhost:8080/api/react \ -H "Content-Type: application/json" \ -d '{"userMessage":"帮我把这份合同存到OSS，并发短信通知张三","conversationId":"conv-001"}' # 2. 查看日志，确认输出： # [REASONING] LLM生成: {"tool":"AliyunOssTool","input":"合同内容..."} # [ACTING] 执行OSS上传，返回URL: https://my-bucket.oss-cn-shanghai.aliyuncs.com/... # [OBSERVING] 更新State，准备下一步... # 3. 再次请求，触发短信发送 curl -X POST http://localhost:8080/api/react \ -H "Content-Type: application/json" \ -d '{"userMessage":"继续","conversationId":"conv-001"}' # 4. 日志显示： # [REASONING] LLM生成: {"tool":"AliyunSmsTool","input":"13800138000,合同已存至OSS，链接：https://..."} # [ACTING] 短信发送成功，MessageId: abc123...

整个链路在2秒内完成，证明ReactEngine与阿里云服务无缝协同。这是“降”的终极体现——技术细节被封装，开发者只关注业务意图。

5. 常见问题与排查技巧实录：踩过的12个坑与解决方案

5.1 百炼API调用失败：HTTP 401 Unauthorized

现象：chatClient.call()抛出HttpClientErrorException.Unauthorized，日志显示{"message":"Invalid API Key"}。
根因：百炼API Key需在Header中以Authorization: Bearer ${API_KEY}格式传递，但Spring AI默认使用X-DashScope-Signature。
解决方案：自定义RestTemplate，重写HttpHeaders：

@Bean public RestTemplate restTemplate() { RestTemplate restTemplate = new RestTemplate(); restTemplate.setInterceptors(Collections.singletonList((request, body, execution) -> { request.getHeaders().set("Authorization", "Bearer " + System.getProperty("aliyun.api.key")); return execution.execute(request, body); })); return restTemplate; }

实操心得：百炼文档未明确说明Header格式，此坑导致3个团队集体卡顿。务必在application.yml中配置aliyun.api.key，并在RestTemplate中注入。

5.2 PGVector向量查询为空：ORDER BY embedding <-> ?无结果

现象：findSimilar()方法返回空List，但数据库确认有数据。
根因：PGVector的<->运算符要求左右向量维度严格一致，而Spring AI的EmbeddingClient默认生成1536维向量，但RDS PostgreSQL的vector(1536)列可能被误建为vector(768)。
解决方案：检查表结构SELECT column_name, data_type FROM information_schema.columns WHERE table_name='document_chunk';，若embedding列为vector(768)，执行：

ALTER TABLE document_chunk ALTER COLUMN embedding TYPE vector(1536) USING embedding::vector(1536);

5.3 OSS上传403 Forbidden：SignatureDoesNotMatch

现象：AliyunOssTool调用ossTemplate.putObject()时抛出com.aliyun.oss.OSSException: The request signature we calculated does not match the signature you provided.
根因：spring-cloud-starter-alicloud-oss2.3.1默认使用V4签名，但OSS Bucket若创建于旧版控制台，可能强制V2签名。
解决方案：在application.yml中显式指定签名版本：

spring: cloud: alicloud: oss: signature-version: V2

5.4 Redis连接超时：Cannot get Jedis connection

现象：RedisChatMemory初始化失败，日志org.springframework.dao.DataAccessResourceFailureException: Cannot get Jedis connection。
根因：阿里云Redis实例开启SSL加密连接，但spring-boot-starter-data-redis默认走非SSL端口。
解决方案：启用SSL并指定证书：

spring: redis: ssl: true lettuce: pool: max-active: 20

同时，将Redis连接字符串改为rediss://（注意s）。

5.5 ReactAgent无限循环：LLM反复生成同一Action

现象：Agent卡在REASONING状态，连续5次生成{"tool":"AliyunOssTool","input":"..."}。
根因：SystemMessage未明确禁止重复调用，LLM将“上传文件”视为唯一解。
解决方案：在系统提示词末尾追加硬性约束：

spring: ai: chat: default-system-message: | ...（原有内容） 约束：同一工具在单次对话中最多调用1次，禁止重复调用。

5.6 短信发送失败：InvalidPhoneNumbers

现象：AliyunSmsTool调用SendSmsRequest返回InvalidPhoneNumbers。
根因：阿里云短信API要求手机号去空格、去横线，且必须为11位纯数字。
解决方案：在Tool执行前清洗号码：

public String execute(String input) { String phone = input.replaceAll("[^0-9]", ""); // 移除所有非数字字符 if (phone.length() != 11) { throw new IllegalArgumentException("手机号格式错误：" + input); } // 继续调用SDK }

5.7 流式响应中断：SSE连接频繁断开

现象：前端EventSource收到部分chunk后断开，错误码net::ERR_INCOMPLETE_CHUNKED_ENCODING。
根因：Nginx默认proxy_buffer太小，无法缓存大块流式响应。
解决方案：Nginx配置追加：

location /api/react { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_cache_bypass $http_upgrade; # 关键：增大缓冲区 proxy_buffering off; proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; }

5.8 RDS连接池耗尽：HikariPool-1 - Connection is not available

现象：高并发下AliyunRdsTool调用失败，日志Connection is not available, request timed out after 30000ms。
根因：HikariCP默认maximumPoolSize=10，而ReactAgent