SpringBoot + Vue3 企业智能体架构：独立服务、独立数据库与主线零侵入

SpringBoot + Vue3 企业智能体架构：独立服务、独立数据库与主线零侵入

🌐 产品手册：https://ruoyioffice.com/
👇 文章底部提供智能体与业务系统两种体验入口 👇
💬 ：17156169080（获取 AgentOS 产品咨询）

企业智能体最容易出现两种架构极端。

一种是完全外挂：单独做个聊天页面，只能问答，拿不到可信身份和业务上下文。另一种是深度掺入：把运行时、模型 SDK、对话表、连接器和所有业务模块塞进原有后端，最终 AI 升级牵动整个业务系统。

RuoYi Office AgentOS 选择了第三条路：保持独立前端、独立 Spring Boot 后端、独立数据库和独立发布流水线；通过 SSO 复用身份，通过受控业务 API 办事，通过连接器适配其他系统。主线业务不反向依赖 AgentOS，AgentOS 也不复制财务、OA、人事、项目等领域逻辑。

这篇文章拆的是已经落地的架构边界，不把“能通过连接器扩展”写成所有第三方系统已经开箱接通。

一、先给结论：独立，不等于割裂

从用户视角看，AgentOS 可以嵌入原业务系统右下角，也可以独立打开工作台；一体化部署时复用当前登录身份，不要求用户理解 OAuth、租户 ID 或授权范围。

▲ 独立前端的真实工作台：工作、管理、开发三个空间运行在 AgentOS 自己的应用中，也可以通过嵌入页进入主线系统。

从工程视角看，它有四条硬边界：

1. AgentOS 后端使用独立启动器和独立端口。
2. 对话、能力、确认单、运行记录等存入独立数据库。
3. 主线业务写入只能走主线领域 API，不直连业务表。
4. 主线后端不依赖 AgentOS，关闭或不购买扩展时不影响原系统运行。

▲ 系统架构图将已上线能力与规划方向分开标记；治理层贯穿编排和能力调用，业务系统仍是唯一真相来源。

结论：架构上的“独立”解决发布、升级和数据边界；身份与 API 上的“连接”解决用户体验和真实业务执行，两者必须同时成立。

二、为什么不能把 AgentOS 直接并进主线后端

智能体运行时和传统业务系统的变化节奏不同。

维度	传统业务系统	企业智能体服务
核心职责	权限、流程、单据、库存、金额、事务	对话、路由、技能、模型、确认和能力编排
版本节奏	稳定优先，升级谨慎	模型与运行时迭代更频繁
负载特征	短请求、确定性事务	SSE 长连接、模型等待、任务调度
数据类型	业务主数据和过程数据	会话、确认上下文、运行步骤和反馈
故障处理	保证业务连续性	可降级、切换模型或暂时停用智能能力

如果把两者强行放入一个进程，模型依赖升级、SSE 连接、智能体任务积压都可能影响核心业务接口。独立服务允许企业按需购买、单独扩容、单独回滚，也让 AgentOS 能连接不止一个业务系统。

独立数据库同样重要。AgentOS 保存的是会话、技能、能力授权、确认单、运行步骤、模型服务和调度任务；它不应该在自己的库里复制用户、组织和财务业务表。身份和业务数据都从可信系统获取。

三、业务 API 是唯一写入口

独立服务不能演变成“跨库直写”。正确的调用链是：

模型理解 → 能力注册表 → 风险闸门 → 数据范围收窄
→ 用户确认 → 携带本人令牌调用领域 API → 返回真实结果

真实执行器在调用主线接口时，会使用当前员工的租户和访问令牌：

private String call(AgentosCapabilityDO capability,
                    Map<String, Object> arguments,
                    AgentosExecutionContext context) {
    HttpMethod method = HttpMethod.valueOf(capability.getHttpMethod());
    boolean hasBody = HttpMethod.POST.equals(method) || HttpMethod.PUT.equals(method);
    String uri = hasBody ? capability.getHttpPath()
            : buildQueryUri(capability.getHttpPath(), arguments);

    RestClient.RequestBodySpec spec = executeRestClient.method(method)
            .uri(uri)
            .header(AgentosTokenHolder.TENANT_HEADER, String.valueOf(context.tenantId()))
            .header("Authorization", "Bearer " + context.token());
    if (hasBody) {
        spec.contentType(MediaType.APPLICATION_JSON)
                .body(JsonUtils.toJsonString(arguments));
    }
    String response = spec.retrieve().body(String.class);
    validateMainlineResponse(response);
    return response;
}

这里不使用拥有超级权限的公共服务账号。员工在原系统里看不到的数据，换成对话入口后仍然看不到；业务系统该拒绝的请求，仍然会拒绝。

HTTP 200 也不等于业务成功。执行器还要识别统一响应中的业务状态，只有真正成功并返回业务主键、单号和详情地址，才能把确认任务标记为完成。

四、能力注册表把几千个接口变成“少量可用动作”

企业后端往往有成百上千个接口。把完整接口目录直接交给模型，既浪费上下文，也把权限风险放大。

AgentOS 会同步候选能力，但默认并不全部上架。管理员需要审查：

• 这个能力属于哪个业务模块；
• 是只读、写入、审批还是资金操作；
• 数据范围是本人、部门还是更大范围；
• 参数中哪些来自模型，哪些必须由登录态注入；
• 写操作是否需要确认；
• 成功后应打开哪个详情页。

▲ 真实能力审核页面：大量候选接口保持待审状态，只有少量明确、可治理的能力上架。

风险闸门在每次执行时再次判断，而不是只靠页面隐藏：

private String checkGate(AgentosCapabilityDO capability,
                         AgentosExecutionContext context) {
    if (!AgentosCapabilityStatusEnum.ONLINE.getStatus()
            .equals(capability.getStatus())) {
        return "该业务能力尚未上架，无法调用。" + NO_RETRY;
    }
    if (context.stepCount() >= guardProperties.getMaxToolSteps()) {
        return "本轮已经查询了太多次，请停止调用工具，用已有结果直接回复员工。";
    }
    String risk = capability.getRiskLevel();
    if (AgentosRiskLevelEnum.READ.getLevel().equals(risk)) {
        return null;
    }
    if (AgentosRiskLevelEnum.FUND.getLevel().equals(risk)) {
        return "这是资金类操作，智能体一律不执行，请到业务系统里自行办理。" + NO_RETRY;
    }
    if (AgentosRiskLevelEnum.APPROVE.getLevel().equals(risk)) {
        return "审批决定必须由审批人本人做出，我不能代替你点同意或驳回。" + NO_RETRY;
    }
    if (AgentosRiskLevelEnum.WRITE.getLevel().equals(risk)) {
        return null;
    }
    return "这是写入类操作，需要你在确认页核对后才能提交，当前版本尚未开放。" + NO_RETRY;
}

这段代码体现了一个关键设计：审批和资金动作不是“以后再补”的普通功能，而是默认关闭的治理红线。

结论：模型不应该拥有接口目录的自由调用权；能力注册、人工审核、运行时闸门和业务权限需要层层收口。

五、人在回路不是前端弹窗，而是持久化业务状态

写操作通过闸门以后仍不会立即执行。执行器先生成确认任务，把最终参数、风险等级、详情路径、过期时间和业务预览固化下来：

private String parkForConfirm(AgentosCapabilityDO capability,
                              Map<String, Object> arguments,
                              AgentosExecutionContext context, long startAt) {
    String summary = "即将调用「" + capability.getName()
            + "」写入业务系统，需你本人确认后才会提交";
    String preview = confirmPresentationService.preview(
            capability, arguments, context, latestOcrPreview(context));
    AgentosConfirmDO confirm = confirmService.createPending(
            capability, arguments, context, summary, preview);
    if (context.confirmListener() != null) {
        Map<String, Object> payload = new LinkedHashMap<>();
        payload.put("confirmId", confirm.getId());
        payload.put("capabilityCode", capability.getCode());
        payload.put("capabilityName", capability.getName());
        payload.put("summary", summary);
        payload.put("preview", preview);
        payload.put("riskLevel", capability.getRiskLevel());
        payload.put("detailPath", capability.getDetailPath());
        payload.put("fields", AgentosConfirmFields.editable(capability, arguments));
        if (confirm.getExpireTime() != null) {
            payload.put("expireTime", confirm.getExpireTime()
                    .format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")));
        }
        context.confirmListener().accept(payload);
    }
    String message = "已生成待员工确认的写操作（confirmId=" + confirm.getId()
            + "）。请用自然语言告诉员工：需要在对话里点「确认」后才会真正提交到业务系统。"
            + "在员工确认之前不要声称已经提交成功，也不要重试调用本工具。";
    recordStep(capability, arguments, message, context, startAt,
            true, AgentosRunStepTypeEnum.CONFIRM);
    return message;
}

确认上下文绑定租户、用户、会话和运行记录。模型只负责把“为什么需要确认”解释给员工，不能在员工确认前声称已经提交成功，也不能重新生成另一组关键参数。

切换会话后确认卡能够恢复，取消保持业务系统零写入；确认后仍通过同一能力执行器调用业务 API，并记录请求摘要、执行结果和耗时。

六、连接器 SPI 让独立服务不只连接一套系统

主线零侵入不等于只能连接 RuoYi Office。对于金蝶、用友或客户自研系统，可以实现连接器适配器，把厂商认证和协议差异封装在边界内。

真实 SPI 保持得很小：

public interface AgentosConnectorAdapter {

    String vendor();

    String name();

    List<AgentosConnectorAuthType> authTypes();

    String test(AgentosConnectorEndpoint endpoint);

    String invoke(AgentosConnectorEndpoint endpoint,
                  AgentosConnectorInvocation invocation);

    List<AgentosConnectorTemplate> templates();
}

适配器只处理协议和认证，不自行绕过治理。能力上架审核、风险闸门、本人范围、写操作确认和全链路留痕，都在进入适配器之前统一完成。

▲ 开发空间真实页面：Build 只组合已经上架的能力，生成的是可检查的智能体草稿，不会凭一句描述发明新接口。

“支持连接第三方系统”属于可扩展能力。要真正上线，客户系统仍需提供稳定鉴权、接口版本、字段字典、业务错误码、数据权限和写入幂等，不能只给数据库账号。

七、技能、能力和接口为什么必须分层

▲ 技能描述员工何时使用、解决什么和不解决什么；能力描述可执行动作；连接器负责实际协议。三层职责不同。

三者可以这样理解：

层次	回答的问题	示例
技能	什么场景下怎么协作	费用报销：先识别、缺什么问什么、确认后生成草稿
能力	可以执行哪个确定动作	查询费用类型、识别发票、创建报销草稿
连接器/API	请求具体发到哪里	主线领域接口或第三方系统接口

把这三层拆开后，同一个“查询本人待办”能力可以被多个智能体复用；同一个费用报销技能也可以根据客户环境映射到不同连接器。

八、部署和故障边界

独立部署通常包含：

• AgentOS 前端：独立构建，可通过 /ai/ 对外提供，也可嵌入主线；
• AgentOS 后端：Spring Boot 独立进程，默认本地端口 48091；
• 主线后端：继续运行在自己的服务边界，默认本地端口 48080；
• AgentOS 数据库：独立保存智能体运行和治理数据；
• OAuth2/SSO：负责一次登录和用户身份交换；
• Nginx/Jenkins：分别发布前后端，不把 AgentOS 构建塞进主线任务。

如果模型服务异常，可以切换备用模型或暂停智能体，不影响员工继续使用原业务系统；如果 AgentOS 发布失败，也不应该让主线后端无法启动。这是“加购扩展”必须具备的故障隔离能力。

结论：主线零侵入不是少改几个文件，而是编译依赖、数据库、发布流水线和故障域都保持单向解耦。

九、常见问题

1. 独立服务会不会导致用户二次登录？

一体化部署通过 OAuth2/SSO 交换身份。理想体验是登录业务系统后直接打开智能体；直接访问智能体时，也只进入一次主线账号登录，不向用户展示租户 ID 和授权范围。

2. AgentOS 为什么还需要自己的数据库？

会话、确认上下文、运行步骤、能力授权、模型服务和定时任务都属于智能体运行数据。把它们混入业务库会增加升级和交付耦合，但独立库也不会复制主线用户、组织和财务业务表。

3. 能不能让 AgentOS 直接读业务数据库提高性能？

不建议。直读可能绕开数据权限，直写会绕开领域事务。高频查询应通过专用只读 API、缓存或报表接口优化，而不是破坏业务边界。

4. 连接第三方系统是否开箱即用？

连接器框架和治理链路已经具备，但具体系统仍需做身份映射、能力映射、字段转换和验收测试，属于可配置、可二开的实施工作。

5. 为什么主线不能反向调用 AgentOS？

主线一旦在编译或启动阶段依赖扩展服务，未购买、停用或升级 AgentOS 都可能影响核心业务。主线只保存可选入口配置，智能体主动通过 API 获取所需能力，更符合加购扩展的生命周期。

十、结语

企业智能体的独立部署不是为了把系统拆得更多，而是为了守住核心业务的稳定边界。双前端、双后端、独立数据库和单向 API 依赖，让模型、运行时与连接器可以快速演进，同时把身份、权限、事务和业务规则继续留在可信系统中。

如果你正在给现有 ERP、OA 或自研系统接智能体，最难处理的是身份映射、业务 API，还是写操作治理？欢迎在评论区交流架构取舍。

如果这篇对你有用，点个「在看」或收藏。

🤖 在线体验·智能体：https://ruoyioffice.com/ai/work
🏢 在线体验·业务系统：https://ruoyioffice.com/web/
📘 产品手册：https://ruoyioffice.com/
💬 微信：17156169080（备注「AgentOS」）

可以直接打开智能体，也可以先进入业务系统，再通过右下角“小擎”使用嵌入式助手。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/zhouzhongyan/article/details/167257935