企业官网建设流程全解析

这半年我们团队一直在折腾一件事：把 AI Agent 的管理能力塞进现有的 Java 后台里，而不是另起炉灶搞一套 Python 管理端。当时手上刚好有一个基于 RuoYi-Vue-Plus 的权限中台项目，业务方又提出要用多智能体编排来做一些自动化流程，于是就促成了这次集成实践——把 AgentScope Harness 接进 RuoYi-Vue-Plus，做一个“管理端纯 Java、执行端交给 Harness”的 AI 平台底座。整个过程踩了不少坑，也总结出了一套相对稳的接法，这篇文章就是这次实践的完整复盘。

如果你现在的处境和我当时类似——Java 技术栈是主力，但又想快速获得 Agent 编排和调度的能力，而不是从零写一套 Agent 运行时，那这篇文章应该能帮你少走不少弯路。我先把核心思路、关键代码、配置细节和坑位都拆开讲清楚，你可以直接照着落地。

1. 项目整体设计与思路拆解

1.1 为什么要选 RuoYi-Vue-Plus 当底座

RuoYi-Vue-Plus 这个脚手架，我的评价是“拿来就能跑，改起来也不疼”。它自带的基础设施相当完整：Sa-Token 权限体系、菜单路由、代码生成器、定时任务、操作日志、在线用户管理，这些模块在一个 AI 平台的管理端里几乎全部用得上。尤其是权限体系，Agent 实例这种资源天然需要按角色划分可见范围，直接用若依的@SaCheckPermission注解就能解决，不用自己再造轮子。

另外一个重要原因是团队熟练度。我们当时项目组成员对 Spring Boot 3、MyBatis-Plus 都很熟，但 Python 技术栈的人手不够。如果为了 Agent 能力硬上一套 FastAPI 管理端，后续的迭代维护成本会摊到整个团队头上，这显然不划算。所以“Java 管理端 + 独立 Agent 运行时”这种架构，是我们在权衡人力、工期和业务需求之后觉得最务实的方案。

1.2 AgentScope Harness 在整个架构里的角色

先解释一下 Harness 这个词。直译是“马具、缰绳”，但在 Agent 工程化领域，它指的是给智能体应用套上的一整套“驾驶装置”——负责管理 Agent 的生命周期、运行时依赖、通信协议、工具装配和日志采集。你可以把它理解成 Agent 的“运行容器 + 调度器”，跟 Tomcat 之于 Servlet 的关系有点像，只不过 Tomcat 装的是 Web 应用，Harness 装的是 Agent 应用。

在我们的架构里，Harness 以独立服务的形式存在，对外暴露 HTTP API。Java 侧的业务系统不需要关心 Agent 内部是怎么编排的，只需要通过 API 下发“创建”“启动”“停止”“查状态”“拉日志”这些操作。这种设计的好处是边界非常清晰：Java 管业务、管资源权限、管流程编排；Harness 管 Agent 进程、管道通信、工具注册和运行日志。两边各司其职，互不侵入。

1.3 集成思路：为什么不直接用 Python SDK

其实 AgentScope 本身提供了完整的 Python SDK，如果团队里都是 Python 工程师，直接在后台服务里调用 SDK 是最顺畅的方式。但我们面临一个很现实的问题：现有的 RuoYi-Vue-Plus 业务系统里有大量的用户体系、工单流、审批流，这些逻辑都是 Java 写的。如果让 Java 工程去依赖 Python SDK，跨语言混编会导致部署流程变得极其复杂——你得保证每个节点上都有 Python 环境和依赖包，还得处理 Python 进程崩溃后对 Java 进程的影响。

所以最终的方案是：把 Harness 独立部署，HTTP 协议作为唯一通信通道。这样 Java 侧只需要一个 HTTP 客户端封装类，不引入任何 Python 依赖。运维层面也简单，Java 应用和 Harness 服务各自一套生命周期管理，互不干扰。这也是我认为最“纯 Java AI 平台”的做法——AI 引擎本身跑在独立的运行时里，但平台化管理、API 暴露、权限管控全都在 Java 侧完成。

2. Harness HTTP API 对接的核心细节

2.1 我们需要关注哪些 API 语义

接 Harness 之前，我先把它的接口语义梳理了一遍。对我们这种集成场景来说，最核心的其实是五个操作：注册 Agent 配置、启动实例、停止实例、查询状态、获取日志。这里要注意一个概念区分：Agent 配置和Agent 实例不是一回事。配置是静态的，描述这个 Agent“是什么”，包括提示词模板、工具列表、模型参数；实例是动态的，代表一次实际运行，有自己的会话上下文和运行状态。

在我们的设计里，RuoYi 的数据库里保存 Agent 配置信息，Harness 侧只负责运行时实例。所以对接时，POST 请求创建的不是“一次运行”，而是“一份可运行的 Agent 模板”。启动操作才是真正产生实例的时刻。

2.2 数据模型设计

既然要存 Agent 配置，那 RuoYi 侧就得有一张对应的表。我设计的时候参考了 Harness 的输入要求和若依本身的字段规范，最终落地的表结构大致是这样：

CREATE TABLE `agent_config` ( `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键', `agent_name` varchar(64) NOT NULL COMMENT 'Agent 名称', `agent_code` varchar(64) NOT NULL COMMENT 'Agent 编码，全局唯一', `scene_type` varchar(32) DEFAULT NULL COMMENT '场景类型：TASK/CHAT/REASONING', `prompt_config` json DEFAULT NULL COMMENT '提示词与模型参数配置', `tool_list` json DEFAULT NULL COMMENT '工具清单', `worker_num` int DEFAULT 1 COMMENT '最大并发运行数', `status` char(1) DEFAULT '0' COMMENT '状态：0草稿 1启用 2停用', `create_by` varchar(64) DEFAULT NULL, `create_time` datetime DEFAULT NULL, `update_by` varchar(64) DEFAULT NULL, `update_time` datetime DEFAULT NULL, PRIMARY KEY (`id`), UNIQUE KEY `uk_agent_code` (`agent_code`) ) ENGINE=InnoDB COMMENT='Agent 配置表';

两个 JSON 字段是我刻意选的。prompt_config里存的是模型名、温度、最大 token 数、System Prompt 这些内容；tool_list放 Agent 能调用的工具列表。用 JSON 而不是 text 的好处是后续如果要做配置项的局部更新、校验，MyBatis-Plus 可以直接映射到实体类的 String 字段，也可以在数据库层面用 JSON 函数做条件查询，比 text 灵活得多。

2.3 实体类与 Mapper 层

实体类的写法遵循 MyBatis-Plus 的常规套路，没有什么花活。唯一想提醒的是，在 JSON 字段上一定要加自动映射的注解，不然查询出来是字符串，插入的时候又会因为类型不匹配导致 SQL 报错。

@Data @TableName("agent_config") public class AgentConfigEntity { @TableId(type = IdType.AUTO) private Long id; private String agentName; private String agentCode; private String sceneType; private String promptConfig; private String toolList; private Integer workerNum; private String status; private String createBy; private LocalDateTime createTime; private String updateBy; private LocalDateTime updateTime; }

Mapper 就是裸继承BaseMapper<AgentConfigEntity>，不需要自定义 SQL。CRUD 全部靠 MyBatis-Plus 的内置方法，只有在后续做分页查询的时候加了一个Page<AgentConfigEntity>条件的封装。这里其实也体现出选 RuoYi 系列的一个隐形好处：MyBatis-Plus 的配置、分页插件、字段自动填充都已经是现成的，不需要自己一个个去调。

3. 实操过程：从配置到 API 对接

3.1 第一步：把 HTTP 客户端封装成可复用的 Manager

RuoYi-Vue-Plus 里已经集成了 Hutool，所以我没有额外引入 RestTemplate 或者 OkHttp，直接用 Hutool 的HttpUtil完成最基础的请求。但直接到处写HttpUtil.post(...)肯定不行，后续要统一加签名、加超时处理，会改到吐血。所以我做了一层HarnessManager的封装，所有与 Harness 的通信都走这个类。

@Component public class HarnessManager { private static final Logger log = LoggerFactory.getLogger(HarnessManager.class); @Value("${harness.base-url}") private String baseUrl; @Value("${harness.api-key}") private String apiKey; @Value("${harness.connect-timeout:5000}") private int connectTimeout; @Value("${harness.read-timeout:60000}") private int readTimeout; public String createAgent(AgentConfigEntity config) { JSONObject body = new JSONObject(); body.set("agentCode", config.getAgentCode()); body.set("agentName", config.getAgentName()); body.set("sceneType", config.getSceneType()); body.set("promptConfig", JSONUtil.parseObj(config.getPromptConfig())); body.set("toolList", JSONUtil.parseArray(config.getToolList())); return requestJson("/api/v1/agents", "POST", body); } public String startAgent(String agentCode) { JSONObject body = new JSONObject(); body.set("agentCode", agentCode); return requestJson("/api/v1/agents/start", "POST", body); } public String stopAgent(String agentCode) { JSONObject body = new JSONObject(); body.set("agentCode", agentCode); return requestJson("/api/v1/agents/stop", "POST", body); } public String getAgentStatus(String agentCode) { return requestJson("/api/v1/agents/status/" + agentCode, "GET", null); } public String getAgentLogs(String agentCode) { return requestJson("/api/v1/agents/" + agentCode + "/logs", "GET", null); } private String requestJson(String path, String method, JSONObject body) { HttpRequest request = HttpUtil.createRequest(Method.valueOf(method), baseUrl + path); request.header("X-API-Key", apiKey) .header("Content-Type", "application/json") .timeout(new Timeout(connectTimeout)); if (body != null) { request.body(body.toString()); } try (HttpResponse response = request.execute()) { int status = response.getStatus(); if (status < 200 || status >= 300) { log.error("Harness request failed, path: {}, status: {}, body: {}", path, status, response.body()); throw new HarnessException("Harness API error, status: " + status); } return response.body(); } catch (IOException e) { log.error("Harness request read timeout or connection error, path: {}", path, e); throw new HarnessException("Harness connection error: " + e.getMessage()); } } }

3.2 第二步：超时参数要单独配置，不能走默认值

这里有一个很值得展开的坑。我们第一次联调时，read-timeout用的是 10 秒，结果发现启动耗时较长的 Agent 任务经常在 Java 侧抛超时异常。查了日志才发现，Harness 侧 Agent 冷启动要加载模型权重和工具包，跑满 30 秒甚至更久是常有的事。HTTP 客户端默认的读超时根本不够用。

所以我的建议是：创建、停止这类轻操作可以给较短的读超时（比如 10~15 秒），但启动和日志查询这类可能耗时较长的操作，必须给到 60 秒甚至更久。如果公司内部有链路追踪系统，也可以在请求头里带上 traceId，方便把 Java 侧的异常和 Harness 侧的执行日志串起来排查。

另外，Hutool 的Timeout对象需要同时设置连接超时和读写超时，我当时只设置了连接超时，导致读超时走的是默认值，这个问题花了我一个下午才定位到。代码里现在显式地建了connectTimeout和readTimeout两个配置项，并且在启动时打印出来，减少后续排查成本。

3.3 第三步：把 Service 层的状态机做强

光有一个 Manager 还不够，因为 Agent 有状态流转：草稿 -> 运行中 -> 已停止/失败。如果 Service 层不做状态判断，一个已经启动的 Agent 会重复被调用 start 接口，Harness 侧要么报错，要么产生一堆无效的实例记录。

我们的做法是在AgentConfigServiceImpl里维护一个简单的状态机：

public boolean changeStatus(Long id, String expectedStatus, String newStatus) { LambdaUpdateWrapper<AgentConfigEntity> wrapper = new LambdaUpdateWrapper<>(); wrapper.eq(AgentConfigEntity::getId, id) .eq(AgentConfigEntity::getStatus, expectedStatus); AgentConfigEntity update = new AgentConfigEntity(); update.setStatus(newStatus); update.setUpdateTime(LocalDateTime.now()); return this.update(update, wrapper); }

这里用 MyBatis-Plus 的eq(status, expectedStatus)作为乐观锁条件，并发操作时只有状态匹配的那条请求能成功更新，从数据库层面杜绝了重复启动问题。虽然 RuoYi 自带了乐观锁插件配置，但很多时候大家只把它用在版本号字段上，像这种“状态即版本”的写法反而更直观，也更好理解。

3.4 第四步：日志对接与检索

Agent 运行日志是一个很容易被低估的需求。一开始我们只是把 Harness 返回的日志原样存进了一个日志表，结果运行几次之后发现，一个 Task 类 Agent 跑一轮下来就是几百上千行日志，全部堆在 MySQL 单表里，查询翻页慢得没法看。

后来我们做了一步很关键的调整：日志表只保留最近一天的明细，历史日志由 Harness 侧负责归档。Java 侧通过定时任务每 5 分钟同步一次运行中 Agent 的状态和日志，并清理超过一天的明细记录。这样数据库保持轻量，用户在后台上看到的又是实时数据。如果业务量再大，可以考虑把日志投递到独立的日志中心，但当前阶段这种“短保留 + 同步归档”的模式已经够用。

4. 权限、菜单与前端接入

4.1 给 Agent 资源加上权限管理

RuoYi-Vue-Plus 的权限体系是现成的，不需要改造。我在菜单配置里加了“Agent 管理”目录，下面挂了“Agent 实例”“运行日志”“工具注册”三个菜单，分别配置了agent:config:list、agent:config:start、agent:log:list这些权限标识。然后给不同角色分配对应的操作权限。

这里有一点需要强调：不要只在菜单上隐藏，接口层面也要用@SaCheckPermission做二次校验。因为菜单权限只控制前端显示，如果用户手动拼 URL，后端没有校验的话照样能调接口。我们用注解锁住了四个核心操作：

@SaCheckPermission("agent:config:start") @PostMapping("/start/{id}") public R<Void> start(@PathVariable Long id) { ... } @SaCheckPermission("agent:config:stop") @PostMapping("/stop/{id}") public R<Void> stop(@PathVariable Long id) { ... }

4.2 前端页面的快速搭建

前端是用 RuoYi-Vue-Plus 自带的代码生成器直接生成的。我把agent_config表的实体类和 Mapper 丢给生成器，自动产出了列表页、表单页、API 调用，基本上开箱即用。唯一手写的前端逻辑是“启动/停止”按钮的状态联调——要根据当前行的 status 字段动态显示按钮，运行中的 Agent 只显示“停止”，草稿状态的只显示“启动”。

前端调接口的时候，我启动按钮的处理方式是：

handleStart(row) { this.$modal.confirm('确认启动 Agent「' + row.agentName + '」吗？').then(() => { return request({ url: '/ai/agent/start/' + row.id, method: 'post' }); }).then(() => { this.$modal.msgSuccess('启动任务已下发'); this.getList(); }); }

这里有一个交互细节：启动请求返回成功，不代表 Agent 已经进入运行状态，因为 Harness 的启动可能是异步的。所以前端文案用“启动任务已下发”而不是“启动成功”，避免误导用户。页面再通过轮询或者下个刷新周期去拉状态，展示真实的运行情况。

4.3 跨域问题的处理方式

因为 Harness 是独立服务，Java 后端的请求本身是服务端到服务端，不存在浏览器跨域问题。但 Harness 可能会有一些需要前端直连的能力，比如流式的日志推送、SSE 消息通道，这时候就会冒出来跨域。我们直接在后端网关层做了一次转发，把 Harness 的 SSE 接口统一收敛成/ai/harness/sse/**路径，由 Java 后端代理转发给前端，而不是让前端跨域直连 Harness。

这样处理有双重好处：一是前端的所有请求都只指向 RuoYi 域名，配置简单；二是 Harness 的 API Key 只保存在后端，不暴露给浏览器，安全性提升一个档次。

5. 常见问题与排查技巧实录

5.1 启动任务下发后，状态一直不更新

这个是我们在联调中最先碰到的问题。 Harness 侧的 Agent 实例确实跑起来了，但 RuoYi 数据库里的状态字段一直是“0”。查到最后发现，是轮询同步的定时任务配置了@Scheduled注解，但任务的执行被 RuoYi 自带的线程池限制住了——默认的调度线程池很小，而系统里已经有不少定时任务在跑，同步任务可能排队排了非常久。

解决办法是把状态同步任务的调度周期调大到 1 分钟一次，同时给调度线程池单独开了一个配置：

spring: task: scheduling: pool: size: 10

其实问题的本质不是周期太长，而是调度线程池没有给足资源。如果项目里有多个定时任务，这个配置建议直接用起来，不然任务一多，单个任务的执行延迟完全不可控。

5.2 删除配置失败：后面还有引用

当我们做一个“删除 Agent 配置”的功能时，报错显示“存在运行中的实例，不能删除”。这个错误其实是 Harness 侧抛出来的。我自己实现的删除逻辑是先调用 Harness 的 stop 接口，确认实例停了之后，再删除数据库里的配置。但有一次 stop 接口返回了失败，抛出的异常信息被吞掉了，导致数据库的删除操作没有被触发。

后来我在 HarnessManager 里给异常处理加了一个统一出口：

public String stopAgent(String agentCode) { try { return requestJson("/api/v1/agents/stop", "POST", body); } catch (HarnessException e) { if (e.getMessage().contains("not running")) { log.warn("Agent {} is not running, skip stop", agentCode); return "{}"; } throw e; } }

这个“重复停止不报错”的处理逻辑很关键。因为在分布式场景下，一个 agent 可能已经被另一个请求停了，再调 stop 接口就会返回“not running”错误。为了保持接口的幂等性，这个场景不能直接报错，而是当作成功处理。否则用户重复点击“停止”按钮，页面就会一直弹错误提示，体验很糟糕。

5.3 Hutool 连接池耗尽导致的 Full GC 问题

系统运行了两天后，我们注意到一个很隐蔽的问题：后端的 Full GC 频率突然变高。看了堆转储，发现有大量的HttpConnection对象没有被释放。原因很简单——Hutool 的HttpUtil每次请求都会走默认连接池，但我们用了流式处理某些响应体，没有把HttpResponse的流主动关掉。

后来我把所有与 Harness 的通信全部改成了 try-with-resources 模式，并统一在requestJson方法内部完成HttpResponse的关闭，业务侧完全感知不到连接管理这件事。如果你在用 RestTemplate 或者 OkHttp，也得注意类似的问题：连接池用完要放回，响应体要读完再关，不然迟早会拖垮应用。

5.4 配置了 API Key 却还是 401

这个问题是典型的“前后端配置不一致”导致的。Harness 部署的实例有两个：一个测试环境，一个生产环境。我们在 RuoYi 的application.yml里配的是生产环境的 API Key，但本地开发时联调的是测试环境的 Harness 服务。由于两套环境的 Key 不一样，请求一直被 401。

排查方法是登录 Harness 管理端生成了一个新的 Key，替换到 local 环境配置后问题立刻消失。这里建议在配置中心管理环境变量，不要在代码仓库里写死环境差异，尤其是多个环境共享一个代码分支的时候，这种低级错误非常容易发生。

5.5 常见问题速查表

6. 优化方向与扩展想法

集成完成之后，我又重新过了一遍整个架构，觉得有三个方向是可以继续深挖的。

第一个是把配置中心用起来。现在 Harness 的 base-url 和 api-key 直接写死在application.yml里，环境一多就麻烦。RuoYi-Vue-Plus 本身可以对接配置中心，建议把它纳入进来，统一管理多环境的不同 Harness 地址。

第二个是做 Agent 资源的编排调度。现在创建、启动、停止还停留在单机串行操作，如果 Agent 数量多了，或者启动一个 Agent 需要同时拉起多个依赖的子 Agent，纯手工管理就会很累。可以在这套基础上，加一个简单的任务编排引擎，把启动、停止、日志采集这些操作做成可编排的流程。

第三个是监控指标的接入。Harness 侧运行时的 CPU、内存、Token 消耗、请求延迟这些指标，目前我们还没有接全。如果能把指标数据同步到 RuoYi 侧的监控大屏，管理员就可以直观看到每个 Agent 的运行情况，这对生产环境的价值很大。

我个人在实际操作中体会最深的一点是：集成工作的核心不是把两套系统连起来，而是把两套系统之间的边界画清楚。Java 侧负责管理、权限、业务编排，Harness 侧负责运行、调度、资源隔离，中间用清晰、幂等的 HTTP 接口通信。边界画清楚了，后续加功能、加节点、加监控都只是在这个框架里做增量，而不会牵一发动全身。

最后再分享一个小技巧：在 HarnessManager 刚写完的时候，建议先写一个简单的开关接口，把 Harness 的连通性测试放到后台的一个隐藏页面里。这样每次发布配置变动、环境切换之后，运维同学点一下按钮就能确认链路是否正常，会省去非常多的排查成本。