SpringBoot + Vue3 企业智能体架构：独立服务、独立数据库与主线零侵入
🌐 产品手册：https://ruoyioffice.com/
👇 文章底部提供智能体与业务系统两种体验入口 👇
💬 ：17156169080（获取 AgentOS 产品咨询）
企业智能体最容易出现两种架构极端。
一种是完全外挂：单独做个聊天页面，只能问答，拿不到可信身份和业务上下文。另一种是深度掺入：把运行时、模型 SDK、对话表、连接器和所有业务模块塞进原有后端，最终 AI 升级牵动整个业务系统。
RuoYi Office AgentOS 选择了第三条路：保持独立前端、独立 Spring Boot 后端、独立数据库和独立发布流水线；通过 SSO 复用身份，通过受控业务 API 办事，通过连接器适配其他系统。主线业务不反向依赖 AgentOS，AgentOS 也不复制财务、OA、人事、项目等领域逻辑。
这篇文章拆的是已经落地的架构边界，不把“能通过连接器扩展”写成所有第三方系统已经开箱接通。
一、先给结论：独立，不等于割裂
从用户视角看，AgentOS 可以嵌入原业务系统右下角，也可以独立打开工作台；一体化部署时复用当前登录身份，不要求用户理解 OAuth、租户 ID 或授权范围。
▲ 独立前端的真实工作台：工作、管理、开发三个空间运行在 AgentOS 自己的应用中，也可以通过嵌入页进入主线系统。
从工程视角看，它有四条硬边界：
-
AgentOS 后端使用独立启动器和独立端口。 -
对话、能力、确认单、运行记录等存入独立数据库。 -
主线业务写入只能走主线领域 API，不直连业务表。 -
主线后端不依赖 AgentOS，关闭或不购买扩展时不影响原系统运行。
▲ 系统架构图将已上线能力与规划方向分开标记；治理层贯穿编排和能力调用，业务系统仍是唯一真相来源。
结论：架构上的“独立”解决发布、升级和数据边界；身份与 API 上的“连接”解决用户体验和真实业务执行，两者必须同时成立。
二、为什么不能把 AgentOS 直接并进主线后端
智能体运行时和传统业务系统的变化节奏不同。
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
如果把两者强行放入一个进程，模型依赖升级、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 只组合已经上架的能力，生成的是可检查的智能体草稿，不会凭一句描述发明新接口。
“支持连接第三方系统”属于可扩展能力。要真正上线，客户系统仍需提供稳定鉴权、接口版本、字段字典、业务错误码、数据权限和写入幂等，不能只给数据库账号。
七、技能、能力和接口为什么必须分层
▲ 技能描述员工何时使用、解决什么和不解决什么；能力描述可执行动作；连接器负责实际协议。三层职责不同。
三者可以这样理解：
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
把这三层拆开后，同一个“查询本人待办”能力可以被多个智能体复用；同一个费用报销技能也可以根据客户环境映射到不同连接器。
八、部署和故障边界
独立部署通常包含：
-
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」）
可以直接打开智能体，也可以先进入业务系统，再通过右下角“小擎”使用嵌入式助手。