接入配置与单点登录

本页以已能正常登录的 RuoYi Office 企业管理一体化平台为基础。首次安装智能体的编译、数据库初始化与容器操作，请先完成完整部署手册；本地研发请用本地启动与调试。

1. 先确认三类地址

平台后端地址供 AgentOS 后端调用；平台前端地址供浏览器登录和打开业务详情；智能体前端地址供浏览器打开对话。这三类地址不能混填。

本地联调示例

在 AgentOS 的 deploy/agentos.env 中替换对应字段：

AGENTOS_MAINLINE_URL=http://127.0.0.1:48080
AGENTOS_MAINLINE_WEB_URL=http://localhost:5800
AGENTOS_WEB_URL=http://localhost:5666/

此例假设后端运行在本机进程中。浏览器登录统一使用 localhost，不要在登录过程中来回切换 127.0.0.1。后端地址不包含 /admin-api。

同域生产示例

AGENTOS_MAINLINE_URL=http://192.168.10.20:48080
AGENTOS_MAINLINE_WEB_URL=https://office.example.com
AGENTOS_WEB_URL=https://office.example.com/ai/

以上 IP、域名均为示例，请替换为实际值。AgentOS 在容器内运行时，平台后端必须填容器可达的地址，不能把 localhost 当宿主机使用。

若平台实际入口为 https://office.example.com/web/#/workspace/home，平台前端根地址应理解为 https://office.example.com/web，而不是业务首页完整地址。平台部署在根目录还是 /web/、使用 history 还是 hash 路由，必须一起核对。

当前工具在本地模式会把该地址写入智能体前端；生产模式生成的 VITE_MAINLINE_WEB_URL 为空，按同域根入口处理，不能只修改后端 env 就认为已适配任意平台子路径。若客户平台部署在 /web/ 等子路径，实施人员还需核对智能体前端构建配置与实际 SSO 路由：前端的 VITE_MAINLINE_WEB_URL 应匹配平台根路径，hash 路由还需匹配 VITE_MAINLINE_ROUTER_HISTORY=hash。这类部署应先按项目构建配置完成适配，再验收，避免每次 prepare 后被生成规则覆盖；本页不承诺该组合已自动适配。

配置只维护一份

AgentOS 的手工配置源是 deploy/agentos.env。首次通过 node tools/setup.mjs init --mode local 或 --mode deploy 生成；已有安装保留原文件与密钥，不要重新 init。修改后运行对应模式的 prepare，再重启后端；涉及前端地址时重新构建前端。不要手改生成的 agentos.properties、agentos.runtime.env 或前端模式配置。

本地标准目录中，在 AgentOS 根目录执行：

node tools/setup.mjs prepare --mode local --platform ../../ruoyi-office

生产目录和 --mode deploy 用法参见完整部署手册。prepare 只生成文件，不自动执行 SQL。

2. 配置平台侧 AI 助手入口

用编辑器打开平台 PC 前端 apps/web-antd/ 下当前构建模式对应的环境文件。本地开发与生产构建可能加载不同文件，以项目启动、构建命令为准。

本地联调填写：

VITE_AGENTOS_ASSISTANT_ENABLE=true
VITE_AGENTOS_URL=http://localhost:5666/

同域生产填写：

VITE_AGENTOS_ASSISTANT_ENABLE=true
VITE_AGENTOS_URL=/ai/

地址填写智能体根路径，并保留末尾 /；不要填写 /ai/work，组件会自行拼接内嵌工作台和独立工作台路径。

生效方式：本地重启平台前端开发服务；生产重新构建并部署平台 PC 前端。仅重启平台 Java 后端或 Nginx，不会改变已经打包的前端变量。

务必显式配置生产路径

当前平台助手组件在生产环境未填写地址时仍回退到 /agentos/，不是 /ai/。采用本教程推荐路径时必须显式设置 VITE_AGENTOS_URL=/ai/，避免助手打开旧地址。

3. 注册 OAuth2 客户端并核对权限

首次空库安装时，部署工具生成 sql/generated/04_mainline.sql。由平台管理员用数据库客户端审核后，在 RuoYi Office 平台数据库执行，而不是在 AgentOS 独立库执行。完整初始化顺序见部署手册。

该脚本配置平台 OAuth2 客户端、菜单与管理员权限。包含客户端密钥，也会更新已有的 agentos 客户端，不能当作无影响的修复脚本反复执行。已有客户升级应按对应版本升级说明处理。

在平台的 系统管理 → OAuth2 → 客户端管理中核对（菜单名称可能因客户权限或定制而不同）：

• 客户端 ID：agentos，状态启用。
• 客户端 Secret：与 deploy/agentos.env 的 AGENTOS_CLIENT_SECRET 一致；使用工具生成值，不公开到前端或截图。
• 授权方式：包含 authorization_code，保留交付脚本所需的其他授权方式。
• 回调白名单：覆盖本地 http://localhost:5666/sso-callback 或生产 https://office.example.com/ai/sso-callback；当前实现按前缀匹配，使用精确的客户入口前缀，不配置宽泛外域。
• 授权范围与自动批准范围：按当前实现核对 user.read、user.write，不要随意放大权限范围。
• 租户与角色：AGENTOS_TENANT_ID、AGENTOS_ADMIN_ROLE_ID 对应实际租户和管理员角色，不是员工用户 ID。

登录过程为：智能体发现未登录 → 进入平台 SSO 授权页面 → 未登录则先登录平台 → 授权码回到智能体 /sso-callback → 建立智能体登录态。平台已有登录态时通常无需再次输入密码；账号权限与浏览器策略仍需实际验收。

不要通过 URL 传 Client Secret，也不要用全权限系统账号替代员工身份调用业务接口。

4. 分配菜单与业务权限

在平台角色管理中按职责分配：

• 普通员工：智能体工作台，以及其岗位所需的平台业务接口权限。
• 智能体管理员：按职责授予智能体、能力、模型、知识库等管理权限，不将全部管理权限授予所有员工。
• 财务场景人员：除工作台权限外，还需平台相应财务权限和有效员工档案、公司、账套等基础资料。

菜单入口通常指向 /ai/work 与 /ai/dev。能看到菜单不代表有全部接口权限；AI 助手也不会绕过平台原有租户、用户、角色与数据权限。

5. 核对 Nginx 和内嵌访问

推荐同域 HTTPS，按以下规则合并到现有站点，不要覆盖平台完整 Nginx 配置：

• /ai/ → 智能体前端，并支持 /ai/work、/ai/sso-callback 等历史路由刷新。
• /admin-api/agentos/ → AgentOS 后端，优先于通用 API 路由。
• 其他 /admin-api/ → 原平台后端，不改变原业务路由。
• 智能体流式接口关闭代理缓冲，配置足够的读取超时；CDN、网关同样需要检查。
• 内嵌页面不得被 iframe 安全策略拦截；只允许实际业务站点来源，不为解决嵌入而全站取消安全限制。

具体代理模板和端口见完整部署手册。分域部署还需额外处理 Cookie、跨域、内嵌策略与回调，不属于本教程的同域快速路径。

6. 业务上下文不等于授权

平台通过受来源约束的消息桥接同步当前业务页面上下文、主题和退出事件，智能体可引用当前页面继续对话。页面标题或业务编号只用于辅助理解，不能作为获取或修改数据的授权依据；实际执行仍按当前员工权限校验。

普通对话只需可用的大模型；发票报销还需 OCR、允许的附件服务域名及兼容的 Finance 接口。请先完成联调验收，再向员工开放。